前言¶

概述

本文档详细的描述了WS63V100相关特性的应用场景、实现原理及接口说明，方便读者了解并使用相关特性。

读者对象

本文档主要适用于以下工程师：

软件开发工程师
技术支持工程师
硬件开发工程师

产品版本

与本文档相对应的产品版本如下。

产品名称	产品版本
WS63	V100

符号约定

在本文中可能出现下列标志，它们所代表的含义如下。

符号	说明
	表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。
	表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。
	表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。
	用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。 “须知”不涉及人身伤害。
	对正文中重点信息的补充说明。 “说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。

修改记录

文档版本	发布日期	修改说明
02	2024-06-27	更新“雷达特性说明”的“概述”、“开发流程”小节内容。更新“BLE配网特性说明”的“使用示例”小节内容。
01	2024-04-10	第一次正式版本发布。更新“FLASH在线解密特性说明”的“接口说明”小节内容。
00B02	2024-03-29	更新“动态国家码特性说明”的“使用示例”小节内容。更新“BLE配网特性说明”的“使用示例”小节内容。
00B01	2024-03-15	第一次临时版本发布

混杂模式特性说明¶

概述¶

混杂模式特性用于抓取所有经过本设备的管理帧/数据帧，并将抓取到的报文保存到文件中，可通过抓包软件例如：WireShark、OmniPeek打开并查看报文信息。

应用场景¶

WiFi混杂模式开启后，会抓取周边AP和STA之间的单播/组播的管理帧/数据帧，典型应用场景之一是支持作为抓包网卡。如下图，WS63芯片作为抓包网卡，通过串口与PC连接，抓取PC周边报文。

图 1 混杂模式进行空口抓包

实现原理¶

无线网络信号在传播过程中是以发射点为中心，像波纹一样往外辐射。理论上来讲，如果一个接收器处于无线信号经过的地方，它可以“听到”任何经过它的信号，只是它可能“听不懂”（无法解析报文内容）。

以下图为例，Phone与Smart Watch通信，Laptop完全有能力从空口监听他们的通信。空口抓包就是基于这个原理工作的。如果我们想要抓某个嵌入式设备的无线报文，只需在它附近运行一个具有监听功能的无线设备。

图 1 混杂模式

接口说明¶

混杂接口声明¶

/**
 * @if Eng
 * @brief  Type of WiFi interface.
 * @else
 * @brief  Type of WiFi interface。
 * @endif
 */
typedef enum {
    IFTYPE_STA,         /*!< @if Eng STAION.
                             @else STAION。 @endif */
    IFTYPE_AP,          /*!< @if Eng HOTSPOT.
                             @else HOTSPOT。 @endif */
    IFTYPE_P2P_CLIENT,  /*!< @if Eng P2P CLIENT.
                             @else P2P CLIENT。 @endif */
    IFTYPE_P2P_GO,      /*!< @if Eng P2P GO.
                             @else P2P GO。 @endif */
    IFTYPE_P2P_DEVICE,  /*!< @if Eng P2P DEVICE.
                             @else P2P DEVICE。 @endif */
    IFTYPES_BUTT
} wifi_if_type_enum;

/**
 * @if Eng
 * @brief  Struct of frame filter config in monitor mode.
 * @else
 * @brief  混杂模式报文接收过滤设置。
 * @endif
 */
typedef struct {
    int8_t mdata_en  : 1;   /*!< @if Eng get multi-cast data frame flag.
                                 @else 使能接收组播(广播)数据包。 @endif */
    int8_t udata_en  : 1;   /*!< @if Eng get single-cast data frame flag.
                                 @else 使能接收单播数据包。 @endif */
    int8_t mmngt_en  : 1;   /*!< @if Eng get multi-cast mgmt frame flag.
                                 @else 使能接收组播(广播)管理包。 @endif */
    int8_t umngt_en  : 1;   /*!< @if Eng get single-cast mgmt frame flag.
                                 @else 使能接收单播管理包。 @endif */
    int8_t custom_en : 1;   /*!< @if Eng get beacon/probe response flag.
                                 @else 使能接收beacon/probe request包。 @endif */
    int8_t resvd     : 3;   /*!< @if Eng reserved bits.
                                 @else 保留字段。 @endif */
} wifi_ptype_filter_stru;

