These are the slides for a presentation we gave at Device Developer Conference 2014 in the UK. The presentation discusses the work done, experiences, and lessons learnt from adding an open source TCP/IP network stack and web server to an existing industrial control system running on an ARM Cortex M3-based processor from TI. The presentation covers the following: · Integrating the network stack into the existing software base · Configuring and using the network stack and web server · Adding support for HTTP basic authentication to restrict user access · Using HTTP to remotely access the target system and retrieve operational data · Debugging hints and tips · Pitfalls to avoid and other lessons learnt

1. Adding Support for Networking
and Web Technologies to an
Embedded System
John Efstathiades
Pebble Bay Consulting

2. 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

3. 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

4. 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

5. 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

6. 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

7. 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, …

8. 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

9. 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()

10. 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

11. 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

13. 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

14. 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

15. 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

16. 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".
*/

17. 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

18. 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);
}

19. 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 =

20. 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>";
}

21. 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?

22. 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, …

23. 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

24. More Information
• Pebble Bay Consulting
• www.pebblebay.com
• info@pebblebay.com
• 01926 421700