The EtherSmart Wildcard User Guide

<< Previous | Next>>

EtherSmart Initialization, Configuration and Diagnostics

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

Initialization Functions

The highest level initialization function in the pre-compiled device driver library is Ether_Task_Setup which accepts as input parameters a 16-bit TASK base address in common memory and the modulenum. (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 Ether_Task_Setup_Default from the demo program that invokes Ether_Task_Setup, passing it the base address of the ether_control_task, and the E_MODULENUM Wildcard address.

Listing 1‑2     Using EtherTaskSetup_Default() from the Demo Program to Initialize the Wildcard Services.

// ************** SETUP ETHERNET TASK TO RUN WEB AND TUNNELING SERVICES **************

TASK ether_control_task; // 1 Kbyte per task area

void Ether_Task_Setup_Default( void )

// performs full initialization of the ether_info struct and mailboxes for the

// specified modulenum, and

// builds and activates an ethernet control task to service the xport

{

 // NEXT_TASK = TASKBASE; // empties task loop; comment out if other tasks allowed

   Ether_Task_Setup( &ether_control_task, E_MODULENUM);

}

Ether_Task_Setup is a high level routine that performs a full initialization of the Ether_Info structure and mailboxes, and builds and activates an Ethernet control task to service the XPort for the specified modulenum.  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_Task_Setup builds and activates a 1 Kbyte task running the Ether_Service_Loop function, and calls Ether_Setup_Default. Ether_Setup_Default specifies a default buffer area base (0x043000 for V4.xx platforms, and 0x178000 for V6.xx platforms) and calls Ether_Setup. Less than 3 Kbytes is allocated in this buffer area; see the glossary entry of Ether_Setup for a detailed description of operation.  Ether_Setup in turn 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 will call only the highest level Ether_Task_Setup 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. Consult the EtherSmart Glossary for more details about the initialization functions.

Configuring the XPort Device

The low level Ethernet interface on this Wildcard is provided by the Lantronix XPort that combines a processor, flash and RAM memory, Ethernet network interface controller, and RJ45 jack into a single component.  The XPort 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 XPort is time consuming (approximately 13 seconds) and modifies flash in the XPort device. 

The two fundamental XPort configuration functions are called Ether_XPort_Defaults and Ether_XPort_Update. As its name suggests, Ether_XPort_Defaults sets the recommended default parameters as 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 be set for proper operation of the EtherSmart Wildcard.  For example, communications between the Wildcard’s UART chip and the XPort 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 XPort flash, so this routine should not be included in an autostart or main routine that runs each time the controller powers up.

The XPort 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 XPort.  Because flash memory can typically be written to 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 typing main or some other function that invokes Ether_Task_Setup_Default.

Listing 1‑3     Interactive Configuration, Reporting and Diagnostic Routines Defined in the Demo Program

.

// ***************** INTERACTIVE CONFIGURATION AND REPORTING ************

_Q int Ether_Set_Defaults( void )

// call this AFTER calling main() or Ether_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_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

// This function returns an error code (0 means no error).

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

{  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_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);

}

The interactive function Ether_Set_Defaults( ) reverts to the Mosaic factory default settings.  It calls Ether_XPort_Defaults and waits for the response from the Ethernet task by invoking Ether_Await_Response. To use it, simply type from the QED Terminal:

Ether_Set_Defaults( )

Ether_XPort_Defaults requires that Ether_Task_Setup or Ether_Task_Setup default has already been executed.  It 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 XPort monitor mode, and sends the default versions of XPort flash block0 (serial and network settings), block3 (additional network settings), and block7 (hardware handshaking configuration) S-records. This routine then executes the XPort monitor mode reset command to instantiate the new values in XPort 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 following functions let you change the configurable values that are to be stored in the XPort flash:

Table 1‑3      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 XPort flash.  If none of the configuration functions shown in Table 1‑3  has been executed, then Ether_Xport_Update performs the same action as Ether_XPort_Defaults.

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‑3 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 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 XPort flash is provided only for the sake of completeness.

