Command Interface

Communication Protocol

The Packet Sniffer target firmware communicates over the UART interface. The host PC typically uses a USB-to-UART bridge. This USB-to-UART bridge is, for example, included in XDS110 emulators on Texas Instruments LaunchPads, e.g. LAUNCHXL-CC1310.

Byte Ordering

Multi byte fields are transferred over the UART interface in little endian format.

Example:

The timestamp field in Data packets are 6 bytes.

A timestamp value of 0x605040302010 will be sent over the UART interface in the following order where the leftmost byte is sent first.

0x10 0x20 0x30 0x40 0x50 0x60

The data received from the radio are treated as byte oriented and sent to host in the same order as received from the radio.

Protocol data types

The communication protocol has three different types of packets:

  • Command Packets
  • Command Response Packets
  • Data Streaming and Error Packets.

The commands from host to sniffer are synchronous. That is the command response is sent when the command is completed.

UART connection settings

The following settings are used for the UART connection:

Table 1 UART connection settings
Baud Rate 921600 baud
Data Bits 8
Stop Bits 1
Parity None
Flow Control No

General packet format

The UART packet format is shown in the table below. Table 3 describes each field of the packet format.

The packet Info field is divided in two bit fields:

  • Packet Category,
  • Packet Type.
Table 2 General UART packet format
Start of Frame Packet Info Packet Length Payload FCS End of Frame (EOF)
2B 1B 2B 0-2049B 1B 2B

Three packet categories are defined:

  • Command: Command and configuration data sent from host to sniffer target. See section Command Packet.
  • Command Response: Response from sniffer target on a received Command packet. See section Command Response Packet.
  • Data Streaming and Error: Packets sent from sniffer target. These packets carry data captured by the radio over the air or error reports. See section Data Streaming and Error Packets.

All of the packet categories are further divided into several packet types.

Table 3 UART packet field descriptions
Field Name Size Bitfield Name Bitfield Size Bitfield Index Description
SOF 2 Bytes       Start of Frame Delimiter (value 0x5340)
Packet Info 1 Byte Packet Category 2 bits 6-7

Category of Packet

  • 0x0: Reserved
  • 0x1: Command
  • 0x2: Command Response
  • 0x3: Data Streaming and Error
Packet Type 6 bits 0-5

Packet type for the specified category:

  • 0-63: Packet type 0-63
Packet Length 2 Bytes       The length of the payload field
Payload Data 0-2049 Bytes       Payload data. The format depends on packet category and packet type
FCS 0-1 Byte       Frame Check Sequence. This field is only included for Command and Command Response packets. It is not used for Data Streaming and Error packets.
EOF 2 Bytes       End of Frame Delimiter value (0x4540)

Frame Check Sequence

The Command and Command Response categories have a 1 byte FCS field after the payload. The FCS value is computed as follows:

  1. Add all bytes in these fields: Packet Info, Packet Length and Payload.
  2. AND the result from step 1 with 0xFF.

Command Packet

Command packets are used during configuration of the sniffer device. Command packets are sent from the host to the sniffer device. The packet format of the command data packets follows the General UART packet format and includes one byte FCS.

The payload data in Command packets is described in the following sections. The maximum payload size for command packets is 255 bytes.

After reception of a Command packet sent from host, the sniffer target responds with a Command Response packet (see section Command Response Packet).

Table 4 Command packet format
Start of Frame Packet Info Packet Length Command data FCS End of Frame (EOF)
2B 1B 2B 0-255B 1B 2B

The table below lists the Packet Info value and payload format for each command packet type.

Command Packet Info Value Packet Category Packet Type Payload
CMD_PING 0x40 0x1 0x0 Not used (0 Bytes)
CMD_START 0x41 0x1 0x1 Not used (0 Bytes)
CMD_STOP 0x42 0x1 0x2 Not used (0 Bytes)
CMD_PAUSE 0x43 0x1 0x3 Not used (0 Bytes)
CMD_RESUME 0x44 0x1 0x4 Not used (0 Bytes)
CMD_CFG_FREQUENCY 0x45 0x1 0x5 4 Bytes. See CMD_CFG_FREQUENCY
CMD_CFG_PHY 0x47 0x1 0x7 1 Byte. See CMD_CFG_PHY
CMD_CFG_WBMS_CHANNEL_TABLE 0x50 0x1 0x10 38 Bytes. See CMD_CFG_WBMS_CHANNEL_TABLE
CMD_CFG_BLE_INITIATOR_ADDRESS 0x70 0x1 0x30 6 Bytes. See CMD_CFG_INITIATOR_ADDRESS

