UBW Firmware D v1.3.0 Documentation

Documentation for Firmware D, version 1.3 for UBW Boards
(New version 1.3, 08/18/2006)
Back to main UBW page

Note: 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.3 (described on this page) you will need to upgrade your UBW as described here. (It is a very easy procedure.) Get the FW D v1.3 hex file here. There have been reports of problems after upgrading from Firmware D v1.1 to v1.2, where the UBW would no longer be recognized by Windows anymore. With the help of several dedicated UBW users, I was able to track the problem down. Version 1.3 has the bug fixed, and hopefully there will be no more problems.

Description:
Firmware version D is a more advanced (and more complicated) firmware version than Firmware C. Wheras 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.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 publically released version, and the version that SparkFun ships on their boards.

Commands:
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" (with a carrige return at the end that you can't see)
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 roubust, 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 conserned, are treated exactly as all of the other analog input pins, so the show up in the "A" packet. Also, AN12 (the 13th anlog 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<LF><CR>"

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" (with a carrige return at the end that you can't see)
Return Packet: "OK<LF><CR>"

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" (with a carrige return at the end that you can't see)
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 chacaters 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<LF><CR>"

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.3.0"
Format: "V<CR>"
Return Packet: "UBW FW D Version 1.3.0<LF><CR>"

The "R" Command

The "R" Command stands for 'Reset to default state' and when you send the UBW an "R" command it will initalize all pins to digital inputs and stop any running timers.
Format: "R<CR>"
Return Packet: "OK<LF><CR>"

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) 10 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.
<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 acutally sampling the digitial 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 reponses between rising or falling edges of pin values and know the time between those events to the precission 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" (with a carrige return at the end that you can't see) - this would send back 10 "I" packets per second, sampled every 100ms.
Example: "T,14,1" (with a carrige return at the end that you can't see) - this would sample all enabled analog inputs and send back an "A" packet every 14ms.
Return Packet: "OK<LF><CR>". Note however, the "I" packet or "A" packet responses will start flowing at regular intervals after the T command is received by the UWB.

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" (with a carrige return at the end that you can't see)
Return Packet: "A,0145,1004,0000,0045<LF><CR>" (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><CR>"
<Value>: This is a number between and includeing 0 to 255. It is the result of reading <Address>.
Example Return Packet: "MR,28<LF><CR>"

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 includeing 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<LF><CR>"
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 curent 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" (with a carrige return at the end that you can't see) - This would change Port B, pin 2 to an input.
Return Packet: "OK<LF><CR>"

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" (with a carrige return at the end that you can't see) - This would read the state of Port C pin 6.
Return Packet: "PI,<Value><CR>"
<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<LF><CR>" (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" (with a carrige return at the end that you can't see) - This would make Port A pin 3 low.
Return Packet: "OK<LF><CR>"

Hints on using Firmware D:

By using the "T" command, you can get up to 100 "I" and/or "A" packets/second back fromt the UBW. (100Hz update rate)
If the "I" or "A" packet reponses 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 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 reponses back to the PC fast enough. You need to have less USB traffic (from other devices) or increase the time between packet responses.

Errors Reponses:
There are some rules about sending these commands to the UBW. If any of the rules is violated, an error charater will be sent back. You can monitor the serial port for these characters to know what you are doing wrong.

If the length of the command you are sending to the UBW is greater than just one character and the carrige return, then the second character needs to be a comma. If not, you will get an error back of ",".
If the last character of the USB packet (the command) is not a carrige return (0x0D) then you will get back an error of "!".
If all of the parameters of a packet are parsed by the UWB and the next character is not a carrige return, you will get back an error of "#".
If you are missing a comma in the packet, you will get an error of "^".
If the value you put in a parameter is out of range, you will get an error of "~".
If the command you send is not recognized by the UBW, you will get a "?".

Other things to note:

Each error responce from the UBW will terminate in a newline and carrige return <LF><CR> (0x0A,0x0D). This should mean that any terminal emulator will receive it correctly.
FW D does not require incoming commands to be placed in a single USB packet. This means you can easily try out your UBW board by connecting it to a terminal emulator on your PC and typing packets to the UBW.
FW D does not require a single <CR> at the end of a command. It can take any number of <CR> or <LF> characters together and recogiznes them as a single "end of packet" symbol. This also helps make the UWB friendly for Terminal Emulator use.

Files:
The full zip file for Firmware D v1.3, including all source and project files necessary to rebuilt it are located here.
If you just want the Firmware D v1.3 HEX file, it is here.

Back to main UBW page

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