UBW Firmware D v1.5.x Documentation

PROPOSED Documentation for Firmware D, version 1.5.x for UBW Boards
Back to main UBW page
NOTE: FW D 1.5.x is not out yet - no HEX file or source is available yet
FW D 1.5.x has been delayed due to other projects - final release date is currently planned for spring '08

Description:
Firmware version D is a more advanced (and more complicated) firmware version than Firmware C. Whereas C just allows you to write out 8 bits at a time to Port B, Firmware D allows you to use every one of the 19 I/O pins on the UBW Board as an input or an output, and to read the state of every one of those pins. In order to do this, it has an actual command structure that must be followed when communicating with it. (Note that there are 3 I/O lines on PortC of the assembled SparkFun version of the UBW board that are difficult to access. The UBW kit from SparkFun has a header for these three I/O lines - they normally control the two LEDs and read the PRG switch.)

28 vs 40 pin UBW designs:
So far, there are two basic groups of UBW boards in existance -

Ones based on the 28 pin PIC (18F2455 or 18F2550)

The origional 28 pin DIP versions I made, as well as the SOIC version I made
The origional SMT (Surface Mount Technology) assembled UBW that SparkFun sells
The the new PTH (Plated Through Hole) UBW kit that SparkFun sells
Any UBWs built based upon any of the above designs

Ones based on the 40/44 pin PICs (18F4455 or 18F4550)

My 44 TQFP and 44 DFN UBW boards
Some custom designs that others have built with the 18F4550

This version of Firmware D contains code to run on both types of UBW boards. The same project files, the same HEX file. When the program runs, it queries the PIC to see what type of processor it is runnign on, and then modifies its behavior accordingly. Any parameters having to do with PortD or PortE are obviously not very usefull on the 28 pin designs. Use the "V" command and parse its output so that your PC application can know what type of UBW board it is talking to.

Version Notes:

Version 1.5.0 (XX/XX/XX)

Added "TP" command for toggleing an output pin [CODED]
Added "SL" command for latching ability on digital inputs [CODED]
Added "RO" command for writing to just one 8-bit port [CODED]
Added "RI" command for reading from just one 8-bit port [CODED]
Added "SC" and "SO" command to enabled unlimited outputs via simple serial shift registers [CODED]
Added "PW" PWM command (Thanks Giles!)
Updated "MR" and "MW" commands to allow reading and writing of EEPROM data storage area [CODED,TESTED]
Added "EC" and "ES" for simple stepper motor motion
Added serial number for same COM port every time. See NOTE 4 under the "MW" command for more information. [CODED,TESTED]
Added backspace ability for terminal emulator usage [CODED,TESTED]
Added code that allows main loop to continue running after USB connection is terminated (Thanks Paul!) [CODED]
Changed command parsing so optional paramters can be left off to save time (Thanks Steven for the idea!) [CODED]
Although some support existed in 1.4.2, this version has complete support for 40/44 pin UBW designs [CODED]
Added "TX", "RX", and "CX" commands to utilize the USART (i.e. async serial I/O) (Thanks again Paul!)
All commands now send an OK packet (default is ON, change with CU command.) [CODED]
Added support for echoing all commands sent to UBW back to PC (default is ON, change with CU command.) [CODED]

Version 1.4.2 (5/25/07)

Fixed a major bug in RC command, where RC,<x>,<y>,0 would not actually stop the RC output.
Changed project files so that both a 40pin and 28pin version of FW D share same directory structure.

Version 1.4.1

Changed blink rate of normal orange (yellow) "connected" LED so that you can easily tell if you have 1.4.1 or above on your board. (It used to be long-long-long-long and now it is long-short-long-short.)

Version 1.4.0

Adds RC command to allow RC Servo output on 19 I/O pins
Adds BC (bulk configure), BO (bulk output) and BS (bulk stream) commands
New error messages, now complete strings, much more informative
Adds CU command (configure UBW) to allow different configuration options
New internal command buffer framework
Multiple internal changes to parameter parsing and sending data back to PC
Removed the limitation for T command of 10ms as fastest update interval. 1ms update rate is now allowed for both analog and digital packets, although care must be used at high speeds

Version 1.3

Fixes a bug in 1.2 that prevented some users' UBW boards from being recognized by windows, among other problems.

It also added an "OK" packet as a reply to all commands that didn't previously have reply packets from the UBW. This allows easier testing with a terminal emulator.

It also fixed a bug with the "R" command so that it works now.

Version 1.2

Added reading up to 9 analog inputs (10 bit, 0 to 5V) ("A" command and new mode of "T" command)
Reading and writing anywhere in memory (PEEK and POKE basically) ("MR" and "MW" commands)
Doing operations on just a single pin (set the pin direction, read the pin, write to the pin). ("PO", "PI" and "PD" commands)
Fixes a bug in version 1.1 that would prevent the UBW from receiving new characters if it's output buffer was full. This would require a UBW reboot and some playing around on the PC side (closing/opening the COM port) to fix.

