Introduction

WIFI-CAST is a connectionless Wi-Fi communication protocol defined by Realtek. In WIFI-CAST, devices can transmit application data without establishing a Wi-Fi connection. It supports one-to-many and many-to-many device connections and communications.

Unlike communication using TCP/IP protocols, WIFI-CAST can transmit data directly to the data link layer, reducing latency caused by packet loss during network congestion and achieving faster response times.

Frame Format

In WIFI-CAST, QoS data frames are transmitted between devices. The data format is as follows:

-------------------------------------------------------------------------------------------------------------
|   MAC Header   | QoS Control |   SNAP   |   WIFI-CAST Header   |   Padding   |   User Payload   |   FCS   |
-------------------------------------------------------------------------------------------------------------
    24 bytes         2 bytes     8 bytes          16 bytes          6-14 bytes     0-1500 bytes     4 bytes

If security is enabled, an 8-byte IV field is added after SNAP.
WIFI-CAST Header: Content of the WIFI-CAST specific header.
Padding: This field is used to align the WIFI-CAST header to 32 bytes.
User Payload: Contains user-defined data content.

The format of the WIFI-CAST specific header is as follows:

----------------------------------
|   Magic   |   Type   |   Seq   |
----------------------------------
  12 bytes    2 bytes    2 bytes

Magic: Fixed as Wcast, indicating WIFI-CAST application.
Type: Data type, where 0x2000 represents WIFI-CAST data, 0x4000 represents WIFI-CAST data acknowledgement (ACK).
Seq: Package sequence number, incremented by 1 for each new package sent, used for deduplication.

Security

WIFI-CAST uses the CCMP-128 method to protect the security of data frames. WIFI-CAST devices maintain several keys, with each paired device having a 16-byte(WIFI_CAST_KEY_LEN) key.

When security is enabled, data frames are encrypted using the CCMP method with the set key. If no key is set for a paired device, the data frame is not encrypted. Currently, encryption of broadcast data frames is not supported.

Initialization and Deinitialization

Call wifi_cast_init() to initialize WIFI-CAST, and call wifi_cast_deinit() to deinitialize WIFI-CAST. WIFI-CAST data can only be transmitted after Wi-Fi is started, so it is recommended to start Wi-Fi before initializing WIFI-CAST, and close Wi-Fi after deinitialization.

During initialization, a device with a broadcast MAC address is added by default. The channel range refers to the channels within the channel table supported by the device. For example, the 2.4G channel range is channels 1 to 14.If the channel is set to 0 and not connected to a router, initialization will abort and return an error code; if connected to a router, the channel will be set to the current router channel, otherwise it will be set according to user-defined settings. All WIFI-CAST devices, by default, only transmit data on the configured channel. If the destination device is not on the same channel, it is necessary to Configuring Send Parameters.

When calling wifi_cast_deinit(), all information about paired devices will be cleared.

Device Management

Before sending data, call wifi_cast_add_node() to add the device to the pairing list. Device parameters refer to WIFI-CAST Device Parameters, where the security enable parameter is encrypt. If security is enabled, a key must be set. The maximum key length is 16(WIFI_CAST_KEY_LEN), and currently, a maximum of 16(MAX_NODE_NUM) paired devices are supported.

For sending and receiving devices, if no paired devices are added, only broadcast packets can be sent and received. To send and receive unicast packets, paired devices must be added. If paired devices need to send and receive encrypted unicast packets, the same key must be set.

Call wifi_cast_del_node() to remove a device from the pairing list.

Use wifi_cast_get_node_info() to obtain device parameters and check if the target device exists before sending WIFI-CAST data.

Sending WIFI-CAST Data

Call wifi_cast_send() to send WIFI-CAST data. If successful, it will return WIFI_CAST_OK, otherwise it will return an Error Codes. For example, sending may fail due to reasons such as the target device not existing, channel mismatch, or over-the-air data frame loss.

Configuring Send Parameters

To ensure the application layer can receive data, wifi_cast_send() provides WIFI-CAST Data Parameters.

The sender can set the ack field to 1 and set wait_ms to the timeout waiting time. After the other end receives the data, it returns an acknowledgement (ACK).

If no response is received after the timeout, it will automatically resend. By assigning sequence numbers to WIFI-CAST data packets, duplicate data can be avoided.
The retry_limit field sets the number of hardware retries at the MAC layer.
The retransmit_count field sets the number of software retries at the application layer.
If not all receiving ends are on the same channel, channel can be set to WIFI_CAST_CHANNEL_ALL.
tx_rate is used to set the data transmission rate at the MAC layer.

Receiving WIFI-CAST Data

Call wifi_cast_register_recv_cb() to register a receive callback function, which will be called when the device receives WIFI-CAST data. This callback runs in the Wi-Fi task context, blocking operations are prohibited, and it is recommended to deliver data to other low-priority tasks through a queue for processing.

Application Examples

Here are examples of sending and receiving WIFI-CAST data between two devices:

API Reference

Header File

component/wifi/wifi_cast/wifi_intf_drv_app_cast.h

APIs

wcast_err_t wifi_cast_init(wifi_cast_config_t *pconfig);

Item	Description
Functionality	WIFI-CAST initialization
Parameters	pconfig: Pointer to wifi_cast_config_t structure, containing WIFI-CAST configuration
Return Value	WIFI_CAST_OK on success WIFI_CAST_ERR on failure

wcast_err_t wifi_cast_deinit(wifi_cast_config_t *pconfig);

