Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

CC3100 & CC3200 Transceiver Mode

From Texas Instruments Wiki
Jump to: navigation, search
Cc31xx cc32xx return home.png

Introduction

This page describes CC3x00’s ‘802.11 Transceiver Mode’, a powerful feature that allows the applications to send and receive raw data respecting 802.11 MAC and PHY layers.

The feature bypasses the IP and MAC layers altogether, thereby allowing application developers define their proprietary protocols over WLAN PHY.

Tx and Rx in 'Transceiver Mode'

Transmission

In ‘Transceiver Mode’, almost the entire frame space, starting from the legacy 802.11 MAC headers, can be used for transmitting proprietary information. Since the higher layers are not used in this mode, it’s not guaranteed that the frame will reach the destination – Also, there are no acknowledgments or retries at MAC level.

In this mode, the responsibility of defining the packet structure lies with the user. ‘Transceiver Mode’ is supported only in disconnected-mode, meaning, the device shouldn’t be connected to any access-point for using this feature

Building a RAW packet

This section explains how a RAW packet is built at the application level. For the purpose of discussion, let’s build a PING packet encapsulated w/ ICMP, IP and MAC protocols. Standard protocols are used to keep the discussion simple – Users can define their own protocols as well for transmitting data over WLAN PHY.

  • Let’s start building the RAW packet using below data – It’s the PING message that needs to be transmitted over WLAN PHY

Ping data tobe sent.png

  • PING is an ICMP QUERY message, and hence, should first be encapsulated w/ ICMP header.

Frame format icmp.png

  1. ICMP TYPE shall be set to 0x08 since this is an ‘Echo-Request’ message
  2. ICMP CODE shall always be 0x00 for PING message
  3. ICMP CHECKSUM is for header and data and is ‘0xA5, 0x51’ for our message
  4. ICMP DATA is “PING data to be sent” defined above
  • Before sending the ICMP encapsulated PING command to MAC layer, the messages should be encapsulated into IP datagrams. Below is the frame-format of IPv4 packet:

Frame format ip.png

  1. VER shall be set to 4 since it’s a IPv4 packet
  2. HLEN is header length in ‘lwords’ - It shall be set to 5 here since the header length is 20Bytes
  3. SERVICE TYPE shall be set to 0x00 since ICMP is a normal service
  4. TOTAL LENGTH shall be set as ‘0x00 0x54’ bytes, which includes header and data length
  5. IDENTIFICATION is the unique identity for all datagrams sent from this source IP – Let’s set it as ‘0x96, 0xA1’ for our packet
  6. FLAG and FRAGMENTATION OFFSET is set to 0x00, 0x00 since we don’t intent to fragment the packet. Reason: The packet that we are sending here is smaller than a WLAN frame size
  7. TIME TO LIVE shall be set to 0x40 since we want to discard the packet after 64 hops
  8. PROTOCOL is set to 0x01 since it’s an ICMP packet
  9. Next 2Bytes is HEADER CHECKSUM which shall be set to 0x57, 0xFA in our case
  10. SOURCE IP ADDRESS is set to 0xc0, 0xa8, 0x01, 0x64 (which is 192.168.1.100)
  11. DESTINATION IP ADDRESS is set to 0xc0, 0xa8, 0x01, 0x65 (which is 192.168.1.101)
  12. OPTIONS field is left blank
  • Next, LLC and MAC headers should be added to the IP encapsulated message. Below is the frame-format of LLC+SNAP header

Frame format ieee802.2.png

  1. DSAP is set to 0xAA to specify that it’s a SNAP frame
  2. SSAP is set to 0xAA to specify that it’s a SNAP frame
  3. CONTROL FIELD is set to 0x03 for SNAP (Sub-Network Access Protocol)
  4. VENDOR ID is set to 0x00, 0x00, 0x00
  5. PROTOCOL TYPE is set to 0x08, 0x00 – This is to indicate that the protocol at layer-4 is IP
  • The message is finally encapsulated w/ the MAC header. Below is the frame-format of 802.11 MAC header

Frame format 802.11MAC.png

  1. FRAME CONTROL is set to 0x88, 0x02 because of below configuration:
