BK Wi-Fi MESH配网及网络控制API介绍
1.简介
Wi-Fi MESH配网提供APP配网和API配网两种方式，均可实现空闲MESH节点发现，MESH节点组网，查询网络拓扑，网络控制，OTA等功能。API接口配网主要用于云端配网。APP配网请参考文档《博通集成Wi-Fi Mesh App使用介绍文档》。
本文档主要介绍Wi-Fi Mesh配网及网络控制API的使用方法，供开发者参考。
2.Wi-Fi MESH配网及网络控制API功能
BK MESH API提供接口，用于获取空闲节点列表，配置MESH网络的各项参数，以及查询网络拓扑(只支持树状)和控制设备等，通过BK MESH API实现对MESH网络的查询及控制。
主要包括以下步骤：
I 获取空闲节点
可在网关节点或任意节点处调用API获取空闲节点，即可获得当前空口环境中全部符合条件的空闲MESH节点的信息，为下一步配网做准备；
II 空闲节点配网
获取到空闲节点后，可在网关节点或任意空闲MESH节点处调用API，向MESH节点发送配网信息，如配网节点数量，指定根节点等，实现空闲节点配网组网，形成MESH网络。
API接口接收到配网请求后，验证配网信息的有效性，将配网信息传递给MESH节点，各节点根据配置信息开始执行配网操作，如扫描，连接，配置MESH网络等。
III MESH网络控制
MESH网络组网成功后，可在根节点调用API，进行以下操作，对MESH网络进行查询或者控制。
查询网络拓扑
在根节点处调用API，查询网络拓扑(只支持树状)，可获取到当前网络情况，如在线节点数，网络层级，节点拓扑关系等；
修改MESH网络
在根节点处调用API，可实现对MESH网络的控制，如增加MESH网络节点数量、删除MESH网络中部分节点或全部节点、修改网络配置等；
设置用户信息/查询用户信息
在根节点处调用API，配置或者查询用户信息；
OTA升级
在根节点处调用API，配置OTA升级信息，启动OTA升级或者通过查询OTA升级状态来确认升级是否完成；
节点重置
当存在某个节点从MESH网络断开且无法重新加入网络时，可使用节点重置功能将该节点Reset，使其恢复到空闲节点状态。
获取节点状态信息
查询节点的状态信息，如状态，层级，父节点以及与起相关联的节点数。
3 Wi-Fi MESH配网及网络控制API使用说明
3.1 设置模式及回调
3.1.1 模式
所有mesh节点在初始化时调用此接口，配置模式；
API：
bk_err_t bk_wifi_mesh_set_net_mode(uint8_t net_mode);
uint8_t net_mode,1:指示广域网模式；2：局域网模式；3：局域网模式，但根节点sta连接了AP;
3.1.2 注册回调函数
在调用配网API之前在所有mesh节点处调用API注册回调函数，用于后续获取空闲节点列表/获取拓扑结果/获取删除节点结果/获取用户信息等；
API：
bk_err_t bk_wifi_mesh_set_api_mode(void* event_cb);
- int event_cb(void *arg, event_module_t event_module, int event_id, void *event_data);
event_data: 返回的数据，具体内容请参考各api说明
event_module: 3(表示当前event为mesh事件)
- event_id：
0- BK_MESH_EVENT_GET_IDLE_NODE
1- BK_MESH_EVENT_GET_TOPO
2- BK_MESH_EVENT_RM_NODE
3- BK_MESH_EVENT_GET_VENDOR
3.2 获取空闲节点列表
可在网关节点或任意节点调用API接口，并注册回调函数获取空闲节点列表，mesh节点收到请求后，将返回全部空闲节点列表。
获取空闲节点示意图
3.2.1 API说明
API：
bk_err_t bk_wifi_mesh_get_idle_node(void);
备注
1、在调用此API接口之前，需要先调用bk_wifi_mesh_set_api_mode函数设置回调函数以获取空闲节点列表。
2、可通过在projet中修改CONFIG_BK_WIFI_MESH_FREE_AP_SSID宏的值改变空闲节点名称；
3.2.2 返回数据格式
返回空闲节点列表数据格式含义如下：
Length：为Length后面的所有字段的长度
node_num：表示返回空闲节点的数量；
node_info_list：仅node_num不为0时存在，表示空闲节点的mac_addr；
3.3 空闲节点配网
可在网关节点或任意空闲节点调用API接口，通知mesh节点配网，mesh节点收到请求后，开始配网并通知其他节点。
空闲节点配网示意图
3.3.1 API说明
API：
bk_err_t bk_wifi_mesh_net_cfg(const bk_wifi_mesh_net_cfg_t *config);
必选参数：
uint16_t node_num; 表示本次配网的mesh节点数量，大于0的整数；
char *node_mac_list; 本次配网的mesh节点对应的mac addr；
uint8_t max_mesh_num; mesh节点最大允许连接的mesh节点个数，1~10为有效值，为0表示使用默认值10；
uint8_t design_root[WIFI_MAC_LEN]; 指定根节点的mac地址；
广域网时，如下参数为必选
char router_ssid[WIFI_SSID_STR_LEN]; 广域网配网时使用，根节点关联的AP的ssid；
char router_pw[WIFI_PASSWORD_LEN]; 广域网配网时使用，根节点关联的AP的pw；
可选参数：
uint32_t net_token;token配网口令，为0表示将使用随机token；
uint8_t mesh_id;mesh网络标识符，为0表示使用默认值；
char sap_ssid[WIFI_SSID_STR_LEN];表示配网时设置的sap的ssid，为0表示使用默认值；
char sap_pw[WIFI_PASSWORD_LEN];表示配网时设置的sap的pw，为0表示使用默认值；
uint8_t max_level;mesh网络的最大层数，可设置为不小于1的整数，为0表示使用默认值10；
备注
1、【必选参数】表示调用API进行操作时必须要设置的值，否则操作不生效。
2、可配合3.3.1查询拓扑确认组网结果及网络结构
3.4 MESH网络控制
3.4.1 查询拓扑
在根节点处调用API接口，查询mesh网络结构，根节点收到查询请求后，返回拓扑结构。
查询拓扑示意图
3.4.1.1 API说明
API：
bk_err_t bk_wifi_mesh_get_topo(void);
备注
在调用此API接口之前，需要先调用bk_wifi_mesh_set_api_mode函数设置回调函数以获取拓扑结果，此API不直接返回拓扑。
3.4.1.2返回数据格式
Mesh节点返回拓扑结构格式消息格式见上图，各参数含义如下：
Length；表示Length后面的所有字段的长度；
Result；表示返回拓扑说明，0：表示返回当前拓扑结果；1：表示当前无拓扑结果，返回拓扑为空；2：表示当前mesh网络不稳定，拓扑结果大于配网节点数，可10s后再次查询（最大重复3次）；
Max Conn Num：表示mesh网络中配置的最大mesh连接个数,由Mesh节点带回当前的配置的值；
Max Non Mesh Num：最大non mesh节点连接个数,由Mesh节点带回当前的配置的值；
Max Level：最大mesh网络层数，由Mesh节点带回当前的配置的值；
Node Num：指示，本次上报的当前Mesh网络的节点个数；
Node Info List：mesh网络的节点信息；
Level：表示该节点的层级；
Node Mac Addr：表示该节点的MAC地址；
Parent Mac Addr：表示该节点的父节点信息，全FFFFFFFFFFFF表示没有父节点信息；
Mesh Conn Left：表示该节点还剩余的mesh节点连接数量；
Non Mesh Conn Left：表示该节点还剩余的non-mesh节点连接数量；
3.4.2 增加节点
在根节点处调用API接口，通知mesh节点增加节点，mesh节点收到请求后，通知其他节点加入MESH网络。
增加节点示意图
3.4.2.1 API说明
API：
bk_err_t bk_wifi_mesh_add_node(const bk_wifi_mesh_add_node_t *add_node);
必选参数：
uint16_t node_num; 表示本次加入网络的mesh节点数量；
char *node_mac_list; 本次加入mesh网络的mesh节点对应的mac addr；
可选参数：
char *design_parent; 增加节点分别对应的父节点；
备注
可配合3.3.1查询拓扑来检查节点是否加入网络；
3.4.3 删除节点
在根节点处调用API接口，根节点收到删除请求后，通知MESH网络中的节点删除。
删除节点示意图
3.4.3.1 API说明
API：
bk_err_t bk_wifi_mesh_remove_node(uint16_t node_num, uint8_t *node_mac_list);
必选参数：
uint16_t node_num; 表示本次删除的mesh节点数量
char *node_mac_list; 本次删除的节点对应的mac addr
备注
在调用此API接口之前，需要先调用bk_wifi_mesh_set_api_mode函数设置回调函数以获取删除结果，此API不直接返回结果。
3.4.3.2返回数据格式
Mesh节点返回删除节点结果消息格式见上图，各参数含义：
Length：表示Length后面的所有字段的长度
node_num：表示删除节点失败的个数，为0表示全部节点删除成功；
node_info_list：仅node_num不为0时存在，携带失败node_info_list；
3.4.4 修改配置
可在根节点处调用API接口，通知修改网络配置，mesh节点收到请求后，通知MESH网络中的节点修改MESH网络配置。
修改配置示意图
3.4.4.1 API说明
API：
bk_err_t bk_wifi_mesh_change_cfg(const bk_wifi_mesh_change_cfg_t *change_cfg);
必选参数：
uint16_t node_num; 表示修改mesh网络配置的节点数量
char *node_mac_list; 表示修改mesh网络配置的节点对应的mac addr
可选参数：
char *design_parent; 修改配置的节点指定的父节点
uint8_t max_mesh_num; 表示修改的mesh节点最大允许连接的mesh节点个数，1~10为有效值；
uint8_t max_level; 修改mesh网络的最大层数，可设置为不小于1的整数；
备注
可配合3.3.1查询网络拓扑确认修改配置是否生效
3.4.5 设置用户信息
在根节点处调用API接口，设置用户信息，节点收到设置请求后，通知MESH网络中的其他节点。
设置用户信息示意图
3.4.5.1 API说明
API：
bk_err_t bk_wifi_mesh_set_vendor(const bk_wifi_mesh_vendor_t *set_vendor);
必选参数：
uint16_t node_num; 表示本次设置用户信息的mesh节点数量；
char *node_mac_list; 本次设置用户信息的节点对应的mac addr；
uint16_t vendor_len; 表示设置用户信息的整体长度。
char *vendor_ptr; 为用户自定义字段
3.4.6 获取用户信息
在根节点处调用API接口，获取用户信息，mesh节点收到请求后，汇总节点用户信息返回。
获取用户信息示意图
3.4.6.1 API说明
API：
bk_err_t bk_wifi_mesh_get_vendor(const bk_wifi_mesh_vendor_t *get_vendor);
必选参数：
uint16_t node_num; 表示本次获取用户信息的mesh节点数量；
char *node_mac_list; 本次获取用户信息的节点对应的mac addr；
uint16_t vendor_len; 表示获取用户信息的长度。
char *vendor_ptr; 为用户自定义字段，指定了本次获取的用户信息类型
备注
在调用此API接口之前，需要先调用bk_wifi_mesh_set_api_mode函数设置回调函数以获取用户信息，此API不直接返回结果。
3.4.6.2返回数据格式
Mesh节点返回消息格式见上图，各参数含义如下：
Length：表示Length后面的所有字段的长度
Node num：表示返回用户信息的节点数
Vendor info result：表示各节点的用户信息
Node mac addr – 该节点的mac addr
vendor length – 用户信息的长度
vendor specific – 用户信息
3.4.7 OTA升级
在根节点处调用API接口，通知OTA升级，根节点收到请求后，通知MESH网络中的所有节点将要开始OTA升级，然后根节点根据ota_type采用不同的方式下载升级固件，并将固件通知给MESH网络中的所有mesh节点。
OTA升级示意图
3.4.7.1 API说明
API：
bk_err_t bk_wifi_mesh_ota_start(const bk_wifi_mesh_ota_t *ota_cfg);
必选参数：
uint8_t ota_type; 表示本次ota升级的类型，1代表云端升级，2代表app升级，3代表串口升级;
uint8_t upgrade_type; 表示本次模式，0代表升级全部，1代表升级单个，2代表升级部分;
uint16_t node_num; 表示本次ota升级的mesh节点数量；
uint8_t * node_mac_list; 表示升级节点的mac地址;
char ap_ssid[WIFI_SSID_STR_LEN]; 【ota_type = 2时为必选参数】 ，表示手机热点的ssid;
char ap_pw[WIFI_PASSWORD_LEN]; 【ota_type = 2时为必选参数】 ，表示手机热点的pw;
uint8_t url_len; 【ota_type为1和2时为必选参数】，代表url长度;
char *url_ptr; 【ota_type为1和2时为必选参数】;
备注
1、ota_type为3时，用户通过UART直接将升级固件发送到根节点的OTA分区而非通过url下载固件。
2、可配合3.3.8查询OTA升级进度。
3.4.8 获取OTA状态
在根节点处调用API接口，获取ota升级状态，根节点收到消息后，会返回当前ota状态。
获取OTA状态示意图
3.4.8.1 API说明
API：
uint8_t bk_wifi_mesh_get_ota_state(void);
3.4.8.2返回数据格式
uint8_t ota_status;
参数含义如下：
OTA status：
0表示空闲状态，未在OTA升级；
1表示当前在OTA升级过程中；
2表示rbl下载失败；
3表示未扫描到手机热点，请确认输入热点名称是否正确；
4表示手机热点密码错误，请确认输入热点密码是否正确；
5表示与热点连接失败，请重试；
3.4.9 Reset节点
在需要进行reset操作的节点处调用API接口，通知该节点reset，mesh节点收到reset消息后，会清除falsh并退出mesh网络恢复为空闲节点。
Reset节点示意图
3.4.9.1 API说明
API：
bk_err_t bk_wifi_mesh_reset_node(const bk_wifi_mesh_reset_node_t *reset_node);
必选参数：
uint16_t node_num; 表示本次reset节点的数量；
uint8_t * node_mac_list; 表示reset节点的mac地址;
3.4.10 获取节点状态信息
在非网关节点处调用API接口获取节点信息，mesh节点收到消息后，返回节点当前状态信息。
3.4.9.1 API说明
API：
bk_err_t bk_wifi_mesh_status_info(bk_wifi_mesh_status_t *link_status);
返回参数含义：
bk_mesh_link_state_t state; 表示节点连接状态，0：空闲节点；1：节点组网中；2：组网完成，加入mesh网络；3：网络恢复中
uint8_t level; 表示节点在mesh网络中的层级;
uint8_t link_mesh_num; 表示与该节点连接的mesh节点数;
uint8_t link_non_mesh_num; 表示与该节点连接的非mesh节点数;
uint8_t parent_mac[6]：表示节点连接的父节点的mac地址;