Introduction to BK Wi-Fi MESH Distribution Network and Network Control API

1.Brief Introduction

The Wi-Fi MESH networking provides two methods: APP-based and API-based network configuration. Both can achieve functions such as discovering idle MESH nodes, setting up MESH node networks, querying network topology, network control, and OTA updates. The API interface-based network configuration is mainly used for cloud-based network configuration. For APP-based network configuration, please refer to the document “Bekencorp Wi-Fi Mesh App Usage Introduction Document.”

This document mainly introduces the usage method of Wi-Fi Mesh API distribution network for developers’ reference.

Note

Document link:https://docs.bekencorp.com/arminodoc/bk_mesh/bk7236/zh_CN/v2.0.1/index.html

2.The Functions of Wi-Fi MESH Distribution Network and Network Control API

The BK MESH API provides an interface for obtaining a list of idle nodes, configuring various parameters of the MESH network, and querying network topology(Only supports tree structure) and control devices. The BK MESH API is used to query and control the MESH network.

The main steps include:

I Obtain idle nodes

Users can call the API at gateway node or any node to obtain information about all idle MESH nodes in the current air interface environment, preparing for the next step of distribution network;

II Idle node distribution network

After obtaining idle nodes, the API can be called at gateway node or any idle MESH node to send distribution network information to the MESH node, such as the number of distribution network nodes, specified root nodes, to achieve idle node distribution network and form a MESH network.

After receiving the distribution network request, the API verifies the validity of the distribution network information and passes it on to the MESH node. Each node starts performing distribution network operations based on the configuration information, such as scanning, connecting, and configuring the MESH network.

III MESH Network Control

After the successful networking of MESH network, users can call the API on the root node to performe the following operations to query or control the MESH network.

Query network topology

By calling the API at the root node and querying the network topology(Only supports tree structure), the current network situation can be obtained, such as the number of online nodes, network hierarchy, node topology relationships;

Modify MESH network

Calling the API at the root node can achieve control over the MESH network, such as increasing the number of MESH network nodes, deleting some or all nodes in the MESH network, modifying network configuration, etc;

Set user information or query user information

Call the API at the root node to configure or query user information;

OTA upgrade

Call the API at the root node, configure OTA upgrade information, initiate OTA upgrade or confirm whether the upgrade is completed by querying the OTA upgrade status;

Reset Node

When a node is disconnected from the MESH network and cannot rejoin the network, the node reset function can be used to reset the node and restore it to an idle node state.

3 Wi-Fi MESH Distribution Network and Network Control API Usage Instructions

3.1 Obtain Idle Nodes

The API interface can be called at gateway node or any node to obtain a list of idle nodes. After receiving the request, the mesh node will return a list of all idle nodes.

Uart — Obtain a schematic diagram of idle nodes

3.1.1 API description

API：

uint8_t * bk_wifi_mesh_get_idle_node(void);

3.1.2 Return Data Format

The meaning of the data format for returning the list of idle nodes is as follows:

Length：Indicate the length of all fields after Length;

node_num： Indicates the number of idle nodes returned;

node_info_list：Only exists when node_num is not 0, indicating the mac_addr list of idle nodes;

3.2 Idle node distribution network

The API interface can be called at gateway node or any idle node to notify the mesh node of the distribution network. After receiving the request, the mesh node starts the distribution network and notifies other nodes.

3.2.1 API description

API：

bk_err_t bk_wifi_mesh_net_cfg(const bk_wifi_mesh_net_cfg_t *config);

Required parameters:

uint16_t node_num; Indicate the number of mesh nodes in this distribution network, an integer greater than 0;

uint8_t *node_mac_list; Indicate the number of mesh nodes in this distribution network, an integer greater than 0;

uint8_t max_mesh_num; The maximum number of mesh nodes that can be connected to a mesh node, with 1 to 10 being valid values and 0 indicating the use of the default value of 10;

uint8_t design_root[WIFI_MAC_LEN]; Specify the MAC address of the root node;

When configuring a wide area network, the following parameters are required

char router_ssid[WIFI_SSID_STR_LEN]; The SSID of the AP associated with the root node；