CMD_PING

CMD_PING can be used to check successful connection between host and sniffer device. This command is always valid, independent of state of the sniffer device. After receiving CMD_PING successfully the sniffer device will respond with a Command Response packet with OK status.

CMD_START

Start packet sniffer with current radio configuration.

CMD_STOP

Stop packet sniffer.

CMD_PAUSE

Pause packet sniffer. The internal timestamp timer will continue to run. Data packets are not forwarded to the UART interface.

CMD_RESUME

Resume packet sniffer. CMD_RESUME shall be issued after a CMD_PAUSE to resume packet forwarding to the UART interface.

CMD_CFG_FREQUENCY

Set frequency for packet sniffer. This command does not change control state, and is only valid after initialization or when sniffer is stopped (CMD_STOP).

CMD_CFG_FREQUENCY shall have a payload of 4 bytes as described in the table below.

The resulting frequency will be set to (frequency + fractFrequency/65536) MHz.

Field Name Byte Index Description
Frequency 0-1 Frequency in MHz
FractFrequency 2-3 Fractional part of frequency in MHz

CMD_CFG_PHY

Set PHY for packet sniffer. This command does not change control state, and is only valid when in the STOPPED or INIT state (see state chart in the ‘Functional Description’ section). This command does not take effect in any other control state.

CMD_CFG_PHY shall have a payload of 1 byte as described in the table below.

The term PHY here is meant as a unique combination of PHY settings/protocol and frequency band. Some examples are shown below where each example listed would correspond to a separate PhyIndex:

  1. IEEE 802.15.4ge with SimpleLink Long Range 5 Kbps PHY in the 915/868 MHz frequency bands.
  2. RF Proprietary mode with SimpleLink Long Range 5 Kbps PHY in the 915/868 MHz frequency bands.
  3. IEEE 802.15.4 in the 2.4 GHz frequency band (O-QPSK PHY).

Each device type have a separate table of supported PHYs (PHY indexes). The tables of supported PHYs for each hardware platform are shown below.

