Serial Wombat
a general-purpose digital interface device for hobbyists, engineers and students

  
Home
Overview
Protocol
Documentation
Getting Started
Connectivity
Pin Mode SDK Beta
Sample Projects
Downloads
Contact Us
Purchase
Forum

Did you know...

 

Serial Wombat Communication Protocol

Basics

Wombat commands are all eight bytes long, and Wombat responses are eight bytes long. The first byte is a command byte. The meaning of following bytes varies depending on the command byte. In some cases padding bytes are added to the end of simple messages to achieve eight bytes. Padding bytes are set to 0x55 (see resyncing, below). Some functionality may require multiple messages to invoke. Multi-byte values are transmitted most-significant byte first.

Loosing Sync

The most important compromise of the Wombat serial protocol is its susceptability to loss of synchronization with the host. This can occur if the host sends a partial message or if environmental conditions cause communication problems or a Wombat reset. If the Wombat interprets the second or later byte of a message to be the command (first) byte, then it will act on that byte when eight total bytes have been received.

Resync Character

When a loss of synchronization is suspected the host should send 0x55 (ASCII 'U' ) eight times. 0x55 is a special value which is discarded when received as a command byte. After this sequence is received the Wombat will always be ready to receive a command.

Preventing loss of synchronization

There are a number of steps the user can take to detect and prevent loss of synchronization:

  • After sending a command to the Wombat wait for the Wombat to begin its response before sending more commands. The Wombat will begin sending a response within two frame times. If no response is sent the host and the Wombat are likely out of sync. It is recommended that a command not be sent until the first two bytes of the previous response have been received.
  • Enable message checksums. This can be done with the Set System Status command. When checksums are enabled each eight byte message is followed by a ninth checksum byte. The value of this byte is the logical inversion (NOT) of the sum of the first eight bytes. The Wombat will send no response to a message with a bad checksum. Using checksums greatly reduces the chance that an out-of-sync message will be acted upon. This functionality is present in the firmware starting with version 1.1.0, but has not yet been documented.
  • Enable Wombat addressing, even if only one Wombat is connected to the host. When addressing is enabled an address byte preceeds the eight byte Wombat command. When using addressing to increase the robustness of the Wombat protocol it is recommended that the address 0xFE be used. This value is far less frequently used in command packets than values such as 0x00 or 0x01. This reduces the chance that a byte of an out-of-sync message will be interpreted as the address byte. The address byte is included in the checksum (if enabled). Since the Wombat thinks that messages with a different address than its own are meant for another chip no response will be sent. This functionality is present in the firmware starting with version 1.1.0, but has not yet been documented.
  • Enable intra-message timeout. The Wombat allows the host to define a timeout between received bytes within a message. If the timeout expires then the message up to that point will be discarded, and no response will be sent. This is particularly useful when checksums are enabled. This functionality is present in the firmware starting with version 1.1.0, but has not yet been documented.

 

For example, suppose the host intends to send two commands. After four bytes of the first message are sent an electrostatic event causes the Wombat to reset. The fifth byte is missed all together during the reset. The Wombat comes out of reset and receives the 6th, 7th, and 8th byte of the first message, which it interprets as the command, 2nd and 3rd byte of a new message. The host waits for a response, which never comes. The Wombat recieve timeout occurs because a 4th byte never comes, and the message is discarded. The Wombat is now ready to receive a new message, and the host is prepared to send one because no response came. In following the resyncing recommendations above, the host will send 0x55 eight times, then send a new message. Note that in the above example the Wombat must be configured to enable receive timeout when coming up from reset. See the section on EEPROM for more information.

Command Types

Serial Wombat commands fall into two broad categories:

  • ASCII commands. These commands are designed to be typed into a terminal program such as Windows Hyperterminal. ASCII commands start with a command byte which corresponds to a typeable character. Numerical parameters are expressed as ASCII strings, rather than as packed binary numbers. Commands are case-sensitive in order to maximize the number of possible commands within the ASCII range. The command byte for ASCII commands is chosen to make the command as easy to remember as possible.
  • Binary commands. These commands are designed to be sent by a program running on the host computer. The command byte numbers are 128 to 253. These correspond to non-ASCII characters. Binary commands typically take some number of 1 to 4 byte long parameters. Multi-byte parameters are sent most-significant byte first. Note that programs can use the ASCII commands as well as Binary commands. Binary commands are allocated command byte numbers in groups. For instance, queue related commands currently use commands 128 through 132. Additional commands will be left unassigned following number 132 in order to support future queue commands.

ASCII Commands:

Command/ASCII / Hexidecimal/ Decimal Description

Echo

'!'
0x21
33

 This command will echo back to the host the same 8 byte packet when it is received. This command has no other effect on the system. This command is useful to verify that communication is possible between the host and the Wombat.