a. 2-Bits for Protocol Version shall be set as 00 for 802.11 standard
b. 2-Bits for Type shall be set as 10 for ‘Data’
c. 4-Bits for Subtype shall be set as 1000 for ‘QoS Data’
d. Frame Control Field 0x02 is to indicate that the frame is coming from a Distributed-System
2. DURATION ID is set to 44uS
3. DESTINATION MAC ADDRESS is set to 0x00, 0x23, 0x75, 0x55,0x55, 0x55
4. BSSID MAC ADDRESS is set to 0x00, 0x22, 0x75, 0x55,0x55, 0x55
5. SOURCE MAC ADDRESS is set to 0x00, 0x22, 0x75, 0x55,0x55, 0x55
6. SEQUENCE CONTROL FIELD is set to 0x42, 0x80
a. Sequence Number is set to 1064 – It’s the unique identity for all datagrams sent from this source MAC
b. Fragmentation Number is set to 0 – Indicates that there is no fragmentation required
  • The data packet is now encapsulated w/ ICMP, IP & MAC headers and is ready to be transmitted over WLAN PHY. Below is the complete packet

<syntaxhighlight lang="c"> RawPingPacket[] = {

               /*---- 802.11 MAC Header -----*/
                      0x88,
                      0x02,
                      0x2C, 0x00,
                      0x00, 0x23, 0x75, 0x55,0x55, 0x55,
                      0x00, 0x22, 0x75, 0x55,0x55, 0x55,
                      0x00, 0x22, 0x75, 0x55,0x55, 0x55,
                      0x80, 0x42, 0x00, 0x00,

/*---- LLC & SNAP Header -----*/

                      0xAA, 0xAA, 0x03, 0x00, 0x00, 0x00, 0x08, 0x00,
                      /*---- IP Header -----*/
                      0x45, 0x00, 0x00, 0x54, 0x96, 0xA1, 0x00, 0x00, 0x40, 0x01,
                      0x57, 0xFA,
                      0xc0, 0xa8, 0x01, 0x64,
                      0xc0, 0xa8, 0x01, 0x65,
                      /*---- ICMP Header -----*/
                      0x08, 0x00, 0xA5, 0x51,
                      0x5E, 0x18, 0x00, 0x00,
               /*---- Payload -----*/
                      0x41, 0x08, 0xBB, 0x8D, 0x00, 0x00,
                      0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                      0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                      0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                      0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                      0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                      0x00, 0x00, 0x00, 0x00
                      };

</syntaxhighlight>

Using host driver APIs to transmit the RAW packet

  • ‘Transceiver Mode’ is supported only in disconnected-mode. The application developers should ensure that the device is disconnected from all access-points and no connection-policies are set on CC3x00 device
  • Firstly, the socket has to be created with a couple of unique parameters to start the ‘Transceiver Mode’ feature
  1. Domain as SL_AF_RF: This is to indicate the device to override 802.11 headers for transmission and reception

For optimized power consumption, the socket will be started in TX-only mode until receive command is activated

  1. Type as SL_SOCK_RAW: This is to indicate that the socket is of raw data-type. And since ‘Domain’ is set to ‘SL_AF_RF’, this indicates the device that it’s a L1 socket
  2. <channel_number>: This is to configure the operational channel to receive and transmit data

On success, a 2Byte socket handle is returned that shall be used for subsequent socket operations

  • The encapsulated raw-data packet can now be sent using ‘sl_Send’ – It shall be called w/ below parameters
  1. <socket_handle>: A 2Byte handler returned when creating the socket
  2. RawPingPacket: It’s the encapsulated raw-data that’s to be transmitted over WLAN PHY
  3. <packet_size>: It’s the size of the packet in bytes
  4. <transmission_param>: In ‘Transceiver Mode’, macro ‘SL_RAW_RF_TX_PARAMS’ shall be used for setting the transmission parameters
a. <channel_number>: This is to configure the operational channel to receive and transmit data
b. <rate>: This is to configure the rate-of-transmission
c. <power_level>: This is to set the Tx power (1 being the highest) – Each level induces a 3dB loss on signal strength
d. <preamble>: This is to set the preamble value – A ‘0’ is to indicate a short-nibble and a ‘1’ is to indicate a long-nibble
  • The opened socket can then be closed using ‘sl_Close’ API

