Packet-Level and Transport-Level Protocols

Revision: 2/16/06

www .d ig ilen tinc .c om

215 E Main Suite D | Pullman, WA 99163 (509) 334 6306 Voice and Fax

Introduction
This document describes the protocols for constructing, sending, and receiving commands and data between master and slave devices using the SPI, TWI, or RS232 binary interface.

Packet-Level Protocol
The packet-level protocol provides a transparent means of sending various command and data payloads between a master and a slave device independent of the hardware interface. All that is required of the interface is the ability to transmit byte-aligned data and to identify boundaries between packets. Fundamentally, the protocol consists of packets containing a simple header (typically one or two bytes) followed by an arbitrary amount of application-specific data. All packets conform to this format, whether they are sent from the master to the slave, or vice-versa. The packet headers upper three bits indicate the type of packet, and the lower five bits (and the second byte, if present) describe the sub-type. The following is a brief summary of all packet types and pre-defined sub-types: 000x xxxx pktSync This packet type includes various synchronization bytes used to implement specific transport-level protocols. The bytes specific meaning is interfacedependent, with some sub-types not being used by all interfaces. 00000 synIdle A filler byte sent by the slave or master. 00001 synReqWr Sent by the master to request to send a packet to the slave. The slave will not respond with meaningful data until it is ready to respond, at which point it will send an rspPacketStart. This is only used in SPI and binary RS232 mode. 00010 synReqRd Sent by the master to request to read a packet from the slave. The slave will not respond with meaningful data until it is ready to respond, at which point it will send an rspPacketStart, then a packet header followed by the packets payload (if any). Should a master attempt to read from the slave when there is no data available for reading, an rspNoData packet will be received. This is only used in SPI and binary RS232 mode. 00011 synDone In binary RS232 mode, this is used to terminate every packet sent (by either the master or the slave). This must be transmitted immediately after the last data byte of the packet for it to be recognized as valid.

001c cccc pktCmdI An immediate command byte. Immediate commands have no operands other than the five lower bits, which denote either an application-specific command (high command id 16 -31) to be executed or one of the mandatory immediate commands (low command id 0 - 15) that all slave devices must respect. All immediate commands may also be implemented in the short format with a single byte parameter.
Doc: 576-278-000
Copyright Digilent, Inc. All rights reserved. Other product and company names mentioned may be trademarks of their respective owners.

page 1 of 6

Packet-Level and Transport-Level Protocols

Digilent, Inc.

00000 cmdReset Resets the device to its power-on defaults. 00001 cmdGetRsp Returns the response code generated by the reception and/or execution of the last packet in a single byte pktRsp packet. Upon sending the response code, the buffer will be reset to the default of rspPacketOk. 00010 cmdGetDevType Returns the device class type and firmware revision within the class in a 2-byte payload pktDataS. The first byte is the device class type, and the second byte is the specific device ID. 00011 cmdGetDevName Returns a null-terminated ASCII string identifying the device and firmware revision. It may be up to 30 characters long (31 with null) in a pktDataS. 00100 cmdGetDevCap Returns a 2-byte payload where each bit flags a device class capability. 00101 cmdGetFirmVer Returns the firmware revision in a 2-byte payload where the MSByte is a major revision number and the LSByte is a minor revision number. For example, Rev 1.0. 00110 cmdGetPacketSize Returns the maximum packet payload size supported by this device in a 2-byte payload.

010s ssss pktCmdS A short-form command packet. The lower five bits in the header byte (shown here as Ss) denote the length of the data contained in the rest of the packet. This payload data represents an application-specific command and operands. Typically, the first byte of the packets payload will indicate the command to execute, with subsequent bytes representing command parameters. 011s ssss pktDataS A short-form data packet. The lower five bits in the header byte (shown here as Ss) denote the length of the data contained in the rest of the packet. 100h hhhh ssss ssss pktDataL A long-form data packet. The lower five bits in the header byte (shown here as Hs) are the lower five bits in the upper byte of the data payloads size, while the second byte (shown here as Ss) is the lower byte of the data payloads size (representing a maximum payload size of 2^(5+8) = 8KB). 101x xxxx pktRsv1 This packet type is reserved for future uses. 110x xxxx pktRsv2 This packet type is reserved for future uses. 111r rrrr pktRsp Response byte. A slave device may generate these bytes in response to a master. The lower five bits (shown here as Rs) denote the response code. The following codes are currently established, with all other codes being reserved for future use: 00000 (pktRsp + 0x00) rspPacketStart Sent by the slave to the master to indicate that it is cleared to begin transmission of a packet. Also sent by the slave immediately prior to transmission of any response packet (pktRsp, pktDataS, etc.). This is only used in SPI and binary RS232 mode. 00001 (pktRsp + 0x01) rspPacketOk Result code generated by the slave to indicate that a packet was successfully received and processed. The response code buffer is populated with this at start-up and after a successful read of the buffer (through cmdGetRsp). 00010 (pktRsp + 0x02) rspNoData Byte sent in response to a master requesting to read data when none is available.
www.digilentinc.com
Copyright Digilent, Inc. All rights reserved. Other product and company names mentioned may be trademarks of their respective owners.