Item	Description
Functionality	WIFI-CAST deinitialization
Parameters	pconfig: Pointer to wifi_cast_config_t structure, containing WIFI-CAST configuration
Return Value	Returns WIFI_CAST_OK

wcast_err_t wifi_cast_add_node(wifi_cast_node_t *pnode);

Item	Description
Functionality	Add WIFI-CAST paired device
Parameters	pnode: Pointer to wifi_cast_node_t structure, containing WIFI-CAST device parameters
Return Value	WIFI_CAST_OK on success Error code on failure

wcast_err_t wifi_cast_del_node(wifi_cast_node_t *pnode);

Item	Description
Functionality	Delete WIFI-CAST paired device
Parameters	pnode: Pointer to wifi_cast_node_t structure, containing WIFI-CAST device parameters
Return Value	WIFI_CAST_OK on success Error code on failure

wifi_cast_node_t *wifi_cast_get_node_info(wifi_cast_node_t *pnode);

Item	Description
Functionality	Get WIFI-CAST paired device information
Parameters	pnode: Pointer to wifi_cast_node_t structure, containing WIFI-CAST device parameters
Return Value	Target device on success NULL on failure

wcast_err_t wifi_cast_send(wifi_cast_node_t *pnode, unsigned char *data, int data_len, wifi_cast_frame_info_t *info);

Item	Description
Functionality	Send WIFI-CAST data
Parameters	pnode: Pointer to wifi_cast_node_t structure, containing WIFI-CAST device parameters data: Pointer to the beginning of the data buffer to be sent data_len: Valid data length (in bytes) info: Pointer to wifi_cast_frame_info_t structure, containing WIFI-CAST data parameters
Return Value	WIFI_CAST_OK on success Error code on failure

wcast_err_t wifi_cast_register_recv_cb(wifi_cast_recv_cb_t recv_cb);

Item	Description
Functionality	Register WIFI-CAST receive callback function
Parameters	recv_cb: Function pointer defined by wifi_cast_recv_cb_t, user-defined receive callback function
Return Value	Returns WIFI_CAST_OK

typedef void (*wifi_cast_recv_cb_t)(wifi_cast_node_t *pnode, unsigned char *buf, unsigned int len, signed char rssi);

Item	Description
Functionality	WIFI-CAST receive callback function definition
Parameters	pnode: Pointer to wifi_cast_node_t structure, user-defined receive callback function buf: Pointer to the beginning of the received data buffer len: Valid data length (in bytes) rssi: Current signal strength
Return Value	Returns WIFI_CAST_OK

Structures

WIFI-CAST Device Parameters:

typedef struct wifi_cast_node {
    wifi_cast_addr_t mac;
    wifi_cast_key_t  key;
    unsigned char encrypt;
    void *priv;
} wifi_cast_node_t;

Field	Description
mac	MAC address of the paired device, 6 bytes in length
key	Key of the paired device, 16 bytes in length
encrypt	Security feature enable flag - 1: Enable security feature, send encrypted unicast packets, must set key - 0: Disable security feature, data is not encrypted when sending

WIFI-CAST Data Parameters:

typedef struct wifi_cast_frame_info {
    unsigned int wait_ms;
    unsigned char ack;
    unsigned char retry_limit;
    unsigned char retransmit_count;
    unsigned char channel;
    unsigned char tx_rate;
} wifi_cast_frame_info_t;

Field	Description
wait_ms	Timeout period (ms) for waiting for ACK if enabled
ack	Whether to enable ACK response - 1: Requires response from peer - 0: Does not require response from peer
retry_limit	Number of hardware retries at the MAC layer
retransmit_count	Number of software retries at the application layer
channel	Transmission channel - WIFI_CAST_CHANNEL_CURRENT - WIFI_CAST_CHANNEL_ALL
tx_rate	Transmission rate, e.g., RTW_RATE_1M, RTW_RATE_2M

WIFI-CAST Configuration Parameters:

typedef struct wifi_cast_config {
   unsigned char channel;
} wifi_cast_config_t;

Field	Description
channel	Channel number; all WIFI-CAST devices must be configured to the same channel.

Error Codes

Item	Description
WIFI_CAST_OK	Function executed successfully
WIFI_CAST_ERR	Function execution failed
WIFI_CAST_ERR_NO_MEMORY	Insufficient system memory
WIFI_CAST_ERR_INVALID_DATA	Invalid data
WIFI_CAST_ERR_NODE_EXIST	Device already exists
WIFI_CAST_ERR_WAIT_TIMEOUT	Transmission timeout; no response received when ack and time_ms set

Macro Definitions

Macro	Description
MAX_NODE_NUM	Maximum number of devices
WIFI_CAST_KEY_LEN	Maximum key length
WIFI_CAST_CHANNEL_CURRENT	Current channel
WIFI_CAST_CHANNEL_ALL	All supported channels

All SoCs

Select SoC via Features

HiFi DSP Series

HiFi DSP Series

Cortex-A Linux Series

Cortex-A Linux Series

Display Series

Display Series

Audio Series

Audio Series

Wi-Fi 6 + BLE Series

Wi-Fi 6 + BLE Series

Wi-Fi 2.4G/5G + BLE Seriess

Wi-Fi 2.4G/5G + BLE Series

Wi-Fi + Classic BT Series

Wi-Fi + Classic BT Series

Wi-Fi R-MESH Series

Wi-Fi R-MESH Series

Select SoC via Applications

IoT Control