Example:

Sent to the Wombat: '!' 'A' 'B' 'C' 'D' 'E' 'F' 'G'
Received by the Host: '!' 'A' 'B' 'C' 'D' 'E' 'F' 'G'

Read Public Data Buffer

'A'
0x41
65

 This command will return the public data for a channel given as an ascii string in the 2nd and 3rd bytes. The command byte can be remembered with the neumonic "A is the command to get the result of an Analog conversion." If the 4th byte is 'H' then the result will be returned in hexadecimal with a leading X. If the 4th byte is not X then the value will be returned in decimal.

Example:

Get the value of the public data provided by pin 4. Return that value in hexadecimal.

Data Sent to the Wombat: 'A' '0' '4' 'H' 'U' 'U' 'U' 'U'
Meaning: Read Public Data buffer Pin 4 Return value in hexadecimal Unused
 
Data Received by the host 'A' '0' '4' 'X' '3' 'D' '7' '4'
Meaning: Read Public Data Buffer Pin 4 Result is Hexadecimal Some Hexidecimal Value Corresponding to the 16 bit value of pin 4's public data


Example:

Get the value of the public data provided by pin 32. Return that value in decimall.

Data Sent to the Wombat: 'A' '3' '2' 'D' 'U' 'U' 'U' 'U'
Meaning: Read Public Data buffer Pin 32 Return value in hexadecimal Unused
 
Data Received by the host: 'A' '3' '2' '4' '3' '1' '2' '7'
Meaning: Read Public Data Buffer Pin 32 Some Hexidecimal Value Corresponding to the value of pin 32's public data. This 16 bit value may range from 0 to 65535.

Set Baud Rate

'B'
0x42
66

 This command will set a new communication Baud (or bits-per-second) rate for communication between the Serial Wombat and the host. No return message will be sent, in order to allow the host time after transmission to change baud rate. If the Autobaud Command is sent, then a 'U' (0x55) character MUST be the next character sent after this command and the host-side Baud Rate change. Failure to do so may cause communication to be permanently disrupted until the next Serial Wombat power-cycle. Other baud rate change commands do not require any additional action by the host.

If the 8th byte is 'E' then system will write to EEPROM to indicate that future powerups should use the new baud rate at powerup. If the 8th byte is not E then the powerup state will not be changed. Writing to EEPROM will suspend all other processing for up to 8 ms.

Note that all baud rates are expressed as a 6 character decimal number, with leading zeros as necessary.

No action will be taken when a baud rate other than one of the following is used:

Possible bps (Baud) values: 75, 110, 150, 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200.

Note that aside from the Autobaud command, these values only work when the Wombat is operating from its internal clock source at the default frequency. Future versions of the Wombat software may allow the user to slow the clock down to conserve power, or to use an external clock source.

Data Sent to the Wombat: 'B' 'A' 'U' 'U' 'U' 'U' 'U' 'E'
Meaning: Set Baud Rate Initiate Auto-baud. Unused. This packet should be followed by at least one 'U' character to initialize the baud rate. If the 8th byte is 'E' then system will write to eeprom to indicate that future powerups should use Autobaud. If the 8th byte is not E then the powerup state will not be changed.


Data Sent to the Wombat: 'B' '0' '0' '0' '0' '7' '5' 'U'
Meaning: Set Baud Rate Set baud rate to 75 bps. unused.


Send Binary Command in ASCII

'C'
0x43
67

 This command is used to send a command from the binary portion of the command set using ascii based commands. Since binary commands are more information dense than ASCII commands, it takes four ASCII commands to send one binary command. This command is useful for testing using a terminal such as hyperterminal, since it allows a sequence of commands to be sent all at once. When sending commands using a stream of text from a file, it is recommended that 8 0x55 characters ( ASCII 'U' ) be placed between each command to minimize corruption should any byte be dropped or misreceived.

The Wombat will echo back each of the four command packets, but will not send the response to the created binary command, as the response would also likely be in binary. Care should be taken that the commands are sent in order. The Wombat will act when a packet marked as fourth is received, even if a previous packet is missing.

The second byte indicates the command number. Valid values are 0, 1, 2, and 3. The 3rd through 5th bytes of each ASCII command are the 1st, 3rd, 5th, or 7th binary command byte (depending on the command number), expressed as a three digit decimal number. The 6th through 8th bytes of each ASCII command 2nd, 4th, 6th, or 8th binary command byte (depending on the command number), expressed as a three digit number.

Doing conversions by hand can be tedious and error prone. Use the script here!

Set Pin Hardware Mode

'H'
0x48
72

 This command is used to configure the way a pin will behave when used as an analog output. A few pins have fixed behavior which cannot be changed:
