Adding Support for Networking

and Web Technologies to an Embedded System

John Efstathiades

Pebble Bay Consulting

About Pebble Bay

• Independent embedded software specialists • founded 8 years ago

• based in Leamington Spa

• Consultancy • independent review and advice

• Software development • fully-managed projects

• Expertise • real-time operating systems

• hardware/software interfacing

• software porting and optimisation

22-May-14 © 2012 Pebble Bay Consulting Limited 2

Project Background

• Industrial control system • Controller with LCD and keypad

• Remote access from PC via RS-485

• Hardware re-design • Cortex M3 processor

• Improved LCD panel

• Reduce manufacturing costs

• Make provision for networking

• Software porting • Update low-level code

• Minimize changes to GUI and remote access API

Networking Update • RS-485 remote access protocol allows:

• Configuration and data access

• Front panel LCD and button mirroring

• New customer requirements: • Access from mobile devices

• Access over LAN/WAN/Internet(?)

• Networking options • RS-485 extenders

• No software changes

• Relatively simple to deploy

• Use on-board networking

• No additional hardware

• Extend product features

Software Requirements • Industry standard networking technology

• Maintain existing remote access protocol • Implement transport independent interface

• Support existing customer base

• Opportunity to sell enhanced capabilities

• Brower-based client • OS and hardware independent

• No additional software to install

• User authentication • Restrict access to device

Software Solution • lwIP TCP/IP network stack

• Mature product with BSD licence

• StellarisWare integration available (?)

• HTTP web server available

• AJAX Programming • Client-side processing

• Dynamic page updates with new information

• HTML and JavaScript • Fast client application prototyping

• DataView class • Efficient mechanism for handling binary data

• Easy to represent arrays and structs in target device memory

lwIP Integration and Configuration • Documentation

• lwIP Application Developers Manual

• lwip/doc/rawapi.txt

• Which release? • Latest (v1.4.1) vs. StellarisWare (v1.3.2)

• lwIP operation • Periodic timer tick

• Task model or interrupt thread

• Compatible with main-loop design with interrupts

• lwipOpts.h • Includes/excludes stack features and behaviour

• Overrides defaults in lwip/src/include/lwip/opt.h

• Debugging, memory management, stack components, …

lwIP Abstraction Layer • No RTOS - define NO_SYS

• Porting Layer • Ethernet hardware interface

• Interrupt handling routines

• lwIPInit()

• Initialises stack modules

• Registers Ethernet hardware with stack

• lwIPEthernetIntHandler()

• Handles received packets

• Sends packets in transmit queue

• lwIPTimer()

• Stack timer processing

HTTP Server • Provided as application add-on module

• HTTP server module

• Raw vs. socket interface

• File system APIs

• Optional ROM-based file system • Stores HTML pages and images

• C array created by makefsdata perl script

• Code space may be issue?

• Integrated with lwIP • Call httpd_init()after

lwip_init()

Device Security • Need to protect device against

• Unauthorised access

• Data theft

• Malicious intent

• Authentication Options • Public key authentication

• Digest authentication

• Basic authentication

• HTTP Basic Authentication • Simple mechanism using HTTP headers

• Credentials encoded with Base64 – not encrypted

• Fits in well with lwIP HTTP header processing

HTTP Basic Authorisation • Supported by all browsers

• Server • Sends Authenticate header with HTTP 401 response

• Client • Sends Authorization request header (in every transaction)

• Base64 encoded username and password

• Cached by browser once accepted by server

• lwIP HTTP header processing easy to extend • Extend http_recv() to look for Authorization header

• Extend get_http_headers() to send 401 if no authorisation

• Add routines to decode and check user credentials

lwIP Hints and Tips • Debug control in lwipOpts.h

• Overrides defaults in lwip/src/include/lwip/debug.h

• LWIP_DEBUGF() common debug macro

• LWIP_PLATFORM_DIAG() device-specific debug output

• Stack runs in interrupt context • Enabling debug could affect system behaviour

• Memory trace buffer and JTAG debugger less intrusive

• May need to experiment with memory configuration • Overall heap size

• lwIP buffer pool size

• Received packets stored in buffer chains • Buffer payload size set by PBUF_POOL_BUFSIZE => default is 256

AJAX Programming Methodology • Collection of related technologies

• HTML for presentation of data

• XMLHttpRequest object for asynchronous server communication

• Document Object Model for dynamic display and manipulation of data

• JavaScript implementation language

• Client application sends request to server (device) • Request encoded in HTTP request

• Read/write operational data

• Send control/status requests – get battery level, start processing, …

• Client application receives asynchronous response • Callback function invoked when data received

• Page contents dynamically updated – no page refresh required

Device Support for Web I/O • HTTP GET vs. POST

• GET has query strings encoded in URL

• POST has query strings in HTTP message body

• POST is “preferred” mechanism but not supported in lwip 1.3.2

• Define query strings for control/status requests www.mydevice.com/control?led=1&status=on

www.mydevice.com/status?led=1

• Direct handling of HTTP Query Strings • Extract name/value tuples from HTTP request

• Implement handler for each query type

