Using the Example Application

This section summarizes the capabilities of the EtherSmart/WiFi driver functions. For a complete listing of all of the driver functions, see the "Categorized List of EtherSmart/WiFi Library Functions" in the Glossary. The glossary contains complete descriptions of each function. In this section we review the functions to put them into context.

The driver code contains a suite of functions that make it easy to:

• Initialize and configure the EtherSmart/WiFi Wildcard,
• Set up serial tunneling connections between two Ethernet- or WiFi -enabled devices,
• Send emails, and,
• Setup a dynamic webserver for monitoring and control of instrumentation from any web browser¹⁾.

After a summary of the data structures used by the driver and an introduction to the demonstration program, each of these capabilities is discussed in turn.

The pre-coded driver contains a suite of functions that make it easy to initialize and configure the EtherSmart and WiFi Wildcards. The relevant functions are summarized in the EtherSmart/WiFi Wildcard Glossary document. For a list of functions, consult the "Configuration and Diagnostics", "Initialization", and "WiFi Configuration" tables in the "Categorized List of EtherSmart/WiFi Library Functions" in the Glossary. The glossary contains complete descriptions of each function. In this section we review the functions to put them into context.

The EtherSmart and WiFi Wildcards share the same code base, but are distinguished at initialization time by the functions listed in Table 1 3. 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 to initialize the WiFi Wildcard. The latter functions include a call to the WiFi_Module function. The last row in Table 1 3 summarizes the calling order of the initialization functions. Consult the function glossary entries for detailed descriptions of each function.

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 the low level WiFi_Module utility function to declare the specified module as a WiFi Wildcard.

For the EtherSmart Wildcard, the high level initialization function in the pre-compiled device driver library is Ether_Setup_Default accepts the modulenum as its input parameter. After this routine runs, it remains for the demo program to declare, build, and activate a task running the Ether_Service_Loop function to service the Ethernet connection. In the listing below, the TASK declaration allocates a task area in common memory. (For the definition of the TASK structure, see the user.h file in the Mosaic include directory of your C compiler distribution.) Listing 1 1 shows an example of a function called Ether_Task_Setup_Default from the demo program that invokes Ether_Setup_Default, passing it the E_MODULENUM Wildcard address, then invoking BUILD_C_TASK and ACTIVATE to build and activate the service task.

Listing 1-1 Using EtherTaskSetup_Default() from the Demo Program to Initialize the EtherSmart Wildcard Services.

// ****** SETUP ETHERNET TASK TO RUN ETHERSMART WEB AND TUNNELING SERVICES ******
 
TASK ether_control_task;  // allocate task area
 
_Q void Ether_Task_Setup_Default( void )
// performs full initialization of the Ether_Info struct and mailboxes for the
// modulenum specified by the E_MODULENUM constant, and
// builds and activates an ethernet control task to service the EtherSmart Wildcard
// Note: GCC for V6.xx platforms requires that we explicitly
// call BUILD_C_TASK as shown here
// This is why we do not use the driver's ETHER_Task_Setup routine
// here (see its glossary for details).
{
 // NEXT_TASK = TASKBASE;   // empties task loop; comment out if other tasks allowed
    Ether_Setup_Default(E_MODULENUM); // allocate&init ~3Kbyte ram buffers    BUILD_C_TASK(0, 0, &ether_control_task );  // build the service task
    ACTIVATE(Ether_Service_Loop, &ether_control_task ); // activate the service routine
}

Ether_Setup_Default is a high level routine that performs a full initialization of the Ether_Info structure and mailboxes. This function calls a chain of lower level initialization functions, each of which is available for use if the default high level routines do not meet the needs of your application. Ether_Setup_Default specifies a default buffer area base (0x043000 for V4.xx platforms, and 0x178000 for V6.xx platforms) and calls Ether_Setup. About 3 Kbytes is allocated in this buffer area; see the glossary entry of Ether_Setup for a detailed description of operation. Ether_Setup calls Ether_Init with a set of default buffer specifications and sizes. Ether_Init calls the lowest level initialization routine Ether_Info_Init. Most users of the EtherSmart Wildcard will call only the highest level Ether_Setup_Default routine, or its caller in the demo program, Ether_Task_Setup_Default. The lower level initialization functions listed in this paragraph allow "power users" to tailor the memory map and/or buffer sizes to suit specialized needs.