Pin 4   16 level (4 bit) D/A converter
Pin 16   Hardware assisted PWM
Pin 17   Hardware assisted PWM

All other pins can be configured for the following modes:

Setting   Function
1   1-bit software PWM
2   2-bit software PWM
3   3-bit software PWM
4   4-bit software PWM
5   5-bit software PWM
6   6-bit software PWM
7   7-bit software PWM
8   Unused
9   MCP4821 12-bit D/A converter

Example:

Set pin 19 to 5 bit software PWM.

Data Sent to the Wombat: 'H' '1' '9' '0' '5' 'U' 'U' 'U'
Meaning: Set Pin Hardware Mode Pin 20 Mode 05      

Jump to App From Bootloader

'J'
0x4A
74

 This command is used to tell the Wombat that it should jump to the application on powerup (as opposed to staying in boot mode). This command is designed for use immediately after downloading a new firmware version using the boot mode.

Example:

Jump to Application on powerup.

Data Sent to the Wombat: 'J' 'U' 'U' 'U' 'U' 'U' 'U' 'U'
Meaning: Jump To App Unused.

Lock Communications

'L'
0x4C
76

 This command is designed to help the Wombat avoid executing unintended commands when operating over a datalink which may provide characters which are not commands. For instance, a typical Hayes compatible modem may send strings such as "CONNECT 9600" or "RING" which should not be interpreted by the Wombat. The Lock command allows the host (or the powerup sequence) to require a specific unlock command before other commands will be processed. The lock command consists of "LOCK" plus an additional 4 bytes provided by the host. Once locked, the Wombat will not respond to any command until the command "Lock" plus the same 4 bytes is sent (note the case difference, lower "ock" is for unlock). The lock and unlock commands must be properly framed, so it is recommended to send resync characters prior to locking or unlocking the Wombat.

Example:

Lock the Wombat with the additional 4 bytes 0x01, 0x02, 0x03 0x04

Data Sent to the Wombat: 'L' 'O' 'C' 'K' 0x01 0x02 0x03 0x04
Meaning: Lock the Wombat. Note upper case "OCK"        

Example:

UnLock the Wombat with the additional 4 bytes 0x01, 0x02, 0x03 0x04

Data Sent to the Wombat: 'L' 'o' 'c' 'k' 0x01 0x02 0x03 0x04
Meaning: UnLock the Wombat. Note lower case "ock" Same 4 bytes as lock command

Set Pin to High, Low, or Input

'P'
0x50
80

 This command is used to set the state of one to five consecutively numbered pins. Each Pin may be set to high, low, input, or left unchanged. The 2nd and 3rd bytes are the pin number of the first pin to be set, in ASCII. The 4th byte contains the state to which the specified pin should be set: '0' (ascii zero) for low, 1 for high, or I for input. Any other value will leave the pin unchanged. Similarly, the 5th byte will change the next pin if 0,1, or I is given. Otherwise, the next pin will stay unchanged. The remaining three bytes will change the next three pins. Is is suggested to use 'U', the resync value, for unused pins.

Example:

Set pin 20 to output high.

Data Sent to the Wombat: 'P' '2' '0' '1' 'U' 'U' 'U' 'U'
Meaning: Set Pins Pin 20 Set Pin 20 high Leave pins 21, 22, 23, and 24 unchanged.


Example:

Set pin 13 to output low, pin 15 to output high, and pin 16 to input.

Data Sent to the Wombat: 'P' '1' '3' '0' 'U' '1' 'I' 'U'
Meaning: Set Pins Pin 13 Set pin 13 low Leave Pin 14 unchanged Set pin 15 high Set pin 16 to Input Leave pin 17 unchanged.

Set Public Data

'S'
0x53
83

 Set a pin's public data. This is used for certain pin modes such as Servo Control which act on their own public data. Values are expressed in ASCII decimal. The first two bytes after 'S' are the pin number (numbers less than 10 start with a zero). The final 5 bytes are a 16-bit value, right justified. Leading digits should be filled with zero.

Example:

Set pin 19's public data to 375 decimal.

Data Sent to the Wombat: 'S' '1' '9' '0' '0' '3' '5' '5'
Meaning: Set Pin Public Data Pin 19 355 (A 16-bit number, expressed in ASCII in decimal with leading zeros).

Write To EEPROM

'e'
0x65
101

 This command is used to write a single byte into EEPROM. The Serial Wombat has 1024 bytes of EEPROM, of which addresses 512 to 1023 (addresses start at 0) are allocated for use by the host in the User EEPROM Area. Additionally, the address 511 is used to indicate how many custom powerup initialization messages are stored in EEPROM.

This command takes a four character, 16-bit address between 0x01FF and 0x03FF (511 to 1023 decimal) expressed in hexidecimal and a two character, 8-bit piece of data expressed in hexadecimal to store in EEPROM. The 8th byte is unused and should be set to the resync character (0x55).