• Response sent to client when operation is complete

• Self-contained => minimal impact on existing software

Query String Processing /*

* Find an asynchronous I/O handler

*/

if (webIoHandlerGet (queryStr, &ioFunc, &bufLen) == 0)

{

char * pBuf;

int responseLen;

/* Allocate memory for the response string */

pBuf = mem_malloc (bufLen);

if (pBuf == 0)

{

mem_free (ptFile);

return NULL;

}

/* Perform the I/O operation */

responseLen = ioFunc (name, pBuf, bufLen);

/*

* After the I/O handler has been invoked all the data to be returned

* is in the response buffer so set index to the end of the "file".

*/

HTTP and Binary Data • Poor browser support for sending/receiving binary data

• Standard problems: • Byte order

• Alignment and packing

• Message/structure delimiters

• DataView and TypedArray objects

• Allows complex data types to be created

• Independent of client’s native byte order

• Base64 encoding • Standard mechanism for encoding binary data into ASCII strings

• Simple algorithm to implement

DataView Example /*

* Construct a key press message

*/

function v42KeypressCmd(key)

{

var buffer = new ArrayBuffer (REM_KEYPRESS_CMD_PKT_LEN);

var dv = new DataView (buffer);

var byteArray = new Uint8Array(buffer);

var crc;

dv.setUint8 (REM_CMD_BYTE_OFFSET, REM_KEYPRESS_CMD_BYTE);

dv.setUint8 (REM_ID_BYTE_OFFSET, unitNum & 0x0f);

dv.setUint16 (REM_MEM_ADDR_OFFSET, 0);

dv.setUint16 (REM_RETURN_MSG_LEN_OFFSET, REM_KEYPRESS_CMD_RESP_MSG_LEN);

dv.setUint16 (REM_PKT_LEN_OFFSET, REM_KEYPRESS_CMD_PKT_LEN);

dv.setUint8 (REM_KEYPRESS_CMD_MSG_KEY, key);

dv.setUint8 (REM_KEYPRESS_CMD_MSG_PREV, 0);

dv.setUint8 (REM_KEYPRESS_CMD_MSG_SLAVE, 1);

crc = crc16 (byteArray, REM_KEYPRESS_CMD_PKT_LEN - REM_TRAILER_LENGTH);

dv.setUint16 (REM_KEYPRESS_CMD_CRC_OFFSET, crc);

return base64Encode (byteArray);

}

HTML Document Object Model • Cross-platform representation of objects in HTML

• HTML elements as objects

• Properties of HTML elements

• Methods and events for HTML elements

Dynamically Get, Change, Add, or Delete HTML elements

• Use JavaScript to create dynamic HTML • Update pages with latest device data

• Build page elements “on the fly” based on device responses

• Periodic page updates using timer

document.getElementById(“<element>").innerHTML =

JavaScript DOM Example /*

* Update the zone summary table

*/

function zoneTableBuild (zoneId, zoneData)

{

document.getElementById("zone_data").innerHTML =

"<table>" +

"<tr>" +

"<td>" + "Zone id" + "</td>" +

"<td>" + zoneId + "</td>" +

"</tr>" +

"<tr>" +

"<td>" + "Name" + "</td>" +

"<td>" + zoneData[ZONE_NAME] + "</td>" +

"</tr>" +

"<tr>" +

"<td>" + "Actual temp" + "</td>" +

"<td>" + zoneData[ZONE_ACTUAL_TEMP] + "</td>" +

"</tr>" +

"<tr>" +

"<td>" + "Target temp" + "</td>" +

"<td>" + zoneData[ZONE_TARGET_TEMP] + "</td>" +

"</tr>" +

"</table>";

}

HTML Hints and Tips • Cross-browser compatibility issues

• HTML element support varies => unexpected behaviour

• HTML rendering varies => unexpected representation

• Browser testing may be time consuming

• HTTP GET request caching • Client can cache GET requests

=> Put random string into each request

www.mydevice.com/control?led=1&status=on&msg=97453

• Consider AJAX framework • GUI development

• Which one to choose?

• Cost and learning time?

Javascript Hints and Tips • +ve – Javascript syntax has similarities to C

• Relatively easy to pick-up

• -ve – Javascript syntax has similarities to C • Subtle semantic differences – easy to make big mistakes

• Many books and online resources

• Get editor that is Javascript (and HTML) aware • Will save considerable time (=money)

• Use console object • Output debug and status messages to browser console window

• Many browsers have Javascript debugger (F12) • Inspect variables, set breakpoints, call stack, …

Summary • HTTP is powerful, flexible device interface

• lwIP integration relatively smooth • Ported to many hardware and software environments

• Good tools are essential – not a surprise!

• Minimal impact on existing device software

• HTML + DOM can produce effective dynamic pages • (in the right hands)

• (Be prepared to) throw away prototypes

• JS can produce elegant, object-oriented code • (in the right hands)

• Very easy to abuse – (be prepared to) throw away prototypes

• Easy to under-estimate effort for JS and HTML development

More Information • Pebble Bay Consulting

• www.pebblebay.com

• info@pebblebay.com

• 01926 421700