Terminal (Software User Interface) : Allows direct user interaction with the
wideband controller or display's inbuilt user interface.
Apart from issuing commands that are executed immediately, a number of related functions are also launched from this tab, including:
Terminal - Buttons, Options, etc.
In the command area, immediately to the right of Cmd :, you enter commands to the device currently connected to the COM port (refer to the General tab. Results are sent back and displayed in the results-area in the lower section of the screen. You can enlarge the display area by resizing it - you will be prevent from making it smaller than 400 x 540.
The way data is displayed can be controlled with the drop-down menu to the right of the [CLS] button. - selecting As ASCII works for most commands (selecting Bytes in Hex or one of the Frame modes shows raw binary data in a more readable format).
Configuration Memory and Configuration Variables
Typically a command either performs an immediate action or reads or modifies a memory variable. Memory variables are stored in either RAM memory or EE memory. RAM memory is used for variables (RAM variables) that are accessed often. EE memory is used for tables and variables that are not often accessed. Configuration RAM memory variables (conf vars) control how the device is configured. During start-up, as a means of configuring the device, conf vars are pre-set by copying them all from a special area of EE memory (called conf EE memory). To permanently re-configure a device the conf RAM variables must be written back to conf EE memory. Different commands modify these different areas of memory
Configuration Variables (called Conf Vars). Conf vars modify the operation of the device and are located in a special part of memory called Configuration Memory or Conf RAM (sometimes abbreviated to just Conf). When the device is powered up Conf RAM is created from a permanent copy of itself in EEPROM memory (abbreviated to EE memory). Other less often used tables are saved directly in EEPROM memory and are not copied to Conf RAM.
Commands are used to read and write Conf RAM (g, s), copy it to EEPROM (w), reload Conf RAM from EEPROM (l), and other commands (r and u which may change in the future). EE tables that are not copied to Conf RAM are read and written with their own specific commands that use a 16 bit address (a & e). Conf commands use an abbreviated 8 bit address as there are less than 255 Conf RAM locations (actual Conf size depends on the device).Some commands relate to a third type of optional memory the device may contain called on-board logging memory. A rudimentary file system is used to allow access to the larger memory sizes (see the k, q, x, y and z commands
Other commands allow hardware registers to be set up for testing, calibration and other maintenance tasks like re-flashing.
Warning : Controllers will normally put out a continuous binary data stream. To Windows® the controller data stream looks a little like that from a serial mouse. So, make sure you have the wideband unit disconnected from the COM or USB port, or powered down, when booting your PC.
Note: binary data from a controller may appear as a garbage so you need to either select the correct As Xxxx filter, or temporarily turn off continuous data by issuing the command tf to the controller. Another scheme is to slow the data speed from the controller (use command s047f).
Basic Commands - ASCII text with Parameters
The format of the commands is quite rigid to avoid complex error handling that would take up code space in the device. No white space is allowed between the single command letter and its parameter(s). The parameters are either zero (none), one, two or four hexadecimal (hex) characters in width. An example of this is the e command used to read EEPROM memory.
e012345 - 7 character command writes 45 (hex) to address 0123 (EEPROM)
In the above command 0123 is the 16 bit (4 hex digit) address and 45 (hex) is the data to write (to EEPROM).
All commands provide feedback that they have successfully completed, or they return the error string Err <cmd> where <cmd> is the command that could not be executed. In the above example, the e012345 command will return the following string:
> 0045 - data 45 was written correctly to EEPROM
Note that there is a <cr><lf> pair before the > symbol. Commands that are not understood (usually because the parameters have the wrong size) are indicated as follows:
Err g00d - g00d is an error (g00 is a good command!)
The following table lists all documented commands that may or may not work as advertised on all controllers. They are not in alphabetic order, but grouped by function. The first column (Cmd) is the single command letter. The second column lists the parameter(s). The third column indicates the format of the response and fourth column indicates what action results from the command. The last column provides more explanation.
|v||-||vers||Display the 4 character hex firmware version||This should match the HXF file. Also used for software reflash setup.|
n = 0
n = F
0 < n < F
|serial logging control, n = single hex character
||The Tx auto-gen flag controls whether serial data frames are automatically generated or not.
A single Tx frame will be generated with the t0 command.
The actual format of the data is determined by a Conf variable.
|a||n ad16||data16||Read EEPROM (n=0) or RAM (n=8)
||The AVR architecture divides non-code memory into EEPROM and RAM,
The a and e commands read and write to those two memory types
with the MSB of the address determining which type is accessed.
eg: e002345 writes 45 to EEPROM address 0023 - the word returned is address (0023).
for the a command the returned value is the 8 bit data there (as a 16 bit value).
|e||ad16 dat8||ad16||Write EEPROM (MSB=0) or RAM (MSB=1)
MSB as for the a command.
|s||adr8 dat8||code||set config byte at adr8 to value dat8||The first section of RAM is called Conf RAM as special configuration data is stored there at run-time. Conf RAM can be read with the g and written with the s commands.|
|g||adr8 ≠ FF
adr8 = FF
|l||-||code||(ie. lower-case L) reload conf-RAM based data from EEPROM||Conf RAM is loaded from EEPROM at startup (like l command)
to make access to it much faster.
If conf RAM changes then the complete EEPROM copy can be updated with the w command.
See next section for extended commands using w
|w||-||code||write conf-RAM based config data to EEPROM|
|r||-||code||reload conf-RAM from ROM (note: command may change)||these two commands (r & u are debug commands and may change or be removed in future versions.|
|u||-||code||update system params from conf-RAM|
|b||vers||(none)||Software reflash setup. vers = firmware version.||Vers must match the firmware (see v command).
See next section for extended commands using b
|m||n||state||Sets the WBo2 main state n
||This does not work for displays (returns an error). Use this only for special testing/debug.
|d||n dat12||w||sets DAC to value dat12 (address embedded)
||The (two channel, 12 bit) hardware DAC is used to both control the wideband sensor
and to provide a wideband output voltage.
|p||n dat10||w||sets PWM value to dat10 (address embedded)
||The (10 bit) PWM output is used to generate the lower accuracy NBsim and SVout voltages.
|i||chn mux||data||reads ADC channel chn with MUX set to mux||The CPU reads analog data from a channel via a MUX input. Different hardware may use different channels and mux input assignments.|
|k||-||string||Read the memory-type string
||Logging to on-board memory and retrieval of logged data is controlled by these 5 commands.
The original 2A0 hardware supported just the 32 kbyte EE memory with the
x and z commands.
Newer hardware (2A1) supported the 1 Mbyte logging module (SST)
and added the q, y & z commands.
More information can be found here.
See next section for extended commands using q
|query SST on-board logging memory status
|x||n||ptr||stop/start logging to on-board logging memory
|z||-||<data>||dump logged data stored in onboard memory|
As noted above, commands interpreted by the device are purposely very simple and have a rigid structure. The primary reason for this is to limit the size of the device's command interpreter (saving code space for useful functionality). Another consideration is to make it easy for someone to enter data, and to this end we can use some intelligence within WButil's terminal itself.
To simplify the entry of data larger than 8 bits in width, the terminal program pre-interprets command-letters b, w & q so they are given new meaning. When the menu item Options -> Interpret Commands Intelligently is checked. These modified commands either read, or if data is supplied, write, Conf-RAM in units of byte (8 bits), word (16 bits) or quad-byte (32 bits). The format of <data> is hex by default, but adding a period (ie. a dot) after the data changes the <format> to decimal. Data can be explicitly declared as hex with the $ symbol. Negative data (but only for decimals) can be entered too by preceding it with a minus (ie. hyphen). Note that <address> is always in hex form. The form of commands is shown below - note that the space between the <address> and <data> is mandatory:
<command-letter> <address> - Read data <command-letter> <address> <data>[<format>] - Write data
Here are some examples.
w 23 - No data so read word at address 0x023 b 23 19. - write the same word with data byte 0x13 (decimal 19.) b 23 -2. - write -2. (= 0xFFFE) to the same address w 12 567 - write hex word 0567 to address 012 q ab 12345678 - write hex 12345678 to address 0AB
Note that the interpretation of these commands occurs in the WButil program itself. A single intelligent-command may result in multiple simple-commands being issued to the device.