The EtherSmart Wildcard User Guide

<< Previous | Next>>

Introduction to the Dynamic Webserver

The EtherSmart Wildcard implements a dynamic webserver that accepts connections from your web browser, serving out static or dynamic web pages. You can "browse into" your instrument using a web browser running on an online PC to monitor the status of your instrument.

Most web pages are "static", meaning that their content does not change with each visit to the page.  However, in the context of embedded computers, "dynamic" web pages that provide up-to-date status information about the computer’s state (inputs, outputs, memory contents, etc.) are very useful.  The pre-coded driver functions enable you to serve both static and dynamic web pages. 

By coding web content into your application, you can enable remote monitoring and control of your instrument from your web-connected PC.  The "embedded web server" that runs when you execute the EtherSmart driver code responds to information requests from your browser.  You can create a set of web pages, each with a specified name, or "URL" (Uniform Resource Locator) and an associated "handler function" that serves out the static or dynamic web content for the requested page. 

The EtherSmart Wildcard’s dynamic webserver should not be confused with the XPort’s built-in static webserver that is used for configuration.  As described in the "EtherSmart Initialization, Configuration and Diagnostics" section, an additional "configuration webserver" is built into the Lantronix XPort device for low-level configuration of the Lantronix firmware, and is available at TCP/IP port 8000.  This configuration webserver is typically not used in conjunction with the EtherSmart Wildcard, and should not be confused with the dynamic webserver discussed in this section.

Web Service Basics

Most web content is authored using "HTML" which stands for HyperText Markup Language.  It is a "tagged" form of ASCII text, in which the tags instruct the web browser how to display the referenced text, data, and images. For example, the HTML line

            <b>This is an important statement</b>

presents the text string "This is an important statement" in a bold font. The <b> tag marks the start of the bold text, and the </b> marks the end of the bold text.  There are many excellent books and free online tutorials that explain how to "mark up" text into an HTML file that will display a nicely formatted web page in your browser window.

The dynamic webserver is available at the standard TCP/IP port 80 used by web browsers.  This port is a "well known port" that is assigned to HTTP (HyperText Transfer Protocol) data exchanges between a web browser (typically running on a PC) and the webserver (in this case running on the EtherSmart Wildcard).  HTTP defines the request format that comes from the browser, and the response format that comes from the server. To learn about the HTTP 1.1 standard in all its detail, type "RFC 2616" into Google and read the referenced document. 

The primary HTTP "method" command from the browser is the "GET" keyword, and this is the only HTTP method supported by the EtherSmart webserver.  The GET keyword is followed by a "URL", or Uniform Resource Locator; it can also be referred to as a URI, or Uniform Resource Identifier. The URL is a web address on the target computer.  For the purposes of this document, the URL does not include the target computer’s name, IP address or port.  The URL starts with the / (forward slash) character and follows rules set out in the HTTP  standard. A URL is a web page address as sent by the browser running on your desktop PC to the embedded web server.  For the purposes of this document, the URL is the portion of the web address that is in the browser’s address bar after the IP address or computer name.  For example, if you have assigned IP address 10.0.1.22 to the EtherSmart Wildcard, and you type into your browser’s address bar:

10.0.1.22/index.html

then the URL as defined in this document is

/index.html

Each URL starts with a / character, and is case sensitive.  Some URL’s include a "query field" that starts with the ? character and contains fieldname and value fields resulting from "forms" that are filled out by the user in the browser window.  The software driver functions make it easy to extract data from these fields to direct the operation of the handler functions.  In fact, form data from the browser provides an excellent way for the web interface to give commands to the embedded computer (to take data samples, extract data from memory and report the results to the browser, etc.)

The webserver contains a suite of functions that start with the HTTP_ prefix to implement the dynamic webserver.  These functions make it easy to respond to the browser request with a properly formatted "HTTP header" and content.  The HTTP header specifies the content type (text/html, image/bitmap, etc.) and whether the referenced page can be "cached" by the browser for fast display after the initial loading.  "Static" web pages can be safely cached, as they do not change over time.  "Dynamic" web pages, on the other hand, should not be cached because they contain dynamic data that changes with time under the control of the application program.

You configure the webserver by defining and posting a "handler function" for each web address that is implemented.  When the browser requests the web address URL, the webserver automatically executes the handler which performs any required actions and transmits the web page to the browser. As described in this section, powerful functions make it easy to use HTML "forms" to request specified data or stimulate particular actions from the Mosaic controller. 