page 2 of 6

Packet-Level and Transport-Level Protocols

Digilent, Inc.

11011 (pktRsp + 0x1B) rspCmdFailure Indicates that an internal error unrelated to the communications protocol was encountered during execution of a command. Commands which generate this error will indicate in their description what conditions can cause such an error. 11100 (pktRsp + 0x1C) rspBadCommand Result code generated by the slave to indicate that it did not recognize a command specified in a command packet. 11101 (pktRsp + 0x1D) rspBadParameter Result code generated by the slave to indicate that a parameter for a valid command packet was invalid (in most cases, this means out-of-range). 11110 (pktRsp + 0x1E) rspBadType Result code generated by the slave to indicate that it does not respect the specified packet type. 11111 (pktRsp + 0x1F) rspBadPacket Result code generated by the slave to indicate that a packet was determined to be malformed. Generally, this is caused by an incorrect quantity of parameter data either too much or too little or by the slave having received a different amount of data than indicated by the header.

Transport-Level Protocols
The transport level is responsible for providing the interface-independent means of sending packets (as described previously). Currently, there are established protocols for sending packets over SPI, TWI, and RS232 binary interfaces.

Serial Peripheral Interface (SPI)

Generally, SPI uses mode 0 (sample on rising clock edge, setup on falling, and the clock line idles low), with the most significant bit (MSB) transferred first. Additionally, for multi-byte parameters, the least significant byte is sent first (little endian). To initiate a transfer with SPI, the master first pulls the slave-select (SS) line low. The master then begins continuously transmitting pktReqWr bytes, while waiting for the slave to respond with an rspPacketStart byte. The first byte received by the master after pulling the SS line low should always be discarded (because there is no way the slave could initially transmit a valid byte). Subsequent bytes will echo what was sent by the master on the previous byte (pktReqWr), until the slave responds with rspPacketStart. On the byte immediately following the reception of rspPacketStart, the master must begin transmitting a valid packet. Packets begin with at least a one-byte packet header identifying the type, length, and payload of a packet. The upper three bits of this first byte identify the packet type (as described in the previous section). During reception of a packet, the slave will transmit synIdles. Once the packet header has been transmitted, the packets payload is then sent. The slave will receive and store all bytes from the master (unless its internal buffers become full a situation that the master will receive no immediate notification of; an rspBadPacket error will, however, be generated and stored). All bytes received are assumed to be part of the packet, and if too few or too many bytes are sent for a particular packet, an rspBadPacket error will be generated. To
www.digilentinc.com
Copyright Digilent, Inc. All rights reserved. Other product and company names mentioned may be trademarks of their respective owners.

page 3 of 6

Packet-Level and Transport-Level Protocols

Digilent, Inc.

properly terminate a packet, the master must pull the SS line high immediately following the transmission of the final byte in a packet. Upon the SS line being pulled high, the slave will then begin processing the packet, and a suitable response code will be generated and stored to an internal buffer (overwriting any previously generated response code). The slave will not respond to additional commands over the SPI interface until packet processing has finished, and the response code is ready. The response code may be read by issuing the cmdGetRsp immediate command, which all slaves are required to respect. To read data from the slave following the execution of an instruction that generates a response (cmdGetRsp, for example), the master must first pull the SS line low. Then, it must continuously send pktReqRd bytes while waiting for the slave to respond with an rspPacketStart byte. The first byte received by the master after pulling the SS line low should always be discarded (because there is no way the slave could initially transmit a valid byte). Subsequent bytes will echo what was sent by the master on the previous byte (pktReqRd), until the slave responds with rspPacketStart. Immediately following the rspPacketStart byte, the slave will begin transmitting its response packet. First the packet header is sent, followed by the packets payload. Should the master attempt to read beyond the length of the packet, it will receive synIdles. Additionally, the master should be transmitting synIdles while receiving the packet from the slave. Should the slave not have any valid data to send, it will instead transmit a single rspNoData byte.

Two-Wire Interface (TWI)

