BK-WIFI-MESH APIs

[zh_CN]

Important

The WiFi API v2.0 is the lastest stable WiFi APIs, it’s used to deprecate the WiFi API v1.0. All new applications should use WiFi API v2.0.

BK Wi-Fi Mesh Interface

Programing Principle

Important

Here is some general principle for API users:

  • Always init the reserved fields of config stuct to 0

  • Use BK_ERR_CHECK to check the return value of the API

  • If you are not sure how to use PIs, study the example code first

  • If you are not sure how to initialize some fields of config struct, use the default configuration macro to use the config first and then set application specific fields, e.g. use WIFI_DEFAULT_BK_MESH_CONFIG() to init bk_wifi_mesh_cfg_t first.

  • Don’t do too much work in event callback, relay the event to your own application task.

API Reference

Header File

Functions

bk_err_t bk_wifi_mesh_config(const bk_wifi_mesh_cfg_t *bk_mesh_config)

Set bk wifi mesh configuration.

Attention

Call bk_wifi_bk_mesh_config() first before call bk_wifi_bk_mesh_start().

Parameters

bk_mesh_config – store the configuration of BK wifi mesh.

Returns

  • BK_OK: succeed

  • others: other errors

bk_err_t bk_wifi_mesh_start(void)

Start BK wifi mesh.

This API notifies the WiFi driver to start a bk wifi mesh node.

Attention

Call bk_wifi_bk_mesh_config() first before call bk_wifi_bk_mesh_start().

Returns

  • BK_OK: succeed

  • others: other errors

bk_err_t bk_wifi_mesh_stop(void)

Stop BK wifi mesh.

This API notifies the WiFi driver to stop a bk wifi mesh node.

Attention

Call bk_wifi_bk_mesh_config() and bk_wifi_bk_mesh_start() if you want to restart a bk wifi mesh node after stop.

Returns

  • BK_OK: succeed

  • others: other errors

bk_err_t bk_wifi_mesh_status_info(void)

Get the link info of the BK WIFI MESH node.

The link status information of the node includes the current state, the type, the current level, the number of the downlink mesh nodes and non-mesh nodes, the MAC address of the parent node.

Returns

  • BK_OK: succeed

  • BK_FAIL: BK WIFI MESH is not enable.

  • others: other errors

void bk_wifi_mesh_set_device_type(uint8_t device_type)

Set device type to BK mesh node.

The device type is defined by user. For example, type 1 indicates that the device is a light.

Parameters

device_type – store the type of device.

uint8_t bk_wifi_mesh_get_device_type(void)

Get the device type of the BK WIFI MESH node.

The device type is defined by user.

Returns

device type of the BK WIFI MESH node.

bk_err_t bk_wifi_mesh_set_vendor_cb_reg(void *set_vendor_cb)

set_vendor callback registration function. For example, set the color of the led, obtain the version, and so on.

callback function format typedef bk_err_t (* bk_mesh_net_set_vendor_cb_t)(uint8_t* vendor_ptr);

Parameters

void* – set_vendor_cb

bk_err_t bk_wifi_mesh_get_vendor_cb_reg(void *get_vendor_cb)

get vendor callback registration function For example, get the color of the lamp, obtain the version, and so on.

callback function format typedef uint8_t* (* bk_mesh_net_get_vendor_cb_t)(uint16_t* len, uint8_t* vendor_ptr); param in:

  • vendor_ptr: get the type of vendor param out

  • len: return the length of vendor

  • vendor: vendor returned according to the query type

Parameters

void* – get_vendor_cb

bk_err_t bk_wifi_mesh_comm_mac_get(uint8_t *my_mac, uint8_t *root_mac)

get communication mac Include my mac address and root’s mac address

Parameters

  • my_mac – is my mac address

  • root_mac – is the mac address of the root node

Returns

  • BK_OK: succeed

  • BK_FAIL: the mac address of the root node is invalid

bk_err_t bk_wifi_mesh_data_send(uint8_t *rcv_mac_addr, uint8_t *data_buf, uint16_t data_len, uint16_t data_type)

Send internal data frame to other node in the same network.

Parameters

  • rcv_mac_addr – send dest mac address

  • data_buf – send data buffer start address

  • data_len – send data length,length mast less than 1.4k

  • data_type – send data type ,user only use 0;

Returns

  • BK_OK: sent succeed

  • BK_FAIL: sent fail

bk_err_t bk_wifi_mesh_ota_data_write(char *data_ptr, uint32_t len)

Write OTA bin to root node, and the function can only be called in root node.

Attention

Call bk_wifi_mesh_ota_data_write() first before config OTA start.

Parameters

  • data_ptr – data address

  • len – data length,length mast be 1024. if last data frame not enought,use 0x0 or 0xf refill.

Returns

  • BK_OK: data write succeed

  • BK_FAIL: data write fail