/**
 * @if Eng
 * @brief  Set monitor mode.
 * @param  [in]  iftype Interface type.
 * @param  [in]  enable Enable(1) or disable(0).
 * @param  [in]  filter Filtered frame type enum.
 * @retval EXT_WIFI_OK        Execute successfully.
 * @retval EXT_WIFI_FAIL      Execute failed.
 * @else
 * @brief  设置混杂模式。
 * @param  [in]  iftype 接口类型。
 * @param  [in]  enable 开启/关闭。
 * @param  [in]  filter 过滤列表。
 * @retval EXT_WIFI_OK   成功。
 * @retval EXT_WIFI_FAIL 失败。
 * @endif
 */
errcode_t wifi_set_promis_mode(wifi_if_type_enum iftype, int32_t enable, const wifi_ptype_filter_stru *filter);

开启和关闭混杂¶

命令格式：AT+CCPRIV=$vap,set_monitor,$switch,$val1,$val2,$val3,$val4

参数说明：

$vap：表示需要维测的vap名字，通常为wlan0。
$switch：表示功能开、关、或者暂停，对应1、0、2。
$val1：表示广播/组播数据帧过滤开关，对应0、1，0表示过滤，1表示不过滤。
$val2：表示单播数据帧过滤开关，对应0、1，0表示过滤，1表示不过滤。
$val3：表示广播/组播管理帧过滤开关，对应0、1，0表示过滤，1表示不过滤。
$val4：表示单播管理帧过滤开关，对应0、1，0表示过滤，1表示不过滤。

命令示例：

开启所有帧上报：AT+CCPRIV=wlan0,set_monitor,1,1,1,1,1
查看混杂收包统计：AT+CCPRIV=wlan0,set_monitor,2 （PS：命令下发成功后，会在DebugKits工具中打印收包统计信息。）
关闭混杂：AT+CCPRIV=wlan0,set_monitor,0

使用示例¶

执行“1.4 接口说明”相关命令后，按需求开启对应帧过滤开关，例如所有帧上报：AT+CCPRIV=wlan0,set_monitor,1,1,1,1,1
若想查看开启混杂后的收包计数统计，可输入命令AT+CCPRIV=wlan0,set_monitor,2后，在DebugKits工具中查看。

动态国家码特性说明¶

概述¶

动态国家码特性用于支持全球发货场景，根据设备预制的国家信息，自动调整发射功率表，以符合全球各地区对发射功率的法律规范。

应用场景¶

在上网问题处理中，经常会碰到来自异国的设备出现扫描/连接/协商速率异常的情况，很多情况与802.11d协议（/国家码设置）相关。

国家码用来标识无线设备所在的国家，不同国家码规定了不同的无线设备射频特性，包括AP的发送功率、支持的信道等。配置国家码是为了使无线设备的射频特性符合不同国家或区域的法律法规要求。在第一次配置WLAN设备时，必须配置正确的国家码，以确保不违反当地的法律法规。

动态国家码提供一种配置方式，客户能够通过设置国家码，调整到国家对应大区（中国、亚太、北美、欧洲）的发射功率，从而符合法律规范

图 1 动态国家码应用场景

实现原理¶

通过配置文件映射国家与大区的关系，每个国家码对应一个大区，每个大区对应一套功率表，国家码变动时，根据重新配置对应的功率表。

图 1 动态国家码设计原理图

接口说明¶

国家码接口声明¶

/**
* @ingroup  soc_wifi_basic
* @brief  Set country code.CNcomment:设置国家码.CNend
*
* @par Description:
*           Set country code(two uppercases).CNcomment:设置国家码，由两个大写字符组成.CNend
*
* @attention  1.Before setting the country code, you must call uapi_wifi_init to complete the initialization.
*             CNcomment:设置国家码之前，必须调用uapi_wifi_init初始化完成.CNend\n
*             2.cc_len should be greater than or equal to 3.CNcomment:cc_len应大于等于3.CNend
* @param  cc               [IN]     Type  #const char *, country code.CNcomment:国家码.CNend
* @param  cc_len           [IN]     Type  #unsigned char, country code length.CNcomment:国家码长度.CNend
*
* @retval #EXT_WIFI_OK  Excute successfully
* @retval #Other           Error code
* @par Dependency:
*            @li soc_wifi_api.h: WiFi API
* @see  NULL
* @since
*/
td_s32 uapi_wifi_set_country(const td_char *cc, td_u8 cc_len);

