This document describes the capabilities of the EtherSmart and WiFi Wildcards, tells how to configure their hardware, presents a description of the unified driver software, describes a demonstration program, and includes hardware schematics.

A separate EtherSmart/WiFi Glossary provides a detailed description of each device driver function

The following figure illustrates the hardware on the WiFi Wildcard:

The large component is the WiPort Wifi device server from Lantronix, providing a WiFi co-processor and network interface built into a shielded housing with an antenna connector. A WiFi antenna is available from Mosaic; it can be mounted on the Wildcard in one of two ways. In Figure 1 2, the antenna connector from the WiPort is bolted through a mounting hole on the Wildcard, enabling the antenna to be screwed onto the board from the top. The antenna has a hinge that allows it to stand straight up or to be oriented parallel to the Wildcard. The alternative procedure is to mount a clamp (supplied by Mosaic with the WiFi antenna) onto the Wildcard, and use this to affix the antenna to the board. This allows more degrees of freedom in antenna orientation, and also eliminates the depth requirement below the Wildcard for the WiPort’s antenna connection. For those who need a remote mounted antenna, a 2 foot extension cable is available from Mosaic.

The WiPort antenna connection terminates in a "Reverse Polarity SMA" (RPSMA) female connector. This is a bit confusing, as the "reverse polarity" designation means that a connector with a center pin (normally considered male) is called female. The WiFi antenna has an RPSMA male connector (no center pin). The optional extension cable has one RPSMA male end, and one RPSMA female end. The non-removable antenna cable on the WiPort module is about 4 inches in length.

A small linear regulator on the Wildcard converts the 5 volt power on the Wildcard bus to the 3.3V supply required by the WiPort. The WiPort draws about 300 mA of current. The regulator can be shut down under program control while the WiPort is not in use to save 1.5 Watts of power.

The WiPort exchanges data via a serial interface, while the Wildcard bus is a parallel interface. A UART (Universal Asynchronous Receiver/Transmitter) chip on the WiFi Wildcard board implements the conversion between the parallel Wildcard bus and the WiPort’s serial data lines. The UART contains two 64-byte FIFO (First In/First Out) buffers, one for incoming data, and one for outgoing data. The WiPort and the UART "handshake" with one another using "Ready to Send" (RTS) and "Clear to Send" (CTS) hardware lines. This scheme ensures that no data is lost due to buffer overflow in the UART or the WiPort: the sending device stops transmitting until the receiving device indicates that there is room in its buffer for more data.

The 24-pin Wildcard bus header interfaces to the host processor (QCard, QScreen, QVGA Board, Handheld, or PDQ series controller). To connect the EtherSmart/WiFi Wildcard to the Wildcard bus on the controller board, follow these simple steps.

With the power off, connect the female 24-pin side of the stacking go-through Wildcard bus header on the bottom of the EtherSmart/WiFi Wildcard to Module Port 0 or Module Port 1 on the controller (or its mating PowerDock). The corner mounting holes on the Wildcard must line up with the standoffs on the mating board. The module ports are labeled on the silkscreen of the controller board. Note that the EtherSmart/WiFi Wildcard headers are configured to allow direct stacking onto the controller board, even if other Wildcards are also installed. Do not use ribbon cables to connect the Wildcard to the bus.

Once you have connected the EtherSmart/WiFi Wildcard to the Wildcard bus, you must set the address of the module using jumper shunts across J1 and J2.

The Wildcard Select Jumpers, labeled J1 and J2, select a 2-bit code that sets a unique address on the module port of the controller board. Each module port on the controller accommodates up to 4 Wildcards. Wildcard Port 0 provides access to Wildcards 0-3 while Wildcard Port 1 provides access to Wildcards 4-7. Two Wildcards on the same port cannot have the same address (jumper settings). The following table shows the possible jumper settings and the corresponding addresses.

The Wildcard address is called the "module number" or simply "modulenum" in the input parameter lists of the software driver functions. Most of the driver functions require that the modulenum be passed as a parameter. Make sure that the jumper settings on the Wildcard hardware match the modulenum parameter that is specified in the application software.

Note that module number 0 is reserved on the QScreen and Mosaic Handheld controllers.

Accessing the Internet and the World Wide Web ("the Web" for short) can quickly lead to a proliferation of protocol names and acronyms. This section reviews some relevant terminology.

The Ethernet protocol defines a packet-based computer networking technology for Local Area Networks (LANs) that is broadly supported by desktop PCs and a variety of computer-based instruments. The Ethernet standard 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.

A LAN is a group of interconnected computers with a "gateway" computer that 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, the following is a valid IP address:

    10.0.1.22

