Introduction

The default firmware shipped with the M52259DEMOKIT and M52259EVB is Web HVAC, which allows people to view and control HVAC via a standard web browser. The web server uses default IP on 169.254.3.3 and assigns IP for connected PC on 169.254.3.x over cross-over Ethernet cable. Of course it has no authentication feature so the developer can visit it freely. The web server also demonstrates extra web pages if you plug a USB stick with requested web pages. It is the 4th lab project in the series of demo projects prepared for the Kirin3 connected microcontroller demo kit. Here is the list of the lab projects.

• Lab 1: HVAC controller, MQX RTOS (HVAC + Remote console + Local UI)
• Lab 2: MQX USB and MFS (HVAC + Remote console + Local UI + USB logger)
• Lab 3: MQX RTCS Telnet and FTP (HVAC + Remote consoles for RS232 & Telnet + Local UI + USB logger + FTP server)
• Lab 4: Web HVAC (HVAC + Remote console + Local UI + HTTP server + USB host / mass storage device with more web pages)
• Lab 5: Finding Errors using Task Aware Debugging (TAD) in CW
• Lab 6: Ethernet to Serial Bridge.

From Lab1 to Lab4, the demo projects are becoming more complicated one by one. The Web HVAC project features MQX RTOS, RTCS TCP/IP, CMX USB host and Mass Storage Device, MFS FAT file system, Web CGI and command shell from RS232 console to demonstrate an embedded HVAC Web server with state-of-art web programming techniques. Because the project implements the Web GUI with AJAX, the overall system response is quite fast. Meanwhile we can separate the CGI function design from the Web UI. It is easy to maintain the project and easy to upgrade for customer requirement. At last, Freescale offers a convenient utility to convert HTML resources from a directory into a C file. Of course, we still have to improve the project to fit an existing network.

Web Programming

If you have used Lynx, you will be impressed by the Web page presented in text mode. HTTP is an application protocol listens to the TCP port 80 (or 8080). The Internet browsers (user agent) convert the HTML pages and tags in the canvas of the browsers, so a web page is presented in graphic mode. In principle, an HTTP server just listens to the port, gets user agent information and userinquires and sends back requested files. The working method is straightforward , any programming languages with standard input/output have been used in web server, including C, shell script (which are named as CGI, Common Gateway Interface) and dedicated web scripting languages (Perl, PHP, Python, Lua, JSP, ASP and etc). In embedded web server, C language  is the preferred one to implement the CGI functions. If you design an embedded project with web server, CGI functions, HTML pages supports get and post method, it is difficult to separate the application logic from UI presentation. Meanwhile, the performance of an embedded web server with restricted computing power and memory is slow since refresh/get/post methods will loads the entire page again. It was a nightmare of web portal like MSN/Yahoo, since there are too many concurrent connections to load a big HTML page with huge number of files. It is worse for an embedded server, which is  overloaded withseveral connections.
 
AJAX is widely deployed since it brings many benefits over traditional approaches. AJAX is a revolution in web programming based upon many existing technologies. AJAX is made up of CSS, JavaScript, DOM, XMLHTTP method. Most of the web sites have migrated to AJAX, since it offers faster response, less transaction, more user interaction, independent data structure, device dependent presentation, object oriented programming, cross-domain operation and mash-up capabilities. Recently, JSON gains more attention for its simpler data structure over XML format. 
 
The web programming is beyond the scope of this article, but it is important in an embedded web server. AJAX (or JSON) can reduce the transaction between browser and embedded server. It is the major benefit for this project.

Convert HTML into C

Freescale offers an utility called mktfs to convert the web resources (including HTML, CSS, JavaScript, images) into a C file. After design the HTML pages with your favorite web designer, you can invoke it in command prompt to convert an entire HTML directory into C file.  
 
C:\Program Files\Freescale\Freescale MQX 3.0\demo\web_hvac\>mktfs.exe web_pages tfs_data.c
Converting web_pages directory to file tfs_data.c ...
Adding file hvac.html
Adding file hvac_input.html
Adding file ipstat.html
Adding file mcf5225x.html
Adding file mqx.html
Adding file rtx.html
Adding file tcpstat.html
Done.

CGI in Embedded Web Server

Please remember you can only convert the static resources into a big C file (530KB). The interactive functions are implemented in the cgi_*.c file. 
 
By searching *.cgi in the web_pages folder, I found following entries:
 
