UBW Firmware D v1.4.3 Documentation

Documentation for Firmware D, version 1.4.3 for UBW Boards
Back to main UBW page

Note 1: SparkFun is shipping Firmware D version 1.1 on their UBW boards.
This means that if you buy a UBW board from Spark Fun, you will get a board with Firmware D version 1.1 on it. If you want version 1.4.3 (described on this page) you will need to get the FW D v1.4.3 hex file here and then upgrade your UBW as described here. (It is a very easy procedure.)

Note 2: SparkFun has recently changed to shipping Firmware D version 1.4.1 on their UBW boards. I'm not exactly sure when this cutover happened, but you can always use the "V" command to find out which version your UBW has. If you look at the orange (yellow) LED, and it is blinking long-short-long-short-long then you have version 1.4.1 or higher.

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.

Version Notes:

Version 1.4.3

All strings changed casts from (rom char *) to (far rom char *) to keep the compiler from complaining as much.
The logic for when the main command parsing functions get called was changed slightly to allow for commands to run even after we loose the USB connection. (None of the commands currently take advantage of this - but if you were to add your own in, you might appreciate it.)
The blinking pattern of the yellow LED when USB is disconnected has been changed to a 'short-long-short-long'.

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 shiped on their first run of 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 this 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.
Currently, the backspace key does not work. For example, if you are typing a command to the UBW from a terminal emulator and you make a mistake and try to backspace to correct your mistake, the UBW will not recognize the backspace and will generate an error. This will hopefully be correct in a future FW D version.
All command names ("C", "BC", etc.) are case insensitive.
All port names ("A", "B", "C") are case insensitive

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><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"
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

Return Packet: "OK"

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><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"
Return Packet: "OK"

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.
Example 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.4.0"
Format: "V"
Return Packet: "UBW FW D Version 1.4.0"

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"
Return Packet: "OK"

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: "OK". Note however, the "I" packet or "A" packet responses will start flowing at regular intervals after the T command is received by the UWB.
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 "MR" Command

The "MR" Command stands for 'Memory Read'.
Format: "MR,<Address><CR>"
<Address>: This is a number between and including 0 to 4095. It is the address in the UBW's RAM that you wish to read.
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"

The "MW" Command

The "MW" Command stands for 'Memory Write'.
Format: "MR,<Address>,<Value><CR>"
<Address>: This is a number between and including 0 to 4095. It is the address in the UBW's RAM that you wish to write into.
<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)
Return Packet: "OK"
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.

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", or "C" 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.
Return Packet: "OK"

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", or "C" 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", or "C" 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.
Return Packet: "OK"

The "CU" Command

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.
Return Packet: "OK"

<Parameter>	<Value>	<Value> meaning
1	0 or 1	0 = Turn off "OK" packets 1 = Turn on "OK" packets (default)

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.
<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.
Return Packet: "OK"
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"
Return Packet: "OK"

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"
Return Packet: "OK"

The "BS" Command
NOTE: (09/18/08) Greg Corson has pointed out a serious bug in this command in Firmware D 1.4.3. If you send any <CR> or <LF> bytes in the binary data section of them command, they get eaten by the command processing fuctions, and don't make it out to the I/O pins! This will get fixed in a future version.

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"
Return Packet: "OK"

Errors Messages: (NOTE - New for version 1.4.0)

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.

Latest Version (1.4.3) Files:
    ZIP file of all project and source files necessary to build 1.4.3 here.
    FW D v1.4.3 HEX here (for programming a UBW)
    Browse the FW D 1.4.3 build files here

Back to main UBW page

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