Version 1.1

First publicly released version, and the version that SparkFun ships on their boards.

Commands:
Notes for ALL commands:

You end a command by sending a <CR> or <LF> or some combination of the two. This is how all commands must be terminated to be considered valid.
The total number of bytes of each command, counting from the very first byte of the command name up to and including the <CR> at the end of the command must be 64 bytes or less. If it is longer than 64 bytes, the command will be ignored, and other bad things may or may not happen. This limitation will hopefully be removed in future FW D versions.
You can string together as many commands as you want into one string, and then send that string all at once to the UBW. As long as each individual command is not more than 64 bytes, this will work well. By putting many commands together (each with their own terminating <CR>) and sending it all to the UBW at once, you make the most efficient use of the USB bandwidth.
After successful reception of a command, the UBW will always send back an OK packet, which will consist of "OK<CR><LF>". For just testing things out with a terminal emulator, this is very useful because it tells you that the UBW understood your command. However, it does add extra communications overhead that may not be appreciated in a higher speed application. Starting with version 1.4.0 you can use the CU command to turn off the sending of "OK" packets. Errors will still be sent, but not any "OK" packets.
The backspace key now functions properly. This is really only useful for typing in a terminal emulator, as sending backspace characters in packets generated by an application simply uses up USB packet space with no productive result. [CODED,TESTED]
All command names ("C", "BC", etc.) are case insensitive.
All port names ("A", "B", "C") are case insensitive
All parameters marked with square brackets [] rather than greater-than and less-than signs <> are considered optional. This means that you may leave the parameters out, and the UBW will not consider it an error. Normally this is just used where there are mulitple port parameters (for ports A through E). HOWEVER - all paramters up to the last parameter you include must be present. For example, in the C command, you can't skip the [DirB] paramter but include the [DirC] parameter. How would the UBW know which was which? So you can choose to leave off as many optional parmaters starting from the end (right hand side) of the command as you want, but all paramters used must be in order and not skip any.
You should always use the "V" command to see what type of UBW you are running on - it will return the chip type at the end of the version string. If you get a 4550 or 4455, then you are running on a 40 pin UBW, which means that all command parameters dealing with PortD and PortE will function. Obviously these parameters will do nothing on the normal 28 pin UBW.
Thanks to Paul's code snippit, the main processing loop continues to run even if there is not an active USB connection. However, the code that sends commands up to the PC, and the code that receives commands from the PC, becomes inactive if there is no USB connection. This feature allows you to set up your UBW, and (if powered from some other source than the USB cable) unplug the USB cable and continue to have your UBW stay in the same state, and continue to do whatever you had it doing before the disconnect.

The "TP" Command (New for 1.5.0)

The "TP" command stands for "Toggle Pin". It allows you to generate a pulse on a single pin. If the pin is set to be an output, then this command will invert the state of the pin, then return it to its origional state. The time between these events is controlled through a system parameter, and can be set using the CU command.
Format: "TP,<Port>,<Pin><CR>"
<Port>: This is the character "A", "B", "C", "D", or "E" depending upon which port you want to set.
<Pin>: This is a number between and including 0 to 7. It indicates which pin in the port for which you want to set the state.
Example: "TP,B,2" - This would toggle PortB bit 2.

The "SL" Command (New for 1.5.0)

The "SL" command stands for "Set Latch". It only has an effect on pins that are configured as digital inputs. If you turn on the Latching function for a pin using this command, then any time a change of state is detected on that pin, the new state will be 'latched'. Reading the pin (using the PI, TI or I commands) clears the latch. The UBW will sample each pin every 1ms (the internal timer rate) and if latching is turned on for a pin, retain the new state of that pin until a PI, TI, or I command comes in that reads the pin. This allows very slow polling to still gaurentee that all pulses greater than 1ms in length will get seen, even if the computer is polling using the PI, TI or I command every second. This may be usefull if you are trying to read the state of a push-button switch. For example, if your input starts out low, has latching turned on, then the pin sees a 1.1ms high pulse, the next read of that pin by the computer will read high, even if that read comes long after the pulse is done. Each time this command is sent, the internal 'latched state' of each port is read from the I/O pins and saved. This becomes the 'starting state'. Any time an I/O pin changes from this starting state, the new value is saved in the 'latched state' and will not be allowed to change until a PI, TI or I command reads that port. Once the latched data from the port has been read, any change from the latched value will be latched for the next read, and so on.
Format: "SL,<PortA>,[PortB],[PortC],[PortD],[PortE]<CR>"
<PortX>: Each of these are numbers between 0 and 255. Any bit that is set will turn on the latching feature for the corresponding pin. On reset, latching is turned off for all pins. (i.e. "SL,0,0,0,0,0")
Example: "SL,0,4" - This turn the input latching feature on for PortB bit 2.