<syntaxhighlight lang="c">

  1. define POWER_LEVEL_TONE 1
  2. define PREAMBLE 1

INT32 TransceiverModeTx(INT8 <channel_number>, RateIndex_e <rate_for_tx>, INT32 <pkts_to_transmit>) {

   INT32 <socket_handle> = -1;
   <socket_handle> = sl_Socket(SL_AF_RF, SL_SOCK_RAW, <channel-number>);
   while(<pkts_to_transmit>--)
   {
       sl_Send(<socket_handle>, RawPingPacket, <packet_szie>, SL_RAW_RF_TX_PARAMS(<channel_number>, <rate_for_tx>, POWER_LEVEL_TONE, PREAMBLE));
   }
   sl_Close(<socket_handle>);

} </syntaxhighlight>

Reception

Using host driver APIs to receive the RAW packet

  • Again for reception in ‘Transceiver Mode’, application developers should ensure that the device is disconnected from all access-points and no connection-policies are set on CC3x00 device
  • Firstly, the socket has to be created with a couple of unique parameters to start the ‘Transceiver Mode’ feature
  1. Domain as SL_AF_RF: This is to indicate the device to override 802.11 headers for transmission and reception

For optimized power consumption, the socket will be started in TX-only mode until receive command is activated

  1. Type as SL_SOCK_RAW: This is to indicate that the socket is of raw data-type. And since ‘Domain’ is set to ‘SL_AF_RF’, this indicates the device that it’s a L1 socket
  2. <channel_number>: This is to configure the operational channel to receive and transmit data

On success, a 2Byte socket handle is returned that shall be used for subsequent socket operations

  • The raw-data packet can now be received using ‘sl_Recv’ – It shall be called w/ below parameters
  1. <socket_handle>: A 2Byte handler returned when creating the socket
  2. <buffer>: It’s the buffer into which the raw-data shall be received
  3. <packet_size>: It’s the size of the packet in bytes
  4. <flag>: It shall be set to ‘0’
  • CC3x00 device will add 8Bytes of proprietary radio header to the received packet. The header will have important information about the packet. The actual data will follow this 8Byte header and the application developers shall have to parse it as per their protocol
  • The opened socket can then be closed using ‘sl_Close’ API

<syntaxhighlight lang="c">

  1. define BUFFER_SIZE 1472

void TransceiverModeRx (INT8 <channel_number>, INT32 <pkts_to_receive>) {

   UINT8 buffer[BUFFER_SIZE] = {'\0'};
   INT32 <socket_hanlde> = -1;
   INT32 recievedBytes = 0;
   <socket_hanlde> = sl_Socket(SL_AF_RF, SL_SOCK_RAW, <channel_number>);
   while(<pkts_to_receive>--)
   {
       memset(&buffer[0], 0, sizeof(buffer));
       recievedBytes = sl_Recv(<socket_hanlde>, buffer, BUFFER_SIZE, 0);
   }
   sl_Close(<socket_handle>);

} </syntaxhighlight>

Decoding a RAW packet

This section explains how a RAW packet is decoded at the application level. For the purpose of discussion, let’s decode the same PING packet that was encapsulated w/ ICMP, IP and MAC protocols in the Building a RAW packet section and extract the source and destination’s MAC & IP address.

  • CC3x00 device will add 8Bytes of proprietary radio header to the received packet. The header will have important information about the packet
  1. 1Byte (unsigned char) for RATE: This has rate of data reception
  2. 1Byte (unsigned char) for CHANNEL: This has the channel-number on which the data is received
  3. 1Byte (signed char) for RSSI: It has the computed RSSI value (in dB) of the current frame
  4. 1Byte for PADDING-BITS: It’s for 4B alignment
  5. 4Byte (unsigned long) for TIMESTAMP: Timestamp (in uS) of the received packet. The received messages are tagged w/ system-time, which by-default starts from 1-1-2000