Note that all processing stops during EEPROM programming, which may take up to 4 milliseconds under some voltage and temperature conditions. During this time no pin-processing will take place, and no communications will be acknowledged. Therefore, if the user is going to stream a number of these commands from a file, it is recommended that enough resync characters be included between messages to take 4ms to transmit. At 9600 Baud this would be approximately 4 characters.

The Wombat returns An echo of the first 5 bytes, followed by the value read from EEPROM after programming, and an echo of the 8th byte. Unless some error occurs this value should match the value sent. A communicatons error message will be returned if the address to program is not between 511 and 1023.

Example:

Program EEPROM location 742 to value 0x3D

Data Sent to the Wombat: 'e' '0' '2' 'E' '6' '3' 'D' 'U'
Meaning: Set Pins Address 742 expressed in hex is 0x02E6 Write Value 0x3D Unused.


Read From EEPROM

'r'
0x72
114

 This command is used to read a single byte from EEPROM. The Serial Wombat has 1024 bytes of EEPROM, of which addresses 512 to 1023 (addresses start at 0) are allocated for use by the host in the User EEPROM Area. Additionally, the address 511 is used to indicate how many custom powerup initialization messages are stored in EEPROM.

This command takes a four character, 16-bit address between 0x0000 and 0x03FF (0 to 1023 decimal) expressed in hexidecimal. The remaining three bytes should be set to the resync character (0x55). The 1st through 5th bytes are echoed back to the user. The value of the given EEPROM Location is returned in the 6th and 7th byte. The 8th byte is an echo of the 8th and unused byte of the command sent to the Wombat.

Example:

Read EEPROM location 742

Data Sent to the Wombat: 'r' '0' '2' 'E' '6' 'U' 'U' 'U'
Meaning: Read EEPROM Location Address 742 expressed in Hexidecimal Unused
 
Data Received by the host: 'r' '3' '2' '4' '3' '3' 'D' 'U'
Meaning: Read EEPROM Location Address 742 expressed in Hexidecimal Value in address 742 is 0x3D (example. Real value will vary) Echo of 8th byte sent to Wombat


Get Firmware Version

'V'
0x56
86

 This command is used to read the version of firmware loaded into the Wombat. It will return a string which starts with "VW" followed by 3 sets of two digits, representing the major, minor, and revision levels of the currently loaded firmware. This command is present in versions starting with WV010200, or 1_2_0.
Data Sent to the Wombat: 'V' 'U' 'U' 'U' 'U' 'U' 'U' 'U'
Meaning: Get Version Unused Unused Unused Unused Unused Unused Unused
 

Binary Commands

Command

Hexidecimal/ Decimal

 Description

Initialize Ram Queue

0x80
128

 This command will create a ram queue in the User RAM area at the given address. The 2nd and 3rd bytes hold the address of the queue. The 4th and 5th bytes hold the size of the queue. The size sent is the number of bytes in the queue, not the number of bytes taken up by the queue plus its internal-use header. The 6th byte contains the queue type. Set this byte to zero, as only standard queues are currently supported. Future queue types may support optimizations for run-length encoding of queue data, data sizes of other than 8 bits, or support for off-board RAM or EEPROM. The 7th and 8th bytes are unused for a standard queue initialization and should be set to the resync character. A communications error message will result if the queue cannot be created.

If successful this command sets the last host modified address parameter to the address of the created queue.

Example:

Create a queue of size 350 bytes at address 0x0020:

Data Sent to the Wombat: 0x80 0x00 0x20 0x01 0x5E 0x00 0x55 0x55
Meaning: Initialize Queue Address 0x0020 Size 350 bytes (0x015E in hexadecimal) Standard Queue Unused.

Get Queue Info

0x81
129

 This command returns the status of a previously created queue. The 2nd and 3rd bytes are the address of the queue to be queried. The 4th through 8th bytes are unused and should be set to the resync character.

The Wombat will respond with the queue info. The 2nd and 3rd bytes contain the allocated size of the queue. The 4th and 5th bytes contain the number of bytes currently used in the queue. The 6th and 7th bytes contain the size of the user data area. The 8th byte is unused and will match 8th byte transmitted to the Wombat.

Example:

Query the status of the queue created in the Initialize Ram Queue example above. Assume that the queue currently has 258 items in it.

Data Sent to the Wombat: 0x81 0x00 0x20 0x55 0x55 0x55 0x55 0x55
Meaning: Get Queue Info Queue Address 0x0020 Unused
 
