packet-level and transport-level protocols

7/28/2019 Packet-Level and Transport-Level Protocols

1/6

PPaacckkeett--LLeevveell aanndd TTrraannssppoorrtt--LLeevveellPPrroottooccoollss

www.digi lent inc.com

Revision: 2/16/06 215 E Main Suite D | Pullman, WA 99163(509) 334 6306 Voice and Fax

Doc: 576-278-000 page 1 of 6Copyright Digilent, Inc. All rights reserved.

Other product and company names mentioned may be trademarks of their respective owners.

Introduction

This document describes the protocols for constructing, sending, and receiving commands anddata 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 datapayloads between a master and a slave device independent of the hardware interface. All that isrequired of the interface is the ability to transmit byte-aligned data and to identify boundariesbetween packets.

Fundamentally, the protocol consists of packets containing a simple header (typically one or twobytes) followed by an arbitrary amount of application-specific data. All packets conform to thisformat, whether they are sent from the master to the slave, or vice-versa. The packet headersupper three bits indicate the type of packet, and the lower five bits (and the second byte, ifpresent) 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 toimplement specific transport-level protocols. The bytes specific meaning is interface-dependent, 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 binaryRS232 mode.

00010 synReqRd Sent by the master to request to read a packet from theslave. 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 bythe packets payload (if any). Should a master attempt to read from the slavewhen there is no data available for reading, an rspNoData packet will bereceived. 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 immediatelyafter 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 operandsother than the five lower bits, which denote either an application-specific command (highcommand id 16 -31) to be executed or one of the mandatory immediate commands (lowcommand id 0 - 15) that all slave devices must respect. All immediate commands may also beimplemented in the short format with a single byte parameter.


2/6

Packet-Level and Transport-Level Protocols Digilent, Inc.

www.digilentinc.com page 2 of 6Copyright Digilent, Inc. All rights reserved.


00000 cmdReset Resets the device to its power-on defaults.

00001 cmdGetRsp Returns the response code generated by the receptionand/or execution of the last packet in a single byte pktRsp packet. Upon sendingthe response code, the buffer will be reset to the default ofrspPacketOk.

00010 cmdGetDevType Returns the device class type and firmware revisionwithin 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 identifyingthe device and firmware revision. It may be up to 30 characters long (31 with null)in apktDataS.

00100 cmdGetDevCap Returns a 2-byte payload where each bit flags adevice class capability.

00101 cmdGetFirmVer Returns the firmware revision in a 2-byte payloadwhere the MSByte is a major revision number and the LSByte is a minor revisionnumber. For example, Rev 1.0.

00110 cmdGetPacketSize Returns the maximum packet payload sizesupported by this device in a 2-byte payload.

