Link here

EtherSmart/WiFi Function Summary

This document lists and summarizes the driver functions that control the EtherSmart and WiFi Wildcards. Their detailed definitions are found in the EtherSmart/WiFi Glossary.

The EtherSmart Wildcard provides wired Ethernet connectivity, and the WiFi Wildcard provides wireless 802.11b/g connectivity for your instrumentation and automation applications. These Wildcards are implemented using similar hardware that enables a common software driver to support both. For each function, a prototype is provided to illustrate the function input and output parameters in both C and Forth formats, and a glossary entry describes the function’s actions. These driver routines are available as pre-compiled libraries for the controller platforms from Mosaic Industries, for both C and Forth programmers. This document contains:

  • An introduction that presents an overview of the glossary entries and defines the terms used in this document; and,
  • A categorized list of all EtherSmart/WiFi Wildcard library functions.

Consult the EtherSmart/WiFi Glossary for detailed definitions for the functions listed here, and a brief glossary of GUI Toolkit functions that help to implement a web-based remote front panel.


Introduction to the EtherSmart/WiFi Wildcard glossary

The form of the glossary definitions

Each entry in the the EtherSmart/WiFi Glossary includes a C prototype declaration, a Forth prototype declaration, and a detailed definition of what the function does. For constants, the prototype simply states the name of the routine. An example of a typical function declaration is as follows:

C: uint Ether_Setup ( xaddr xbuffer_area_base, addr mailbox_base_addr, int modulenum )
4th: Ether_Setup ( xbuffer_area_base\ mailbox_base_addr \module -- numbytes )

This function initializes an EtherSmart Wildcard; see WiFi_Setuup to initialize a WiFi Wildcard. Ether_Setup is a high level initialization routine that calls Ether_Init with default buffer locations and sizes starting at the specified xbuffer_area_base, and returns the number of bytes allocated there. Also passes to Ether_Init the addresses of three mailboxes in common RAM starting at mailbox_base (a 16-bit address). The mailboxes are ether_command at mailbox_base_addr, ether_response at mailbox_base_addr+4, and …

The presence of both C and Forth prototypes conveys a lot of information. The C prototype explicitly states the type of each input and output parameter. The Forth prototype provides a descriptive name for the output parameter (a detail that is missing from the C prototype).

Let’s look at the sample C prototype first. The leading uint tells us that a 16-bit unsigned integer is returned. The input parameter list starts with xaddr xbuffer which tells us that the first parameter is a 32-bit eXtended address (xaddress) as explained in the next section. Next, addr mailbox_base_addr tells us that the second parameter is a 16-bit address. The int modulenum parameter tells us that the final input is an integer specifying the Wildcard module number (corresponding to the hardware jumper address, as explained below).

The Forth prototype includes a standard stack picture in parentheses, with the input parameters to the left of the -- and the output parameter(s) to the right. A parameter with a leading x is a 32-bit extended address, so we know that the first parameter in the example is a 32-bit xaddress that specifies a buffer. The \ character in the stack picture is read as under; this character separates the stack items. The next input parameter is a 16-bit address in common memory. The final input parameter is the module number, specifying the Wildcard module number (corresponding to the hardware jumper address, as explained below). Each of the last 2 input parameters and the output parameter have the default 16-bit integer size: all Forth parameters are 16 bits unless otherwise indicated, as shown in the Stack Symbols table below.

Note that C is case-sensitive, while Forth is case-insensitive. For simplicity and clarity, both C and Forth versions of the functions in this glossary are spelled identically using the same case.


C type abbreviations used in function declarations

Standard C type specifiers such as char, int, and long are used in the glossary declarations. In addition, we use four convenient typedefs that are defined in the TYPES.h header file:

typedef unsigned char uchar;
typedef unsigned int uint;
typedef unsigned long ulong;
typedef unsigned long xaddr;

The meanings of the first three typedefs are obvious; they are abbreviations for unsigned types. The xaddr typedef means "extended address", and is used when a 32-bit address parameter is passed. The least significant 16-bits of the xaddress specify the standard 16-bit machine address, and the most significant 16-bits specify the page.

Any other required C typedefs are described in the text of the relevant glossary entry.


Forth stack symbols

The following table describes the standard symbols used to represent items placed on the Forth data stack.