Data Received by the host: 0x81 0x01 0x5E 0x01 0x02 0x02 0xA4 0x55
Meaning: Get Queue Info Queue Size is 350 bytes (constant once queue is initalized) The queue currently contains 258 bytes (varies as data is added and removed from queue) The user data area is 676 bytes long (constant for any release of the Wombat) Echo of 8th byte sent to Wombat


Get Queue Data

0x82
130

 This command is used to move data from a Wombat Queue to the Host. The host sends a message containing the address of the queue and the number of bytes requested. The host may request up to 6 bytes per message. If more than 6 bytes are requested, or if the queue is not valid, then a communications error message will be returned. The 2nd and 3rd byte contain the address of the queue to be accessed. The 4th byte contains the maximum number of bytes to be gotten from the queue. The 5th through 8th bytes are unused, and should be set to the resync character. Note that no error will be returned if this command is issued against a valid but empty queue.

The Wombat will return a packet. The 2nd byte will indicate how many bytes were removed from the queue. The 3rd through 8th bytes will contain the removed data. The first byte removed from the queue will be placed in the 3rd byte of the response message.

If successful this command sets the last host modified address parameter to the address of the queue. A return of 0 bytes from a vaild but empty queue will set the last host modified queue parameter to the address of the queue.

Example:

Query the status of the queue created in the Initialize Ram Queue example above. Assume that the queue currently has 4 items in it: 0x23, 0x47, 0xAF, and 0xC0.

Data Sent to the Wombat: 0x82 0x00 0x20 0x06 0x55 0x55 0x55 0x55
Meaning: Get Queue Data Queue Address 0x0020 Retreive up to 6 bytes from queue Unused.
 
Data Received by the host: 0x82 0x04 0x23 0x47 0xAF 0xC0 0x55 0x55
Meaning: Get Queue Data Four bytes were removed from the queue. First Byte Removed from queue Second Byte Removed from queue Third Byte Removed from queue Fourth Byte Removed from queue Not used since only 4 bytes removed Not used since only 4 bytes removed

Put Queue Data

0x83
131

 The Put Queue Data command is used to move data from the Host to a Wombat Queue. This command can be used to send up to four bytes of data to the Wombat. The message contains the address of the queue into which the data will be placed, the number of bytes to place (0 to 4) and the data to be placed in the queue. An communications error message will be returned if the queue is not valid, or if there is not enough space in the queue to place the requested number of bytes.

If successful this command sets the last host modified queue parameter to the address of the queue.

Upon success, the Wombat will echo the first four bytes of the message. The 5th and 6th byte will contain the size of the queue. The 7th and 8th bytes will contain the number of bytes in the queue following the insertion of the sent data.

Example: Place 3 bytes, 0x11, 0x00, and 0xEC into the queue created in the Initialize Ram Queue example above. Assume that 271 bytes of data are in the queue before this message.

Data Sent to the Wombat: 0x83 0x00 0x20 0x03 0x11 0x00 0xEC 0x55
Meaning: Put Queue Data Queue Address 0x0020 Put 3 bytes in queue Data Data Data Unused in this example
 
Data Received by the host: 0x83 0x00 0x20 0x03 0x01 0x5E 0x01 0x12
Meaning: Put Queue Data Queue Address 0x0020 3 bytes added to queue Queue size is 350 bytes 274 bytes are now in the queue

Queue Seven Bytes

0x84
132

 The Queue Seven Bytes command is designed to immediately follow the Put Queue Data command when many bytes need to be added to a queue. This command will place the 2nd through 8th bytes into the queue indicated by the last host modified queue parameter. This parameter is set by any command which modifies a queue.

The Wombat will respond with a message which has the address of the modified queue in the 2nd and 3rd bytes, 0x07 in the fourth byte, the queue size in the 5th and 6th bytes. The 7th and 8th bytes will contain the number of bytes in the queue following the insertion of the sent data.

An communications error message will be sent if the last host modified address parameter points to an invalid queue, or if there are not 7 bytes of available space in the queue.

Example: Place 7 bytes, 0x21, 0x14, 0xFC, 0x3D, 0x05, 0x12, and 0x78 into the queue created used in Put queue data example above. Assume this command is issued immediately after that example.

Data Sent to the Wombat: 0x84 0x21 0x14 0xFC 0x3D 0x05 0x12 0x78
Meaning: Queue Seven Bytes Data Data Data Data Data Data Data
 
Data Received by the host: 0x83 0x00 0x20 0x07 0x01 0x5E 0x01 0x19
Meaning: Queue Seven Bytes Queue Address 0x0020 3 bytes added to queue Queue size is 350 bytes 281 bytes are now in the queue

Set User RAM

0x92
146

 The Set User RAM command allows the user to place data into the User RAM area for use by various pin modes. 0 to 4 bytes can be written. The first byte of this message is 146. The next two bytes represent the address in user RAM where the first data byte is to be stored. The fourth byte is the number of data bytes to write, and the 5th through 8th bytes are data. The packet must always be 8 bytes long. Set unused bytes to 0x55. The sent message is echoed by the Wombat.

