Staging:CC3100 & CC3200 Protocol

Introduction
This page addresses the logical communication protocol between the CC3100 BoosterPack/CC3200 LaunchPad and the SPI host. This includes the synchronization from host to device and device to the host, as well the communication through operation codes and events. All communication between the device and the SPI host (e.g., a microcontroller) is carried out using SPI packets, and thus the SPI packet forms the outermost logical protocol layer. A single SPI packet is transferred always within a single active chip select period (between one falling and rising nCS edge). The CC3100/CC3200 protocol offers no means to fragment packets, that is all data belonging to a single packet must be sent inside one nCS active period. This page discusses what SPI communication to expect from each API command.

Every packet transferred over the SPI-Bus consists of 4-byte long SPI header followed by data bytes (SPI Payload). The CC3100 and CC3200 expect 32-bit aligned SPI communication, thus an SPI packet must always have even number of bytes. In case the data being transported has an odd number of bytes of data, an additional padding byte must be added. Although it is recommended to use 0x00 for a padding byte, this byte is not being evaluated and can therefore be arbitrary.

The shortest a packet can be to stay 32-bit aligned is 4 bytes, which can be seen when synchronizing the device and the host, this means the payload can be 0 bytes.

The fields in the 4-byte SPI header have different meanings, according to the direction of their communication.

As SPI-Bus is under full control of SPI master, the master has to select either to push (write) or pull (read) data from the CC3100/CC3200 device. The first packet of every API command the SPI master sends out is the synchronization word to tell the device if it is ready to read or write data. The table below has both of the synchronization words from the host to the device, as well as the sync word from the device to the host. The two LSBits of the sync word can have any value managed by the driver and the device.

For more information on the structure of the API command transmissions visit CC31xx Host Interface.

The SPI-Bus is capable of full duplex communications, but the CC3100 and CC3200 SPI communication protocol is implemented in a half-duplex manner: if the SPI master is sending data towards the device on the MOSI line, the bytes originating from the device can be ignored; and vice versa when the device sends data to the master on the MISO line, the device will not interpret the incoming bytes on the MOSI line.

Every command starts with the host sending the synchronization word towards the device, and after the synchronization word, whether it is read or write, that selection is valid and cannot be changed until the nCS goes back high.

Host to Device Protocol
The host communicates with the device using the following structure: When an API command is executed multiple packets are sent out over the SPI MOSI line. The API command can be broken up into two sections, the header which consists of the SYNC H2D-Write, the OPCODE, and the LENGTH, and the payload which consists of the DESCRIPTORS, and the PAYLOAD. The first packet is the SYNC H2D-Write, and always consists of the same four bytes.

Command
The next packet of the WRITE protocol contains the command OPCODE and then LENGTH of the payload. The first two bytes are the OPCODE; each API command has its own specific OPCODE. Within the command the last two bytes are the LENGTH that follows the command packet. The LENGTH is always two bytes but can notify any certain length for the payload from 0 bytes to 65535 bytes.

Data
The payload contains the DESCRIPTOR and the PAYLOAD. Both the DESCRIPTOR and the PAYLOAD can vary in length, but the longest the two can be together is 65535 bytes. The DESCRIPTOR contains and communicates information such as the parameters for each command. The PAYLOAD contains and communicates extra information that the host believes the device should know. There does not always have to be a DESCRIPTOR or a PAYLOAD, there can be one without the other, or both could not exist for a certain command.

During the entire transmission the device continues to send the same number of busy bytes over the MISO line as the host sends over the MOSI line, but because the SPI is implemented in a half-duplex manner the SPI master can ignore all bytes sent by the device during the WRITE protocol.

Device to Host Protocol
The device communicates with the host using the following structure:

For the device to communicate back to the host the CC3100/CC3200 must pull the IRQ line low. It is then up to the SPI master to respond to this (e.g., using a falling edge interrupt configured pin) by sending the SYNC H2D-Read packet over the MOSI line. The SYNC H2D-Read packet is always the same 4 bytes. The device then needs to synchronize with the host before it can begin communication. The device sends out the SYNC D2H packet which is almost always the same 4 bytes, one bit will vary between commands. Between the SYNC H2D-READ and the SYNC D2H garbage bytes will be sent on the MOSI and MISO. After the SYNC H2D-READ all bytes should be ignored until the IRQ line is pulled high again.