Stack Symbol Size on Stack Size in Memory Valid Data Size
addr 1 cell 2 bytes 2 bytes 16-bit address. Range: 0 to 65,535 (0-0xFFFF).
page 1 cell 2 bytes 1 byte Page. Range: 0 to 0x3F on PDQ platforms, 0 to 0xFF on earlier platforms.
xaddr 2 cells 4 bytes 3 bytes 32-bit extended address comprising an address and page: addr\page.
xmailbox 2 cells 4 bytes 3 bytes Extended address of a mailbox variable.
xcfa 2 cells 4 bytes 3 bytes Code field xaddr (execution address, corresponding to a 32-bit function pointer in C)
flag 1 cell 2 bytes 2 bytes Boolean flag, 0 indicates false. Non-zero indicates true.
true 1 cell 2 bytes 2 bytes Boolean flag, = -1 = 0xFFFF.
false 1 cell 2 bytes 2 bytes Boolean flag, = 0
char 1 cell 1 byte 1 byte ASCII character.
count 1 cell 2 bytes 2 bytes A string count. While standard Forth strings are restricted to 1-byte counts, this library employs "long strings" and "long buffers" with 2-byte counts, supporting up to 65,533 bytes in the string.
cnt 1 cell 2 bytes 2 bytes Synonym for count
bufsize 1 cell 2 bytes 2 bytes A buffer size that constrains the maximum number of characters that can be stored in the buffer. 0- 65,535.
xstring 2 cells 4 bytes 3 bytes Extended address of the first data-containing byte of a string.
xbuffer 2 cells 4 bytes 3 bytes Extended address of a buffer.
xbuffer 2 cells 4 bytes 3 bytes Extended address of a buffer.
xlbuffer 2 cells 4 bytes 3 bytes Extended address of a "long buffer" comprising a 2-byte count followed by the buffer data.
n 1 cell 2 bytes 2 bytes Signed 16-bit (single) integer. Range: -32,768 to 32,767.
u 1 cell 2 bytes 2 bytes Unsigned 16-bit (single) integer range: 0 to 65,535.
d 2 cells 4 bytes 4 bytes 32-bit integer. Used to represent encryption keys.
task_base 1 cell 2 bytes 2 bytes 16-bit address. Range: 0 to 65,535 (0-0xFFFF), the base address in common RAM of a task area (typically 1 Kbyte long).
timeout_msec 1 cell 2 bytes 2 bytes Unsigned 16-bit (single) integer range: 0 to 65,535, representing the number of milliseconds before a timeout for the operation.
modulenum 1 cell 2 bytes 1 byte Integer that specifies the module number (hardware address) of a Wildcard I/O module. Range: 0 to 7. The modulenum must correspond to the 2-bit hardware jumper setting of the target Wildcard combined with its Wildcard bus position (0 or 1) as the top bit of the 3-bit code.

Selecting the module address

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

The Module 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 modules. Module Port 0 provides access to modules 0-3 while Module Port 1 provides access to modules 4-7. Two modules on the same port cannot have the same address (jumper settings). Consult the EtherSmart/WiFi Wildcard User Guide for more information.


Ethernet and WiFi

The EtherSmart Wildcard uses an Ethernet hardware implementation called the "XPort" made by Lantronix. "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.

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 functions described in this document can operate on both the EtherSmart and WiFi Wildcards. Because the EtherSmart Wildcard was produced first and the names were left intact, the majority of these 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.

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. In fact, WiFi_Setup simply calls Ether_Setup, and then invokes WiFi_Module to declare the specified module as a WiFi Wildcard.

Ethernet/WiFi Function Names

Except for initialization functions as noted in the glossary descriptions, functions that start with "Ether_", "HTTP_" or "HTTP_GUI" can be used to control both EtherSmart and WiFi Wildcards. Functions that start with "WiFi_" apply only to the WiFi Wildcard.

EtherSmart and WiFi Wildcards are distinguished at initialization time. 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. See the "Initialization" section in the categorized function list below to view a list of initialization functions for EtherSmart and WiFi Wildcards.

The WiFi Wildcard driver was coded as an extension of the driver for the EtherSmart Wildcard, and the original function names were left intact. Thus, it is best to interpret the words "Ethernet" and the prefix "Ether" as referring to the TCP/IP communications link which can be implemented via Ethernet or WiFi.


Internet terminology

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.


Internet addresses

A LAN (Local Area Network) 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 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,


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 to the EtherSmart/WiFi Wildcard, and you type into your browser’s address bar,

then the URL as defined in this document is,


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.)


Remote front panels

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.


WiFi terminology

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 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 glossary entry for the WiFi_Security function 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.


Function naming conventions

Functions that provide basic Ethernet functionality, including configuration, 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 identifies 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 the "Initialization" section in the categorized function list 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.


Browser notes

The Lantronix hardware on the EtherSmart/WiFi Wildcard supports only one active connection at a time. However, the HTTP/1.1 standard (and consequently all browsers1) 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, text/html and image/bmp) are present in a single webpage. The second connection will typically be refused by the Lantronix hardware, causing an incomplete page load. The solution is to configure the browser to expect only one connection from the webserver.

We highly recommend the use of the free Opera web browser available for download at Simply go to and select "Download Opera". The download and install are quick, and the program is compact. And, it’s very easy to configure for the single-connection EtherSmart/WiFi Wildcard web servers. 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 the Opera web browser with the EtherSmart/WiFi Wildcard dynamic webserver.


Categorized list of EtherSmart/WiFi library functions

A summary of the firmware functions available to you, the developer.


Configuration and diagnostics

(see also Initialization and WiFi configuration)

