The EtherSmart Wildcard User Guide

<< Previous | Next>>

Appendix A: Installing the Software

The EtherSmart Wildcard device driver software is provided as a pre-coded modular runtime library, known as a "kernel extension" because it enhances the on-board kernel’s capabilities.  The GUI Toolkit that runs the touchscreen-based Graphical User Interface is also provided as a kernel extension library.  One or more kernel extension libraries can be generated simultaneously.  The library functions are accessible from C and Forth. 

Generating the EtherSmart Kernel Extension Library

Mosaic Industries can provide you with a web site link that will enable you to create a packaged kernel extension that has drivers for all of the hardware that you have on your system.  In this way the software drivers are customized to your needs, and you can generate whatever combination of drivers you need.  Make sure to choose the correct controller platform and specify the EtherSmart Wildcard Driver in the list of kernel extensions you want to generate, and download the resulting packages.zip file to your hard drive.

For convenience, a separate pre-generated kernel extension for the EtherSmart Wildcard is available from Mosaic Industries on the software distribution CD.  Look in the directory named:

C:\Mosaic\Demos_and_Drivers\EtherSmart_WC_Code\Ether_Demo\Library

The V4_4 kernel subdirectory contains the EtherSmart kernel extension for QCard, QScreen, and Mosaic Handheld products.  The V4_09 kernel subdirectory is for the QVGA controller and other products based on the QED-Board.

The kernel extension is downloaded as a "zipped" file named packages.zip. Unzipping it (using, for example, winzip or pkzip) extracts the following files:

  readme.txt        Provides summary documentation about the library.

  install.txt      Installation file, to be loaded to COLD-started Mosaic Controller.

  library.4th      Forth name headers and utilities; #include in top of Forth program.

  library.c          C callers for all functions in library; #include in C code.

  library.h          C prototypes for all functions; #include in extra C files.

The library.c and library.h files are only needed if you are programming in C.  The library.4th file is only needed if you are programming in Forth.  The uses of all of these files are explained below. 

We recommend that you move the relevant files to the same directory that contains your application source code, or into a convenient nearby sub-directory.

Creating Web Page and Image Resources with the Image Converter

The most convenient way to create HTML or text web page strings as well as web images is to use the "Image Converter" program that is part of your Mosaic development environment.  This program converts one or more files, each containing a single string, image or other resource into a named 32-bit xaddress and count that can be used by your application program. 

To define a set of text or text/HTML web page as resources that can be passed to the HTTP data output routines such as HTTP_Send_Buffer or HTTP_Send_2Buffers, simply place each string into a separate file with the file extension .str or .htm or .html and a file name that will become a part of the symbol name.  All files to be converted should be in a single directory.  Make sure you use C-compatible filenames that include only alphanumeric and _ (underscore) characters, and do not start with a numeral.  Invoke the Image Converter from your development environment.  In the Image Converter control panel, select the controller platform, and check the "Web files" box.  If you are programming in Forth, click the "Advanced" menu and select Forth as the programming language. 

If your web pages reference images that are to be served out by the EtherSmart itself, simply place the files containing these images into the same directory.  Each image file must have a valid file extension; the allowed file types are png, gif, or jpg.  Note that bitmap (bmp) files are not convertible as web resources by the Image Converter, as bitmap images are reserved for the GUI (Graphical User Interface) toolkit which is also supported by the Image Converter.

In the "Directory" area of the control panel, select the directory that contains the specified file(s).  Then click on "Convert Files Now".  A pair of files named image_data.txt and image.headers.h will be created by the Image Converter.  The image_data.txt contains S-records and operating system commands that load the string image into flash memory on the controller.  Because flash memory is nonvolatile, you only need to download this file once to the controller; it need not be reloaded until you change the resources.  The image_headers.h file declares the xaddress and count (size) constants to be used by your application program. 

For example, let’s say that you have created a rather lengthy email body and stored it in a file named mail_body.html where the .html file extension indicates that the file contains HTML text.  The image_headers.h file declares the following two macros with the appropriate numeric xaddress and count values:

#define HOME_BODY_HTML_XADDR 0x700360

#define HOME_BODY_HTML_SIZE 0x98E

Of course, the actual numeric xaddress value depends on the controller platform that you have selected and the other resources that are converted.

You can then use these macros as parameters passed to the HTTP_Send_Buffer or HTTP_Send_2Buffers functions to specify the string.

Loading the Software onto the Controller

To use the kernel extension, the runtime kernel extension code contained in the install.txt file must first be loaded into the flash memory of the Mosaic Controller. Power up the Mosaic Controller, connect it to the serial port, and start the QED Terminal software.  If you have not yet tested your Mosaic Controller and terminal software, please refer to the documentation provided with your Mosaic Controller.  Once you can hit enter and see the ‘ok’ prompt returned in the terminal window, type

COLD

to ensure that the board is ready to accept the kernel extension install file.  Use the "Send File" menu item of the terminal to download the install.txt to the Mosaic Controller.