Command Complete
The second packet of the READ protocol contains the OPCODE and the LENGTH of the rest of the message. The first 2 bytes contain the OPCODE of the command complete and will vary between different API commands. The command complete OPCODE tells the host that the device successfully received the command and executed it. The last 2 bytes is the LENGTH. The LENGTH will vary between commands based on parameters of the code or if the command needed to collect data, this data will be transmitted in the PAYLOAD. The last half of the READ protocol contains the STATUS, DESCRIPTOR, and PAYLOAD. The next packet after the OPCODE and the LENGTH is the STATUS. The STATUS is 4 bytes long and represent the number of packets that NWP has room for. This means that the driver can send X amount of packets without being blocked. After the STATUS the DESCRIPTOR and PAYLOAD take up the rest of the transmission. Both the DESCRIPTOR and the PAYLOAD can vary in length, but the longest the two can be together along with the STATUS is 65535 bytes. The DESCRIPTOR contains and communicates information such as the parameters for each command. The PAYLOAD contains and communicates extra information that the device believes the host should know, or information that the host asked the device for. There does not always have to be a DESCRIPTOR or a PAYLOAD, there can be one without the other, or both could not exist for a certain command.

Event
Events have the same structure as command completes, but they are not the same thing. An Event is used to either acknowledge a command or to notify the SPI master of asynchronous unsolicited events. They follow exactly the same READ protocol as command completes do. Not every API command has a command complete and an event. The table below shows OPCODEs, command completes, and the event for each SimpleLink API.

During the entire transmission the host continues to send the same number of busy bytes over the MOSI line as the device sends over the MISO line, but because the SPI is implemented in a half-duplex manner the device can ignore all bytes sent by the SPI master during the READ protocol.

Summary Table
xxxxxx means there is no code for this value of the command

Device
The following information are for APIs used in device.h within the SDK. Please refer to device.h for a more detailed look on the parameters of the APIs. sl_Start 

sl_Stop

sl_EventMaskSet

sl_EventMaskGet

sl_DevSet

sl_DevGet

Net Config
The following information are for APIs used in netcfg.h within the SDK. Please refer to netcfg.h for a more detailed look on the parameters of the APIs. sl_NetCfgSet

sl_NetCfgGet

WLAN
The following information are for APIs used in wlan.h within the SDK. Please refer to wlan.h for a more detailed look on the parameters of the APIs. sl_WlanSetMode

sl_WlanConnect

sl_WlanDisconnect

sl_WlanProfileAdd

sl_WlanProfileGet

sl_WlanProfileDel

sl_WlanPolicySet

sl_WlanPolicyGet

sl_WlanRxStatStart

sl_WlanRxStatStop

sl_WlanRxStatGet

sl_WlanGetNetworkList

sl_WlanSmartConfigStart

sl_WlanSmartConfigStop

sl_WlanSet

sl_WlanGet

sl_WlanRxFilterAdd

sl_WlanRxFilterSet

sl_WlanRxFilterGet

Socket
The following information are for APIs used in socket.h within the SDK. Please refer to socket.h for a more detailed look on the parameters of the APIs. sl_Socket

sl_Close

sl_Bind

sl_Listen

sl_Accept

sl_Connect

sl_Select

sl_Send

sl_SendTo

sl_Recv

sl_RecvFrom

sl_SetSockOpt

sl_GetSockOpt

Net App
The following information are for APIs used in netapp.h within the SDK. Please refer to netapp.h for a more detailed look on the parameters of the APIs. sl_NetAppStart

sl_NetAppStop

sl_NetAppSet

sl_NetAppGet

sl_NetAppDnsGetHostByName

sl_NetAppMDNSRegisterService

sl_NetAppMDNSUnRegisterService

sl_NetAppGetServiceList

sl_NetAppDnsGetHostByService

sl_NetAppPingStart

File System
The following information are for APIs used in fs.h within the SDK. Please refer to fs.h for a more detailed look on the parameters of the APIs. sl_FsOpen

sl_FsClose

sl_FsRead

sl_FsWrite

sl_FsGetInfo

sl_FsDel

For more detailed information visit CC3xxx SimpleLink APIs