Using the Embedded Web and Email Servers
Getting started with the EtherSmart WiFi Wildcard driver and its built-in internet protocols for TCP/IP and serial tunneling

The EtherSmart Wildcard™ and the WiFi Wildcard™ let you put your instrument online so it can communicate with other computers on a Local Area Network (LAN) or Wireless Local Area Network (WLAN). The 2" x 2.5" EtherSmart and WiFi products are members of the Wildcard family that connects to Mosaic controllers. You can plug one or more EtherSmart or WiFi Wildcards into any QCard, QScreen, QVGA Board, PDQ Board, PDQScreen, or Mosaic Handheld system to deliver the benefits of Ethernet or WiFi connectivity to your application.

With the EtherSmart or WiFi Wildcard, your application program can send emails to alert other computers on the network when significant events occur. You can browse into your instrument using a web browser running on an online PC to monitor the status of your instrumentation¹⁾. The instrument can implement Serial Tunneling by initiating or accepting TCP/IP Ethernet connections and exchanging binary and/or ASCII text data with other devices on the local area network.

The EtherSmart Wildcard uses an Ethernet hardware implementation called the XPort made by Lantronix (www.lantronix.com). Ethernet is a packet-based computer networking technology for Local Area Networks (LANs). It defines wiring and signaling for the physical layer, and frame formats and protocols. The wired version of Ethernet used by the EtherSmart Wildcard is known as IEEE 802.3. The Lantronix XPort combines a processor, flash and RAM memory, Ethernet network interface controller, and RJ45 jack into a single component. The Lantronix device can support one Ethernet connection at a time. A UART (Universal Asynchronous Receiver/Transmitter) chip on the EtherSmart board provides the interface between the parallel Wildcard bus and the Lantronix device’s serial data lines. Loss-less data integrity is ensured by the combination of built-in 64-byte data buffers in the UART plus hardware handshaking between the UART and the Lantronix device. The 3.3V supply that runs the Lantronix module can be shut down under program control while the interface is not in use to conserve power.

WiFi is short for wireless fidelity; some readers will recognize this as a play on the HiFi nickname that was originally given to high fidelity stereo audio systems. WiFi is a wireless communications standard that allows the same type of packets sent via Ethernet to be sent wirelessly. WiFi is a packet-based computer networking technology for Wireless Local Area Networks (WLANs). It defines signaling for the physical layer, and frame formats and protocols. The protocol used by the WiFi Wildcard is known as IEEE 802.11b/g.

The WiFi Wildcard uses a hardware implementation called the WiPort made by Lantronix. The XPort and the WiPort are controlled in a very similar way by the Mosaic controller, and this enables a common set of driver functions to control either the EtherSmart or WiFi Wildcards.

Most of the features described in this document apply to both the EtherSmart and WiFi Wildcards. A single software driver supports both of these Wildcards. Because the EtherSmart Wildcard was produced first and the names were left intact, the majority of these driver functions start with the Ether_ prefix. For example, the Ether_Send_Email function can be used to send an email via the EtherSmart Wildcard or the WiFi Wildcard.

In this document, we use the expression EtherSmart/WiFi Wildcard when no distinction needs to be made between the two types of Wildcards.

Software driver functions that start with WiFi_ apply only to the WiFi Wildcard, and cannot be used with the EtherSmart Wildcard. For example, the WiFi_Security function configures the wireless security options for the WiFi Wildcard; these wireless options are not implemented on the EtherSmart Wildcard.

Multiple EtherSmart and WiFi Wildcards can be installed on a Mosaic controller. The EtherSmart and WiFi Wildcards are distinguished from one another when each is initialized. A parallel set of initialization routines is provided, some starting with Ether_ to initialize the EtherSmart Wildcard, and others starting with WiFi_ to initialize the WiFi Wildcard. The initialization process marks the identity of the Wildcard. For example, the Ether_Setup function initializes the EtherSmart Wildcard using specified memory parameters, while the parallel function WiFi_Setup initializes the WiFi Wildcard.