/**
* @ingroup  soc_wifi_basic
* @brief  Get country code.CNcomment:获取国家码.CNend
*
* @par Description:
*           Get country code.CNcomment:获取国家码，由两个大写字符组成.CNend
*
* @attention  1.Before getting the country code, you must call uapi_wifi_init to complete the initialization.
*             CNcomment:获取国家码之前，必须调用uapi_wifi_init初始化完成.CNend
* @param  cc               [OUT]     Type  #char *, country code.CNcomment:国家码.CNend
* @param  len              [IN/OUT]  Type  #int *, country code length.CNcomment:国家码长度.CNend
*
* @retval #EXT_WIFI_OK  Excute successfully
* @retval #Other           Error code
* @par Dependency:
*            @li soc_wifi_api.h: WiFi API
* @see  NULL
* @since
*/
td_s32 uapi_wifi_get_country(td_char *cc, td_u8 *len);

设置和读取国家码¶

AT+CC=&country
AT+CC?

说明：

$COUNTRY：国家码，可配置范围：CN,JP,US,CA,KHRU,AU,MY,ID,TR,PL,FR,PT,IT,DE,ES,AR,ZA,MA,PH,TH,GB,CO,MX,EC,PE,CL,SA,EG,AE.

使用示例¶

加载驱动时，根据nv配置文件配置大区功率，如图1所示。

图 1 nv国家码配置示例

中继特性说明¶

概述¶

中继特性主要用于无线网络连接中，通过对报文的转发，实现远距离无线通信，达到扩大网络覆盖范围、降低网络部署成本的目的。

应用场景¶

中继特性通过创建一个Repeater-STA端口与ROOT AP建立连接，创建一个Repeater-AP端口为其它STA提供服务，其工作原理为：Repeater-STA和Repeater-AP之间支持报文转发，从而进一步实现ROOT AP与STA的报文交互、完成网络业务的功能。Repeater-STA支持与一个ROOT AP接入，Repeater-AP支持最多5个设备同时接入。

图 1 中继场景

实现原理¶

STA发给ROOT AP的报文经过Repeater时，报文中的源MAC地址与源IP地址的映射关系会被记录进入转发表，并且将报文中的源MAC修改为Repeater-STA的MAC发送给ROOT AP。

ROOT AP发送给STA的报文经过Repeater时，会根据目的IP在转发表中查询，更改报文中的目的MAC地址，将报文转发到正确的STA中。

图 1 Repeater-STA 上行数据场景

图 2 Repeater-STA下行数据场景

接口说明¶

暂无

使用示例¶

创建ap0端口。
```
AT+STARTAP="my_ap",13,2,"12345678"
```

创建wlan0端口并关联上ROOT AP。

AT+STARTSTA
AT+SCAN
AT+CONN="ROOTAP",,"12345678"

使能repeater功能。
```
AT+BRCTL=addbr
```
将ap0端口、wlan0端口分别加入repeater，分别作为Repeater-AP和Repeater-STA。
```
AT+BRCTL=addif,wlan0
AT+BRCTL=addif,ap0
```
陪测STA关联Repeater-AP并获取IP地址，进行ping测试、Iperf测试等。
测试完成，将wlan0端口、ap0端口从repeater删除，并关闭repeater功能。
```
AT+BRCTL=delif,wlan0
AT+BRCTL=delif,ap0
AT+BRCTL=delbr
```

雷达特性说明¶

概述¶

雷达特性为周期性地收发雷达信号以检测运动目标的功能特性，用户可以调用雷达 APIs接口使用该特性，详细内容请参见《WS63V100 雷达快速入门指南》。

开发流程¶

数据结构¶

雷达状态设置枚举定义：

typedef enum {
    RADAR_STATUS_STOP = 0,  /* 雷达状态配置停止 */
    RADAR_STATUS_START,     /* 雷达状态配置启动 */
    RADAR_STATUS_RESET,     /* 雷达状态配置复位 */
    RADAR_STATUS_RESUME,    /* 雷达状态配置状态恢复 */
} radar_set_sts_t;

雷达状态查询枚举定义：

typedef enum {
    RADAR_STATUS_IDLE = 0,  /* 雷达状态未工作 */
    RADAR_STATUS_RUNNING,   /* 雷达状态工作 */
} radar_get_sts_t;

雷达结果上报结构体定义：