char router_pw[WIFI_PASSWORD_LEN]; The password of the AP associated with the root node；

Optional parameters:

uint32_t net_token; Token distribution network password, 0 indicates that a random token will be used;

uint8_t mesh_id; Mesh network identifier, 0 indicates the use of default values;

char sap_ssid[WIFI_SSID_STR_LEN]; The SSID of SAP set during the distribution network is 0, indicating the use of the default value;

char sap_pw[WIFI_PASSWORD_LEN]; The pw of SAP set during distribution network, 0 indicates the use of default value;

uint8_t max_level; The maximum number of layers in a mesh network can be set to an integer not less than 1, with 0 indicating the use of the default value of 10;

Note

1.”Required parameters” indicates the value that must be set when calling the API for operation, otherwise the operation is invalid.

2.Cooperate with 3.3.1 to query topology and confirm network results and structure

3.3 MESH Network Control

3.3.1 Query topology

Call the API interface at the root node to query the mesh network structure. After receiving the query request, the root node returns the topology structure.

3.3.1.1 API description

API：

uint8_t * bk_wifi_mesh_get_topo(void);

3.3.1.2 Return Data Format

The message format for the topology structure returned by Mesh nodes is shown in the above figure, and the meanings of each parameter are as follows:

Length；Indicate the length of all fields after Length;

Max Conn Num：maximum number of mesh connections

Max Non Mesh Num：the maximum number of non mesh node connections

Max Level：and the maximum number of mesh network layers configured in the mesh network

Node Num：The number of nodes in the current Mesh network reported this time;

Node Info List：Node information of mesh network;

Level：Indicate the hierarchy of the node;

Node Mac Addr：represents the MAC address of the node;

Parent Mac Addr： represents the parent node information of the node, all FFFFFFFF indicates no parent node information;

Mesh Conn Left：represents the number of remaining mesh node connections for the node;

Non Mesh Conn Left：represents the remaining number of non mesh node connections for the node;

3.3.2 Add Node

The API interface can be called at the root node to notify the addition of MESH nodes. After receiving the request, the root node notifies other nodes to join the MESH network.

3.3.2.1 API description

API：

bk_err_t bk_wifi_mesh_add_node(const bk_wifi_mesh_add_node_t *add_node);

Required parameters:

uint16_t node_num; Indicate the number of mesh nodes joining the network this time;

uint8_t *node_mac_list; List of MAC addresses corresponding to nodes joining the mesh network;

Optional parameters:

uint8_t *design_parent; Add parent nodes corresponding to each node separately;

Note

In the future, they can be checked whether the nodes have joined the network by querying the topology in 3.3.1;

3.3.3 Remove Node

Call the API interface at the root node, After receiving the deletion request, the root node notifies the nodes in the MESH network to delete.

3.3.3.1 API description

API：

uint8_t* bk_wifi_mesh_remove_node(uint16_t node_num, uint8_t *node_mac_list);

Required parameters:

uint16_t node_num; Indicate the number of mesh nodes deleted this time

uint8_t *node_mac_list; The MAC address list corresponding to the deleted node

3.3.3.2 Return Data Format

The format of the message returned by the Mesh node for deleting nodes is shown in the above figure, and the meanings of each parameter are as follows:

Length：Indicate the length of all fields after Length

node_num：Indicates the number of nodes that failed to be deleted, 0 indicates that all nodes were successfully deleted;

node_info_list：Only exists when node_num is not 0, carrying the failed node_info_ist;

3.3.4 Change Config

The API interface can be called at the root node to notify the modification of network configuration. After receiving the request, the mesh node notifies the nodes in the MESH network to modify the MESH network configuration.

3.3.4.1 API description

API：

bk_err_t bk_wifi_mesh_change_cfg(const bk_wifi_mesh_change_cfg_t *change_cfg);

Required parameters:

uint16_t node_num; Indicate the number of modified nodes

uint8_t *node_mac_list; Indicate the mac_addr_list corresponding to the modified nodes

Optional parameters:

uint8_t *design_parent; Modify the parent node specified by the configured node

uint8_t max_mesh_num; Indicates the maximum number of mesh nodes allowed for connection, with 1 to 10 being valid values;