Table 5 CMD_CFG_PHY payload data
Field Name Byte Index Description
PhyIndex 0 Index of the PHY to use. See description of term PHY in the text above this table.
Table 6 PHY index table for LAUNCHXL-CC1312R1
PHY Index Protocol Frequency Band PHY
0x0 IEEE 802.15.4ge (15.4 Stack) 868 and 915 MHz bands GFSK 50 kbps
0x1 IEEE 802.15.4ge (15.4 Stack) 868 and 915 MHz bands SLR (SimpleLink Long Range) 5 kbps
0x2 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 50 kbps (Wi-SUN mode 1a)
0x3 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 50 kbps (Wi-SUN mode 1b)
0x4 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 100 kbps (Wi-SUN mode 2a)
0x5 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 100 kbps (Wi-SUN mode 2b)
0x2 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 150 kbps (Wi-SUN mode 3)
0x7 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 200 kbps (Wi-SUN mode 4a)
0x8 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 200 kbps (Wi-SUN mode 4b)
0x9 ZigBee R23 868 and 915 MHz bands GFSK 100 kbps
0xA ZigBee R23 868 and 915 MHz bands GFSK 500 kbps
0xB RF Proprietary/EasyLink 868 and 915 MHz bands GFSK 50 kbps
0xC RF Proprietary/EasyLink 868 and 915 MHz bands SLR (SimpleLink Long Range) 5 kbps
Table 7 PHY index table for LAUNCHXL-CC1352R1
PHY Index Protocol Frequency Band PHY
0x0 IEEE 802.15.4ge (15.4 Stack) 868 and 915 MHz bands GFSK 50 kbps
0x1 IEEE 802.15.4ge (15.4 Stack) 868 and 915 MHz bands SLR (SimpleLink Long Range) 5 kbps
0x2 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 50 kbps (Wi-SUN mode 1a)
0x3 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 50 kbps (Wi-SUN mode 1b)
0x4 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 100 kbps (Wi-SUN mode 2a)
0x5 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 100 kbps (Wi-SUN mode 2b)
0x2 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 150 kbps (Wi-SUN mode 3)
0x7 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 200 kbps (Wi-SUN mode 4a)
0x8 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 200 kbps (Wi-SUN mode 4b)
0x9 ZigBee R23 868 and 915 MHz bands GFSK 100 kbps
0xA ZigBee R23 868 and 915 MHz bands GFSK 500 kbps
0xB RF Proprietary/EasyLink 868 and 915 MHz bands GFSK 50 kbps
0xC RF Proprietary/EasyLink 868 and 915 MHz bands SLR (SimpleLink Long Range) 5 kbps
0xD IEEE 802.15.4 2.4 GHz band O-QPSK (IEEE 802.15.4)
0xE Bluetooth LE 2.4 GHz band BLE 1 Mbps
Table 8 PHY index table for LAUNCHXL-CC1352P1, LAUNCHXL-CC1352P-2 and LAUNCHXL-CC1352P-4
PHY Index Protocol Frequency Band PHY
0x0 IEEE 802.15.4ge (15.4 Stack) 868 and 915 MHz bands GFSK 50 kbps
0x1 IEEE 802.15.4ge (15.4 Stack) 433 MHz band GFSK 50 kbps
0x2 IEEE 802.15.4ge (15.4 Stack) 868 and 915 MHz bands SLR (SimpleLink Long Range) 5 kbps
0x3 IEEE 802.15.4ge (15.4 Stack) 433 MHz band SLR (SimpleLink Long Range) 5 kbps
0x4 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 50 kbps (Wi-SUN mode 1a)
0x5 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 50 kbps (Wi-SUN mode 1b)
0x6 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 100 kbps (Wi-SUN mode 2a)
0x7 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 100 kbps (Wi-SUN mode 2b)
0x8 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 150 kbps (Wi-SUN mode 3)
0x9 Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 200 kbps (Wi-SUN mode 4a)
0xA Wi-SUN (15.4 Stack) 868 and 915 MHz bands GFSK 200 kbps (Wi-SUN mode 4b)
0xB ZigBee R23 868 and 915 MHz bands GFSK 100 kbps
0xC ZigBee R23 868 and 915 MHz bands GFSK 500 kbps
0xD RF Proprietary/EasyLink 868 and 915 MHz bands GFSK 50 kbps
0xE RF Proprietary/EasyLink 433 MHz band GFSK 50 kbps
0xF RF Proprietary/EasyLink 868 and 915 MHz bands SLR (SimpleLink Long Range) 5 kbps
0x10 RF Proprietary/EasyLink 433 MHz band SLR (SimpleLink Long Range) 5 kbps
0x11 IEEE 802.15.4 2.4 GHz band O-QPSK (IEEE 802.15.4)
0x12 Bluetooth LE 2.4 GHz band BLE 1 Mbps
Table 9 PHY index table for LAUNCHXL-CC1350 and LAUNCHXL-CC1310
PHY Index Protocol Frequency Band PHY
0x0 IEEE 802.15.4ge (15.4 Stack) 868 and 915 MHz bands GFSK 50 kbps
0x1 IEEE 802.15.4ge (15.4 Stack) 433 MHz band GFSK 50 kbps
0x2 IEEE 802.15.4ge (15.4 Stack) 868 and 915 MHz bands GFSK 50 kbps Legacy*
0x3 IEEE 802.15.4ge (15.4 Stack) 868 and 915 MHz bands GFSK 200 kbps
0x4 IEEE 802.15.4ge (15.4 Stack) 868 and 915 MHz bands SLR (SimpleLink Long Range) 5 kbps
0x5 IEEE 802.15.4ge (15.4 Stack) 433 MHz band SLR (SimpleLink Long Range) 5 kbps
0x6 RF Proprietary/EasyLink 868 and 915 MHz bands GFSK 50 kbps
0x7 RF Proprietary/EasyLink 433 MHz band GFSK 50 kbps
0x8 RF Proprietary/EasyLink 868 and 915 MHz bands GFSK 200 kbps
0x9 RF Proprietary/EasyLink 868 and 915 MHz bands SLR (SimpleLink Long Range) 5 kbps
0xA RF Proprietary/EasyLink 433 MHz band SLR (SimpleLink Long Range) 5 kbps
Table 10 PHY index table for LAUNCHXL-CC26X2R1
PHY Index Protocol Frequency Band PHY
0x0 IEEE 802.15.4 2.4 GHz band O-QPSK (IEEE 802.15.4)
0x1 Bluetooth LE 2.4 GHz band BLE 1 Mbps
Table 11 PHY index table for LAUNCHXL-CC26X2RB
PHY Index Protocol Frequency Band PHY
0x0 IEEE 802.15.4 2.4 GHz band O-QPSK (IEEE 802.15.4)
0x1 Bluetooth LE 2.4 GHz band BLE 1 Mbps
Table 12 PHY index table for LAUNCHXL-CC2650
PHY Index Protocol Frequency Band PHY
0x0 IEEE 802.15.4 2.4 GHz band O-QPSK (IEEE 802.15.4)