If you have created resources such as web pages or images using the image converter file, use the "Send File" menu item of the terminal to download the image_data.txt file to the Mosaic Controller.

Now, type

COLD

again and the kernel has been extended with the driver and resources!  Once install.txt has been loaded, it does not need to be reloaded each time you revise your source code.  Similarly, once image_data.txt has been loaded, it does not need to be reloaded unless and until you decide to change the web page or image sources.

For C programmers, the C_Ether_demo_includer.txt file in the EtherSmart_WC_Code\Ether_Demo directory loads the install.txt and image_data.txt files and the C compiler output file for the Ethernet demo program.  For Forth programmers, the Ether_demo_includer.4th file in the EtherSmart_WC_Code\Ether_Demo directory loads these files and the source code file for the Ethernet demo program.

As explained in the next section, only the much smaller library.c and library.h (for C programmers) or library.4th file (for Forth programmers) need to be included with each compile/load cycle during programming.

Using the EtherSmart Driver with C

If the library.c and library.h files are in the same directory as your other C source code files, use the following directive in your source code file:

#include "library.c"

If the files are in a different directory, place the path before the filename separated by the \ character to specify where the file is in relation to the source code file.  The library.c file contains calling primitives that implement the functions in the kernel extension package.  The library.c file automatically includes the library.h header file if it is not already included.  If you have a project with multiple source code files, you should only include library.c once, but use the directive

#include "library.h"

in every additional source file that references the EtherSmart functions.

If you have created resources such as web pages or images using the image converter file, then also use the directive

#include "image_data.h" // if web resources have been defined

in each source code file.  The image_data.h file contains macros that define the base xaddress and size of each string or image resource; these macro constants are typically passed as input parameters in the handler functions that serve out web pages.

To compile the C program, use the "make" icon in your C IDE (Integrated Development Environment) to create the *.dlf (download file) to be sent to the controller.

The C_Ether_demo_includer.txt file in the EtherSmart_WC_Code\Ether_Demo directory loads the install.txt and image_data.txt files and the .dlf C compiler output file for the Ethernet demo program.  After the first load of this includer file, only the .dlf file needs to be sent to the controller after each run of the C compiler during program development. To send a file to the controller, use the "Send File" menu item in the QED Terminal. 

Type main in the terminal window to execute the program

Note that all of the functions in the kernel extension are of the _forth type.  While they are fully callable from C, there are two important restrictions.  First, _forth functions may not be called as part of a parameter list of another_forth function. 

Second, for all V4.xx operating system kernels that use the Fabius C compiler, _forth functions may not be called from within an interrupt service routine unless the instructions found in the file named forthirq.c in the compiler distribution are followed.  The new PDQ line of controllers that use V6.xx kernels with the GCC compiler tool chain are not subject to this restriction.

Using the Driver Code with Forth

C programmers can skip this section.

After loading the install.txt and image_data.txt files and typing COLD, use the terminal to send the "library.4th" file to the Mosaic Controller (or #include library.h from the top of your Forth source code file).  The library.4th file sets up a reasonable memory map and then defines the constants, structures, and name headers used by the EtherSmart Wildcard kernel extension. This file leaves the memory map in the download map.

After library.4th has been loaded, the board is ready to receive your high level source code files.  Be sure that your software doesn’t initialize the memory management variables DP, VP, or NP, as this could cause memory conflicts.  If you wish to change the memory map, edit the memory map commands at the top of the library.4th file itself. The definitions in library.4th share memory with your Forth code, and are therefore vulnerable to corruption due to a crash while testing.  If you have problems after reloading your code, try typing COLD and reload everything starting with library.4th. It is very unlikely that the kernel extension runtime code itself (install.txt) or the resource file (image_data.txt) can become corrupted since these are stored in flash that is not typically accessed by code downloads. 

The Ether_demo_includer.4th file in the EtherSmart_WC_Code\Ether_Demo directory loads the install.txt and image_data.txt files and the Ether_demo.4th source file for the Ethernet demo program.  After the first load of this includer file, only the Ether_demo.4th file needs to be sent to the controller after each source code editing cycle during program development.  To send a file to the controller, use the "Send File" menu item in the QED Terminal.

We recommend that your source code file end with the following sequence that is compatible with all Mosaic controller platforms shipped to date:

FIND WHICH.MAP       \ v4.xx: we’re in download map:

IFTRUE          \ nesting is ok if endiftrues are next to each other

 XDROP

   4 PAGE.TO.FLASH

  5 PAGE.TO.FLASH

  6 PAGE.TO.FLASH

   STANDARD.MAP

  SAVE

OTHERWISE          \ for V6.xx kernels, store to shadow flash and save pointers

    SAVE.ALL .     \ for V6.xx. this takes some time, should print FFFF for success

ENDIFTRUE

This copies all loaded code from RAM to flash.  The SAVE (V4.xx) or SAVE.ALL (V6.xx) command means that you can often recover from a crash and continue working by typing RESTORE.

<< Previous | Next>>