Wi-Fi CAST

概述

Wi-Fi CAST 是由 Realtek 定义的一种无连接 Wi-Fi 通讯协议。在 Wi-Fi CAST 中，设备之间可以在无需建立 Wi-Fi 连接的情况下传输应用数据。它支持一对多、多对多的设备连接与通讯。

与使用 TCP/IP 协议通信不同， Wi-Fi CAST 可以将数据直接传输到数据链路层，这减少了网络拥塞时因丢包带来的延迟，实现了更快速的响应时间。

帧格式

在 Wi-Fi CAST 中，设备间传输的是 QoS 数据帧。数据格式如下：

../../_images/wifi_cast_data_frame_format.svg

若启用了安全功能，8 字节的 IV 字段会添加在 SNAP 后。
Wi-Fi CAST Header：Wi-Fi CAST 特定头部的内容。
- Magic：固定为 Wcast，表示 Wi-Fi CAST 应用。
- Type：数据类型，其中 0x2000 表示 Wi-Fi CAST 数据， 0x4000 表示 Wi-Fi CAST 数据确认（ACK）。
- Seq：包序号，每发送一个新包递增 1，用于去重。
Padding：用于使报文头部按 32 字节对齐。
User Payload：实际要发送的用户自定义的数据内容。

安全

Wi-Fi CAST 采用 CCMP-128 方法保护数据帧的安全。 Wi-Fi CAST 设备维护若干密钥，每个配对设备拥有一个密钥，长度均为 16 （ WIFI_CAST_KEY_LEN ）字节。

启用安全功能后，通过 CCMP 方法使用设置的密钥对数据帧进行加密。如果未设置配对设备的密钥，则数据帧不进行加密。目前，不支持加密广播的数据帧。

初始化与反初始化

调用 wifi_cast_init() 初始化 Wi-Fi CAST ，调用 wifi_cast_deinit() 反初始化 Wi-Fi CAST。Wi-Fi CAST 数据必须在 Wi-Fi 启动后才可传输，因此建议在初始化 Wi-Fi CAST 前先启动 Wi-Fi，去初始化后再关闭 Wi-Fi。

初始化过程中默认会加入一个带广播 MAC 地址的设备。可设置的信道范围为设备所支持的信道表内的信道，如 2.4G 信道范围为 1~14。如果信道设置为 0 且未连接路由器，则初始化中止并返回错误码；若已连接路由器，则信道会设为当前路由器信道，否则按用户自定义设置。

所有 Wi-Fi CAST 设备默认只在所设置的信道上发送数据，如果发送对象与自己不在同一信道上，需要配置发送参数。

调用 wifi_cast_deinit() 时，配对设备的所有信息会被清空。

设备管理

在发送数据前，请先调用 wifi_cast_add_node() 将设备添加至配对列表。设备参数参考 Wi-Fi CAST 设备参数, 其中安全功能启用参数为 encrypt 。如果启用安全功能，则必须设置密钥。密钥最大长度为 16（ WIFI_CAST_KEY_LEN ），当前最多支持 16（ MAX_NODE_NUM ）台配对设备。

对于发送设备和接收设备，如果没有添加配对设备，只能发送和接收广播包。如果需要接收和发送单播包，则必须添加配对设备。如果配对设备间需要发送和接收加密单播包，则必须设置相同的密钥。

调用 wifi_cast_del_node() 可将设备从配对列表中移除。

通过 wifi_cast_get_node_info() 可获取设备参数及在发送 Wi-Fi CAST 数据前判断目标设备是否已存在。

发送 Wi-Fi CAST 数据

调用 wifi_cast_send() 发送 Wi-Fi CAST 数据，发送成功会返回 WIFI_CAST_OK，否则返回错误码。比如，目标设备不存在、信道不一致或空中数据帧丢失等原因可能导致发送失败。

配置发送参数

为确保应用层可收到数据， wifi_cast_send() 提供了 Wi-Fi CAST 数据参数。

发送方可将 ack 字段设为 1 ，同时 wait_ms 设为超时等待时长。对端收到数据后返回应答（ ACK ），如超时未收到则自动重发。通过给 Wi-Fi CAST 数据包分配序号，可避免重复数据。
retry_limit 字段设置 MAC 层的硬件重发次数。
retransmit_count 字段设置应用层的软件重发次数。
如果不是所有接收端都处于同一信道，可将 channel 设为 WIFI_CAST_CHANNEL_ALL 。
tx_rate 用于设置 MAC 层的数据传输速率。

接收 Wi-Fi CAST 数据

调用 wifi_cast_register_recv_cb() 注册接收回调函数，设备接收到 Wi-Fi CAST 数据时会调用该回调函数。此回调函数在 Wi-Fi 任务上下文运行，禁止阻塞操作，建议将数据通过队列投递至其他低优先级任务中处理。

应用示例

以下为两台设备间发送接收 Wi-Fi CAST 数据的示例：

API 参考

头文件

头文件：component/wifi/wifi_cast/wifi_intf_drv_app_cast.h。

