The EtherSmart Wildcard User Guide

<< Previous | Next>>

The EtherSmart Software Driver Routines

This section summarizes the capabilities of the EtherSmart driver functions. For a complete listing of all of the driver functions, see 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.

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

  Initialize and configure the EtherSmart Wildcard,

  Perform code downloads and debugging via Ethernet,

  Set up serial tunneling connections between two Ethernet-enabled devices,

  Send emails, and,

  Setup a dynamic webserver for instrument monitoring and control. 

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

EtherSmart Driver Data Structures

There are two distinct modes in which the EtherSmart Wildcard can be used.  One mode is to use the Wildcard to replace the serial port on the controller, enabling code downloads and interactive development to be performed via Ethernet instead of via RS-232.  This is called "revectored serial via Ethernet".  The other mode is to configure the EtherSmart Wildcard to provide communications services including serial tunneling, outgoing email, and web service.  These two modes use different data structures as described in the following subsections.

Revectored Serial via Ethernet

Revectored serial via Ethernet is conceptually very simple: the three fundamental serial primitives Key, AskKey, and Emit are "revectored" so that they use the Ethernet port instead of the serial port on the controller.  The simplest approach to revectoring is to store the correct modulenum into the global variable named ether_revector_module, and then to call Ether_Serial_Revector. This runs the default (startup) task through the specified EtherSmart Wildcard with no additional data structures needed.  Setting up a separate Ethernet task for revectoring is possible but not required.  See the section titled "Code Downloads and Interactive Communications via Ethernet" below for more details.

Communications Services Require a Dedicated Ethernet Task

Most users will want to configure the EtherSmart Wildcard to provide communications services including serial tunneling, outgoing email, and web service.  This requires more sophisticated data structures and a dedicated task to run the services.  The pre-coded driver functions automate the required interactions between the application program and the Ethernet task.

As explained in the User Guide for your Mosaic controller board, a "task" is an environment that is capable of running a program.  The task contains a user area, stacks, and buffers that enable a program to run independently of other tasks.  The operating system switches between tasks using cooperative multitasking mediated by the Pause routine, and using the timeslice multitasker to force periodic task switches.  Each of the tasks typically manages a defined set of services, and the tasks interact by means of shared variables or mailboxes. 

Mailboxes

A "mailbox" is a 32-bit variable in common memory that conveys a message from one task to another.  A mailbox must be cleared before a new message may be sent; this helps to synchronize the tasks and ensures that no messages are discarded or written over without being read by the receiving task.  A mailbox may be read and cleared by a "blocking" function that waits until the mailbox contains a message (that is, until it contains a non-zero value) and then reads out, reports, and zeros the mailbox.  It may also be checked by a "non-blocking" function that reads and reports the contents of the mailbox and, if it contains a non-zero value, clears it.  Non-blocking mailbox reads are often preferred because they avoid tying up one task while waiting for another task to send a message.

The EtherSmart driver code uses mailboxes to coordinate the provision of communications services by the Ethernet task to the programmer’s main application task.  This is all done transparently, so you don’t have to be an expert on inter-task communications to use the EtherSmart Wildcard. Three 32-bit mailboxes named ether_command, ether_response, and ether_gui_message are allocated in common RAM when the initialization routine executes.  For example, when the application program invokes a command such as Ether_Send_Email, a message is dispatched via the ether_command mailbox to the Ethernet task.  Consequently, the Ethernet task opens a connection to the specified remote computer, sends the email, and closes the connection.  The Ethernet task then sends a result error code in the ether_response mailbox.  This mailbox must be cleared by the application program using either the blocking function Ether_Await_Response, or the non-blocking function Ether_Check_Response. The main loop of your program’s application task should periodically call one of these two functions to manage the interactions with the EtherSmart task. See the Email and Serial Tunneling sections (and the corresponding functions in the demo program) for examples of use.

Variables

In addition to the mailboxes, there are two variables declared in the driver code named ether_revector_module and ether_service_module. As mentioned above, ether_revector_module specifies which module (if any) is being used for revectored serial via Ethernet.  The ether_service_module variable is set by the initialization functions Ether_Init and its calling functions (Ether_Setup, Ether_Setup_Default, and Ether_Task_Setup). It specifies which Wildcard module is accessed by the Ether_Service_Loop routine running in the Ethernet control task.   Because each of these variables is automatically initialized by higher level functions, you typically don’t have to worry about them.  It is easy to install two EtherSmart Wildcards, one for revectored serial, and the other providing communications services including serial tunneling, email, and web service. 