This command sets the last host modified address to the next address after those which were written.

Example: Write the string "JonB" to address 302 in user memory.

Data Sent to the Wombat: 0x92 0x01 0x2E 4 74 111 110 66
Meaning: Set User Ram Address 302 represented in hex is 0x12E 4 bytes of data follow Ascii 'J' is 74 Ascii 'o' is 111 Ascii 'n' is 110 Ascii 'B' is

66

Set 7 Bytes of User RAM

0x93
147

 This command is designed to increase efficiency when moving data into User RAM. After the user has sent up to 4 bytes using the Set User RAM command, addtional sets of 7 bytes can be sent to the immediately following addresses in User RAM. The first byte is 0x93. The seven following bytes are data bytes to be written to RAM, starting at the last host modified address.

This command sets the last host modified address to the next address after those which were written.

See the next command for an example.

Set X Bytes of User RAM

0x94
148

 This command is designed to complete user RAM settings using the Set User RAM and Set 7 Bytes of User RAM commands. Up to 6 bytes can be sent to the immediately following addresses in User RAM. The first byte is 0x94. The second byte is the number of data bytes that follow. The six following bytes are data bytes to be written to RAM, starting at the last host modified address. This packet must always be 8 bytes long. Unused bytes should be set to 0x55.

This command sets the last host modified address to the next address after those which were written.

Example: Place the string "Serial Wombat Rocks!!!" in User Ram starting at at address 0x100

Set the address and send the first four bytes with the Set User RAM command:

Data Sent to the Wombat: 0x92 0x01 0x00 4 83 101 114 105
Meaning: Set User Ram Address 0x100 4 bytes of data follow Ascii 'S' is 83 Ascii 'e' is 101 Ascii 'r' is 114 Ascii 'i' is 105

Send as many bytes as possible using the Set 7 Bytes of User RAM Command:

Data Sent to the Wombat: 0x93 97 108 32 87 119 109 98
Meaning: Set 7 Bytes of User Ram Ascii 'a' is 97 Ascii 'l' is 108 Ascii ' ' is 32 Ascii 'W' is 87 Ascii 'o' is 111 Ascii 'm' is 109 Ascii 'b' is 98
Data Sent to the Wombat: 0x93 97 116 32 82 111 99 107
Meaning: Set 7 Bytes of User Ram Ascii 'a' is 97 Ascii 't' is 116 Ascii ' ' is 32 Ascii 'R' is 82 Ascii 'o' is 111 Ascii 'c' is 99 Ascii 'k' is 107

Send remaining bytes using the Set X Bytes of User Ram Command:

Data Sent to the Wombat: 0x94 4 115 33 33 33 0x55 0x55
Meaning: Set X Bytes of User Ram 4 bytes follow Ascii 's' is 115 Ascii '!' is 33 Ascii '!' is 33 Ascii '!' is 33 Unused Unused

Get System Info

0x96
150

 This command is used to get various information from the Serial Wombat. The 2nd byte of this command specifies what information is to be retrieved. The 3rd through 8th bytes are unused.

The following table gives the information provided by each information identification number. The first byte of the return message is the Get System Info command number, 0x96. All multibyte values are transmitted most-significant byte first.

Information
Identification
Number (2nd sent byte) (Hex and decimal) 		Description 2nd Byte 3rd Byte 4th Byte 5th Byte 6th Byte 7th Byte 8th Byte
0x00

0

Wombat Application Firmware Version Number Major Revision Number Minor Revision Number Interm Release Number Unused
0x01

1

 18F4620 Configuration Bits. Values from flash addresses 0x300001 through 0x300007. See the 18F4620 Data Sheet for their meanings. These are included to assist in debugging when a problem report is submitted to serialwombat.com. Contents of 0x300001 Contents of 0x300002 Contents of 0x300003 Contents of 0x300004 Contents of 0x300005 Contents of 0x300006 Contents of 0x300007
0x02

2

 18F4620 Configuration Bits. Values from flash addresses 0x300008 through 0x30000D, and 0x3FFFFE. See the 18F4620 Data Sheet for their meanings. These are included to assist in debugging when a problem report is submitted to serialwombat.com. Contents of 0x300008 Contents of 0x300009 Contents of 0x30000A Contents of 0x30000B Contents of 0x30000C Contents of 0x30000D Contents of 0x3FFFFE
0x03

3

 18F4620 Configuration Bits. Values from flash address 0x3FFFFF. See the 18F4620 Data Sheet for their meanings. These are included to assist in debugging when a problem report is submitted to serialwombat.com. Contents of 0x3FFFFF Unused Unused Unused Unused Unused Unused