uint8_t max_level; The maximum number of layers in a MESH network can be set to an integer not less than 1;

Note

Can cooperate with 3.3.1 to query network topology and confirm whether the modified configuration is effective.

3.3.5 Set Customer Information

Call the API interface at the root node to set customer Information. After receiving the setting request, the node notifies other nodes in the MESH network.

3.3.5.1 API description

API：

bk_err_t bk_wifi_mesh_set_vendor(const bk_wifi_mesh_vendor_t *set_vendor);

Required parameters:

uint16_t node_num; Indicate the number of mesh nodes for customer information setup this time；

uint8_t *node_mac_list; MAC Address List Corresponding to node_num;

uint16_t vendor_len; Indicate the overall length of setting user information;

uint8_t *vendor_ptr; User Defined Fields

3.3.6 Get Customer Information

Call the API interface at root node to obtain user information. After receiving the request, the mesh node summarizes the node’s user information and returns it.

3.3.6.1 API description

API：

uint8_t* bk_wifi_mesh_get_vendor(const bk_wifi_mesh_vendor_t *get_vendor);

Required parameters:

uint16_t node_num; Indicates the number of mesh nodes；

uint8_t *node_mac_list; MAC addr list corresponding to the node;

uint16_t vendor_len; Indicates the length of obtaining customer information.

uint8_t *vendor_ptr; User defined field that specifies the customer information type to be obtained

3.3.6.2 Return Data Format

The message format returned by Mesh nodes is shown in the above figure, and the meanings of each parameter are as follows:

Length：Indicate the length of all fields after Length

Node num：Indicate the number of nodes that return customer information data

vendor info result：Indicate customer information for each node

Node mac addr – The MAC address of this node

vendor length – Customer Information length

vendor specific – customer information data

3.3.7 OTA Upgrade

Call the API interface at the root node to notify OTA upgrade. Upon receiving the request, the root node notifies all nodes in the MESH network that OTA upgrade is about to begin. Then, the root node downloads the upgrade firmware in different ways based on the otaotype and notifies all mesh nodes in the MESH network of the firmware.

3.3.7.1 API description

API：

bk_err_t bk_wifi_mesh_ota_start(const bk_wifi_mesh_ota_t *ota_cfg);

Required parameters:

uint8_t ota_type; Indicate the type of OTA upgrade this time, where 1 represents cloud upgrade, 2 represents app upgrade, and 3 represents serial port upgrade

char ap_ssid[WIFI_SSID_STR_LEN]; 【Required when otaotype is 2】 ，SSID representing mobile hotspot;

char ap_pw[WIFI_PASSWORD_LEN]; 【Required when otaotype is 2】 ，password representing mobile hotspot;

uint8_t url_len; 【Required when otaotype is 1 or 2】，url_ptr length；

uint8_t *url_ptr; 【Required when otaotype is 1 or 2】 ；

Note

Note: When ota_date is 3, users can directly send the upgraded firmware to the OTA partition of the root node through UART instead of downloading the firmware through a URL.
Can be used in conjunction with 3.3.8 to check the progress of OTA upgrades.

3.3.8 Get OTA Status

Call the API interface at the root node to obtain the OTA upgrade status. After receiving the message, the root node will return the current OTA status.

3.3.8.1 API description

API：

uint8_t bk_wifi_mesh_get_ota_state(void);

3.3.8.2 Return Data Format

uint8_t ota_status;

The meanings of each parameter are as follows:

OTA status：

0 - Indicates idle status, not upgraded in OTA;

1 - Indicates that the current OTA upgrade process is underway;

2 - Indicates RBL download failure;

3 - Indicates that no mobile hotspot has been scanned. Please confirm if the hotspot name is entered correctly;

4 - Indicates that the mobile hotspot password is incorrect. Please confirm if the hotspot password entered is correct;

5 - Failed to connect to hotspot, please try again;

3.3.9 Reset Node

Call the API interface at the node that needs to perform a reset operation, notify the node to reset. After receiving the reset message, the mesh node will clear the false and exit the mesh network to recover as an idle node.

3.3.9.1 API description

API：

bk_err_t bk_wifi_mesh_reset_node(void);