If you need more than one EtherSmart providing communications services, consult the section below titled "Initializing Multiple EtherSmart Wildcards".

Information Structure Holds Control Parameters

Most of the control data for the EtherSmart Wildcard is contained in a structure whose extended 32-bit base xaddress is returned by the Ether_Info function.  There is one of these structures for each initialized EtherSmart Wildcard providing communications services.  This structure contains error results, flags to enable the web server and serial tunneling services, buffer sizes, pointers to the mailboxes and buffers, web service form parsing pointers, and configuration data.  The configuration data includes local and gateway IP addresses, ports and netmasks, timeout parameters, and pointers to strings used by the email routine.  The structure also stores the input parameters passed to each service request function until the Ethernet task can extract the parameters and perform the requested action.

Several of the functions in the driver code allow the programmer to set and read the values in the Ether_Info structure.  The structure is declared and initialized by Ether_Init and its calling functions.  Using one of the high level functions Ether_Task_Setup or Ether_Setup_Default writes reasonable default values into this data structure.

Allocated Buffers Support Tunneling, Email and Web Services

Communicating via Ethernet requires the use of buffers to hold incoming and outgoing data.  The input and output buffers for serial tunneling and email are called Ether_Inbuf and Ether_Outbuf, respectively. The web service input and output buffers are called HTTP_Inbuf and HTTP_Outbuf. Each of these buffers has a default maximum size that is set at initialization time.  The default size of Ether_Inbuf and Ether_Outbuf is given by the constant ETHER_BUFSIZE_DEFAULT. The default size of the HTTP_Inbuf and HTTP_Outbuf are given by the constants HTTP_INBUFSIZE_DEFAULT and HTTP_OUTBUFSIZE_DEFAULT, respectively.  The functions that write to the buffers typically accept the maximum buffer size as an input parameter, and ensure that they never write beyond the allowed buffer size.

If you need specify a new buffer base xaddress or size that is different from the values set at initialization time, use the functions Ether_Set_Inbuf, Ether_Set_Outbuf, HTTP_Set_Inbuf, and HTTP_Set_Outbuf.

The LBuffer, a Counted Buffer

Functions that manipulate buffers need to know the number of valid bytes stored in the buffer.  A convenient place to store this information is in the buffer itself.  For this reason, this driver code uses a data structure called an "LBuffer", defined as a buffer with a 16-bit count stored in the first two bytes of the buffer, with the data following. For example, a function like Ether_Send_LBuffer expects the 32-bit extended address (xaddress) of the LBuffer as an input parameter, and sends the contents on the active Ethernet connection.  This function automatically fetches the number of data bytes in the buffer (its "count") from the buffer’s first 2 bytes, and sends data starting at the specified xaddress+2.  Data reception functions such as Ether_Get_Data, Ether_Get_Chars and Ether_Get_Line expect the 32-bit extended address (xaddress) of an LBuffer as an input parameter, and receive incoming data to the buffer, storing the count at the specified xaddress, and storing the data starting at xaddress+2.   The glossary entry for each buffer handling function tells whether it is dealing with an uncounted buffer or an LBuffer.

Note that the maximum size of a buffer set at initialization time refers to the data portion of the buffer; the allocated size of the LBuffer is two bytes larger than the data size.  For example, ETHER_BUFSIZE_DEFAULT equals 510 bytes.  The resulting allocated size of Ether_Inbuf and Ether_Outbuf is 512 bytes each, with the first 2 bytes of each buffer containing the count, and the remaining 510 bytes containing the data.

Web Handlers Are Posted to the Autoserve Array

The EtherSmart Wildcard driver includes a programmable dynamic webserver. You configure the webserver by defining and posting a "handler function" for each web address that is implemented.  When the browser requests the web address (known as a URL, or Uniform Resource Locator), the webserver automatically executes the associated handler which performs any required actions and transmits the web page to the browser.  As described in a later section, versatile functions make it easy to use HTML "forms" to request particular data or stimulate particular actions from the Mosaic controller.