Note that the Ether_Task_Setup function which allocates and builds a task running the service routine is not recommended for V6.xx/PDQ platforms programmed in GCC, so it is not described here. The initialization shown in Listing 1 1 works for all platforms. Consult the EtherSmart/WiFi Glossary for more details about the EtherSmart Wildcard initialization functions.

For the WiFi Wildcard, the high level initialization function in the pre-compiled device driver library is WiFi_Setup_Default accepts the modulenum as its input parameter. After this routine runs, it remains for the demo program to declare, build, and activate a task running the Ether_Service_Loop function to service the WiFi connection. In the listing below, the TASK declaration allocates a task area in common memory. (For the definition of the TASK structure, see the user.h file in the Mosaic include directory of your C compiler distribution.) Listing 1 2 shows an example of a function called WiFi_Task_Setup_Default from the demo program that invokes WiFi_Setup_Default, passing it the E_MODULENUM Wildcard address, then invoking BUILD_C_TASK and ACTIVATE to build and activate the service task.

Listing 1-2 Using WiFi_TaskSetup_Default() from the Demo Program to Initialize the WiFi Wildcard Services.

// ******* SETUP ETHERNET TASK TO RUN WIFI WEB AND TUNNELING SERVICES **********
 
TASK ether_control_task;  // allocate the task area for web instrumentation
 
_Q void WiFi_Task_Setup_Default( void )
// same as Ether_Task_Setup_Default, but marks Wildcard as WiFi
// performs full initialization of the Ether_Info struct and mailboxes for the
// modulenum specified by the E_MODULENUM constant, and
// builds and activates an ethernet control task to service the WiFi Wildcard
// Note: GCC for V6.xx platforms requires that we explicitly
// call BUILD_C_TASK as shown here
// This is why we do not use the driver's WiFi_Task_Setup routine
// here (see glossary for details).
{
 // NEXT_TASK = TASKBASE; // empties task loop; comment out if other tasks allowed
    WiFi_Setup_Default(E_MODULENUM); // allocate&init ~3Kbyte ram buffers
    BUILD_C_TASK(0, 0, &ether_control_task );  // build the service task
    ACTIVATE(Ether_Service_Loop, &ether_control_task );    // activate the service routine
}

WiFi_Setup_Default is a high level routine that performs a full initialization of the Ether_Info structure and mailboxes. This function calls a chain of lower level initialization functions, each of which is available for use if the default high level routines do not meet the needs of your application. WiFi_Setup_Default specifies a default buffer area base (0x043000 for V4.xx platforms, and 0x178000 for V6.xx platforms) and calls WiFi_Setup. About 3 Kbytes is allocated in this buffer area; see the glossary entry of WiFi_Setup for a detailed description of operation. WiFi_Setup calls WiFi_Init with a set of default buffer specifications and sizes. WiFi_Init calls the lowest level initialization routine WiFi_Info_Init. Most users of the WiFi Wildcard will call only the highest level WiFi_Setup_Default routine, or its caller in the demo program, WiFi_Task_Setup_Default. The lower level initialization functions listed in this paragraph allow "power users" to tailor the memory map and/or buffer sizes to suit specialized needs.

Note that the WiFi_Task_Setup function which allocates and builds a task running the service routine is not recommended for V6.xx/PDQ platforms programmed in GCC, so it is not described here. The initialization shown in Listing 1 2 works for all platforms. Consult the EtherSmart/WiFi Glossary for more details about the EtherSmart Wildcard initialization functions.

The low level Ethernet interface on the EtherSmart Wildcard is provided by the Lantronix XPort, and the low level WiFi interface on the WiFi Wildcard is provided by the Lantronix WiPort. Each of these modular devices combines a processor, flash and RAM memory, network interface controller, and physical interface into a single component. Each Lantronix device can support one Ethernet connection at a time, and limits incoming connections to a single TCP/IP port number that must be specified in advance. Changing the configuration parameters of the Lantronix device is time consuming (approximately 13 seconds) and modifies flash in the device.

The two fundamental functions that configure the Lantronix device on the EtherSmart or WiFi Wildcard are called Ether_XPort_Defaults and Ether_XPort_Update. Despite the names, each function works on both the EtherSmart Wildcard and the WiFi Wildcard.