Accessing the Internet and the World Wide Web (the Web for short) can quickly lead to an alphabet soup of protocol names. This section introduces some relevant terminology.

A LAN (Local Area Network) is a group of interconnected computers with a gateway computer that typically serves as a router to direct traffic on the LAN and between the LAN and other networks. Each computer on the LAN must have a unique 32-bit IP address (Internet Protocol address). An IP address is typically written as 4 decimal numbers (each between 0 and 255) separated by periods. For example:

    10.0.1.22

The EtherSmart/WiFi Wildcard can be assigned an IP address explicitly by calling some configuration functions, or it can get its IP address automatically via DHCP (Dynamic Host Configuration Protocol) running on the gateway computer. The assigned IP address can be associated with a computer name (so you don’t have to type numbers in your browser’s address bar if you don’t want to). The name can be assigned by asking your LAN system administrator to make an entry in the DNS (Domain Name Service) config file. Alternatively, you can create a local name on your PC by editing the hosts file; on a Windows XP machine, this file is found at:

    C:\Windows\system32\drivers\etc\hosts

The format of the communications among the computers on the LAN is defined by various protocols. The fundamental point-to-point connection protocol is called TCP/IP (Transmission Control Protocol/Internet Protocol).

Serial tunneling is a name for a simple exchange of serial data between two computers, typically using the raw TCP/IP protocol. Other protocols build on TCP/IP. For example, World Wide Web traffic uses HTTP (Hyper Text Transfer Protocol). Email uses SMTP (Simple Mail Transfer Protocol).

Web pages that are served out using HTTP are typically formatted using the HTML (Hyper Text Markup Language) format. Many good books and online references describe HTTP and HTML. 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 driver code described in this glossary enables you to code both static and dynamic web pages.

The embedded web server that runs when you execute the EtherSmart/WiFi library code responds to information requests from your browser. You can create a set of web pages, each with a specified name, or URL (Universal Resource Locator) and an associated handler function that serves out the static or dynamic web content. 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/WiFi 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 were filled out by the user in the browser window. The functions described in this glossary make it easy to extract data from these fields to direct the operation of the handlers. 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 web interface can be used to implement a remote front panel on instruments that contain a Graphical User Interface (GUI) and touchscreen. This feature allows a replica of the GUI screen to be presented in the browser window on a remote PC, and enables mouse clicks to mimic the action of touches on the instrument’s touchscreen. A set of functions in this driver and a complementary set of functions in the GUI toolkit coordinate this capability. The relevant GUI Toolkit functions are presented in a separate glossary section at the end of this document.

All WiFi nodes that share the same SSID (Service Set IDentifier) can associate with one another, and they can communicate if their security settings and security keys are compatible. The default SSID of the WiFi Wildcard is

    WIFI_WILDCARD

SSID’s are case sensitive.

A WLAN (Wireless Local Area Network) is typically operated in infrastructure mode meaning that a wireless access point (AP) coordinates messages among various WiFi nodes. A device that is not in infrastructure mode is in ad hoc mode, meaning that it is configured for one-to-one communications with another WiFi device that is in ad hoc mode and that has the same SSID and security settings. WiFi devices communicate on channels within the 2.4GHz band. Channel numbers range from 1 to 13, with channels 1 to 11 allowed in the US and Canada. The channel numbers are typically automatically negotiated by the WiFi nodes, but the WiFi Wildcard allows you to specify the default channel when in ad hoc mode (the default is channel 11).

Because wireless signals can be intercepted remotely, securing the data traffic using encryption is wise. The original WiFi security suite is called WEP, or Wired Equivalent Privacy. WEP is widely supported, but it is not a strong form of encryption and can be broken. The two key strengths of WEP are known as WEP64 and WEP128. WEP64 uses a 40-bit key concatenated with a 24-bit initialization vector, and WEP128 uses a 104-bit key concatenated with a 24-bit initialization vector.

