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 header’s 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 byte’s 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 packet’s 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

011s ssss – pktDataS A short-form data packet. The lower five bits in the header byte (shown here as H’s) are the lower five bits in the upper byte of the data payload’s size. 010s ssss – pktCmdS A short-form command packet. page 2 of 6 . while the second byte (shown here as S‘s) is the lower byte of the data payload’s size (representing a maximum payload size of 2^(5+8) = 8KB). The lower five bits (shown here as R’s) denote the response code. This is only used in SPI and binary RS232 mode. 100h hhhh ssss ssss – pktDataL A long-form data packet. with subsequent bytes representing command parameters. and the second byte is the specific device ID.digilentinc. Other product and company names mentioned may be trademarks of their respective owners. 00011 – cmdGetDevName Returns a null-terminated ASCII string identifying the device and firmware revision. Rev 1.0.). the buffer will be reset to the default of rspPacketOk. Also sent by the slave immediately prior to transmission of any response packet (pktRsp. etc. • • • • • • • 00000 – cmdReset Resets the device to its power-on defaults. 00010 – cmdGetDevType Returns the device class type and firmware revision within the class in a 2-byte payload pktDataS. 00110 – cmdGetPacketSize Returns the maximum packet payload size supported by this device in a 2-byte payload. 110x xxxx – pktRsv2 This packet type is reserved for future uses. • 00010 (pktRsp + 0x02) – rspNoData Byte sent in response to a master requesting to read data when none is available. All rights reserved. The first byte is the device class type. • 00001 (pktRsp + 0x01) – rspPacketOk Result code generated by the slave to indicate that a packet was successfully received and processed. Inc. www. Upon sending the response code. For example. 111r rrrr – pktRsp Response byte. The lower five bits in the header byte (shown here as S‘s) denote the length of the data contained in the rest of the packet. The lower five bits in the header byte (shown here as S’s) denote the length of the data contained in the rest of the packet.Packet-Level and Transport-Level Protocols Digilent. Typically. 101x xxxx – pktRsv1 This packet type is reserved for future uses. pktDataS. A slave device may generate these bytes in response to a master. Inc.com Copyright Digilent. The response code buffer is populated with this at start-up and after a successful read of the buffer (through cmdGetRsp). 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. 00001 – cmdGetRsp Returns the response code generated by the reception and/or execution of the last packet in a single byte pktRsp packet. It may be up to 30 characters long (31 with null) in a pktDataS. This payload data represents an application-specific command and operands. 00100 – cmdGetDevCap Returns a 2-byte payload where each bit flags a device class capability. 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. the first byte of the packet’s payload will indicate the command to execute. The following codes are currently established.

Generally. All bytes received are assumed to be part of the packet. and payload of a packet. the least significant byte is sent first (little endian). 11100 (pktRsp + 0x1C) – rspBadCommand Result code generated by the slave to indicate that it did not recognize a command specified in a command packet. Serial Peripheral Interface (SPI) Generally.com Copyright Digilent. with the most significant bit (MSB) transferred first. Once the packet header has been transmitted. 11110 (pktRsp + 0x1E) – rspBadType Result code generated by the slave to indicate that it does not respect the specified packet type. and the clock line idles low). To www. an rspBadPacket error will. The master then begins continuously transmitting pktReqWr bytes. During reception of a packet. the packet’s payload is then sent. Packets begin with at least a one-byte packet header identifying the type. length. and if too few or too many bytes are sent for a particular packet. this means out-of-range). 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). an rspBadPacket error will be generated. page 3 of 6 . setup on falling. Inc. the master must begin transmitting a valid packet. for multi-byte parameters. however. Other product and company names mentioned may be trademarks of their respective owners. • • • • • 11011 (pktRsp + 0x1B) – rspCmdFailure Indicates that an internal error unrelated to the communications protocol was encountered during execution of a command. TWI. be generated and stored). Subsequent bytes will echo what was sent by the master on the previous byte (pktReqWr). Currently. 11111 (pktRsp + 0x1F) – rspBadPacket Result code generated by the slave to indicate that a packet was determined to be malformed. Transport-Level Protocols The transport level is responsible for providing the interface-independent means of sending packets (as described previously). the master first pulls the slave-select (SS) line low. until the slave responds with rspPacketStart. The upper three bits of this first byte identify the packet type (as described in the previous section). 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. On the byte immediately following the reception of rspPacketStart. there are established protocols for sending packets over SPI. SPI uses mode 0 (sample on rising clock edge. Additionally. Commands which generate this error will indicate in their description what conditions can cause such an error.digilentinc. and RS232 binary interfaces. while waiting for the slave to respond with an rspPacketStart byte. 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. Inc. To initiate a transfer with SPI. All rights reserved. the slave will transmit synIdles.Packet-Level and Transport-Level Protocols Digilent. 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.

and a suitable response code will be generated and stored to an internal buffer (overwriting any previously generated response code). The response code may be read by issuing the cmdGetRsp immediate command. When a slave is successfully addressed. Upon the SS line being pulled high.Packet-Level and Transport-Level Protocols Digilent. Two-Wire Interface (TWI) The complete details of the TWI bus’ operation are beyond the scope of this document. Additionally. and methods for delaying communications when a slave is busy. www. To read data from the slave following the execution of an instruction that generates a response (cmdGetRsp. the master should break off communications by issuing a stop condition (bringing the SDA line high while the SCL line is already high). With TWI. the master must first pull the SS line low. All rights reserved. If the slave fails to acknowledge. the master must pull the SS line high immediately following the transmission of the final byte in a packet. Then. Immediately following the rspPacketStart byte. it first places a start condition on the bus by bringing the data line (SDA) low while the clock line (SCL) remains high. 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). there are methods for indicating a master’s desire to read or write data to a slave. Subsequent bytes will echo what was sent by the master on the previous byte (pktReqRd). by leaving the SDA line high on the ninth clock (known as a NACK condition). and the response code is ready.com Copyright Digilent. Inc. see the TWI section of the Atmel data sheet for an AVR microcontroller such as the ATmega64. First the packet header is sent. the master should be transmitting synIdles while receiving the packet from the slave. it will send an acknowledge (ACK) to the master by pulling the SDA line low on the ninth clock from the master. The SDA line. Inc. Should the master attempt to read beyond the length of the packet. 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. For a complete reference on how the TWI bus operates. When a master wishes to communicate with a slave. Other product and company names mentioned may be trademarks of their respective owners. it will instead transmit a single rspNoData byte. it will receive synIdles. This eliminates the need for any pktSync bytes to be sent when using the TWI interface. it must continuously send pktReqRd bytes while waiting for the slave to respond with an rspPacketStart byte. followed by the packet’s payload. 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). The slave will not respond to additional commands over the SPI interface until packet processing has finished.digilentinc. Should the slave not have any valid data to send. except during start and stop conditions. properly terminate a packet. page 4 of 6 . for example). which all slaves are required to respect. the slave will then begin processing the packet. the slave will begin transmitting its response packet. until the slave responds with rspPacketStart.