010s ssss pktCmdS A short-form command packet. The lower five bits in the headerbyte (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, thefirst byte of the packets payload will indicate the command to execute, with subsequentbytes 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 theheader byte (shown here as Hs) are the lower five bits in the upper byte of the datapayloads size, while the second byte (shown here as Ss) is the lower byte of the datapayloads 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 responseto a master. The lower five bits (shown here as Rs) denote the response code. Thefollowing codes are currently established, with all other codes being reserved for future use:

00000 (pktRsp + 0x00) rspPacketStart Sent by the slave to the master toindicate that it is cleared to begin transmission of a packet. Also sent by the slaveimmediately 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 toindicate that a packet was successfully received and processed. The responsecode buffer is populated with this at start-up and after a successful read of thebuffer (through cmdGetRsp).

00010 (pktRsp + 0x02) rspNoData Byte sent in response to a masterrequesting to read data when none is available.


3/6




11011 (pktRsp + 0x1B) rspCmdFailure Indicates that an internal errorunrelated to the communications protocol was encountered during execution of acommand. Commands which generate this error will indicate in their descriptionwhat conditions can cause such an error.

11100 (pktRsp + 0x1C) rspBadCommand Result code generated by theslave 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 (inmost cases, this means out-of-range).

11110 (pktRsp + 0x1E) rspBadType Result code generated by the slave toindicate that it does not respect the specified packet type.

11111 (pktRsp + 0x1F) rspBadPacket Result code generated by the slave toindicate that a packet was determined to be malformed. Generally, this is causedby an incorrect quantity of parameter data either too much or too little or bythe slave having received a different amount of data than indicated by theheader.

Transport-Level Protocols

The transport level is responsible for providing the interface-independent means of sendingpackets (as described previously). Currently, there are established protocols for sendingpackets 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 lineidles low), with the most significant bit (MSB) transferred first. Additionally, for multi-byteparameters, 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 masterthen begins continuously transmitting pktReqWr bytes, while waiting for the slave to respondwith an rspPacketStartbyte. The first byte received by the master after pulling the SS line lowshould always be discarded (because there is no way the slave could initially transmit a validbyte). 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 begintransmitting a valid packet. Packets begin with at least a one-byte packet header identifying thetype, length, and payload of a packet. The upper three bits of this first byte identify the packettype (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 willreceive and store all bytes from the master (unless its internal buffers become full a situationthat the master will receive no immediate notification of; an rspBadPacketerror will, however, begenerated and stored). All bytes received are assumed to be part of the packet, and if too few ortoo many bytes are sent for a particular packet, an rspBadPacket error will be generated. To


4/6




properly terminate a packet, the master must pull the SS line high immediately following thetransmission of the final byte in a packet.

Upon the SS line being pulled high, the slave will then begin processing the packet, and asuitable response code will be generated and stored to an internal buffer (overwriting anypreviously 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. Theresponse code may be read by issuing the cmdGetRsp immediate command, which all slavesare 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 continuouslysend pktReqRd bytes while waiting for the slave to respond with an rspPacketStart byte. Thefirst 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 willecho what was sent by the master on the previous byte (pktReqRd), until the slave respondswith rspPacketStart.

Immediately following the rspPacketStart byte, the slave will begin transmitting its responsepacket. First the packet header is sent, followed by the packets payload. Should the masterattempt to read beyond the length of the packet, it will receive synIdles. Additionally, the mastershould be transmitting synIdles while receiving the packet from the slave. Should the slave nothave 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 acomplete reference on how the TWI bus operates, see the TWI section of the Atmel data sheetfor 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 foranypktSyncbytes 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 busby bringing the data line (SDA) low while the clock line (SCL) remains high. It then clocks out asingle byte (MSB first) whose upper seven bits are the address of the slave device and whoselower 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 SCLline 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 bypulling the SDA line low on the ninth clock from the master. If the slave fails to acknowledge, byleaving the SDA line high on the ninth clock (known as a NACK condition), the master shouldbreak off communications by issuing a stop condition (bringing the SDA line high while the SCLline is already high).


5/6




It should be noted that there are two ranges of eight addresses that are reserved in the officialspecification, 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 notacknowledge 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 theexecution of a higher priority interrupt, or merely storing a previously received byte), it maydelay transmission of additional data by clock-stretching. That is, the slave will hold the SCLline low until it is no longer busy. When the master then attempts to bring the line back high, itmust detect that the SCL line is still low, and wait for it to be released by the slave to resumeclocking.

To perform a write to a slave, the master must address the slave in write mode, as previouslydescribed. 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 followingeach byte sent. If an ACK is not received, it can be inferred that the packet has failed tosuccessfully transmit, and communications should be immediately terminated by issuing a stopcondition to the bus.

Once the packet has been transmitted, the master must signal an end to communications byissuing a stop condition to the bus. At this point, the slave will begin processing the packet andgenerate an appropriate response code (overwriting any previously generated code). This codecan be queried using the immediate command cmdGetRsp. The slave may not respond to itsaddress 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 previouslydescribed). Following successful addressing (indicated by the slave acknowledging its address),subsequent bytes from the slave will contain the response packet, with the packet header sentfirst, followed by the payload. To conform to the TWI specification, the master shouldacknowledge every byte sent by the slave, except for the last byte, in response to which it mustsend 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 formarking boundaries between packets, or any other niceties. As such, additional synchronizationbytes are used to facilitate the transmission of the aforementioned interface-independentpackets.

To initiate a write to a slave, the master begins continuously transmitting synReqWrbytes to theslave. The slave, when it is ready, will respond with an rspPacketStart byte for every four


6/6




synReqWrs that it successfully receives (it will always respond to the first synReqWr followingreception of anything besides a synReqWr). Upon receiving the first start byte, the master mayimmediately begin transmitting a packet, as usual. No response is generated by the slave forany 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 atthis crucial point, the slave will discard the packet and generate an rspBadPacketerror. Oncethe 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 finishedprocessing the packet. Also note that sending a synDone immediately in response to anrspPacketStartwill also generate an rspBadPacketerror.

Reading from the slave is accomplished in a similar fashion. Initially, the master continuallytransmits synReqRd bytes, until the slave responds with a rspPacketStart. Note that due tobuffering issues on the master side, there is a potential for multiple rspPacketStartbytes to bereceived; 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 notaccept a packet received from the slave as valid unless it is prefixed with a rspPacketStartandterminated with a synDone. If there is no data to be read, the slave will send an rspNoDatapacket. The slave may not respond to consecutive requests to read with no data present.

packet-level and transport-level protocols

Documents