typedef struct {
    uint32_t lower_boundary;    /* 雷达结果靠近检测下边界 */
    uint32_t upper_boundary;    /* 雷达结果靠近检测上边界 */
    uint8_t is_human_presence;  /* 雷达结果有无人体存在 */
    uint8_t reserved_0;
    uint8_t reserved_1;
    uint8_t reserved_2;
} radar_result_t;

结果回调函数数据结构定义：

typedef void (*radar_result_cb_t)(radar_result_t *result);

APIs¶

雷达 APIs接口如下表所示。

接口名称	描述	参数说明	返回信息说明
uapi_radar_set_status	设置雷达状态	sts:: 雷达状态	接口返回值：错误码。
uapi_radar_get_status	获取雷达状态	*sts: 雷达状态	接口返回值：错误码。
uapi_radar_register_result_cb	雷达结果回调注册函数	cb: 回调函数	接口返回值：错误码。
uapi_radar_set_delay_time	设置退出延迟时间	time: 退出延迟时间	接口返回值：错误码。
uapi_radar_get_delay_time	获取退出延迟时间	*time: 退出延迟时间	接口返回值：错误码。
uapi_radar_get_isolation	获取天线隔离度信息	*iso: 天线隔离度信息	接口返回值：错误码。

错误码¶

序号	定义	实际数值	描述
1	ERRCODE_SUCC	0	执行成功错误码。
2	ERRCODE_FAIL	0xFFFFFFFF	执行失败错误码。

注意事项¶

雷达特性需要在WiFi信道上进行工作，所以需注意打开雷达前，需要确保WiFi信道有配置，WiFi进入softAP或STA模式即可。

编程实例¶

typedef void (*radar_result_cb_t)(radar_result_t *result);

#define WIFI_IFNAME_MAX_SIZE             16
#define WIFI_MAX_SSID_LEN                33
#define WIFI_SCAN_AP_LIMIT               64
#define WIFI_MAC_LEN                     6
#define WIFI_INIT_WAIT_TIME              500 // 5s
#define WIFI_START_STA_DELAY             100 // 1s

#define RADAR_STATUS_SET_START            1
#define RADAR_STATUS_QUERY_DELAY         1000 // 10s

// WiFi启动STA模式实现样例
td_s32 radar_start_sta(td_void)
{
    (void)osDelay(WIFI_INIT_WAIT_TIME); /* 500: 延时0.5s, 等待wifi初始化完毕 */
    PRINT("STA try enable.\r\n");
    /* 创建STA接口 */
    if (wifi_sta_enable() != 0) {
        PRINT("sta enbale fail !\r\n");
        return -1;
    }

    /* 连接成功 */
    PRINT("STA connect success.\r\n");
    return 0;
}

// 雷达结果回调函数实现样例
static void radar_print_res(radar_result_t *res)
{
    PRINT("[RADAR_SAMPLE] lb:%u, hb:%u, hm:%u\r\n", res->lower_boundary, res->upper_boundary, res->is_human_presence);
}

int radar_demo_init(void *param)
{
    PRINT("[RADAR_SAMPLE] radar_demo_init sta!\r\n");

    param = param;
    // WiFi启动STA模式
    radar_start_sta();

    // 注册雷达结果回调函数
    uapi_radar_register_result_cb(radar_print_res);

    // 启动雷达
    (void)osDelay(WIFI_START_STA_DELAY);
    uapi_radar_set_status(RADAR_STATUS_SET_START);

    // 雷达查询接口示例
    while(1) {
        (void)osDelay(RADAR_STATUS_QUERY_DELAY);
        uint8_t sts;
        uapi_radar_get_status(&sts);
        uint16_t time;
        uapi_radar_get_delay_time(&time);
        uint16_t iso;
        uapi_radar_get_isolation(&iso);
    }

    return 0;
}

BLE配网特性说明¶

概述¶

BLE配网是指通过BLE辅助WIFI入网。

应用场景¶

在 BLE 配网模式下，设备在无网模式下通过BLE发送配网广播，附近的手机扫描到该广播，可通过多种方式与用户交互：

1）手机应用主动弹框询问手机用户是否允许该设备加入家庭网络。

2）手机应用主动扫描后显示在可用设备列表，用户手动选择将该设备加入家庭网络。