The actual data will follow this 8Byte header and the application developers shall parse it as per their protocol

  • Considering 8Bytes of proprietary radio header that gets added to the received packet, 802.11 MAC Header starts from offset-8 of the received packet
  1. DESTINATION MAC ADDRESS (6Byte information) is at offset-4 of 802.11 MAC Header and hence can be extracted starting from offset-12 of received packet
  2. SOURCE MAC ADDRESS (6Bytes information) is at offset-16 of 802.11 MAC Header and hence can be extracted starting from offset-24 of received packet
  • Considering 8Bytes of proprietary radio header, 26B of MAC header and 8B of LLC & SNAP header, IP-Header starts from offset-42 of received packet
  1. SOURCE IP ADDRESS (4Byte information) is at offset-12 of ‘IP Header’ and hence can be extracted starting from offset-54 of received packet
  2. DESTINATION IP ADDRESS (4Byte information) is at offset-16 of ‘IP Header’ and hence can be extracted starting from offset-58 of received packet
  • The rest of the packet can be decoded as per the next level protocol

<syntaxhighlight lang="c"> typedef struct {

   UINT8   rate;
   UINT8   channel;
   INT8    rssi;
   UINT8   padding;
   UINT32 timestamp;

}

TransceiverRxOverHead_t;

void TransceiverModeRx (INT8 <channel_number>, INT32 <pkts_to_receive>) {

   TransceiverRxOverHead_t *frameRadioHeader = NULL;
   UINT8 buffer[BUFFER_SIZE] = {'\0'};
   INT32 <socket_hanlde> = -1;
   INT32 recievedBytes = 0;
   <socket_hanlde>= sl_Socket(SL_AF_RF, SL_SOCK_RAW, <channel_number>);
   while(<pkts_to_receive>--)
   {
       memset(&buffer[0], 0, sizeof(buffer));
       recievedBytes = sl_Recv(<socket_hanlde>, buffer, BUFFER_SIZE, 0);
       frameRadioHeader = (TransceiverRxOverHead_t *)buffer;
       PRINT(" ===>>> Timestamp: %iuS, Signal Strength: %idB\n\r", frameRadioHeader->timestamp, frameRadioHeader->rssi);
       PRINT(" ===>>> Destination MAC Address: %02x:%02x:%02x:%02x:%02x:%02x\n\r", buffer[12], buffer[13], buffer[14], buffer[15], buffer[16], buffer[17]);
       PRINT(" ===>>> Source MAC Address: %02x:%02x:%02x:%02x:%02x:%02x\n\r", buffer[24], buffer[25], buffer[26], buffer[27], buffer[28], buffer[29]);
       PRINT(" ===>>> Source IP Address: %d.%d.%d.%d\n\r", buffer[54],  buffer[55], buffer[56],  buffer[57]);
       PRINT(" ===>>> Destination IP Address: %d.%d.%d.%d\n\r", buffer[58],  buffer[59], buffer[60],  buffer[61]);
   }
   sl_Close(<socket_handle>);

} </syntaxhighlight>

Use-cases

Sniffer

In ‘Transceiver Mode’, the device can receive every packet that’s on the air and hence can be used to implement ‘Sniffer’ like applications. The section Using host driver APIs to receive the RAW packet has detailed description on how raw-packets could be received in ‘Transceiver Mode’.

The application developers can as well define filters and apply them to the received frames.

Tagging

In ‘Transceiver Mode’, the device can transmit raw-packets continuously and hence can be used to implement ‘Tagging’ applications. The section Using host driver APIs to transmit the RAW packet has detailed description on how raw-packets could be transmitted in ‘Transceiver Mode’.

Receiver-Statistics

In ‘Transceiver Mode’, the device can transmit raw-packets continuously and hence can be used to implement applications that could measure the packet loss at the receiver.

CC3x00’s host-driver has functions defined to measure the Rx-statistics on the receiver side.

Radio Tool for RF evaluation

Using the Tx and Rx functionalities defined above for/in ‘Transceiver Mode’, application developers can design radio-tools for evaluating their device’s RF performance.

In addition to the legacy transmission and reception discussed above, application developers can as well:

  • Set the raw socket properties, instructing WLAN PHY to continuously transmit a given packet ‘n’ number of times
  • Instruct the device to transmit a ‘Continuous Wave’ at a given power-level

Proprietary Protocol Definition

As underlined above, in ‘Transceiver Mode’, almost the entire frame space, starting from the legacy 802.11 MAC headers, can be used for transmitting proprietary information and hence can be used by application developers to define their own protocols over WLAN PHY for data transmission.

Links

{{#invoke: Navbox | navbox }}