CGI and SSI with lwip on Stellaris

Posted on June 11, 2012
Tags: , , ,
by Sanchayan Maity

CGI stands for Common Gateway Interface and SSI stands for Server Side Include. The below post is going to be about, how to use them with lwip for employing web page interface in your embedded system.

First, I would like to give some clarification. My work on the above was build up over and above the enet_io example code provided by Texas Instruments with their Stellaris LM3S6965 boards. My main aim of this post is to help you in understanding the code flow and is very specific to the example provided. I have not done any work in porting lwip nor written this application from ground up.

So let’s get started.

You will need to have the html code and the program code side by side to understand what’s going on.

With web pages, you would like to display some data and send data entered on the web page to your embedded system.

  1. SSI Server Side Includes (Displaying data on web page)

When a web page request is sent from a browser to your embedded system, which has got lwip configured with CGI and SSI, if any SSI tag is present on the web page being served, the SSI handler is called. These handlers are registered with a call to the function 

http_set_ssi_handler(SSIHandler, g_pcConfigSSITags, NUM_CONFIG_SSI_TAGS)

where SSIHandler is the function which gets called, when the web page is served containing SSI tags. g_pcConfigSSITags is an array containing the list of SSI tags. These names you will find in the html code of the web page and in the program code file  enet_io.c.  NUM_CONFIG_SSI_TAGS is the number of individual SSI tags, the http server can expect to find.

To understand what I said, let me take you through the enet_io code. Open the folder fs in the code directory, and open the htm web page with a web browser. In the web page, the SSI tag corresponding to this, can be found in I/O Control Demo2 link. Use view source, by right clicking on the web page. The SSI tag will be like 

<!--#PWMfreq-->
In the g_pcConfigSSITags array, you will see “PWMfreq”. So, whenever the system is serving this web page, as there is an occurrence of an SSI tag, the SSI handler is called, and the value of PWMfreq is substituted by the actual value. In the SSI handler, you will find something like below, 

case SSI_INDEX_PWMFREQ:
ulVal = io_get_pwmfreq();
usnprintf(pcInsert, iInsertLen, "%d", ulVal);
break;

When the user requests the web page, on seeing the occurence of the SSI tag, the SSI handler gets called, the case corresponding to PWMFreq, is selected and executed, the io_get_pwmfreq() returns the value of pwm frequency on the system, and this is inserted in the web page by usnprintf function. This gets done for each SSI tag in the web page. In case, you have defined a tag on the web page, but, not written a corresponding entry in the tags array and the handler, you will get an error on the web page, complaining no tag found.

To summarise, register your SSI handler, include the SSI tag in the tags array, include a corresponding entry in the handler, which will return its value. And viola!. You can now display values on web pages.

  1. CGI Common Gateway Interface (Sending data to the system)

Lets say you enter a new value of PWM frequency and click on Update Settings. On clicking, just check what url is displayed on the address bar of your browser. I entered a value of 50 for PWM frequency and the url changed to 

file:///C:/StellarisWare/boards/ek-lm3s6965/enet_io/fs/iocontrol.cgi?LEDOn=1&PWMFrequency=50&PWMDutyCycle=100&Update=Update+Settings"

Note that I was not connected to the board while writing this and executed it from my local drive, so the file url). You can see, how the value of 50 was appended and send to the system. Also, notice the iocontrol.cgi in the url. This is defined along with the corresponding CGI handler in the g_psConfigCGIURIs array. When your board, receives this web page request, the lwip stack knows which function to call. The handlers are registered with a call to

http_set_cgi_handlers(g_psConfigCGIURIs, NUM_CONFIG_CGI_URIS).

In the corresponding CGI handler, the parameters are extracted from the URL, by FindCGIParameter function and GetCGIParam function, and the functions are called for setting these values.

This is how data gets passed to the system using CGI through web pages.

I hope, I was able to at least clear a little bit for you to start off on your own and make changes you want. In case, I missed something, do post a comment and I will try to help you out.