bk_err_t bk_wifi_mesh_ota_finish(void)

Notify ota bin download finish,and check crc is right.

Attention

Call bk_wifi_mesh_ota_finish() before all OTA bin data send finish.

Parameters

void –

Returns

  • BK_OK: bin crc succeed

  • BK_FAIL: bin crc fail

uint8_t *bk_wifi_mesh_get_idle_node(void)

Get the idle node list of BK WIFI MESH node.

Returns

idle node list.

  • uint16_t length: Indicate the length of all fields after Length;

  • uint16_t node_num: Indicates the number of idle nodes returned;

  • uint8_t *node_list: Indicating the mac_addr list of idle nodes;

bk_err_t bk_wifi_mesh_net_cfg(const bk_wifi_mesh_net_cfg_t *config)

Set bk wifi mesh networking configuration.

Parameters

config – refer to the parameptr description of bk_wifi_mesh_net_cfg_t

Returns

  • BK_OK: succeed

  • others: other errors

uint8_t *bk_wifi_mesh_get_topo(void)

Get the topology of mesh network.

Attention

Call bk_wifi_mesh_get_topo at the root node.

Returns

mesh network topology.

  • uint16_t length: Indicate the length of all fields after Length;

  • uint8_t max_conn_Num: maximum number of mesh connections and non mesh connections;

  • uint8_t max_non_mesh_num: the maximum number of non mesh node connections;

  • uint8_t max_level: the maximum number of mesh network layers configured in the mesh network

  • uint16_t node_num: The number of nodes in the current Mesh network reported;

  • uint8_t *node_info_list: Node information of mesh network;

    • uint8_t level: Indicate the hierarchy of the node;

    • uint8_t node_mac_addr[6]: represents the MAC address of the node;

    • uint8_t parent_mac_addr[6]: represents the parent node information of the node,0 indicates no parent node information;

    • uint8_t mesh_conn_left: represents the number of remaining mesh node connections for the node;

    • uint8_t non_mesh_conn_left: represents the remaining number of non mesh node connections for the node;

bk_err_t bk_wifi_mesh_add_node(const bk_wifi_mesh_add_node_t *add_node)

Set add node configuration.

Attention

Call bk_wifi_mesh_add_node at the root node.

Parameters

add_node – refer to the parameptr description of bk_wifi_mesh_add_node_t

Returns

  • BK_OK: succeed

  • others: other errors

uint8_t *bk_wifi_mesh_remove_node(uint16_t node_num, uint8_t *node_mac_list)

Set remove node configuration.

Attention

Call bk_wifi_mesh_remove_node at the root node.

Parameters

  • node_num – Indicate the number of remove

  • node_mac_list – The MAC address list corresponding to the remove node.

Returns

remove fail list

  • uint16_t length: Indicate the length of all fields after Length;

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

  • uint8_t *node_info_list: Only exists when node_num is not 0, carrying the failed node_info_list;

bk_err_t bk_wifi_mesh_change_cfg(const bk_wifi_mesh_change_cfg_t *change_cfg)

Set the change mesh config configuration.

Attention

Call bk_wifi_mesh_change_cfg at the root node.

Parameters

change_cfg – refer to the parameptr description of bk_wifi_mesh_change_cfg_t

Returns

  • BK_OK: succeed

  • others: other errors

bk_err_t bk_wifi_mesh_set_vendor(const bk_wifi_mesh_vendor_t *set_vendor)

Set the vendor information configuration.

Attention

Call bk_wifi_mesh_set_vendor at the root node.

Parameters

  • set_vendor – refer to the parameptr description of bk_wifi_mesh_vendor_t

  • node_num – Indicate the number of mesh nodes for customer information setup

  • node_mac_list – The MAC address list corresponding to the node_num.

  • vendor_len – Indicate the overall length of setting custom information

  • vendort_ptr – User Defined Fields.

Returns

  • BK_OK: succeed

  • others: other errors

uint8_t *bk_wifi_mesh_get_vendor(const bk_wifi_mesh_vendor_t *get_vendor)

Get the vendor information configuration.

Attention

Call bk_wifi_mesh_get_vendor at the root node.

Parameters

get_vendor – refer to the parameptr description of bk_wifi_mesh_vendor_t

Returns

vendor information

  • uint16_t length: Indicate the length of all fields after Length;

  • uint16_t node_num: Indicate the number of nodes that return customer information data;

  • uint8_t *vendor_info_list: Indicate customer information for each node;

    • uint8_t node_mac_addr[6]: The MAC address of mesh node;

    • uint16_t vendor_length: Customer Information length;

    • uint8_t * vendor_specific: customer information data;

bk_err_t bk_wifi_mesh_ota_start(const bk_wifi_mesh_ota_t *ota_cfg)

Set the OTA ugrade configuration.

Attention

Call bk_wifi_mesh_ota_start at the root node.