CMD_CFG_INITIATOR_ADDRESS

Set the address of the specific Master (Initiator) device to follow in a BLE data connection.

Field Name Byte Index Description
InitiatorAddress 0-5 Address of Master (Initiator) device

CMD_CFG_WBMS_CHANNEL_TABLE

Force user specified channel table. The channel table found in received Pairing Request will be ignored after this command, until Link Layer is reset.

Field Name Byte Index Description
ChannelTableLength 0 Length of the new channel table
ChannelTable 1-37 Channel table

Command Response Packet

The command response packet is sent from the sniffer device in response to a Command packet. The Command Response data field includes at least 1 byte status, and may include more information bytes.

Table 13 Command Response packet format
Start of Frame Packet Info Packet Length Command Response data FCS End of Frame (EOF)
2B 1B 2B 0-255B 1B 2B

Command Response packet types

Packet info value for Command Response packets is 0x80 (Packet Category value is 0x2 and Packet type is 0x0).

General Command Response data

  • The Command Response packet sent as response to all commands except for CMD_PING has a 1 byte status field as data.

  • The Command Response to CMD_PING has additional data (see section CMD_PING Command Response data).

    Status
    1B

The status field shall have one of the following values:

Table 14 Status field values
Status Value Description
OK 0 Command was received correctly.
Timeout 1 Reception of Command timed out before all data was received.
FCS failed 2 Computation of frame check sequence did not succeed.
Invalid Command 3 The Command has invalid format or is not supported.
Invalid State 4 The Command is invalid for the current state of sniffer FW.

CMD_PING Command Response data

The data field for CMD_PING Response has the same 1 byte status field as the response to other commands plus additional data.

Status Chip ID Chip Rev FW ID FW Rev
1B 2B 1B 1B 2B
Field Description
Status The status field has the same value as described in Table 14.
Chip ID 2 bytes Chip Id field (for example 0x1350).
Chip Rev 1 byte Chip Revision hex value (for example Revision 2.1 -> 0x21).
FW ID 1 byte FW ID field. See Table 15.
FW Rev 2 bytes FW revision field. 1 byte major revision (MSB) and 1 byte minor revison (LSB).
Table 15 FW ID values
FW ID Target Board
0x0 LAUNCHXL-CC1350/LAUNCHXL-CC1310
0x20 LAUNCHXL-CC2650
0x21 LAUNCHXL-CC26X2R1
0x22 LAUNCHXL-CC26X2RB
0x30 LAUNCHXL-CC1352R1
0x40 LAUNCHXL-CC1312R1
0x50 LAUNCHXL-CC1352P1/LAUNCHXL-CC1352P-2/LAUNCHXL-CC1352P-4