0x04

4

 Frame Counters. These numbers indicate the number of times the Frame Timer Interrupt has gone off, and the number of times that a Frame has been serviced. These are useful for evaluations of throughput. This 32-bit value indicates the number of times the Frame Timer Interrupt has fired. If this interrupt fires every 1ms, this value will roll-over from 0xFFFFFFFF to 0 in approximately 50 days. This number is reset to 0 when the Wombat is reset. This 24-bit value indicates the number of frames that have been serviced. If this value differs by more than one from the Frame Timer Interrupt Count, the Wombat may be set up to do more work than the processor can handle.
0x09

5

 Free Running Timer

A 2 MHz 24 bit free running timer is used to timestamp the transitions detected by the Hardware Pulse Measurement channel mode. This 24 bit timer can be accessed by the host through this interface. User should be aware that some time will elapse between the reading of the timer and the return of the data through the serial connection. This timer rolls over approximately every 8.4 seconds.

 Unused. Echos 0x09 Free Running Timer High Byte Free Running Timer Middle Byte Free Running Timer Low Byte Unused Unused Unused

Set System Parameter

0x97
151

 This command is used to set various system wide- parameters. The 2nd byte of the transmitted message is the System Parameter number. The 3rd through 8th bytes vary in meaning depending on the System Parameter number. Unless otherwise indicated the command received by the Wombat will be echoed back to the host upon successful completion of the setting the System Parameter.

This command exists to bridge the gap between two Wombat principles. It allows the user to modify registers which are specific to the 18F4620. At the same time, it contains the need to know about these registers to a single command.

System Parameter Number (2nd sent byte)
(Hex and decimal)		 Description 3rd Byte 4th Byte 5th Byte 6th Byte 7th Byte 8th Byte
0x00

0

Baud Rate. This command allows the user to specifically configure the baud rate registers of the 18F4620. This allows the user to select non-standard baud rates, and may be used in the future to change baud rates if a clock source other than the internal oscillator is used. See the 18F4620 for defintions. This command will not issue a response. Caution should be used in executing this command, as improper settings may prevent the Wombat from communicating until a power cycle occurs. If autobaud is enabled, then the next character received by the Wombat should be the resync character. SPBRGH Register SPBRG Register BRGH bit (0 or 1) Autobaud enable bit (0 or 1) Unused
0x01

1

 Port B (pins 33 through 40) internal pullup resistor enable. Pull-up resistors are used most often with various types of switches and other input devices that sometimes conduct and sometimes don't. When the switch is active, it connects an input pin to ground, yielding a 0 input. When the switch is inactive, the pull-up resistor pulls the pin high, yielding a 1 input. The internal pullup resistors are enabled by default. This makes pins 33 through 40 ideal for button, switch, keypad and rotary encoder inputs, as the need for an external pull-up resistor is eliminated. 0: Disable internal pull-up resistors

1: Enable internal pullup resistors

 Unused
0x02
2		 Pin Service Start and End. This parameter allows the user to specify a range of pins to be serviced in each frame. By default, all pins (1 through 40) are serviced. However, servicing every pin can consume substantial system throughput even if the pins are not doing anything. By reducing the number of pins which are serviced by each frame the time between pin servicings can be as short as 100us. Start Pin. This must be between 1 and the number of physical pins (40 on the 18F4620 based Serial Wombat) End Pin. This must be between the Start Pin value and the number of physical pins. Unused
0x03
3		 Reset Systime. Calling this parameter resets the Frame Counters from the 0x04 Get System Info command to zero. It has no parameters. Unused.
0x04
4		 Frame Counter Reset Value. This value is used to determine the the amount of time between the start of one frame and the start of the next frame. It is used to set Timer 0 of the 18F4620. The 16 bit value of this timer can be determined by the following equation:

Reset_value = 65532 - (Timer Clock Frequency/ Frames_Per_Second)

If the result is negative, use a slower timer clock frequency.

For example, the value for 500 frames per second with an 8000000 clock is 49532, or 0xC17C.

The value for 50 frames per second (20ms frames) with a 1,000,000 clock is 45536, or 0xB1E0.

Note that this command did not work properly before firmware Revision 1.2.0

 Reset Value (16 bits) Clock Frequency:

0: 8MHz
1: 4MHz
2: 2MHz
3: 1MHz
4: 500 kHz
5: 250 kHz
6: 125 kHz
7: 62.5kHz

  
0x05
5		 Enable Throughput Pin Output. Sets pin 6 to display when the processor is busy servicing an interrupt or the periodic frame. See the Throughput section of the documentation for more information. (Coming soon) 0: Pin 4 is a standard pin

1: Pin 4 shows processor utilization

 Unused