Parameters

ota_cfg – refer to the parameptr description of bk_wifi_mesh_ota_t

Returns

  • BK_OK: succeed

  • others: other errors

uint8_t bk_wifi_mesh_get_ota_state(void)

Get the OTA state.

Attention

Call bk_wifi_mesh_get_ota_state at the root node.

Returns

  • 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;

bk_err_t bk_wifi_mesh_reset_node(void)

Reset the mesh node. mesh node will clear flash and become idle node.

Attention

Call bk_wifi_mesh_reset_node at the root node.

Returns

  • BK_OK: succeed

  • others: other errors

API Typedefs

Header File

Structures

struct bk_wifi_mesh_cfg_t

BK MESH configuration.

BK MESH configuration parameters.

Public Members

uint8_t mesh_id

The Mesh ID

char router_ssid[WIFI_SSID_STR_LEN]

The SSID of the router

char router_password[WIFI_PASSWORD_LEN]

The password of the router

char ap_ssid[WIFI_SSID_STR_LEN]

The SSID of an access point

char ap_password[WIFI_PASSWORD_LEN]

The password of the access point

uint8_t max_mesh_conn_num

The maximum number of mesh stations allowed to connect in.

uint8_t max_non_mesh_conn_num

The maximum number of non-mesh stations allowed to connect in.

uint8_t max_level

The maximum level allowed

bool is_designated_root

Ture if the node is designated root node.

struct bk_wifi_mesh_net_cfg_t

BK MESH networking configuration.

Public Members

uint32_t net_token

net token.

token for the first network distribution,use random value when set 0

uint16_t node_num

Indicates the number of selected mesh nodes

uint8_t *node_mac_list

MAC addr list corresponding to the node_num

uint8_t mesh_id

Mesh network identifier, 0 indicates use default values

char router_ssid[WIFI_SSID_STR_LEN]

The SSID of the AP associated with the root node,wide area networkis mandatory

char router_pw[WIFI_PASSWORD_LEN]

The password of the AP associated with the root node, wide area networkis mandatory

char sap_ssid[WIFI_SSID_STR_LEN]

The SSID of SAP, 0 indicating use default value

char sap_pw[WIFI_PASSWORD_LEN]

The password of SAP, 0 indicating use default value

uint8_t max_mesh_num

The maximum number of mesh nodes that can be connected, with 1 to 10 being valid, 0 indicating use default value 10

uint8_t max_level

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

uint8_t design_root[WIFI_MAC_LEN]

designated root node mac address

struct bk_wifi_mesh_add_node_t

BK MESH add node configuration.

Public Members

uint16_t node_num

Indicates the number of selected mesh nodes

uint8_t *node_mac_list

MAC addr list corresponding to the node_num

uint8_t *design_parent

Add parent nodes corresponding to each node separately

struct bk_wifi_mesh_change_cfg_t

BK MESH change config configuration.

Public Members

uint16_t node_num

Indicates the number of selected mesh nodes

uint8_t *node_mac_list

MAC addr list corresponding to the node_num

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

uint8_t max_level

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

struct bk_wifi_mesh_vendor_t

BK MESH vendor configuration.

Public Members

uint16_t node_num

Indicates the number of selected mesh nodes

uint8_t *node_mac_list

MAC addr list corresponding to the node_num

uint16_t vendor_len

Indicates the length of customer information

uint8_t *vendort_ptr

custom defined fields

struct bk_wifi_mesh_ota_t

BK MESH ota configuration.

Public Members

uint8_t ota_type

1: cloud upgrade; 2 :app upgrade; 3: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, url

Macros

BK_WIFI_MESH_MAX_LEVEL

Maximum level allowed

BK_WIFI_MESH_MAX_MESH_NODE_PER_LEVEL

Maximum mesh node number per level allowed

BK_WIFI_MESH_MAX_NON_MESH_NODE_PER_LEVEL

Maximum non-mesh node number per level allowed

WIFI_SSID_STR_LEN

Maximum NULL-terminated WiFi SSID length

WIFI_BSSID_LEN

Length of BSSID

WIFI_MAC_LEN

Length of MAC

WIFI_PASSWORD_LEN

Maximum NULL-terminated WiFi password length

SSID_MAX_LEN
ETH_ALEN
WIFI_DEFAULT_BK_MESH_CONFIG()

default BK WIFI MESH configuration

Enumerations

enum bk_wifi_mesh_cfg_type_t

BK MESH configuration type.

BK MESH configuration Type.

Values:

enumerator BK_WIFI_MESH_CFG_TYPE_NONE
enumerator BK_WIFI_MESH_CFG_TYPE_LOCAL
enumerator BK_WIFI_MESH_CFG_TYPE_APP
enumerator BK_WIFI_MESH_CFG_TYPE_WEBPAGE
enumerator BK_WIFI_MESH_CFG_TYPE_MAX