Because the web service is running in the Ethernet task, the web requests are handled automatically without the need for intervention by the application task.  The Ethernet task’s connection manager accepts the incoming request from the browser, identifies it as a web request by finding the "GET" keyword at the start of the first incoming line, matches the URL to those that have been declared, executes the corresponding handler to serve the requested web page, and closes the connection.

Your Browser Accesses the Dynamic Webserver

You’ll use a web browser running on your PC to interact with the webserver running on the EtherSmart Wildcard.  As explained in the "Browser Notes" section above, popular browsers include Microsoft Internet Explorer, Netscape based browsers such as Firefox and Mozilla, and other high quality free browsers such as Opera.  All of these browsers work with the web demonstration program that comes with the EtherSmart Wildcard (see the demonstration program source code listings in the Appendices).

Additional considerations can limit the performance of some of these browsers if your application needs to serve out more complex web pages that require more than one TCP/IP connection per web page.  This can occur, for example, when mixed text and image data originating from the XPort are served out in a single web page. The Lantronix XPort hardware on the EtherSmart Wildcard supports only one active connection at a time.  However, the HTTP/1.1 standard (and consequently all browsers in their default configuration) expect the webserver to be able to host two simultaneous connections.  A default-configured browser will try to open a second connection when two or more content types (for example, HTML text and a JPEG image) are present in a single web page.  The second connection will typically be refused by the XPort hardware, causing an incomplete page load.  The solution is to configure the browser to expect only one connection at a time from the webserver. 

Appendix F explains how to reconfigure Internet Explorer to work with any web page that the EtherSmart can serve out.  For the best solution, though, consider downloading the free Opera browser from www.opera.com and using it for all your interactions with the EtherSmart Wildcard. It’s free, the download file is compact, and the install takes only a few seconds. Once Opera is installed, simply go to its Tools menu, and select:

Preferences->Advanced->Network->Max Connections Per Server

and enter 1 in the box.  Now you’re ready to use Opera with the EtherSmart Wildcard dynamic webserver.

Using the Image Converter to Create Web Resources

The most convenient way to create HTML or text web page strings as well as web images is to use the "Image Converter" program that is part of your Mosaic development environment.  This program converts one or more files, each containing a single string, image or other resource, into a named 32-bit xaddress and count that can be used by your application program. 

To define a set of text or text/HTML web page as resources that can be passed to the HTTP data output routines such as HTTP_Send_Buffer or HTTP_Send_2Buffers, simply place each string into a separate file with the file extension .str or .htm or .html.  The file name and extension (with the dot replaced by an underscore) will become a part of the symbol name.  All files to be converted should be in a single directory.  Make sure you use C-compatible filenames that include only alphanumeric and _ (underscore) characters, and do not start with a numeral. Invoke the Image Converter from your development environment.  In the Image Converter control panel, select the controller platform, and check the "Web files" box.  If you are programming in Forth, click the "Advanced" menu and select Forth as the programming language. 

If your web pages reference images that are to be served out by the EtherSmart itself, simply place files and the image files into the same directory.  Each image file must have a valid file extension; the allowed file types are png, gif, or jpg. Note that bitmap (bmp) files are not convertible as web resources by the Image Converter, as bitmap images are reserved for the GUI (Graphical User Interface) toolkit which is also supported by the Image Converter.

In the "Directory" area of the Image Converter control panel, select the directory that contains the specified file(s).  Then click on "Convert Files Now".  A pair of files named image_data.txt and image.headers.h will be created by the Image Converter.  The image_data.txt contains S-records and operating system commands that load the string image into flash memory on the controller.  Because flash memory is nonvolatile, you only need to download this file once to the controller; it need not be reloaded until the web pages or images are edited.  The image_headers.h file declares the xaddress and count (size) constants to be used by your application program. 

For example, let’s say that you have created a HTML "home page" and stored it in a file named home_body.html where the .html file extension indicates that the file contains HTML marked-up text.  The image_headers.h file declares the following two macros with the appropriate numeric xaddress and count values:

#define HOME_BODY_HTML_XADDR 0x700360

#define HOME_BODY_HTML_SIZE 0x98E

Of course, the actual numeric xaddress value depends on the controller platform that you have selected and the other resources that are converted.

You can then use these macros as parameters passed to the HTTP_Send_Buffer or HTTP_Send_2Buffers functions to specify the email body string. 

<< Previous | Next>>