The complete details of the TWI bus operation are beyond the scope of this document. For a complete reference on how the TWI bus operates, see the TWI section of the Atmel data sheet for an AVR microcontroller such as the ATmega64. With TWI, there are methods for indicating a masters desire to read or write data to a slave, and methods for delaying communications when a slave is busy. This eliminates the need for any pktSync bytes to be sent when using the TWI interface. When a master wishes to communicate with a slave, it first places a start condition on the bus by bringing the data line (SDA) low while the clock line (SCL) remains high. It then clocks out a single byte (MSB first) whose upper seven bits are the address of the slave device and whose lower bit indicates whether the master is reading (LSB = 1) or writing (LSB = 0) from the slave. The SDA line, except during start and stop conditions, should always be stable while the SCL line is high (the data on SDA is setup while the SCL is low and sampled while it is high). When a slave is successfully addressed, it will send an acknowledge (ACK) to the master by pulling the SDA line low on the ninth clock from the master. If the slave fails to acknowledge, by leaving the SDA line high on the ninth clock (known as a NACK condition), the master should break off communications by issuing a stop condition (bringing the SDA line high while the SCL line is already high).

www.digilentinc.com
Copyright Digilent, Inc. All rights reserved. Other product and company names mentioned may be trademarks of their respective owners.

page 4 of 6

Packet-Level and Transport-Level Protocols

Digilent, Inc.

It should be noted that there are two ranges of eight addresses that are reserved in the official specification, to which no standard-mode TWI device should respond. These include 0x00 0x07 and 0x78 0x7F (inclusive). If the slave is busy (processing a previously received packet, for example), it may choose to not acknowledge its address on the TWI bus. This will allow the master to move on to communicating with other devices, if it wishes, while the busy device finishes its current task. The master should attempt to re-address the device and resume communications later. If the slave becomes temporarily busy during communications (for example, due to the execution of a higher priority interrupt, or merely storing a previously received byte), it may delay transmission of additional data by clock-stretching. That is, the slave will hold the SCL line low until it is no longer busy. When the master then attempts to bring the line back high, it must detect that the SCL line is still low, and wait for it to be released by the slave to resume clocking. To perform a write to a slave, the master must address the slave in write mode, as previously described. Following an ACK from the slave, the master should then transmit the packet header and then the packets payload. The master should check for an ACK from the slave following each byte sent. If an ACK is not received, it can be inferred that the packet has failed to successfully transmit, and communications should be immediately terminated by issuing a stop condition to the bus. Once the packet has been transmitted, the master must signal an end to communications by issuing a stop condition to the bus. At this point, the slave will begin processing the packet and generate an appropriate response code (overwriting any previously generated code). This code can be queried using the immediate command cmdGetRsp. The slave may not respond to its address until it has finished processing the packet. To read data from the slave following execution of a command expected to generate response data (cmdGetRsp, for example), the master must address the slave in read mode (as previously described). Following successful addressing (indicated by the slave acknowledging its address), subsequent bytes from the slave will contain the response packet, with the packet header sent first, followed by the payload. To conform to the TWI specification, the master should acknowledge every byte sent by the slave, except for the last byte, in response to which it must send a NACK. Should there be no data available to read, the slave will return a single byte rspNoData packet. Attempting to read beyond the length of a packet will merely yield synIdles.

Binary RS232 Interface

Because RS232 is an inherently asynchronous interface, there are no built-in provisions for marking boundaries between packets, or any other niceties. As such, additional synchronization bytes are used to facilitate the transmission of the aforementioned interface-independent packets. To initiate a write to a slave, the master begins continuously transmitting synReqWr bytes to the slave. The slave, when it is ready, will respond with an rspPacketStart byte for every four
www.digilentinc.com
Copyright Digilent, Inc. All rights reserved. Other product and company names mentioned may be trademarks of their respective owners.

page 5 of 6

Packet-Level and Transport-Level Protocols

Digilent, Inc.

synReqWrs that it successfully receives (it will always respond to the first synReqWr following reception of anything besides a synReqWr). Upon receiving the first start byte, the master may immediately begin transmitting a packet, as usual. No response is generated by the slave for any bytes received at this point. Immediately following transmission of the last byte in the packet, the master must transmit a synDone to indicate the end of the packet. Should the master fail to send the appropriate byte at this crucial point, the slave will discard the packet and generate an rspBadPacket error. Once the synDone is received, the slave will begin packet processing and generate a response code (readable via cmdGetRsp). The slave may not respond to additional queries until it has finished processing the packet. Also note that sending a synDone immediately in response to an rspPacketStart will also generate an rspBadPacket error. Reading from the slave is accomplished in a similar fashion. Initially, the master continually transmits synReqRd bytes, until the slave responds with a rspPacketStart. Note that due to buffering issues on the master side, there is a potential for multiple rspPacketStart bytes to be received; these should be discarded. Immediately following the last start byte, the slave will then (with no intervention from the master) send the rest of the packet. Following the last byte of the packet, the slave will also send a synDone. The master should not accept a packet received from the slave as valid unless it is prefixed with a rspPacketStart and terminated with a synDone. If there is no data to be read, the slave will send an rspNoData packet. The slave may not respond to consecutive requests to read with no data present.

www.digilentinc.com
Copyright Digilent, Inc. All rights reserved. Other product and company names mentioned may be trademarks of their respective owners.

page 6 of 6