Assigning an IP Address to the EtherSmart Wildcard

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 XPort to wait for an IP address to be assigned via DHCP (Dynamic Host Configuration Protocol) running on the gateway computer of the LAN (Local Area Network).  If your LAN has an active DHCP service, then the EtherSmart Wildcard should be assigned an IP address automatically when it is powered up and connected to the LAN via the Ethernet jack. Assuming that you’ve loaded the demo program onto your controller board as described in Appendix A and typed main to initialize the Ethernet task, you can learn the EtherSmart Wildcard’s IP address by typing at the QED Terminal:

Ether_IP_Report( )

(Forth users would type Web_Demo to start the program followed by the Ether_IP_Report command without any parentheses).  This 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 Ether_Task_Setup or Ether_Task_Setup_Default, 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.  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 Wildcard from the terminal window.  For example, to set the IP address to 10.0.1.22, simply type the following into the QEDTerm terminal window:   

main

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

Reporting Routines

The Lantronix XPort on the EtherSmart Wildcard implements a "monitor mode" than enables the examination of some of the parameters stored in the XPort flash.  This mode also allows "ping" diagnostic packets to be sent to a specified IP address on the LAN.  Unfortunately, these capabilities require an XPort 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 Ether_Task_Setup or Ether_Task_Setup_Default. In the C demo program, calling main performs the required initialization.

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 typed main to initialize 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. 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 XPort monitor mode and retrieves the local IP address, gateway IP address, and netmask that are currently in use by the XPort on the specified EtherSmart 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 XPort 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.

Using "Ping" for Diagnostics

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. For example, to ping a computer at the remote IP address 10.0.1.3, simply type the following into the terminal window:          

main

DECIMAL

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 Wildcard and the specified remote host.

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_Task_Setup_Default() !

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

Shutting Down the XPort To Save Power

The EtherSmart Wildcard draws power from the +5Volt regulated supply on the Wildcard bus.  The Lantronix XPort draws 0.25A from a linear +3.3V regulator on the Wildcard.  Shutting down the +3.3V regulator saves 1.25 Watts; this can extend operational time in battery powered systems. To attain these power savings, call the Ether_Shutdown function. Of course, the Ethernet 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 or one of its calling functions (Ether_Setup, Ether_Setup_Default, Ether_Task_Setup, or Ether_Task_Setup_Default).

Initializing Multiple EtherSmart Wildcards

The standard driver and demo software enables you to install two EtherSmart Wildcards on a single controller, using one for code downloads and interactive communications ("revectored serial via Ethernet") 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.  Initialize the other Wildcard for communications services using the standard initialization functions such as Ether_Task_Setup or Ether_Task_Setup_Default.

If you are using more than one EtherSmart Wildcard to provide communications services (serial tunneling, email, and web service), you will need to define a custom version of Ether_Service_Loop and Ether_Task_Setup for each additional EtherSmart 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.  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 Wildcard that you are adding.

Your custom version of Ether_Task_Setup 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.

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

Enabling the Encryption Feature

The Lantronix XPort device supports 256 bit AES Rijndael encryption. Rijndaell 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 XPort devices with the same keys and key length allows them to communicate with one another on a LAN, while preventing anyone who does not know the encryption key from deciphering the network data.

To enable encryption, initialize the EtherSmart Wildcard using Ether_Setup or one if its calling functions, and then invoke Ether_Encryption, passing it eight 32-bit encryption keys in order from left to right.  (Forth users should remember to type DIN before each 32-bit key.)  Be careful to specify the proper numeric base for the entered key parameters.  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 XPort’s known IP address using the "raw" data transfer mode of a free Ethernet terminal program such as Putty.  (See the section titled "Using the Free Putty Ethernet Terminal for Testing and Development").  Once connected to the XPort 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 another appropriate initialization function, and execute Ether_Xport_Defaults.

Lantronix asks that we include this product notice: This and other devices that implement encryption cannot be exported or re-exported to a national resident of Cuba, Iran, North Korea, Sudan, Syria or any other country to which the United States has embargoed goods; see the Lantronix documentation and website for details.

<< Previous | Next>>