the master must signal an end to communications by issuing a stop condition to the bus. Other product and company names mentioned may be trademarks of their respective owners. and communications should be immediately terminated by issuing a stop condition to the bus.digilentinc. with the packet header sent first. All rights reserved. it may delay transmission of additional data by “clock-stretching”. If an ACK is not received. At this point. The slave. page 5 of 6 . When the master then attempts to bring the line back high. Attempting to read beyond the length of a packet will merely yield synIdles. will respond with an rspPacketStart byte for every four www. As such. These include 0x00 – 0x07 and 0x78 – 0x7F (inclusive). the slave will hold the SCL line low until it is no longer busy. subsequent bytes from the slave will contain the response packet. If the slave is busy (processing a previously received packet. the master must address the slave in write mode. The master should attempt to re-address the device and resume communications later. To initiate a write to a slave. To read data from the slave following execution of a command expected to generate response data (cmdGetRsp. followed by the payload. Following successful addressing (indicated by the slave acknowledging its address). the slave will begin processing the packet and generate an appropriate response code (overwriting any previously generated code). while the busy device finishes its current task. additional synchronization bytes are used to facilitate the transmission of the aforementioned interface-independent packets.com Copyright Digilent. it must detect that the SCL line is still low. Inc. Binary RS232 Interface Because RS232 is an inherently asynchronous interface. the master must address the slave in read mode (as previously described). or any other niceties. except for the last byte. or merely storing a previously received byte). The master should check for an ACK from the slave following each byte sent. Following an ACK from the slave. it may choose to not acknowledge its address on the TWI bus. It should be noted that there are two ranges of eight addresses that are reserved in the official specification. To perform a write to a slave. for example). for example). the slave will return a single byte rspNoData packet. when it is ready. This code can be queried using the immediate command cmdGetRsp. if it wishes. there are no built-in provisions for marking boundaries between packets. to which no standard-mode TWI device should respond. Once the packet has been transmitted. and wait for it to be released by the slave to resume clocking. the master should acknowledge every byte sent by the slave. If the slave becomes temporarily busy during communications (for example. The slave may not respond to its address until it has finished processing the packet. Should there be no data available to read. due to the execution of a higher priority interrupt. in response to which it must send a NACK. the master should then transmit the packet header and then the packet’s payload. it can be inferred that the packet has failed to successfully transmit. To conform to the TWI specification. the master begins continuously transmitting synReqWr bytes to the slave. as previously described.Packet-Level and Transport-Level Protocols Digilent. Inc. That is. This will allow the master to move on to communicating with other devices.

there is a potential for multiple rspPacketStart bytes to be received.com Copyright Digilent. these should be discarded. Note that due to buffering issues on the master side.Packet-Level and Transport-Level Protocols Digilent. the slave will send an rspNoData packet. the slave will then (with no intervention from the master) send the rest of the packet. Immediately following the last start byte. 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. Upon receiving the first start byte. Following the last byte of the packet. Initially. Immediately following transmission of the last byte in the packet. the master may immediately begin transmitting a packet. Inc. If there is no data to be read. the master continually transmits synReqRd bytes. Also note that sending a synDone immediately in response to an rspPacketStart will also generate an rspBadPacket error. the slave will also send a synDone. The slave may not respond to additional queries until it has finished processing the packet. the slave will discard the packet and generate an rspBadPacket error. as usual. No response is generated by the slave for any bytes received at this point. page 6 of 6 . Other product and company names mentioned may be trademarks of their respective owners. synReqWrs that it successfully receives (it will always respond to the first synReqWr following reception of anything besides a synReqWr). Should the master fail to send the appropriate byte at this crucial point. until the slave responds with a rspPacketStart. Reading from the slave is accomplished in a similar fashion. Inc. www. The slave may not respond to consecutive requests to read with no data present.digilentinc. All rights reserved. the master must transmit a synDone to indicate the end of the packet. Once the synDone is received. the slave will begin packet processing and generate a response code (readable via cmdGetRsp).