The "TO" Command (New for 1.5.0)

The "TO" command stands for "porT Output". It allows you to output a single byte to a single port.
Format: "TO,<Port>,<Value><CR>"
<Port>: This is the character "A", "B", "C", "D", or "E" depending upon which port you want to set.
<Value>: This is a number between and including 0 to 255. It is the value that is writtten to the LATch (output latch) register of the given port.
Example: "TO,B,8" - This would write the value 8 (0b00001000) to PortB.

The "TI" Command (New for 1.5.0)

The "TI" command stands for "porT Input". It allows you to read the state of the pins on just one port.
Format: "TI,<Port><CR>"
<Port>: This is the character "A", "B", "C", "D", or "E" depending upon which port you want to read.
Example: "TI,C" - This would read the state of the pins on PortC.
Return Packet Format: "TI,<Value>", where <Value> is the 8-bit number (from 0 to 255) that indicates the current value, or status, of the pins on that port.
Return Packet: "TI,56"

The "PW" Command (New for 1.5.0)

The "PW" command stands for "PWm". It allows you to create a PWM output on any digital output pin. This PWM signal can be used to dim an LED, to generate pulse trains, or, with a little bit of filtering (probably just a cap and resistor) you can generate analog outputs with it. Note that you can turn PWM on for pins on all ports simultainously if you want. Make sure the pin is already an output, or you won't see much. The <Value> is in units of XXX, and the PWM has a repeat rate of XXXms. When you send a new value for a pin that is already outputting a PWM value, the new PWM value only gets used once the current PWM cycle is over, so there are no glitches on the output. A <Value> of zero means the pin will never go high, a <Value> of 255 means the pin will always stay high.
Format: "PW,<Port>,<Pin>,<Value><CR>"
<Port>: This is the character "A", "B", "C", "D", or "E" depending upon which port you want to affect.
<Pin>: The particular pin you want to enable PWM on (0 through 7).
<Value>: The value for the PWM cycle (NEED MORE).
Example: "PW,B,5,23" - This would turn PWM output on for PortB pin 5 at a level of 23.

The "SC" Command (New for 1.5.0)

The "SC" command stands for "Serial Configure". It configures the pins for use with the "SO" command. It defines the data pin, the clock pin, and the latch pin and their inital states. Make sure all necessary pins are set up as outputs before using the SO command.
Format: "SC,<DataPort>,<DataPin>,<DataState>,<ClockPort>,<ClockPin>,<ClockState>,<LatchPort>,<LatchPin>,<LatchState><CR>"
<DataPort>, <ClockPort>, <LatchPort>: These parameters specify the port you want to use for your each function, "A", "B", "C", "D", or "E".
<DataPin>, <ClockPin>, <LatchPin>: These parameters specify which pin (within the previously specified ports) are used for each function. Must be between or including 0 through 7.
<DataState>,<ClockState>,<LatchState>: These pameters specify the inital states (high or low, 1 or 0) for each of the three functions.
Example: "SC,B,0,0,B,1,1,B,2,0" - This would tell the SO command to use PortB bit 0 for data starting low, PortB bit 1 for Clock starting high, and PortB bit 2 for latching starting low

The "SO" Command (New for 1.5.0)

The "SO" command stands for "Serial Output". It allows you to clock bytes of data out to serial shift registers like the 74HC595. You can chain togehter an unlimitd number of these 8-bit serial to parallel converter chips to expand the output capibility of your UBW to any number of bits. You should always set up with the "SC" command before you begin to use the "SO" command. When you send an SO command, the UBW will read in each data byte, starting with <Data1>. For each byte, it will invert the data pin if the least significant bit of the data byte is 1, and set the data pin to its default state if the data bit is 0. It will then toggle the clock pin. Then it does the same with the next bit of the data byte, until all 8 bits are clocked out. It then moves on to the next data byte. This all happens as fast as the PIC can output data. After all of the data bytes have been clocked out, the UBW looks at the <Latch> paramter. If it was a 1, then it toggles the latch bit. If it was a 0, then the latch bit is left alone. This allows you to send many "SO" commands, and only latch the data out on the last one. If you had 1000 74HC595s all chained together, you would probably want to send out 100 "SO" commands, each with 10 data bytes, where the last "SO command had the <Latch> parameter set to 1.
Format: "SO,<Latch>,<Data1>,[Data2],[Data3]...<CR>"
<Latch>: This parameter needs to be a 1 or a 0. If this parameter is a 1, then after the last <DataX> byte is clocked out, the latch bit will be toggled to latch all of the newly written output values.
<DataX>: These are the data bytes that you want to send out. Each is a number between and including 0 through 255. You can add as many data bytes as you want to the command, up to the USB packet limit of 64 bytes total in the entire command.
Example: "SO,1,55,61,142,2,97"