如用户选择加入，手机与设备建立BLE连接，再将WIFI入网信息（SSID、密码等）传输给设备。与SoftAP 配网相比，用户无需切换WIFI AP与STA模式，可以大大提升终端用户体验。

实现原理¶

BLE配网参考流程如图1所示。

图 1 BLE配网流程

使用WS63芯片的设备，在无网模式下启动，自动发送配网广播，用户可以调整广播持续时间、间隔以及重新广播的触发条件。

接口说明¶

参考《WS63V100 软件开发指南》BLE开发流程章节。

使用示例¶

在SDK根目录下执行命令“python3 build.py ws63-liteos-app menuconfig”，并按下图配置对应编译选项进行配置。

图 1 BLE Demo配置选项
完成配置后执行命令python3 build.py ws63-liteos-app，将生成的镜像通过BurnTool烧录进单板中。
在Android手机安装“EasyConnect”软件，单击“wifi configuration”，配置待连接的Wi-Fi参数。

图 2 配置Wi-Fi参数
单击“Set Ble Name”，默认配置为ble_wifi_config。

图 3 配置蓝牙名称
配置完成后，单击“配网”，待Android手机和63模组连接成功后，会显示连接成功并播报。

图 4 WS63模组配网成功

说明： 配网软件“EasyConnect”可通过技术支持获取。

BLE网关特性说明¶

概述¶

BLE网关做为中继，帮助无法直接与服务器通信的BLE设备上云。

应用场景¶

BLE网关实现多个BLE子设备的认证、连接管理，以及路由转发功能。从云发送的命令通过网关下发到BLE设备；BLE设备的状态也可以通过网关上报给服务器。

实现原理¶

BLE网关的工作流程参考：

网关开启背景扫描，BLE子设备发送广播，网关识别支持的服务ID主动建立BLE连接，完成认证和数据传输。
网关服务程序将收到的BLE数据，通过WIFI路由器上传到服务器。
服务器将BLE设备的信息在手机应用或者控制中枢显示屏显示，控制指令也可通过WIFI由服务器传给网关，再由网关通过BLE传输给设备。

接口说明¶

参考《WS63V100 软件开发指南》BLE开发流程章节。

安全启动特性说明¶

概述¶

安全启动是指在系统启动时，使用efuse中预先写入的秘钥对镜像逐级校验的功能。

应用场景¶

安全启动用于保证镜像的完整性和安全性，防止镜像被破解和篡改。

须知： 安全启动功能在产测阶段通过烧录efuse打开，开启该功能后仅能使用efuse中对应的秘钥组对镜像签名才能正常启动。

实现原理¶

预先在efuse中写入根公钥HASH值和安全启动使能位；

系统复位后从bootrom启动，

在bootrom中计算镜像中的根公钥HASH值与efuse中的进行校验。
根公钥校验通过后，使用根公钥验签ssb镜像。
Ssb镜像校验通过后，使用ssb镜像中的二级公钥校验Flashboot镜像。
Flashboot镜像校验通过后，使用flashboot中的三级公钥校验App镜像。
App镜像校验通过后，跳转到app镜像启动完成。

图7.1 安全启动镜像逐级校验流程

接口说明¶

配置efuse安全启动使能位写1。
配置根公钥HASH值烧写到efuse。

说明： 可参照《WS63V100 二次开发网络安全注意事项》中安全启动配置章节进行配置。

FLASH在线解密特性说明¶

概述¶

FLASH在线解密是指CPU在访问FLASH上的加密镜像时在线解密后运行。

应用场景¶

FLASH在线解密特性主要用于对加密存储在FLASH上的APP镜像进行解密运行。

须知： FLASH在线解密功能需要在编译前打开镜像加密，并将对应的秘钥派生参数写入efuse中。

实现原理¶

开启FLASH在线解密功能后：

在编译阶段签名后会对镜像加密。
镜像烧写到flash上为加密存储状态。
启动时会自动配置解密区域。
cpu运行时通过配置由硬件自动解密。

图 1 FLASH在线解密示意图

接口说明¶

在配置文件hi3863/boards/HI3863/sdk/build/config/target_config/ws63/sign_config/liteos_app_bin_ecc.cfg中将SignSuite配置为1，并配置秘钥派生参数对应的IV和PlainKey。
将秘钥派生参数写入efuse对应位置

说明： 可参照《WS63V100 二次开发网络安全注意事项》中镜像加密配置章节进行配置。