接口定义

wifi_cast_init

wcast_err_t wifi_cast_init(wifi_cast_config_t *pconfig);

项目	描述
功能	Wi-Fi CAST 初始化
参数	pconfig：指向 wifi_cast_config_t 结构体的指针，包含 Wi-Fi CAST 配置
返回值	成功返回 WIFI_CAST_OK 失败返回 WIFI_CAST_ERR

wifi_cast_deinit

wcast_err_t wifi_cast_deinit(wifi_cast_config_t *pconfig);

项目	描述
功能	Wi-Fi CAST 反初始化
参数	pconfig：指向 wifi_cast_config_t 结构体的指针，包含 Wi-Fi CAST 配置
返回值	返回 WIFI_CAST_OK

wifi_cast_add_node

wcast_err_t wifi_cast_add_node(wifi_cast_node_t *pnode);

项目	描述
功能	添加 Wi-Fi CAST 配对设备
参数	pnode：指向 wifi_cast_node_t 结构体的指针，包含 Wi-Fi CAST 设备参数
返回值	成功返回 WIFI_CAST_OK 失败返回错误码

wifi_cast_del_node

wcast_err_t wifi_cast_del_node(wifi_cast_node_t *pnode);

项目	描述
功能	删除 Wi-Fi CAST 配对设备
参数	pnode：指向 wifi_cast_node_t 结构体的指针，包含 Wi-Fi CAST 设备参数
返回值	成功返回 WIFI_CAST_OK 失败返回错误码

wifi_cast_get_node_info

wifi_cast_node_t *wifi_cast_get_node_info(wifi_cast_node_t *pnode);

项目	描述
功能	获取 Wi-Fi CAST 配对设备信息
参数	pnode：指向 wifi_cast_node_t 结构体的指针，包含 Wi-Fi CAST 设备参数
返回值	成功返回目标设备失败返回 NULL

wifi_cast_send

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

项目	描述
功能	发送 Wi-Fi CAST 数据
参数	pnode：指向 wifi_cast_node_t 结构体的指针，包含 Wi-Fi CAST 设备参数 data: 指向需要发送的数据缓冲区首地址 data_len: 有效数据长度（单位：字节） info: 指向 wifi_cast_frame_info_t 结构体的指针，包含 Wi-Fi CAST 数据参数
返回值	成功返回 WIFI_CAST_OK 失败返回错误码

wifi_cast_register_recv_cb

wcast_err_t wifi_cast_register_recv_cb(wifi_cast_recv_cb_t recv_cb);

项目	描述
功能	注册 Wi-Fi CAST 接收回调函数
参数	recv_cb：指向 wifi_cast_recv_cb_t 定义的函数指针，用户自定义的接收回调函数
返回值	返回 WIFI_CAST_OK

wifi_cast_recv_cb_t

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

项目	描述
功能	Wi-Fi CAST 接收回调函数定义
参数	pnode：指向 wifi_cast_node_t 定义的结构体指针，用户自定义的接收回调函数 buf：指向接收的数据缓冲区首地址 len：有效的数据长度（单位：字节） rssi: 当前的信号强度
返回值	返回 WIFI_CAST_OK

结构体

Wi-Fi CAST 设备参数

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

字段

描述

mac

配对设备的 MAC 地址，长度为 6 字节

key

配对设备的密钥，长度为 16 字节

encrypt

安全功能开启标志

1：开启安全功能，发送加密单播数据包，必须同时设置密钥
0：关闭安全功能，发送数据时不加密

Wi-Fi CAST 数据参数

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;

字段	描述
wait_ms	启用 ack 时设置超时等待时长
ack	是否开启 ACK应答 1：表示需要对端应答 0：表示不需要对端应答
retry_limit	MAC 层硬件重试次数
retransmit_count	应用层软件重试次数
channel	发送信道 WIFI_CAST_CHANNEL_CURRENT WIFI_CAST_CHANNEL_ALL
tx_rate	发送速率 RTW_RATE_1M、RTW_RATE_2M 等

Wi-Fi CAST 配置参数

typedef struct wifi_cast_config {
    unsigned char channel;
} wifi_cast_config_t;

字段	描述
channel	信道，所有 Wi-Fi CAST 设备需设置为同一信道

错误码

项目	描述
WIFI_CAST_OK	函数执行成功
WIFI_CAST_ERR	函数执行失败
WIFI_CAST_ERR_NO_MEMORY	系统内存不足
WIFI_CAST_ERR_INVALID_DATA	数据无效
WIFI_CAST_ERR_NODE_EXIST	设备已添加
WIFI_CAST_ERR_WAIT_TIMEOUT	发送超时，ack 和 wait_ms 设置时未收到响应

宏定义

宏	描述
MAX_NODE_NUM	设备最大数量
WIFI_CAST_KEY_LEN	密钥最大长度
WIFI_CAST_CHANNEL_CURRENT	当前信道
WIFI_CAST_CHANNEL_ALL	支持的所有信道