The IP addresses 0.0.0.0 and 255.255.255.255 are reserved and should never be assigned to a device on a LAN. The EtherSmart Wildcard can be assigned an IP address by calling some configuration functions as explained in a later section, 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) configuration 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 "gateway" is the router computer on the LAN. The gateway routes to a subset of IP addresses specified by the zeros in the LAN’s "netmask". The number of "subnet bits" is equal to the number of bits specified as zeros in the LAN’s netmask. For example, setting the number of subnet bits to 8 is equivalent to specifying a "netmask" of 255.255.255.0, meaning that a maximum of 255 IP addresses can be represented on the LAN; this is a "type C" LAN. Specifying 16 subnet bits is equivalent to a netmask of 255.255.0.0, corresponding to a "type B" LAN. Specifying 24 subnet bits is equivalent to a netmask of 255.0.0.0, corresponding to a "type A" LAN.

The IP addresses on the LAN are typically accessible only to other computers on the same LAN. The gateway or router is the only computer on the LAN that is accessible to one or more networks in "the outside world". The gateway typically has one IP address for use on the LAN, and a different one that allow it to be accessed by other networks. Sometimes the external IP address of the gateway changes from session to session; this is how most "DSL" network connections function. To be able to connect to the EtherSmart or other computers on a specified LAN from an arbitrary computer on the Internet, you must know the externally available IP address of the LAN’s gateway or router device. Talk to your system administrator about how to accomplish this if you need to access the EtherSmart/WiFi Wildcard from computers that are not part of the Wildcard’s Local Area Network.

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). TCP is a connection-based protocol that ensures that no data is lost as long as the connection remains open. If for some reason a packet sent by one computer does not arrive at the communicating partner, the TCP protocol re-transmits the packet until it is received intact.

When one host (computer, instrument, etc.) wants to communicate with a remote host via TCP, it requests a connection by sending a "SYN" (synchronization) packet to the remote’s IP address. The remote accepts the connection by responding with a [SYN, ACK] acknowledge packet directed to the IP address of the requester, and the requester completes the process with an ACK acknowledge packet to establish the connection. This handshaking is performed by the Lantronix firmware and requires no intervention on the part of the programmer or the application. The application program simply uses a high level function such as Ether_Connect to open a connection as described in a later section, and then calls other high level functions to send and receive data.

For experts who want to view the raw TCP/IP packet exchange on the LAN, download the Ethereal network analyzer software that is available at www.ethereal.com. This free PC software can be very useful when debugging TCP/IP network software for web-enable instrumentation applications.

"Serial tunneling" is a common name for the exchange of serial data between two computers, typically using the TCP/IP protocol that is common to Ethernet and WiFi. In network terminology, a "tunnel" is a path that passes data without the sender and receiver having to know or care about the details of the transfer mechanism. "Serial tunneling" was originally coined as a term to describe a method for allowing instruments and computers that were designed to communicate via RS-232 to now communicate via TCP/IP. Its meaning has broadened to encompass a variety of serial data exchanges between instruments via Ethernet and WiFi.

The SMTP (Simple Mail Transfer Protocol) email protocol builds on a TCP/IP connection. The EtherSmart/WiFi Wildcard can send outgoing email using SMTP. A single high level function named Ether_Send_Email handles all of the details for you. You pass to the function the gateway IP address on your LAN, and strings that specify the sender email address, recipient email address, and the email body. The Wildcard’s driver software and the mail server running on the gateway computer cooperate to process the email. Sending email is explained in detail in a later section.

World wide web traffic uses "HTTP" (HyperText Transfer Protocol) which builds on a TCP/IP connection. Web pages that are served out using HTTP are typically formatted using the "HTML" (HyperText 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 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 Wildcard’s library 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.

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 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 web interface can be used to implement a "remote front panel" on instruments that contain a Graphical User Interface (GUI) and touchscreen such as the QVGA Controller or PDQScreen. This feature allows a pixel-by-pixel replica of the GUI screen to be presented in the browser window on a remote PC, and 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. This feature is described in a later section.

Functions that provide TCP/IP functionality, serial tunneling (point to point TCP/IP communications), and email start with the Ether_ prefix; these functions can be used to control both EtherSmart and WiFi Wildcards.

As explained above, the EtherSmart and WiFi Wildcards share the same code base, but are distinguished at initialization time. The low level function WiFi_Module marks a specified module as a WiFi Wildcard. For each of the EtherSmart initialization functions that start with the Ether_ prefix, a parallel initialization function that starts with the WiFi_ prefix is available. The latter functions include a call to the WiFi_Module function. See Table 1 3 below for a list of initialization functions for EtherSmart and WiFi Wildcards, and consult the initialization function glossary entries for details.

Functions that implement world-wide-web functionality start with the HTTP_ prefix. The HTTP protocol underlies the web data exchanges.

Functions that implement the web "remote front panel" feature for GUI-based instruments start with the HTTP_GUI prefix.

See also → Installing and Using Your WiFi Wildcard