The "Autoserve Array" is a data structure that holds a pointer to each URL string, and the corresponding 32-bit function pointer (execution address) of the handler associated with that URL.  HTTP_Autoserve_Ptr returns an address that contains the 32-bit base address of this array which is set up by Ether_Info_Init and its calling functions (Ether_Init, Ether_Setup, Ether_Setup_Default, and Ether_Task_Setup). The functions HTTP_Add_Handler and HTTP_Add_GUI_Handler post the required information into this array, so the programmer does not need to directly access the contents of this low-level data structure.

Passing String Extended Addresses as Function Parameters

A number of the functions in the EtherSmart software driver expect as input parameters the 32-bit extended address ("xaddress") of a string.  An xaddress includes page information that is not available in a 16-bit address.  Because by default the C compiler treats string addresses as 16-bit parameters, a conversion must be performed to generate the 32-bit xaddress.  Listing 1‑1 from the strdefs.h file referenced by a #include statement in the C demonstration (demo) program illustrates a macro called STRING_XADDR that performs the required conversion.  Simply invoke the STRING_XADDR macro with the string specifier as the macro argument to generate the corresponding 32-bit xaddress.  It is best to use the macro right in the argument list of the function being called.  For an example of use, see Listing 1‑7.

Listing 1‑1     STRING_XADDR Macro Converts a String to an Xaddress.

// ************** USEFUL MACRO FOR STRINGS IN V4.xx C COMPILER **************

// the TO_XADDR defined in /mosaic/include/types.h

// transforms a separate 16-bit addr, page into a 32-bit xaddress:

// #define TO_XADDR(address,page) ((xaddr) (((page)<<16)+ (0xFFFF & (address))))

// We want to substitute THIS_PAGE (also defined in types.h) for the page,

// as the V4.xx C compiler replicates the strings on each page;

// therefore, in most cases, the calling function’s page

// is the same as the string page:

#define STRING_XADDR(str_addr) ((xaddr) TO_XADDR(((xaddr) str_addr), \

         ((xaddr) THIS_PAGE)))

The Demo Program Provides an Example of Use

For an example of an application program that exercises the capabilities of the EtherSmart Wildcard, see the demonstration ("demo") program listings that are provided in both C and Forth in Appendices B and D of this document. Appendix A tells you how to compile and load the program. Briefly, you’ll need a version of the pre-compiled driver code which includes an install.txt file and *.c and *.h (C code and header) files. 

You’ll also need the "resource files" created by the "Image Converter" program that is part of the CD you get from Mosaic when you buy your starter kit.  The Image converter creates an image_data.txt download file and an image_headers.h (for C) and image_headers.4th (for Forth) header file that encode any images and/or HTML pages you define if you are implementing a web server.  After sending the driver’s install.txt file and the image_data.txt file to the controller, you’ll send the program.  C programs are compiled by clicking the "make" icon in the Mosaic IDE and sending the resulting file to the controller.  Forth programs are compiled by simply sending the source file to the controller using the QED Terminal program. Note that the demo program references the driver library files using #include statements near the top of the file listing.

The remainder of this section presents code examples that are excerpted from the C version of the demo program.  We recommend that you look at the code listing now in Appendix B or D to familiarize yourself with the demo program.  Because function names and parameter lists are the same in both the C and Forth versions of the code, interested Forth programmers can look up the relevant excerpts by examining Appendix D and locating the referenced function name. 

Recall that most of the functions expect the Wildcard address called the "module number" or simply "modulenum" in their input parameter lists. Make sure that the jumper settings on the Wildcard hardware match the modulenum parameter that is specified in your application program.  In the demo program, the constant E_MODULENUM is declared to hold the modulenum. Its default value is 4 in the provided code.  If your EtherSmart Wildcard is not installed as module number 4, you must change the value of this constant to equal the hardware modulenum as specified in the "Selecting the Wildcard Address" section above.

Once you’ve loaded the demo program onto your controller board as described in Appendix A and typed main to start the program, 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). 

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.  See the section below titled "Assigning an IP Address to the EtherSmart Wildcard". 

The remainder of this document explains all the features of the demo program.

<< Previous | Next>>