C:\Program Files\Freescale\Freescale MQX 3.0\demo\web_hvac\web_pages>grep -irn ".cgi" ./
./hvac.html:308:                makeRequest("hvacdata.cgi");
./hvac_input.html:310:          makeRequest("hvacdata.cgi");
./hvac_input.html:363:<form name="HVAC" action="http:hvacoutput.cgi" method="POST">
./ipstat.html:333:              makeRequest("ipstat.cgi");
./rtc.html:304:         makeRequest("rtcdata.cgi");
./tcpstat.html:360:             makeRequest("tcpstat.cgi");
 
These CGI function entries are defined in a table named cgi_lnk_tbl in cgi_index.c. You can add your own CGI entries for more features.
 
When browser requests for entire HTML page, the server will print the embedded string table defined in C file for the requested HTML page to browser. The CGI entries are defined in a structure table. In an AJAX page, the JavaScript uses XMLHTTP to call a CGI entry in the server with HTTP post or get method. The parameters of post/get method can be parsed in web server with standard C string library. When a CGI entry is invoked remotely, the output stream is encoded in XML format. When user request to update the data, the JavaScript running in the browser will call CGI functions to get updated data in XML, and present it in the specific <div> sections. Since most of the HTML will not be loaded again, the transaction and response time are reduced.

RTCS Ethernet Connection

The Web HVAC is only a demo project. In order to install a real server into an existing network, we must add more pages for application specific and administrative purposes. You can check out a router, which is the commonly available embedded server in our daily life. Usually the basic authentication and WAN/LAN connection options are essential features in an embedded server. 
 
Freescale's RTCS is a complete TCP/IP stack, most of the essential protocols have been implemented. These features can be defined in compile time configuration. It is very important to check the RTCS user manual first, before you rush to implement the features by yourself . In most cases, you can just reconfigure the library, then rebuild it for practical requirement. After rebuilding the RTCS library, it can be linked to the project to support features. For detail information of MQX and RTCS, please check the documentation in the MQX 3.0 folders.
 
Obviously the Web HVAC is working as a DHCP server, we have to replace it with DHCP client, static IP and PPPoE. It is easy to enable these options individually. However the developer must add more pages, and enable these options in the same time for user selection.
 
Actually the authentication has already implemented in the source. Try to search HTTPD_AUTH_CALLBACK in the CodeWarrior, you can enable it to prevent unauthorized access to the protected features.

Web Mash-up

A web mashup is a website or web application that uses content from more than one source to create a completely new service. We can find many popular web services available from Google, Amazon and Yahoo. However what kind of web services are suitable for embedded web servers? Here I prepare some samples. You can use Widgets API to create visualizations and reporting applications that access structured data in a common format. You can contact web administrators with SMS/IM API. You can use one stop log-on API to access the protected server. You can record current data into an online spreadsheet via Google Speadsheet API... Don't limit your imagination. Most of the Web APIs are designed for web servers in Internet, you must test the Web mashup for a Web server in the LAN.

Bandwidth Optimization

if you have restricted budget for ROM size and bandwidth, you have many tricks to archive that.  
 
You can convert the HTML page into UNIX format because UNIX uses single LF termination string. You can use local encode rather than UTF-8 because of smaller size, which is quite useful in non-latin encodes. Most of the browsers support gzip compression, so you can use gzip (in Linux, Cygwin or even 7zip, Winrar and Winzip) to compress the html resources into individual zip files before convert them into C file. Additionally, you can compress the JavaScript code with JavaScript compressor, move the common part of the CSS and JavaScript code into standard alone files to optimize the bandwidth usage (but you have to check if the server can support multiple connections).  
 
If you have many features implemented in web page, you can compare the performance before and after compression. Fine tune the system, you can feel the improvement.

Reference

MCF52259 TCP/IP and USB Lab Guide

M52259DEMOKIT One-stop-shop connectivity MCU with USB, Ethernet and CAN, featuring Freescale MQX software solutions Guick Start Guide

Content used in mashups is typically obtained from a third party source through a public interface or API (web services).

The Open Directory for Mashups & Web 2.0 APIs | Applications.

ProgrammableWeb Mashup

CONTACT REQUEST
If you want to know more about this Freescale product, please submit your request to Arrow Italy using this form.

NOTE: this form is valid ONLY for Companies or Customers based in Italy and working in the Italian area.

Read the Italian version: Web HVAC per KIRIN3 da Freescale