The "EC" Command (New for 1.5.0)

The "EC" command stands for "stEpper Configure". It sets up the pins and paramters for the "SS" command below.
Format: "EC,<CR>"
<Port>: This is the character "A", "B", "C", "D", or "E" depending upon which port you want to read.
Example: "TI,C" - This would read the state of the pins on PortC.
Return Packet Format: "TI,<Value>", where <Value> is the 8-bit number (from 0 to 255) that indicates the current value, or status, of the pins on that port.
Return Packet: "TI,56"

The "ES" Command (New for 1.5.0)

The "ES" command stands for "stEper Step". It tells the steper motors set up with the "EC" command above to actually take some steps.
Format: "ES,<Port><CR>"
<Port>: This is the character "A", "B", "C", "D", or "E" depending upon which port you want to read.
Example: "TI,C" - This would read the state of the pins on PortC.
Return Packet Format: "TI,<Value>", where <Value> is the 8-bit number (from 0 to 255) that indicates the current value, or status, of the pins on that port.
Return Packet: "TI,56"

The "MR" Command (Updated for 1.5.0) [CODED,TESTED]

The "MR" Command stands for 'Memory Read'.
Format: "MR,<Address><CR>"
<Address>: To read the UBW's RAM, use a number between and including 0 to 4095. It is the address in the UBW's RAM (also known as SFR) that you wish to read. If you wish to read an EEPROM address, just use a value between and including 8192 to 8447. (The EEPROM on the UBW has actual address of 0 through 255. So you just add 8192 to the EEPROM address you want to read and use that with the MR command to read that EEPROM address.)
Example: "MR,3968" (asks the UBW to read the value in the PORTA register)
Return Packet: "MR,<Value>"
<Value>: This is a number between and including 0 to 255. It is the result of reading <Address>.
Example Return Packet: "MR,28"
NOTE: Please note that the UBW internal code reserves EEPROM locations 224 through 255. You may certinaly read these, but please don't write to them.

The "MW" Command (Updated for 1.5.0) [CODED,TESTED]

