Description:
The firmware (application) that comes with the UBW32 gives the user a
basic set of input/output commands. For example, the user can set any
I/O pin to be an input or output, read the inputs, write to the
outputs, etc. Future versions of the firmware will allow more
complicated commands (like analog input, timing related commands, PWM,
SPI, USART, etc.)
Version Notes:
Version 1.0
First publicly released version, and the version that
SparkFun is shipping on their first run (v2.4) 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.
You can string together as many commands as you want into one
string, and then send that string all at once to the UBW32. 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 UBW32 at once, you make the most
efficient use of the USB bandwidth.
After successful reception of a command, the UBW32 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 UBW32 understood your command. However,
it
does add extra communications overhead that may not be appreciated in a
higher speed application. You can
use the CU command to turn off the sending of "OK" packets. Errors will
still be sent, but not any "OK" packets.
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>,<DirD>,<DirE>,<DirF>,<DirG><CR>"
where <DirX> is a value between 0 and 65,535 that indicates the
direction bits for that port. A 1 is an input, a 0 is an
output.
Example:
"C,0,0,0,0,65535,0,0" - This would set all ports as outputs except port
E which would be all input
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>,<PortD>,<PortE>,<PortF>,<PortG><CR>"
where
<PortX> is a value between 0 and 65,535 that indicates the value
of
the port pins for that register.
Example:
"O,0,0,131,0,0,0,0"
Return Packet:
"OK"
The "I" Command
The "I" Command stands for 'Input state' and when you send the
UBW32 an "I" command, it will respond with an "I" packet back that will
hold the value of each bit in each of the seven ports A, B, C, D, E, F
and G. It
reads the state of the pin, no matter if the pin is an input or an
output.
Format: "I<CR>"
Example: "I"
Return Packet:
"I,<StatusA>,<StatusB>,<StatusC>,<StatusD>,<StatusE>,<StatusF>,<StatusG><CR>"
where
<StatusX> is a number from 0 to 65,535 that indicates the current
value of the pins on that port. Note that <StatusX> will always
be 5 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,50943,64479,24606,65535,01015,12607,62403"
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: "UBW32 Version 1.0"
Format: "V"
Return Packet:
"UBW32 Version 1.0"
The "R" Command
The "R" Command stands for 'Reset to default state' and when you
send the
UBW32 an "R" command it will initialize all pins to digital inputs.
Format: "R"
Return Packet:
"OK"
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, E, F or G depending upon which port you want to
change.
<Pin>: This is a
number between and including 0 to15. 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, C, D, E, F or G depending upon which port you want to
change.
<Pin>: This is a
number between and including 0 to 15. 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, E, F or G depending upon which port you want to
set.
<Pin>: This is a
number between and including 0 to 15. 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 UBW32". It is designed to
be
a generic command for setting things that affect the general operation
of the UBW32.
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 "BL" Command : Enter Boot Loader mode
The "BL" command stands for "Boot Loader". When you issue a BL
command, the UBW32 will reset itself into bootloader mode and wait for
a download from the HID Bootloader application.
Format: "BL<CR>"
Example: "BL"
Return Packet: none
The "T1" Command : Execute Test 1
The "T1" command stands for "Run Test 1". It set all pins to be
digital outputs, and set them all high. It will then pull each one
down, in turn, for the length of time specified. It will start with
A15, and progress clockwise around the UBW to D8, then cycle back
around to A15. It will repeat this the number of times specified. The
purpose of this command is to test all 78 I/Os, and show that they are
all connected properly to the CPU, and that there are no opens or
shorts. If you put an LED through a resistor to +3.3V on each I/O pin,
you'll end up with a nice Knight Rider effect.
Format: "T1,<duration>,<iterations><CR>"
<Duration>: This is
an unsigned 16 bit integer, and represents the time, in milliseconds,
that each I/O will be pulled low
<Iterations>: This
is an unsigned 16 bit integer, and represents the number of times to
repeat the pattern
Example: "T1,200,4" -
This would run the pattern four times, with each pin going low for
200ms.
Return Packet:
"OK"
Errors Messages:
There are two ways that one might communicate with a UBW32:
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 UBW32.
The long error messages are very useful for debugging the system, and
especially when using the UBW32 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 UBW32 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 UBW32 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 UBW32 is receiving data
from the PC, the internal receive buffer is overfilled.
"!4 Err: Missing parameter(s)"
The UBW32 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 UBW32 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 UBW32 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 UBW32 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 UBW32 received that did not match any
know
commands.
Version 1.0 Files:
ZIP file of all project and source files necessary
to build 1.0 here.
v1.0 HEX
here (for
programming a
UBW32)
Browse the v1.0 build files here
Documentation UBW32 Firmware