An improved WiFi security suite is WPA (WiFi Protected Access). An even newer security suite associated with the 802.11i protocol is known as WPA2, and its associated encryption scheme is known as CCMP.

The encryption key for WEP and WPA can be entered as a hexadecimal value, or as a passphrase. A passphrase is an 8 to 63 byte printable ASCII string that is processed by a hash function to create one or more numeric keys. If a passphrase is used, the WiFi Wildcard always uses key index 0 generated by the passphrase hash function.

Each security suite (such as WEP or WPA) can be configured in a number of ways. Configuration options include pairwise encryption method, group encryption method, and authentication using Pre-Shared Keys (PSK). See the WiFi Wildcard Configuration section for a description of these options.

Note that both the EtherSmart Wildcard and the WiFi Wildcard offer a completely independent means of AES (Advanced Encryption Standard) data encryption that is configured by the Ether_Encryption function; see its glossary entry for details.

The companion to this document is the EtherSmart/WiFi Wildcard Glossary which describes each of the driver functions in detail. Browsing the Categorized List of EtherSmart/WiFi Library Functions in the Glossary will yield a good overview of the capabilities of the driver software.

The EtherSmart and WiFi Wildcards implement the following protocols to establish and manage communications:

• TCP/IP (Transmission Control Protocol/Internet Protocol) enables reliable data exchange between the EtherSmart/WiFi Wildcard and a remote host with no lost data. Simple data exchanges with other Ethernet or WiFi devices use the basic TCP/IP protocol to establish a connection and transfer data. TCP/IP is the basis of data exchange protocols including Rlogin and Telnet which can be used to download code and interactively communicate with the operating system on Mosaic controllers via a simple network terminal such as Putty. This capability is explained in the section titled Code Downloads and Interactive Communications via TCP/IP. TCP/IP is also the foundation of higher level services including HTTP and SMTP.
• HTTP (HyperText Transfer Protocol) is implemented to deliver a dynamic webserver under the control of your application program. This webserver is available at the standard TCP/IP port 80 used by web browsers. 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 (known as a URL, or Uniform Resource Locator), the EtherSmart/WiFi webserver automatically executes the handler which performs any required actions and transmits the web page to the browser. As described in a later section, versatile functions make it easy to use HTML forms to request particular data or stimulate particular actions from the Mosaic controller. An additional configuration webserver is built into the Lantronix device for low-level configuration of the Lantronix firmware, and is available at TCP/IP port 8000.
• SMTP (Simple Mail Transfer Protocol) is implemented to enable the EtherSmart/WiFi Wildcard to send outgoing email to a mail server on the LAN. The recipient, destination IP (Internet Protocol) address, subject and email contents can be dynamically controlled by the application program. Outgoing emails can be used by your instrument to send alerts or status updates.
• ICMP (Internet Control Message Protocol) allows the EtherSmart/WiFi Wildcard to send and return ping packets. These can be useful for network diagnostics. This low-level protocol is implemented by the Lantronix firmware.
• ARP (Address Resolution Protocol) establishes the correspondence between the 48-bit Ethernet Media Access Control (MAC) address which is visible on the Lantronix label, and the assignable 32-bit IP (Internet Protocol) address that identifies the parties on a network. This low-level protocol is implemented by the Lantronix firmware.
• DHCP (Dynamic Host Configuration Protocol) allows the gateway computer (or Wireless Access Point) on a Local Area Network to automatically assign an IP address to the EtherSmart/WiFi Wildcard as soon as it is plugged into the network. As described in a later section, an IP address can also be explicitly assigned using a web configuration screen, a telnet configuration session, or by calling an easy-to-use driver function from the application program. The low-level DHCP protocol is implemented by the Lantronix firmware.

The following table summarizes the capabilities of the EtherSmart and WiFi Wildcards:

See also → Using Embedded Web and Email Servers