0x06
6		 Number of Analog Channels. The Wombat may have 0 to 13 pins configured as analog input channels. Each channel configured as an analog input uses some time out of the periodic frame to do its conversion. By default, 4 pins are set to analog inputs. For each number of analog inputs, specific pins become analog inputs. This is a property of the 18F4620 chip, and cannot be altered:
# of analog pins:   Analog pin numbers:
0   -
1   2
2   2,3
3   2,3,4
4   2,3,4,5
5   2,3,4,5,7
6   2,3,4,5,7,8
7   2,3,4,5,7,8,9
8   2,3,4,5,7,8,9,10
9   2,3,4,5,7,8,9,10,35
10   2,3,4,5,7,8,9,10,35,36
11   2,3,4,5,7,8,9,10,34,35,36
12   2,3,4,5,7,8,9,10,34,35,36,37
13   2,3,4,5,7,8,9,10,33,34, 35,36,37

After issuing this command it is left to the user to properly update all of the pins which have changed function to a mode which is compatible with that function.

 Number of Analog Channels  
0x19
25		 Configure Timer Base I/O See the page on this feature.
0x1C
28		 Enable / disable and Set Pin to be used as CTS pin (0 disables this feature, which is the default setting). The Wombat will delay sending response packets if the CTS pin is high. When this setting is configured it is also stored in EEPROM for use at subsequent power-ups. 0: Disable CTS functionality
1: Enable		 Pin to configure to CTS        

Configure Pins 1 to 28

0xA0
160

 This command is used to modify numerous pins with one command. The command uses 28 two-bit entries to represent the action for each pin:
Value Pin State
00 Low
01 High
10 Input
11 Unchanged

Pin 1 is represented by the two least-significant bits in the 2nd byte. Pin 4 is represented by the two most-significant bits in the 2nd byte. Pin 5 is represented by the two least-significant bits in the 3rd byte. Pin 28 is represented by the two most significant bits in the 7th byte.

The pins do not simultaneously change state. If requested, Pin 1 will change state first, followed by Pin 2, followed by Pin 3, and so on through pin 28. Pins which are acted on by this command change mode to CHANNEL_MODE_DIRECT.

This command is echoed back to the host upon completion.

Example: Set pin 1 to Low, pin 6 to High, pin 19 to Input, and pin 25 to Low. Leave all other pins unchanged.

Data Sent to the Wombat: 0xA0 0xFC 0xF7 0xFF 0xFF 0xEF 0xFF 0xFC
Binary:   11111100 11110111 11111111 11111111 11101111 11111111 11111100
Meaning: Configure Pins 1 to 28 Pins 1 to 4 Pins 5 to 8 Pins 9 to 12 Pins 13 to 16 Pins 17 to 20 Pins 21 to 24 Pins 25 to 28

Configure Pins 13 to 40

0xA1
161

 This command is used to modify numerous pins with one command and works in the same manner as Configure Pins 1 to 28, but operates on a different range of pins.

Pin 13 is represented by the two least-significant bits in the 2nd byte. Pin 14 is represented by the two most-significant bits in the 2nd byte. Pin 17 is represented by the two least-significant bits in the 3rd byte. Pin 40 is represented by the two most significant bits in the 7th byte.

The pins do not simultaneously change state. If requested, Pin 13 will change state first, followed by Pin 14, followed by Pin 15, and so on through pin 40. Pins which are acted on by this command change mode to CHANNEL_MODE_DIRECT.

This command is echoed back to the host upon completion.

Example: Set pin 17 to Low, pin 18 to High, pin 19 to Input, and pin 39 to Low. Leave all other pins unchanged.

Data Sent to the Wombat: 0xA1 0xFF 0xE4 0xFF 0xFF 0xFF 0xFF 0xCF
Binary:   11111111 11100100 11111111 11111111 11111111 11111111 11001111
Meaning: Configure Pins 13 to 40 Pins 13 to 16 Pins 17 to 20 Pins 21 to 24 Pins 25 to 28 Pins 29 to 32 Pins 33 to 36 Pins 37 to 40

Configure Channel Mode

0xC8 through 0xD1

200 thorugh 209

 The Configure Channel Mode command allows the host to configure a Wombat Pin or Channel to a specific function. For each Channel Mode one or more configuration commands will be defined. Some channel modes such as CHANNEL_MODE_ROTARY_ENCODER require more than one command to complete initialization. Other commands, such as CHANNEL_MODE_PWM_FOLLOW_DIRECT have multiple interfaces, one simple, and one which is more powerful but longer and more complicated. When a channel has multiple initialization commands they are differentiated by which command byte (200 through 209) is used to send the message.

See the section on channel modes for specific configuration commands for each channel mode.

 

 

 

 

 

 

  

Copyright Wombat Interface Products, 2005-2008. All Rights Reserved.