Table of Contents

The USB Wildcard User Guide

<< Previous | Next>>

PC Driver Software

There are two distinct software drivers needed for USB communications: the driver that runs on the host PC, and the driver that runs on the Mosaic controller.  This section describes the PC driver.

PC USB Driver Software

USB drivers for the PC are available at no charge from FTDI, the company that makes the core FT245BM chip that implements the USB hardware protocol on the Wildcard.  At the time of this writing, these drivers are available at the FTDI web site at

http://www.ftdichip.com/FTDrivers.htm

There are two types of drivers available from FTDI: Virtual Com Port (VCP) and direct (D2XX/DLL) drivers.  The VCP driver emulates a standard PC serial port such that the USB device may be communicated with as a standard RS232 device.  The D2XX driver allows direct access to a USB device via a DLL (dynamic link library) interface.  The VCP drivers are required if you want to use the Mosaic Terminal to interactively communicate with the USB Wildcard (see the USB Demo code as discussed in Mosaic Software Driver section).  For all Windows operating systems released after Windows ME, both the VCP and DLL drivers are included in a single driver installation package from FTDI.  For Windows 98 and Windows ME, you can choose either VCP or DLL and install the corresponding driver package. 

These FTDI drivers are also available on the Mosaic distribution disk.  Look in the USB Wildcard directory for the subdirectory:

FTDI_drivers

There are named folders for the various Windows platforms (Windows XP, etc.) containing the driver installation files for that operating system.

The easiest way to install the drivers is to plug in the USB Wildcard via the appropriate USB cable to your PC.  The PC should recognize the FTDI USB device.  If the FTDI USB drivers are not already present, Windows will start a “wizard” to guide you through the driver installation.  When the wizard asks you to specify a directory that contains the drivers, you can browse to the directory containing the FTDI USB drivers, and the wizard will choose the correct driver and install it. 

Customizing the EEPROM on the USB Wildcard

Using the Windows Device Manager to View USB Properties

USB is a “plug and play” protocol: when a USB device is plugged into a PC running Windows, the operating system automatically detects it and, if the proper PC drivers are available, establishes communications with the USB peripheral device.  The Windows “Device Manager” lets you view the status and properties of all USB devices known by the operating system.

On a Windows XP machine, you can get to the Windows Device Manager by right clicking on the “My Computer” icon on your Windows desktop, selecting “Properties” from the drop-down box, selecting the “Hardware” tab in the System Properties dialog box, and choosing the “Device Manager” button.  The Device Manager dialog box displays a list of devices. Expand the item labeled “Ports (COM and LPT)” to view the virtual communications ports including any installed USB Wildcards.  The USB Wildcard will appear as an entry such as “USB Serial Port (COM4)”.  In this example, the “COM4” describes the communications port assigned to the USB Wildcard.  This COM port information is used to configure the Mosaic Terminal as described in the next section.

Using the Mosaic Terminal with the USB Wildcard

The USB Wildcard can provide an interactive link between a Mosaic controller and a PC.  A convenient interface for this link is the Mosaic Terminal, available on the distribution CD and on Mosaic’s website (www.mosaic-industries.com).  When you first start the Mosaic Terminal, if more than one terminal window is open you may get a warning such as “Port already open”; you can ignore this warning.

To use the Mosaic Terminal, you’ll need to specify the COM port number.  To find the currently assigned COM port number, follow the instructions in the prior section (“Using the Windows Device Manager to View USB Properties”).  Open the Mosaic Terminal, and in the Settings>Comm menu item, activate the drop-down box labeled “Port” and choose the correct COM port number (COM1 through COM9 are available). 

To test this capability, use the USB_Demo program as described in the next section. 

Once the Mosaic Terminal program establishes communications with the USB Wildcard, unplugging or powering down the Wildcard will display a Mosaic Terminal message such as “Internal error retrieving device control block for the port”.  Acknowledging this error exits the Terminal program.

Mosaic USB Driver Software

A package of pre-coded device driver functions is provided to make it easy to control the USB Wildcard.  This code is available as a pre-compiled "kernel extension" library to C and Forth programmers.  Both C and Forth source code versions of a demonstration program are provided.  This demo program illustrates how to initialize and use the USB Wildcard in a multitasking application.

Overview of the Mosaic USB Software Device Driver Functions

The USB Wildcard driver code makes it easy to direct serial input and output via the USB port.  A demonstration program shows how to use the functions, and how to revector the serial primitives so that standard I/O print routines (such as printf in C and .” in Forth) will automatically use the USB Wildcard port.

Most of the Mosaic USB driver functions accept as an input parameter the USB Wildcard number (0 through 7). The remaining functions take the contents of the usb_module variable to specify the wildcard module number. The Wildcard number passed to the software functions, and the contents of the usb_module variable (as set by the USB_MODULE_NUM constant in the demo program) must correspond to the hardware jumper settings as described in Table 1‑3 above. 

The fundamental serial I/O routines are called USB_Emit_Module, USB_Ask_Key_Module, and USB_Key_Module. Each accepts a Wildcard module number as an input parameter.  The corresponding routines that access the module number in the usb_module variable are called USB_Emit, USB_Ask_Key, and USB_Key. These routines have the correct parameter list to enable revectoring of serial I/O functions as illustrated in the demonstration program.

