USB Wildcard Glossary

The USB Wildcard™ implements a standard USB (Universal Serial Bus) interface that enables a PC host to communicate with Mosaic's microcontroller-based embedded computers to implement remote data loggers, data acquisition systems, and instrumentation. This tiny 2" by 2.5" board is a member of the Wildcard series of mezzanine boards that connect to Mosaic embedded instrument controllers.

C language library functions cover sending and receiving serial data, revectoring the controller's serial input through the USB port, managing communications buffers for received characters, and creating tasks for communication through the USB serial port.

The main glossary entries presented in this document are listed in case-insensitive alphabetical order (the underscore character comes at the end of the alphabet). The keyword name of each entry is in bold typeface. Each function is listed with both a C-style declaration and a Forth-style stack comment declaration as described below. The "C:" and "4th:" tags at the start of the glossary entry distinguish the two declaration styles.

The Forth language is case-insensitive, so Forth programmers are free to use capital or lower case letters when typing keyword names in their program. Because C is case sensitive, C programmers must type the keywords exactly as shown in the glossary. The case conventions are as follows:

• Function names begin with a capital letter, and every letter after an underscore is capitalized. Other letters are lower case, except for capitalized acronyms such as "USB".
• Constant names and C macros use capital letters.
• Variable names use lower case letters.

Each glossary entry starts with C-style and Forth-style declarations, and presents a description of the function. Here is a sample glossary entry:

The C declaration specifies that return data type before the function name, and lists the comma-delimited input parameters between parentheses, showing the type and a descriptive name for each.

The Forth declaration contains a "stack picture" between parentheses; this is recognized as a comment in a Forth program. The items to the left of the double-dash ( -- ) are input parameters, and the item to the right of the double-dash is the output parameter. Forth is stack-based, and the first item shown is lowest on the stack. In the Forth declaration the parameter names and their data types are combined. All unspecified parameters are 16-bit integers. Forth promotes all characters to integer type.

The presence of both C and Forth declarations is helpful: the C syntax shows the types of the parameters, and the Forth declaration provides a descriptive name of the output parameter.

C: int USB_Ask_Key ( void )
4th: USB_Ask_Key ( -- flag )

Returns a flag indicating the receipt of a character on the USB port. The flag is true true (-1) if there is at least one character in the input buffer. Otherwise the returned flag is false (0). See also USB_Ask_Key_Module and USB_Revector.

C: int USB_Ask_Key_Module ( int module_num )
4th: USB_Ask_Key_Module ( module_num -- flag )

Returns a flag indicating the receipt of a character on the USB port. The contents of the usb_module variable specifies the module number. The flag is true (-1) if there is at least one character in the input buffer of the specified channel. Otherwise the returned flag is false (0). See also USB_Ask_Key and USB_Revector.

C: void USB_Demo ( void )
4th: USB_Demo ( -- )

The top level function in the demonstration program. When called, it builds and activates a task named USB_TASK which runs the infinite loop USB_Monitor program to exchange data on the USB port. The task revectors the Emit, Key and Ask_Key (also called ?KEY) primitives so that all task I/O is implemented via the USB Wildcard. The default QED-Forth task stays active using the serial port on the Mosaic Controller. Thus, invoking this function allows you to simultaneously run an additional serial connection on the Mosaic Controller. To exercise the demo, start the Mosaic terminal and set its Settings→ Comm→ Port to the USB Wildcard's hardware port assigned by your PC (use your PC's "Hardware Device Manager" to find out which port is assigned to the Mosaic USB Wildcard).

C: void USB_Emit ( uchar character )
4th: USB_Emit ( char -- )

This function queues the specified character in the output buffer for transmission on the USB port. The usb_module variable specifies the module number. If the output buffer is full, this routine waits and PAUSEs until there is room in the buffer, then puts the specified character in the buffer so that it will be transmitted. See also USB_ Emit_Module and USB_Revector.

C: void USB_Emit_Module ( uchar character, int module_num )
4th: USB_Emit_Module ( char \module_num -- )

Queues the specified character in the output buffer for transmission on the USB port. If the output buffer is full, this routine waits and PAUSEs until there is room in the buffer, then puts the specified character in the buffer so that it will be transmitted. See also USB_Emit and USB_Revector.

C: void USB_Flush ( int module_num )
4th: USB_Flush ( module_num -- )

Reads and discards any input characters that are present in the receive buffer of the specified USB module. This function is useful when initializing the USB port to ensure that any "garbage" characters in the input buffer are discarded.

C: uchar USB_Key ( void )
4th: USB_Key ( -- char )

Waits (if necessary) for receipt of a character from the USB port, and returns the received character. The usb_module variable specifies the module number. PAUSEs while waiting. The returned byte is the next pending character in the input buffer (that is, the oldest unretrieved character in the receive buffer). See also USB_Key_Module and USB_Revector.

C: uchar USB_Key_Module ( int module_num )
4th: USB_Key_Module (module_num -- char )

Waits (if necessary) for receipt of a character from the USB port on the specified Wildcard module, and returns the received character. PAUSEs while waiting. The returned byte is the next pending character in the input buffer (that is, the oldest unretrieved character in the receive buffer). See also USB_Key and USB_Revector.

C: int usb_module
4th: usb_module ( -- xaddr )

A 16-bit variable that holds the module_num of the USB Wildcard. The contents of this variable are used by USB_Ask_Key, USB_Key, USB_Emit, and USB_Revector. Functions that rely on this variable are not re-entrant.
Note: It is possible to install and control more than one USB Wildcard on a single controller, but in this case the functions USB_Ask_Key_Module, USB_Key_Module, and USB_Emit_Module should be used to specify which module is being accessed.

C: USB_MODULE_NUM
4th: USB_MODULE_NUM ( -- n )

A constant in the demonstration program whose value equals the Wildcard number. This value must correspond to the jumper settings as shown in Table 1-3. Edit the source code of the demonstration program so that the value of this constant matches your hardware jumper settings. This constant is used by the demonstration program to initialize the usb_module variable; see its glossary entry.

C: void USB_Revector ( void )
4th: USB_Revector (-- )

Revectors serial I/O in the current task to use the USB wildcard port whose module number is stored in the usb_module variable. After executing this function, the serial I/O primitives Emit, Key, and AskKey (?KEY in Forth) will execute USB_Emit, USB_Key, and USB_Ask_Key, and higher level print and scan functions that invoke these primitives in the current task will use the USB port.

C: void USB_Send_Immediate_Wakeup ( int module_num )
4th: USB_Send_Immediate_Wakeup ( module_num -- void )

If the USB port is active, this routine forces the immediate sending of all characters in the USB transmit buffer. If the USB port is suspended, this function requests a wakeup from the PC USB host. Implementation detail: Briefly strobes the USB chip's SI_/WU pin active low.

See also → USB C Demo
USB Forth Demo