Data Streaming and Error Packets

Data Streaming and Error packets are always sent from the sniffer device to the host. The packet format of Data Streaming and Error packets is shown in Table 16.

The Data Streaming and Error category has two different packet types:

  • Data packets are used to carry data from the radio received over the air.
  • Error packets are used to indicate error situations.
Table 16 Data streaming and error packet format
Start of Frame Packet Info Packet Length Payload End of Frame (EOF)
2B 1B 2B 0-2049B 2B

Data Streaming and Error packet formats

This section describes the formats of Data and Error packet types.

The packet info field is set as shown in the following table:

Packet Type Packet Info Packet Category Packet Type
Data 0xC0 0x3 0x0
Error 0xC1 0x3 0x1

Payload format, data packets

Table 17 Data Streaming packet type 1 payload format
Timestamp Payload RSSI Status byte
6B 0-2049B 1B 1B
Table 18 Data streaming and error packet payload fields
Field Size Description
Timestamp 6 Bytes Time stamp in microseconds since sniffer capture was started.
Payload 0-2047 Bytes Data as received over the air. May or may not include CRC bytes depending on the radio setting.
RSSI 1 Byte RSSI value. This is a copy of the RSSI byte generated by the radio in packet reception.
Status 1 Byte Status byte. 0x80: FCS OK, 0x00: FCS Not OK

The complete Data packet format is shown below:

Table 19 Complete Data packet
Start of Frame Packet Info Packet Length Timestamp Payload RSSI Status End of Frame (EOF)
2B 1B 2B 6B 0-2049B 1B 1B 2 B

For BLE packets, the first 8 bytes of the Payload field consists of BLE meta information as shown in the table below:

Table 20 BLE meta information in Payload field
Field Size Description
Channel 1 Byte The BLE channel that the packet was received on.
Connection Event Counter 2 Bytes Value of the connection event counter (only valid when in connected state).
Info 1 Byte

Information field with the following bit fields:

Bit 0-1: Direction info (direction of the packet when in connected state).

  • 0: Not connected
  • 1: Master to slave
  • 2: Slave to master
  • 3: Unknown direction

Bit 2-7: Reserved for future use
Access Address 4 Bytes The 4-byte Access Address.

Payload format, error packets

Error packets are used to indicate error situations. The payload is a 1 byte error code.

Error
1B
Table 21 Error codes
Error Error Code Description
RX_BUF_OVERFLOW 0x01 Radio Rx buffer have overflowed. Over Air packets may have been lost
Table 22 Complete Error packet
Start of Frame Packet Info Packet Length Error End of Frame (EOF)
2B 1B 2B 1B 2 B

The following table shows an example of a valid Error packet. The error code is in this example set to 0x01.

Start of Frame Packet Info Packet Length Error End of Frame (EOF)
0x40 0x53 0xC1 0x01 0x00 0x01 0x40 0x45

Start of Frame & End of Frame

All packets start with 2 Start of Frame bytes (SOF) and ends with 2 End of Frame bytes (EOF).

  • The SOF delimiter is 0x5340 (@S in Ascii letters).
  • The EOF delimiter is 0x4540 (@E in Ascii letters).

Command Examples

This section shows command examples with expected response.

The bytes are shown in the transmission order on the UART interface. The leftmost byte is transmitted first.

CMD_PING

SOF Packet Info Length FCS EOF
0x40 0x53 0x40 0x00 0x00 0x40 0x40 0x45

Expected response on CMD_PING with status OK:

Table 23 Command Response OK
SOF Packet Info Packet Length Status FCS EOF
0x40 0x53 0x80 0x01 0x00 0x00 0x81 0x40 0x45

CMD_CFG_FREQUENCY

This will set frequency to 865.5 MHz.

SOF Packet Info Length Frequency FractFrequency FCS EOF
0x40 0x53 0x45 0x04 0x00 0x61 0x03 0x00 0x80 0x2D 0x40 0x45

The expected response is the same as shown in Table 23.