Ether_DHCP_Name Ether_Remote_Port_Ptr
Ether_Encryption Ether_Set_Inbuf
Ether_Gateway Ether_Set_Outbuf
Ether_Gateway_IP_Ptr Ether_Shutdown
Ether_Info Ether_TCP_Control
Ether_Internal_Webserver_Port Ether_Telnet_Password
Ether_IP_Info_Report Ether_XPort_Defaults
Ether_IP_Info_Request Ether_XPort_Update
Ether_Netmask_Ptr HTTP_Set_Inbuf
Ether_Ping_Report HTTP_Set_Outbuf

GUI remote front panel

(These GUI toolkit functions for building a remote front panel are summarized in a separate section in the EtherSmart/WiFi Glossary)

Globalize_TVars Screen_To_Image
Graphic_To_Image Simulate_Touch
Has_Screen_Changed Simulated_Touch_To_Image

HTTP webserver

Ether_Command_Manager HTTP_Outbuf
Ether_Connection_Manager HTTP_Outbuf_Cat
Ether_Error HTTP_Outbufsize
Ether_Service_Loop HTTP_Parse_URL
ether_service_module HTTP_Plus_To_Space
HTTP_Add_Handler HTTP_Put_Content_Type
HTTP_Autoserve_Ptr HTTP_Send_2Buffers
HTTP_Default_Handler HTTP_Send_LBuffer
HTTP_Default_Handler_Ptr HTTP_Server
HTTP_Enable_Ptr HTTP_Set_Inbuf
HTTP_Fieldname_Count HTTP_Set_Outbuf
HTTP_Fieldname_Ptr HTTP_Status_Ptr
HTTP_Inbuf HTTP_URL_Base_Count
HTTP_Inbufsize HTTP_URL_Full_Count
HTTP_Index_Ptr HTTP_Value_Count
HTTP_Is_Autoserve_Array HTTP_Value_Ptr

HTTP/GUI webserver for remote front panel

(see also HTTP webserver)

Ether_Check_GUI HTTP_GUI_Send_Buffer
HTTP_Add_GUI_Handler HTTP_GUI_Send_LBuffer
HTTP_GUI_Send_2Buffers HTTP_Imagemap


(see also Configuration and diagnostics)

Ether_Info_Init WiFi_Check
Ether_Init WiFi_Info_Init
Ether_Setup WiFi_Init
Ether_Setup_Default WiFi_Module
Ether_Task_Setup WiFi_Setup
Ether_C_Task_Setup WiFi_Setup_Default
  Functions call others in this order, wherer A→ B means A calls B:
    Ether_Task_Setup →  Ether_Setup_Default →  Ether_Setup →  Ether_Init →  Ether_Info_Init
    Use Ether_C_Task_Setup instead of Ether_Task_Setup in PDQ V6.xx C.
    WiFi_Task_Setup →  WiFi_Setup_Default →  WiFi_Setup →  WiFi_Init →  WiFi_Info_Init
    Use WIFI_C_TASK_SETUP instead of WiFi_Task_Setup in PDQ V6.xx C.



Revectored serial via ethernet

E_ASCII_Key Ether_Emit
E_Ask_Key Ether_Key
E_Emit Ether_Monitor
E_Key ether_revector_module
Ether_ASCII_Key Ether_Serial_Revector
Ether_Ask_Emit XTERM/38400SSP (Forth only)

Serial tunneling and email

Ether_Add_Chars Ether_Get_Line
Ether_Add_Data Ether_Inbuf
Ether_Add_Line Ether_Inbufsize
Ether_Await_Response ETHER_MIN_BUFFER_SIZE
Ether_Check_Response Ether_Outbuf_Cat
Ether_Command_Manager Ether_Outbufsize
Ether_Connect Ether_Passive_Non_Web_Connection
Ether_Connect_Status Ether_Ready_For_Command
Ether_Connection_Manager Ether_Send_2Buffers
Ether_Disconnect Ether_Send_Buffer
Ether_Disconnect_During_Send Ether_Send_Email
Ether_Disconnect_Flush Ether_Send_LBuffer
Ether_Error Ether_Service_Loop
Ether_Error_Clear ether_service_module
Ether_Flush Ether_Set_Inbuf
Ether_Flush_NBytes Ether_Set_Outbuf
Ether_Get_Chars Ether_Tunnel_Enable_Ptr

String primitives

Cat LCOUNT (Forth only)
Ether_Outbuf_Cat LPARSE (Forth only)

WiFi configuration

(see also Initialization)


See also →
WiFi Wildcard
Ethersmart Wildcard

Using any standard web browser, Microsoft's Internet Explorer, Mozilla's Firefox, Apple's Safari, Google's Chrome, or Opera, on any device, including laptops, desktops, netbooks, tablets, or smart phones.
This page is about: C Programming Functions for Embedded Email, Embedded Web Servers, Serial Tunneling – EtherSmart/WiFi Function Summary lists and summarizes the driver functions that control the EtherSmart and WiFi Wildcards.