Ether_XPort_Defaults sets the recommended default parameters on the EtherSmart or WiFi Wildcard to be the same as those set at the Mosaic factory. Note that these default values are not the same as those set by the Lantronix configuration webserver’s "Set Defaults" function. Mosaic’s defaults as initialized by Ether_XPort_Defaults or Ether_XPort_Update must be set for proper operation of the EtherSmart/WiFi Wildcard. For example, communications between the Wildcard’s UART chip and the Lantronix device take place at 115 Kbaud, while the Lantronix default baud rate is only 9600 baud. Execution of Ether_XPort_Defaults takes approximately 13 seconds and modifies the Lantronix flash, so this routine should not be included in an autostart or main routine that runs each time the controller powers up.

The Lantronix configuration functions called Ether_XPort_Defaults and Ether_XPort_Update can be called interactively during program development and when the instrument is being prepared for shipment. These functions modify flash memory in the Lantronix device. Because flash memory can typically be written only 1000 to 10000 times before burning out, these flash-modifying routines should not be called frequently by a running application program.

A number of convenient interactive configuration, reporting and diagnostic functions are defined in the demo program. Listing 1 3 presents these functions. The _Q tag marks each function as callable from the terminal monitor. As explained in the Software User Guide for the controller product that you are using, you must type the function name and ( opening parenthesis with no intervening spaces, then at least one space after the ( before any parameters or the closing ) character. If you are typing numeric input parameters, be sure to set the numeric base by typing either DECIMAL or HEX. The selected base is retained until changed, so you need only type it once per session.

Before calling any of these functions, be sure to initialize the Wildcard by invoking an initialization function. If you have an EtherSmart Wildcard, you can type one of the following at the terminal prompt:

Ether_Task_Setup_Default( )

or:

Ether_Web_Demo( )

or any other function that invokes Ether_Task_Setup_Default.

If you have a WiFi Wildcard, you can initialize it by typing one of the following at the terminal prompt:

WiFi_Task_Setup_Default( )

or:

WiFi_Web_Demo( )

or any other function that invokes WiFi_Task_Setup_Default.

Listing 1-3 Interactive Configuration, Reporting and Diagnostic Routines Defined in the Demo Program. These work for both EtherSmart and WiFi Wildcards.

// ***************** INTERACTIVE CONFIGURATION AND REPORTING ************
 
_Q int Ether_Set_Defaults( void )
// works for xport or wiport (ethernet/wifi)
// call this AFTER calling main() or Ether_Web_Demo or Ether_Task_Setup_Default()
// or WiFi_Web_Demo or WiFi_Task_Setup_Default.
// sets mosaic factory defaults; returns error code
// sets local IP and gateway to 0.0.0.0 = unassigned, so IP address
// gets assigned via DHCP (Dynamic Host Configuration Protocol) by the LAN's gateway.
// see user guide for more information.
{  printf(“\rSetting defaults...\r”);
   Ether_XPort_Defaults(E_MODULENUM);
   return((int) Ether_Await_Response(E_MODULENUM)); // error code is in lsword
}
 
_Q int Ether_Set_Local_IP(int my_ip1, int my_ip2, int my_ip3,  int my_ip4)
// call this AFTER calling main() or Ether_Web_Demo or Ether_Task_Setup_Default()
// or WiFi_Web_Demo or WiFi_Task_Setup_Default.
// sets the IP address of the EtherSmart Wildcard specified by E_MODULENUM as:
//   ip1.ip2.ip3.ip4
// For example, to set the IP address to 10.0.1.22,
// pass to this function the parameters:
//   10 0 1 22
// returns error code
// NOTES: type DECIMAL at the monitor before invoking this function interactively!
//        The input types are declared as int to simplify interactive calling,
//        as the interactive debugger would require char specifiers before each input
//        parameter if the char type were used.
// NOTE: assigning a nonzero IP address disables DHCP!
{  printf(“\rSetting local IP address...\r”);
   Ether_Local_IP(my_ip1, my_ip2, my_ip3,  my_ip4, E_MODULENUM);
   Ether_XPort_Update(E_MODULENUM);
   return((int) Ether_Await_Response(E_MODULENUM)); // error code is in lsword
}
 
_Q void Ether_IP_Report(void)
// call this AFTER calling main() or Ether_Web_Demo or Ether_Task_Setup_Default()
// or WiFi_Web_Demo or WiFi_Task_Setup_Default.
// takes 7 seconds to execute, so be patient.
// Report is of the form:
// IP 010.000.001.019 GW 010.000.001.022 Mask 255.255.255.000
// which summarizes the IP address, gateway address, and netmask, respectively.
{  Ether_IP_Info_Report(E_MODULENUM);
}

As noted in the text above and in the comments in the listing, Ether_XPort_Defaults works only after the Wildcard has been initialized. Ether_XPort_Defaults SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. This function enters the Lantronix monitor mode, and sends the default versions of flash block0 (serial and network settings), block3 (additional network settings), and block7 (hardware handshaking configuration) S-records. If the Wildcard has been declared as WiFi, block 8 (WiFi configuration settings) and block 9 (WiFi security password) are also initialized. This routine then executes the Lantronix monitor mode reset command to instantiate the new values in Lantronix flash memory. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response, but note that the result will not be present until over 13 seconds have elapsed, so please be patient. Consult the glossary entry for implementation details.

If you want to change some of the Mosaic default parameters, use Ether_XPort_Update after setting the desired parameter values. The functions listed in Table 1-4 let you change the configurable values that are to be stored in the Lantronix flash:

Table 1-4 Functions that set configurable parameters to be stored by Ether_XPort_Update.

You can invoke one or more of these functions to set parameters, then use Ether_XPort_Update to instantiate the values in the Lantronix flash. If none of the configuration functions shown in Table 1-4 has been executed, then Ether_Xport_Update performs the same action as Ether_XPort_Defaults. For a WiFi Wildcard, all of the functions in Table 1-4 are relevant. For an EtherSmart Wildcard, the WiFi_Options, WiFi_Security, and WiFi_SSID functions have no effect.

The functions that end in _Ptr return a 32-bit pointer xaddress in RAM that can be used to read or write the associated value. The other functions in Table 1-4 accept parameters and write the new values into the Ether_Info structure for use by Ether_XPort_Update; see their glossary entries for more details. Be careful before changing the default values. For example, changing the Ether_Local_Port to a number other than its default value of 80 will impact the dynamic webserver, requiring browsers to specify a different port than the default when accessing the EtherSmart/WiFi dynamic webserver. (Typing the IP address followed by a colon and then the port number in the browser’s address bar allows a browser to connect to a webserver on the specified port).

The default values associated with these parameters are as follows. The Ether_Internal_Webserver_Port (for the configuration by web feature) is 8000. By default, there is no DHCP name or telnet password assigned. See the glossary entry for Ether_TCP_Control for a description of the default values of the associated low-level timeouts and character handling parameters. The Ether_Gateway, Ether_Local_IP, Ether_Remote_IP, and netmask are all set to 0.0.0.0 (unassigned). Note that the Ether_Remote_IP parameter is never used by the driver software, as all connections explicitly specify the remote IP and port as a set of passed parameters. The ability to change the remote IP value stored in Lantronix flash is provided only for the sake of completeness.

See the glossary entry of WiFi_Options for a description of the transmit power and rate settings, and the "ad hoc" mode; these are also described in detail in the WiFi Configuration section. The default WiFi_Security settings turn off all security and encryption. The default WiFi_SSID (Service Set ID) is "WIFI_WILDCARD" as described in the WiFi Configuration section.

The Mosaic factory defaults set via Ether_XPort_Defaults set the local IP address and the Gateway IP address and netmask to 0.0.0.0. This has the effect of causing the Wildcard to wait for an IP address to be assigned via DHCP (Dynamic Host Configuration Protocol). The DHCP server that assigns the IP is typically running on the gateway computer of the LAN (Local Area Network), or the gateway or wireless access point of the WLAN (Wireless Local Area Network). If your LAN or WLAN has an active DHCP service, then the EtherSmart/WiFi Wildcard should be assigned an IP address automatically when it is powered up and connected to the network. (See the "WiFi Configuration" section for a description of how to set up your WLAN). If you’ve loaded the demo program onto your controller board as described in Appendix A and typed one of the functions Ether_Web_Demo( ) or WiFi_Web_Demo( ) to initialize the Wildcard and start the web demo, you can learn the EtherSmart or WiFi Wildcard’s IP address by typing at the QED Terminal:

Ether_IP_Report( )

(Forth users would type the function names without any parentheses). The Ether_IP_Report function is described in the next section.

Assuming that the reported IP address is non-zero, you can then type the reported IP address into the web address bar of your web browser to see the demonstration web page. If the reported IP address is 0.0.0.0, then there is no DHCP service running on your LAN to assign an IP address, and you must explicitly assign one.

To explicitly assign an IP address and/or gateway IP and netmask, make sure that the Ethernet task is running by calling one of the functions Ether_Setup_Default( ), Ether_Task_Setup_Default( ), Ether_Web_Demo( ), WiFi_Setup_Default( ), WiFi_Task_Setup_Default( ) or WiFi_Web_Demo( ). Then invoke the Ether_Local_IP and/or Ether_Gateway functions with the desired IP parameters, and then call Ether_XPort_Update. The presence of the non-zero IP address will override any DHCP value and disable DHCP on the EtherSmart/WiFi Wildcard. Likewise, specifying a non-zero gateway IP address or netmask will override any gateway IP and netmask values and disable DHCP.

The Ether_Set_Local_IP function in the demo program excerpt in Listing 1 3 makes it easy to interactively assign an IP address to the EtherSmart or WiFi Wildcard from the terminal window. For example, assuming that you’ve already invoked one of the initialization routines Ether_Setup_Default( ), Ether_Task_Setup_Default( ), Ether_Web_Demo( ), WiFi_Setup_Default( ), WiFi_Task_Setup_Default( ) or WiFi_Web_Demo( ), you can set the IP address to 10.0.1.22 by typing the following into the QEDTerm terminal window:

DECIMAL
Ether_Set_Local_IP( 10, 0, 1, 22 )

Following the sample source code of Ether_Set_Local_IP, you can create a function to invoke the Ether_Gateway function to specify the gateway IP address and netmask. Then, to instantiate the values in Lantronix flash, execute Ether_Update followed by Ether_Await_Response.

To use an IP address that is automatically assigned by the LAN’s gateway host, specify an IP address, gateway and netmask of 0.0.0.0 (the factory default). In this case, the Lantronix hardware relies on DHCP (Dynamic Host Configuration Protocol) running on the local area network’s gateway server to set the IP address. To revert to the factory defaults which rely on a DHCP-assigned IP, gateway IP and netmask, execute Ether_Xport_Defaults or the convenient interactive version Ether_Set_Defaults as discussed above (see the demo program excerpt in Listing 1-3).

The Lantronix device on the EtherSmart/WiFi Wildcard implements a "monitor mode" than enables the examination of some of the parameters stored in the Lantronix flash. This mode also allows "ping" diagnostic packets to be sent to a specified IP address on the local area network. Unfortunately, these capabilities require a Lantronix reset sequence, and are slow, taking 7 seconds for a status report, and over 13 seconds for a ping report. Consequently, they are most useful for interactive diagnostics as opposed to runtime use. All of these functions require that you have initialized the Ethernet task using one of the functions Ether_Setup_Default, Ether_Task_Setup_Default, Ether_Web_Demo, WiFi_Setup_Default, WiFi_Task_Setup_Default or WiFi_Web_Demo.

The demo program excerpt in Listing 1 3 includes the convenient interactive Ether_IP_Report function which simply passes the E_MODULENUM constant to the Ether_IP_Info_Report routine. As described above, the _Q tag makes the function interactively callable from the terminal window. To use it, make sure that you have initialized the Wildcard, then type at your terminal

Ether_IP_Report( )

with at least one space after the ( character. If the info request was successful, the report is of the form:

IP 010.000.001.022 GW 010.000.001.002 Mask 255.255.255.000

This summarizes the IP address, Gateway (GW) IP address, and netmask. If there is a problem, an error message is displayed. Note that the Lantronix firmware may report indeterminate results if DHCP (Dynamic Host Configuration Protocol) is enabled but there is no active network connection.

The two IP information functions defined in the driver comprise a non-printing function called Ether_IP_Info_Request, and a printing version called Ether_IP_Info_Report. These work for both EtherSmart and WiFi Wildcards. Ether_IP_Info_Request SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. This function enters the Lantronix monitor mode and retrieves the local IP address, gateway IP address, and netmask that are currently in use by the specified EtherSmart/WiFi Wildcard. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response, but note that the result will not be present until over 7 seconds have elapsed, so please be patient. This routine can be used to discover which IP address, gateway and netmask were automatically assigned by the DHCP (Dynamic Host Configuration Protocol) server on the Local Area Network (LAN). After the ether_response mailbox has been successfully read, the returned results are available by fetching 4 bytes each from the Ether_My_IP_Ptr, Ether_Gateway_IP_Ptr, and Ether_Netmask_Ptr locations. The counted ASCII response string from the Lantronix device is stored as a 2-byte count followed by the string data at Ether_Outbuf. Ether_IP_Info_Report builds on this function, automatically waiting for the response and printing the output string as described above.

Ping is a computer network tool used to test whether a particular host is reachable across an IP network. Ping works by using the ICMP (Internet Control Message Protocol) to send "echo request" packets to the target host and listening for ICMP "echo response" replies. Using interval timing and response rate, ping estimates the round-trip time between hosts. Ping was named after active sonar in submarines, in which a pulse of energy (analogous to the network packet) is aimed at the target, which then bounces from the target and is received by the originator.

The demo program excerpt in Listing 1 4 includes an interactive function named Ether_Ping that pings a remote computer at a specified IP address. As usual, this function requires that you have initialized the Ethernet task using one of the functions Ether_Setup_Default( ), Ether_Task_Setup_Default( ), Ether_Web_Demo( ), WiFi_Setup_Default( ), WiFi_Task_Setup_Default( ) or WiFi_Web_Demo( ). For example, to ping a computer at the remote IP address 10.0.1.3, simply type the following into the terminal window:

Ether_Ping( 10, 0, 1, 3)

If there is a problem, the appropriate error message "Couldn’t enter monitor mode" or "No response from remote" is printed. If there is a ping response, a report of the following form is printed:

Seq 001 time 10ms
Seq 002 time 10ms
Seq 003 time 10ms
Seq 004 time 10ms
Seq 005 time 10ms
Seq 006 time 10ms

The printed display specifies the round-trip travel times between the EtherSmart/WiFi Wildcard and the specified remote host.

Listing 1-4 Interactive Ping Function from the Demo Program.

Listing 1-4    Interactive Ping Function from the Demo Program.
_Q void Ether_Ping(int remote_ip1, int remote_ip2, int remote_ip3,  int remote_ip4)
// call this AFTER calling main() or Ether_Web_Demo or Ether_Task_Setup_Default()
// or WiFi_Web_Demo or WiFi_Task_Setup_Default.
// on error, prints " Couldn't enter monitor mode!" or " No response from remote".
// on error, prints “ Couldn’t enter monitor mode!” or “ No response from remote”.
// takes thirteen seconds to execute, so be patient.
// Report is of the form (summarizes response time from specified remote host):
// Seq 001 time 10ms
// Seq 002 time 10ms
// Seq 003 time 10ms
// Seq 004 time 10ms
// Seq 005 time 10ms
// Seq 006 time 10ms
// NOTES: type DECIMAL at the monitor before invoking this function interactively!
//        The input types are declared as int to simplify interactive calling,
//        as the interactive debugger would require char specifiers before each input
//        parameter if the char type were used.
{  Ether_Ping_Report(remote_ip1, remote_ip2, remote_ip3, remote_ip4, E_MODULENUM);
}

The two ping functions defined in the EtherSmart/WiFi driver comprise a non-printing function called Ether_Ping_Request, and a printing version called Ether_Ping_Report. These behave in ways that are parallel to Ether_IP_Info_Request and Ether_IP_Info_Report as described in the prior section.

Ether_Ping_Request SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response, but note that the result will not be present until over 13 seconds have elapsed, so please be patient. After the ether_response mailbox has been successfully read, the counted ASCII response string is stored as a 2-byte count followed by the string data at Ether_Outbuf. Ether_Ping_Report builds on this function, automatically waiting for the response and printing the output string as described above.

The EtherSmart and WiFi Wildcards draw power from the +5Volt regulated supply on the Wildcard bus. The Lantronix XPort draws 250 mA from a linear +3.3V regulator on the Wildcard. Shutting down the +3.3V regulator saves 1.25 Watts. 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. This can extend operational time in battery powered systems. To attain these power savings, call the Ether_Shutdown function. Of course, the Ethernet/WiFi interface on the specified wildcard is not useable while in the shutdown state. To revert to the default powered-up state, power cycle the hardware, or execute Ether_Init, WiFi_Init or one of their calling functions listed in Table 1 3.

The standard driver and demo software enables you to install two EtherSmart and/or WiFi Wildcards on a single controller, using one for code downloads and interactive communications ("revectored serial via TCP/IP") and the other for communications services such as email, serial tunneling, and web service. Simply store the modulenum of the revectored serial Wildcard into the ether_revector_module variable as illustrated by the Ether_Monitor_Demo function in the demonstration program as described below. Ether_Monitor_Demo works for EtherSmart and WiFi Wildcards. Initialize the other Wildcard for communications services using the standard initialization functions such as Ether_Setup_Default( ), Ether_Task_Setup_Default( ), Ether_Web_Demo( ), WiFi_Setup_Default( ), WiFi_Task_Setup_Default( ) or WiFi_Web_Demo( ).

If you are using more than one EtherSmart or WiFi Wildcard to provide communications services (serial tunneling, email, and web service), you will need to define a custom version of Ether_Service_Loop, and a custom version of Ether_Setup_Default and Ether_Task_Setup_Default, or WiFi_Setup_Default and WiFi_Task_Setup_Default for each additional Wildcard. Each Wildcard that runs communications services must have its own task running the service loop, with its own set of buffers and mailboxes.

Ether_Service_Loop is a simple infinite loop function; it works for both EtherSmart and WiFi Wildcards. In the loop body are calls to Ether_Connection_Manager, Ether_Command_Manager, and Pause. The default version of Ether_Service_Loop specifies the contents of the ether_service_module variable as the parameter passed to Ether_Connection_Manager and Ether_Command_Manager in the infinite loop body. Your custom version should not use this variable; rather, it should specify the modulenum of the additional EtherSmart/WiFi Wildcard that you are adding.

If you are adding an EtherSmart Wildcard, your custom version of Ether_Setup_Default should call Ether_Setup with a unique buffer base xaddress, mailbox base address, and the modulenum of the additional EtherSmart Wildcard. It must then build a new task and call ACTIVATE to install the custom version of the Ethernet service loop function as described in the prior paragraph. If you are adding a WiFiSmart Wildcard, your custom version of WiFi_Setup_Default should call WiFi_Setup with a unique buffer base xaddress, mailbox base address, and the modulenum of the additional WiFi Wildcard. It must then build a new task and call ACTIVATE to install the custom version of the Ethernet service loop function.

Using this technique, multiple EtherSmart and/or Wildcards can be configured to provide communications services. If you have questions, feel free to contact Mosaic Industries for assistance.

The Lantronix XPort and WiPort devices support 256 bit AES Rijndael encryption. Any AES-enabled devices that share the same key can communicate securely with one another. This encryption is not to be confused with WiFi security encryption; the AES encryption is separate and independent from WiFi security.

Rijndael is the block cipher algorithm chosen by the National Institute of Science and Technology (NIST) as the Advanced Encryption Standard (AES) to be used by the US government. Configuring two or more Lantronix devices with the same keys and key length allows them to communicate with one another on a network, while preventing anyone who does not know the encryption key from deciphering the network data.

To enable AES encryption, initialize the EtherSmart/WiF Wildcard using one of the initialization functions in Table 1 3. Store a 32-byte, 256 bit key into a buffer in memory and then invoke Ether_Encryption, passing it the base xaddress and count of the key buffer, plus the relevant modulenum. Make sure there are no active connections during the execution of this function, as they will be interfered with when monitor mode is entered. Double check the key values, as there is no way to read them back after they are set. The function requires approximately 13 seconds to complete.

An alternate way to configure the encryption settings is to go into "setup mode" by connecting to port 9999 at the Lantronix device’s known IP address using the "raw" data transfer mode of a free network terminal program such as Putty. (See the section titled "Using the Free Putty TCP/IP Terminal for Testing and Development"). Once connected to the Lantronix device using Putty, hit the "Enter" key within 3 seconds. Then choose option 6 (security), then follow the prompts to enable encryption, choose the key length, and change or enter a key.

To return to non-encrypted operation, make sure that the Ethernet task is running by executing Ether_Task_Setup_Default or WiFi_Task_Setup_Default or another appropriate initialization function. Then execute Ether_XPort_Defaults; this works for both EtherSmart and WiFi Wildcards.

See also → Using Example Application