The "MW" Command stands for 'Memory Write'.
Format: "MR,<Address>,<Value><CR>"
<Address>: For writing to the UBW's RAM (also known as SFR) use a number between and including 0 to 4095. It is the address in the UBW's RAM that you wish to write into. If you wish to write into the UBW's EEPROM, use a value between and including 8192 to 8447. (This is 8192 + the EEPROM address you want to write to.)
<Value>: This is a number between and including 0 to 255. It is the value you wish to write into <Address>.
Example: "MW,3968,56" (asks the UBW to write the value 56 into the PORTA register)
NOTE: This command can be extremely dangerous unless you read the PIC datahseet and understand what you are doing. With this command you have the ability to write over all of the current RAM in the UBW - including all variables that the firmware is using, and all of the Special Function Registers in the PIC. It can be a very handy thing, but use it with caution.
NOTE 2: Please note that the UBW internal code reserves EEPROM locations 224 through 255. Please don't write to them. Use the addresses below 224 for your own use.
NOTE 3: When writing to EEPROM, other commands that depend upon steady interrupts (like the RC command for example) will have 'skips' in them, as writing to EEPROM automatically disables interrupts briefly.
NOTE 4: The UBW's serial number is stored in EEPROM locations 252, 253, 254 and 255, which are passed into the MW command as Addresses 8444 through 8447. This serial number is printed out at the end of the version string. (See the "V" command.) It also is used by Windows to know which COM port number to assign to a given UBW. By deftault, these EEPROM locations are in an erased state, which is all 1's (0xFF for each byte). When the UBW connects to the computer (when reset or plugged in) it reads location 252. If this location is 0xFF or 0x00, then the UBW will use a default serial number of "ABCD". However, if you want to connect more than one UBW to your computer, you MUST program these four EEPROM locations to something else so that each of your UBWs has a unique serial number. This is how the PC will know which COM port to assign to each UBW (so that the COM port numbers don't change each time you move your UBW around on the USB.) I suggest you use four bytes that are easily printable ASCII characters, but technically you can use whatever values you want. Each time you change your UBW's serial number and reset it, it will grab the next COM port number.

The "CU" Command (Updated for 1.5.0)

The "CU" command stands for "Configure UBW". It is designed to be a generic command for setting things that affect the general operation of the UBW.
Format: "CU,<Parameter>,<Value><CR>"
<Parameter>: This is an unsigned 8 bit value, representing the parameter number you wish to change. (See table below)
<Value>: This is a value who's meaning depends upon the <Parameter> number chosen.
Example: "CU,1,0" - This would turn off the sending of the "OK" packets after each command.

<Parameter>	<Value>	<Value> meaning
1	0 or 1	0 = Turn off "OK" packets 1 = Turn on "OK" packets (default)
2	0 or 1	0 = Turn off echoing of all data sent to UBW 1 = Turn on echoing of all data sent to UBW (default)
3	1 to 1000	Length of delay in <XXX> units for pulse in TP command (default 10)

The "C" Command:

The "C" command stands for 'Configure' and allows you to set the state of the port direction registers for ports A, B and C, as well as enable analog inputs. This allows you to turn each pin into an input or an output on a pin by pin basis, or enable one or more of the pins to be analog inputs.
Format: "C,<DirA>,[DirB],[DirC],[AnalogEnableCount],[DirD],[DirE]<CR>" where <DirX> is a value between 0 and 255 that indicates the direction bits for that port. A 1 is an input, a 0 is an output.

[AnalogEnableCount] If this value is sent as a zero, then all analog inputs are turned off and all of the pins behave as just digital inputs or outputs.
If [AnalogEnableCount] is sent as a value from 1 to 12, then one or more of the analog inputs (see below) are enabled and will start sampling every millisecond. Any value over 12 is an error. Use the "A" command to retrieve the values of the enabled analog inputs.

Example: "C,4,245,52,0,4,0"
Warning on Analog Inputs: It is very important that if you enable an analog input on a pin, that you set that pin as an input (set the proper <DirX> bit). If you have a pin set as an output in the <DirX> bit but have it enabled as an analog input, your analog reading will simply convert the current digital output voltage on the pin (which may be what you want, but probably not). Also, if you have a pin set as a digital output with the <DirX> bit, but DON'T enable it as an analog input and then apply analog input levels to the pin, that pin may draw excessive power because it may float around between a High (5V) and Low (0V). PICs are very robust, but be careful.
Analog Input Matrix:

If one or more of the analog inputs are enabled, then use this chart to see which number for <AnanlogEnableCount> enables which pins as analog inputs. The PIC core that all of the USB PICs are built on has 13 analog input channels. However, on the 28 pin parts (which are currently used in UBW designs) three of those analog inputs (AN5,AN6 and AN7) do not come out as pins. They still exist, and as far as Firmware D v1.2 is concerned, are treated exactly as all of the other analog input pins, so the show up in the "A" packet. Also, AN12 (the 13th analog input) is not available for Firmware D v1.2 use because enabling all 13 would create a USB packet greater than 64 bytes, which is not allowed.

<AnalogEnableCount>
value

AN11
RB4

AN10
RB1

AN9
RB3

AN8
RB2

AN7
N.A.

AN6
N.A.

AN5
N.A.

AN4
RA5

AN3
RA3

AN2
RA2

AN1
RA1

AN0
RA0

The "O" Command:

The "O" command stands for 'Output state' and will take the values you give it and write them to the port A, B and C data registers. This allows you to set the state of all pins that are outputs.
Format: "O,<PortA>,[PortB],[PortC],[PortD],[PortE]<CR>" where <PortX> is a value between 0 and 255 that indicates the value of the port pins for that register.
Example: "O,0,255,22"

The "I" Command

The "I" Command stands for 'Input state' and when you send the UBW an "I" command, it will respond with an "I" packet back that will hold the value of each bit in each of the three ports A, B and C. It reads the state of the pin, no matter if the pin is an input or an output. If the pin is configured as an analog input, the bit will always read low (0) in the "I" packet.
Format: "I<CR>"
Example: "I"
Return Packet: "I,<StatusA>,<StatusB>,<StatusC><CR>" where <StatusX> is a number from 0 to 255 that indicates the current value of the pins on that port. Note that <StatusX> will always be 3 characters long, which means that leading zeros will be added so that the return packet is always the same length regardless of the data values. If the UBW is a 40 pin variety, then there will also be a <StatusD> and <StatusE> for PortD and PortE on the end of the I packet.
Return Packet: "I,001,045,205"

The "V" Command

The "V" Command stands for 'Version' and when you send the UBW an "V" command, it will respond with a text string that looks something like this: "UBW FW D Version 1.5.0 on 18F2550". You can parse this string to find the version number and the type of PIC (so you can decide to use PortD and PortE).
Format: "V"
Return Packet: "UBW FW D Version 1.5.0 on 18F2550"

The "R" Command

The "R" Command stands for 'Reset to default state' and when you send the UBW an "R" command it will initialize all pins to digital inputs and stop any running timers.
Format: "R"

The "T" Command

The "T" Command stands for 'Timer read inputs' and when you send the UBW an "T" command, it will set the delay for one of two timers. When the timer times out, it will cause an "I" packet or "A" packet response to get sent to the PC.
Format: "T,<TimeBetweenPacketsInMilliseconds>,<Mode><CR>"
<TimeBetweenPacketsInMilliseconds>: The time between response packets is determined by the <TimeBetweenPacketsInMilliseconds> value, and is expressed as a number between (and including) 1 and 30000 . If you send a 10 for <TimeBetweenPacketsInMilliseonds> then a new packet response would be sent every 10ms. If you sent a value of 30000, then it would send a packet response every 30 seconds. If you want to turn off either timer so that no more packets are sent, send a <TimeBetweenPacketsInMilliseconds> of zero. You have to send a time of zero for both "I" and "A" timers if you want them both to turn off. Note: just because the UWB can kick out I and A packets every 1ms (at its fastest) doesn't mean that your PC app can read them in that fast. Some terminal emulators are not able to keep up with this data rate coming back from the UBW, and what happens is that the UBW's internal buffers overflow. This will generate error messages being sent back from the UBW. If you write your own custom application to receive data from the UBW, make sure to not read in one byte at a time from the serial port - always ask for large amounts (10K or more) and then internally parse the contents of the data coming in. (Realizing that the last packet may not be complete.) Note 2: It has been discovered that if an attempt is made to have all 13 channels of analog be reported any faster than every 4ms, then an internal UBW buffer overflow occurs. Be careful with the speed you choose for A packets. The maximum speed is based upon how many analog channels are being sent back.
<Mode>: If <Mode> is "0" then the "I" packet timer (digital input packet) is set and will generate "I" packets back to the PC. If <Mode> is "1" then the "A" packet timer (analog input packet) is set and will generate "A" packets back to the PC. Both timers can be active and sending back their respective packets at different (or the same) rates.
Note: The UBW is actually sampling the digital input pins at an extremely precise time interval of whatever you sent in the T command. The values of the pins are stored in a buffer, and then packet responses are generated whenever there is 'free time' on the USB back to the PC. So you can count the I packet responses between rising or falling edges of pin values and know the time between those events to the precision of the value of <TimeBetweenPacketsInMilliseconds>. This is true for <Mode>=0. For <Mode>=1, the analog inputs are sampled every 1ms. Each time the "A" timer times out, the latest set of analog values is used to create a new "A" packet and that is then sent out.
Example: "T,100,0" - this would send back 10 "I" packets per second, sampled every 100ms.
Example: "T,14,1" - this would sample all enabled analog inputs and send back an "A" packet every 14ms.
Return Packet: None directly. Note however, the "I" packet or "A" packet responses will start flowing at regular intervals after the T command is received by the UBW.
Note: If the "I" or "A" packet responses stop coming back after you've done a "T" command, and you didn't stop them yourself (with a "T,0,0" or "T,0,1") then what's happened is that the internal buffer in the UBW for I or A packet data has been filled up. (There is room for 3 I packets and 3 A packets.) This means that the USB system is too busy to get the packet responses back to the PC fast enough. You need to have less USB traffic (from other devices) or increase the time between packet responses.

The "A" Command

The "A" Command stands for 'Sample Analog Inputs'. When you send the "A" packet to the UBW, it will send back the last sampled set of analog inputs. All enabled analog inputs are sampled every 1ms, and stored. Whenever an "A" packet is received, the latest stored value for the analog inputs is sent back in a returning "A" packet.
Format: "A<CR>"
Example: "A"
Return Packet: "A,0145,1004,0000,0045" (The return packet would look like this if there were 4 analog inputs enabled with the "C" command). There can be up to 12 analog input enabled, and thus there might 12 numbers between 0 and 1023 after the "A,". See the chart in the "C" command above for information on which analog inputs correspond to which pins. The numbers represent the analog voltage on each enabled analog input from 0V (0000) to 5V (1023). The first number after the "A," is for AN0, and the last number is for the highest analog input channel (ANx) that is currently enabled.

The "PD" Command

The "PD" command stands for "Pin Direction". It allows you to set the direction on just one pin at a time. (Input or Output)
Format: "PD,<Port>,<Pin>,<Direction><CR>"
<Port>: This is the character "A", "B", "C", "D" or "E" depending upon which port you want to change.
<Pin>: This is a number between and including 0 to 7. It indicates which pin in the port you want to change the direction on.
<Direction>: This is either "0" or "1", for Output (0) or Input (1).
Example: "PD,B,2,1" - This would change Port B, pin 2 to an input.

The "PI" Command

The "PI" command stands for "Pin Input". It allows you to read the state of just one pin at a time. (High or Low)
Format: "PI,<Port>,<Pin><CR>"
<Port>: This is the character "A", "B", "C", "D" or "E" depending upon which port you want to change.
<Pin>: This is a number between and including 0 to 7. It indicates which pin in the port you want to change the direction on.
Example: "PI,C,6" - This would read the state of Port C pin 6.
Return Packet: "PI,<Value>"
<Value>: This is either a High (1) or a Low (0) depending upon the voltage on the pin at the time it was read.
Example Return Packet: "PI,1" (Means that the pin was high.)

The "PO" Command

The "PO" command stands for "Pin Output". It allows you to set the output value (if it is currently set to be an output) on just one pin at a time. (High or Low)
Format: "PO,<Port>,<Pin>,<Value><CR>"
<Port>: This is the character "A", "B", "C", "D", or "E" depending upon which port you want to set.
<Pin>: This is a number between and including 0 to 7. It indicates which pin in the port for which you want to set the state.
<Value>: This is either "0" or "1", for Low (0) or High (1).
Example: "PD,A,3,0" - This would make Port A pin 3 low.

The "RC" Command

The "RC" command stands for "RC Servo Output". It will turn any pin into an RC servo output, if that pin is already configured as a digital output.
Format: "RC,<Port>,<Pin>,<Value><CR>"
<Port>: This is the character "A", "B", or "C" depending upon which port you want to set. (Note: PortD and PortE are not supported yet.)
<Pin>: This is a number between and including 0 to 7. It indicates which pin in the port for which you want to set the state. Note that some pins do not come out of the chip (RA6, RA7, RC3, RC4 and RC5), and some pins are not accessible via headers on the SparkFun version of UBW (RC0, RC1, RC2). You can still set RC outputs on those pins, but the non-existent ones will just be skipped by the RC code, and if you set RC outputs on RC0, RC1 or RC2, you may see interesting results (since RC0 and RC1 have LEDs on them).
<Value>: This is a value between 0 and 11890.

A <Value> of 0 (zero) will turn the RC output (for that pin) completely off. A <Value> of 1 will cause a 1ms high pulse on the pin. A <Value> of 11890 will cause a 2ms high pulse on the pin. Any <Value> inbetween 1 and 11890 will cause a high pulse whose duration is proportionally between 1ms and 2ms. These pulses repeat every 19ms.

Example: "RC,B,3,5945" - If PortB pin 3 was already an output, then there would be a 1.5ms (which is 'center' to an RC servo) high pulse coming out of PortB pin 3 every 19ms.
Note: This command allows you to have up to 16 independant RC servo outputs (on a SparkFun UBW).

    Binary Output Commands
       The "BC", "BO" and "BS" commands all work together to allow for high speed parallel output to a hardware device like an LCD panel or other latched 8-bit parallel interface. The basic idea is to take a byte, write it out to PortB, set a strobe bit on PortA, wait a bit, then clear the strobe bit on PortA, then wait for a busy bit to go high (or low) on PortA, then wait for the busy bit to go low (or high) on PortA and then repeat for as many bytes as there are to send out PortB. So PortB is used as the output to the parallel bus and two bits on PortA are used as a strobe bit (output) and a busy bit (input).

       The BC command sets up all of the parameters, and then the BO or BS commands stream the data out PortB. Before this scheme will be very successful, make sure to set the direction bits on PortB and PortA properly.

    The "BC" Command

The "BC" command stands for "Bulk Configure". It allows you to configure the options for the BO and BS commands.
Format: "BC,<Init>,<WaitMask>,<WaitDelay>,<StrobeMask>,<StrobeDelay>,<CR>"
<Init>: This is the inital value written to PortA.
<WaitMask>: Each bit that is set in this mask indicates a 'busy' bit coming back from the LCD (or other hardware). This value is only used if <WaitDelay> is not zero.
<WaitDelay>: The <WaitDelay> is the maximum amount of time to wait for the busy bit to become asserted, and then to become de-asserted. If <WaitDelay> expires, then the next byte is just sent out. <WaitDelay> is in units of about 400ns.
<StrobeMask>: Each bit that is set in this mask indicates the strobe bits that are to be inverted after the byte is written to PortB. When <StrobeDelay> is over, the initial value (<Init>) is written back to PortA.
<StrobeDelay>: The length of time that the strobe bits (from <StrobeMask>) are inverted from their intial values. <StrobeDelay> is in units of about 830ns.
Example: "BC,1,1,1,1,1"

The "BO" Command

The "BO" command stands for "Bulk Output". It uses the settings from the BC command and outputs bytes to PortB. PortA bits are used as control bits, with at least one used as a strobe output (indicating that a new byte is present on PortB) and an optional second PortA bit used as a 'busy' input to prevent the next byte from being sent out before the receiver is able to process it.
Format: "BO,<ASCII_HEX_Bytes><CR>"
<ASCII_HEX_Bytes>: This group of characters are the hexadecimal representation of the bytes that you whish to send out PortB. For example, if you wanted to send 3 bytes, of values 0x55, 0xA7 and 0x21, you would use "BO,55A721" as your command. The total length of this command must not be more than 63 bytes, so at most you can pack 30 bytes worth of ASCII hex characters into this command.
The way that the bytes get sent out PortB is by using the WaitMask, WaitDelay, StrobeMask, StrobeDelay and Init values from the BC command above. When the BC command is accepted, PortA will be initalized to the value in the <Init> parameter. Note that you must have already set up PortB as outputs and have the direction of each bit in PortA set up according to what you need. When it is time to output a byte (with the BO or BS commands), the chain of events is as follows:

The byte is output on PortB.
The bits that are high in the <StrobeMask> are inverted on PortA.
A delay is executed for <StrobeDelay> units (each unit is about 830ns)
The PortA is then returned to the <Init> value.
If <WaitDelay> is greater than zero,

Wait (up to <WaitDelay> units) for the busy bit to become the state it is in <Init>
Wait (up to <WaitDelay> units) for the busy bit to become the inverse of what it is in <Init>

Repeat

Example: "BO,55A721"

The "BS" Command

The "BS" command stands for "Bulk Stream". It uses the settings from the BC command and streams raw binary bytes to PortB, just like the "BO" command does.
Format: "BC,<ByteCount>,<BinaryStreamOfBytes><CR>"
<ByteCount>: This is the number of bytes in <BinaryStreamOfBytes>. It must be an exact number, because this his how the UBW knows when the end of <BinaryStreamOfBytes> is and when to begin looking for the <CR>. The range of acceptable values for <ByteCount> are from 1 to 56 inclusive.
<BinaryStreamOfBytes>: Must be exactly <BinaryStreamOfBytes> bytes long. This stream is the _binary_ (NOT ASCII) bytes that you want to send out PortB. In other words, if you wanted to send three bytes who's values are 0x23, 0x49 and 0x6A then the three bytes in <BinaryStreamOfBytes> would be "#Ij" and <ByteCount> would be 3. Note that since this is pure binary, it does not suffer from the lower bandwidth utilization that the "BO" command has (where each byte to be output is represented by two ASCII HEX bytes in the command string). But it is also more difficult to use because many of the characters inside the binary stream are not printable, and/or are difficult to generate with a terminal emulator.
Example: "BS,3,#Ij"

Errors Messages:

The error messages returned by version 1.4.0 and up are totally different from those in previous versions. One of the changes in 1.4.0 is that code within the UBW can now use printf() (and associated functions) to send bytes back to the PC. This makes complex error reporting much easier.

There are two (or more) scenarios that one might use a UBW:

By typing commands into a terminal emulator on a computer, to 'test out' commands and how the system is working.
By writing a computer program that will automatically generate commands to send to a UBW.

The long error messages are very useful for debugging the system, and especially when using the UBW by hand from a terminal emulator. The long messages are not as useful when running under scenario 2) above, as the PC application has a much harder time parsing the long error messages.