USB_Emit_Module and USB_Emit each accept a character which is queued in the output buffer for transmission on the USB port. USB_Ask_Key_Module and USB_Ask_Key test whether an input character is pending in the receive buffer; if so, a true (-1) flag is returned, and if not, a false (0) flag is returned. USB_Key_Module and USB_Key each return the next pending character in the input buffer; if the buffer is empty, the function waits for a character and returns it.

The USB_Revector function installs the USB serial primitives in the current task so that the task’s serial I/O routines use the USB port.  For example, after executing USB_Revector, a printf statement in a given task would print via the USB Wildcard port.

The USB_Send_Immediate_Wakeup function causes any characters in the output buffer to be sent immediately if the USB port is active.  If the USB port is suspended, executing this function requests a “wakeup” from the PC host.

For detailed specifications regarding control of the communications port, refer to the FTDI USB data sheet (FTDI Part# FT245BM).

Demo Illustrates Revectoring of Serial I/O

The demonstration program presents an example of how to use the USB port.  The multitasking operating system on the Mosaic Controller allows each task to access its own distinct serial I/O channel by pointing the three primitives Emit, Ask_Key (called ?KEY in Forth), and Key to the desired serial I/O handler functions. The advantage of revectoring is that higher level serial management functions that accept and print characters and strings will then use the designated serial channel.  The USB_Monitor function in the demonstration performs the revectoring, and then calls functions that perform interactive echoing via the specified serial channel on the USB Wildcard.  The Run_Demo function (or the main function in C) starts and runs the multitasking demonstration using the USB Wildcard.  The demonstration program source code is presented in a later section.

Installing the Mosaic USB Wildcard Driver Software

The USB 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 library functions are accessible from C and Forth. 

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 specify the USB Wildcard Drivers 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 USB Wildcard is available from Mosaic Industries on the Demo and Drivers media (diskette or CD).  Look in the Drivers directory, in the subdirectory corresponding to your hardware (the Mosaic Controller of your choice) in the USB_Wildcard folder.

The kernel extension is shipped 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   - The installation file, to be loaded to COLD-started Mosaic Controller.

   ◙   library.4th - Forth name headers and utilities; prepend to Forth programs.

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

Library.c and library.h are only needed if you are programming in C. Library.4th 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.

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. Start the Terminal software with the Mosaic Controller connected to the serial port and turned on.  If you have not yet tested your Mosaic Controller and terminal software, please refer to the documentation provided with the Terminal software.  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.

Now, type

COLD

again and the kernel has been extended!  Once install.txt has been loaded, it need not be reloaded each time that you revise your source code.

Using the Mosaic USB Driver Code with C

Move the library.c and library.h files into the same directory as your other C source code files.  After loading the install.txt file as described above, use the following directive in your source code file:

#include “library.c”

This 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 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 USB functions.

To load the optional demonstration program described above, use the “make” icon of the C compiler to compile the file named

            usbdemo.c

that is provided on the distribution media.  Use the terminal to send the resulting usbdemo.txt file to the Mosaic Controller, and type main to run the program.  See the demo source code listing below for more details.

Note that all of the functions in the kernel extension are of the _forth type. While they are fully callable from C, there are important restrictions.  First, the _forth functions may not be called as part of a parameter list of another _forth function. Second, _forth functions may not be called from within an interrupt service routine unless the instructions found in the file named

            \fabius\qedcode\forthirq.c

are followed (this second restriction is lifted for V6.xx kernels as shipped with the PDQ line).  Also, in most cases Key and Emit functions should not be called from within interrupt service routines, because these routines call PAUSE, and use of PAUSE within an interrupt routine can halt the multitasker.  

Using the Mosaic USB Driver Code with Forth

After loading the install.txt file and typing COLD, use the terminal to send the “library.4th” file to the Mosaic Controller.  Library.4th sets up a reasonable memory map and then defines the constants, structures, and name headers used by the USB Wildcard kernel extension. Library.4th 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) can become corrupted since it is stored in flash on a page that is not typically accessed by code downloads. 

We recommend that your source code file begin with the sequence:

WHICH.MAP 0=
IFTRUE 4 PAGE.TO.RAM  \ if in standard.map...
       5 PAGE.TO.RAM
       6 PAGE.TO.RAM 
      DOWNLOAD.MAP
ENDIFTRUE

This moves all pre-loaded flash contents to RAM if the Mosaic Controller is in the standard (flash-based) memory map, and then establishes the download (RAM-based) memory map.  At the end of this sequence the Mosaic Controller is in the download map, ready to receive additional code. 

We recommend that your source code file end with the sequence:

4 PAGE.TO.FLASH
5 PAGE.TO.FLASH
6 PAGE.TO.FLASH
STANDARD.MAP
SAVE

This copies all loaded code from RAM to flash, and sets up the standard (flash-based) memory map with code located in pages 4, 5 and 6.  The SAVE command means that you can often recover from a crash and continue working by typing RESTORE as long as flash pages 4, 5 and 6 haven't been rewritten with any bad data.

<< Previous | Next>>