To help make the error messages useful in both scenarios, each error message starts out with an exclamation mark "!" and then is immediately followed by an integer error number, then a space, and then the long text of the error message with a <CR><LF> at the end. This means that if your PC application wants to parse the error message, it can look in the data coming back from the UBW for the exclamation mark "!" and then read in the error number and ignore everything else until the next <CR><LF>.

Error Message List:

"!0" (unused)
"!1" (unused)
"!2 Err: TX Buffer overrun"

This error is generated if, for some reason, the internal code of the UBW tries to send too much back to the PC at once, and the internal transmit buffer back to the PC overflows.

"!3 Err: RX Buffer overrun"

This error is generated if, while the UBW is receiving data from the PC, the internal receive buffer is overfilled.

"!4 Err: Missing parameter(s)"

The UBW will send back this error if it expected to find another parameter in the command, but instead found a <CR> or <LF>.

"!5 Err: Need comma next, found: '<some_char>'"

The UBW will send back this error if it expected to find a comma, but found something else instead. The <some_char> will be the character it found instead of the comma.

"!6 Err: Invalid parameter value"

This error means that the UBW found a parameter, but its value was outside of the acceptable range for that particular parameter.

"!7 Err: Extra parameter"

This error indicates that the UBW expected to see a <CR> or <LF> command terminator, but instead found an extra comma or extra parameter.

"!8 Err: Unknown command '<command_chars>'"

This error indicates that the single or double byte command name was not understood or doesn't exist. <command_chars> will be the one or two bytes that the UBW received that did not match any know commands.

Back to main UBW page

Questions? E-mail me at my e-mail address