 |
WICED Smart™ v2.2.3 - API Reference Guide |  |
|||
|
WICED Smart™ v2.2.3 - API Reference Guide | |
|||
BLE mesh definitions. More...
Data Structures | |
| struct | BlemeshNodeData |
| struct | BlemeshConfig |
| BLE mesh operation parameter configuration data structure. More... | |
| struct | _BlemeshCalloutFuncs |
| Struct for BLE mesh core callout functions which shall be provided by the mesh core application. More... | |
Typedefs | |
| typedef UINT32 | ACKREF |
| typedef UINT32 | BlemeshPktType |
| typedef void(* | BlemeshTxAckFunc )(UINT8 src_id, const UINT8 *data, UINT32 len, BOOL ack_timed_out, ACKREF ack_ref) |
| BLE mesh data packet Tx (send) ack function definition. More... | |
| typedef struct _BlemeshCalloutFuncs | BlemeshCalloutFuncs |
| Struct for BLE mesh core callout functions which shall be provided by the mesh core application. | |
Functions | |
| BlemeshResultCode | blemesh_core_init (BlemeshCalloutFuncs *funcs) |
| Initialize the mesh core. More... | |
| UINT32 | blemesh_get_lib_version (void) |
| Mesh core library function to retrieve mesh core library version. More... | |
| UINT8 | blemesh_get_node_id (void) |
| Mesh core library function to return the node ID. More... | |
| void | blemesh_create_node (BOOL force_reset, const BlemeshConfig *config, BOOL *node_authenticated) |
| Mesh core library function to create the node. More... | |
| BlemeshResultCode | blemesh_set_node (const BlemeshNodeData *node_data) |
| Mesh core library function to authenticate a node by setting the node info. More... | |
| BlemeshResultCode | blemesh_add_group (UINT8 group_id) |
| Mesh core library function to add this node into the specified group. More... | |
| BlemeshResultCode | blemesh_delete_group (UINT8 group_id) |
| Mesh core library function to delete this node from the specified group. More... | |
| void | blemesh_update_mesh_param (const BlemeshConfig *config) |
| Mesh core library function to update the mesh operation parameters. More... | |
| BlemeshResultCode | blemesh_start_mesh (void) |
| Mesh core library function to start BLE mesh. More... | |
| void | blemesh_stop_mesh (void) |
| Mesh core library function to stop BLE mesh. More... | |
| BlemeshResultCode | blemesh_start_beaconing (UINT32 beacon_type, UINT8 *beacon_adv, UINT32 beacon_adv_len) |
| Mesh core library function to enable beaconing when mesh is idle. More... | |
| void | blemesh_stop_beaconing (void) |
| Mesh core library function to stop the beaconing function. More... | |
| void | blemesh_get_neighbor_map (UINT8 *neighbor_map) |
| Mesh core library function to return the current neighbor node map. More... | |
| void | blemesh_get_node_neighbor_map (UINT8 dst_id, UINT8 *neighbor_map, void(*cb_func)(UINT8 dst_node, UINT8 *neighbor_map, BOOL map_valid)) |
| Mesh core library function to request for a remote node current neighbor node map. More... | |
| BlemeshResultCode | blemesh_send_data (BlemeshPktType type, const UINT8 *data, UINT32 data_len, BlemeshTxAckFunc ack_func, ACKREF ack_ref, BOOL local, BOOL retransmitDelay) |
| Mesh core library function to send a data packet over the mesh network. More... | |
| BlemeshResultCode | blemesh_send_p2p_data (UINT8 dst_id, UINT32 dst_node_pkt_cntr, const UINT8 *dst_node_iv, const UINT8 *dst_node_key, const UINT8 *data, UINT32 data_len, BlemeshTxAckFunc ack_func, ACKREF ack_ref) |
| Mesh core library function to send a point-to-point data packet over the mesh network. More... | |
| void | blemesh_send_p2m_ack (UINT8 dst_id, const UINT8 *data, UINT32 data_len, UINT8 ack_ref) |
| Mesh core library function to send a point-to-multi-point (P2M) ack packet. More... | |
| void | blemesh_send_p2p_ack (UINT8 dst_id, const UINT8 *data, UINT32 data_len, UINT8 ack_ref) |
| Mesh core library function to send a point-to-point (P2P) ack packet. More... | |
| void | blemesh_1s_timer (void) |
| 1s (one second) timer function to be invoked once a second to provide a timer tick. More... | |
| void | blemesh_dev_conn_up (void) |
| Device connection up function call. More... | |
| void | blemesh_dev_conn_down (void) |
| Device connection down function call. More... | |
| BOOL | blemesh_handle_adv (const UINT8 *adv_data, UINT32 adv_len, UINT8 adv_type, INT8 rssi, UINT8 *remote_bda) |
| Handle a received adv packet. More... | |
| void | blemesh_dev_filter_set (const UINT8 *NodeIDs, UINT8 count) |
| Set list of devices to ignore messages from. More... | |
| void | blemesh_send_notification (const UINT8 *data, UINT32 data_len) |
| Send a data packet to host via notofocations. More... | |
Variables | |
| BOOL | blemesh_info_trace_enabled |
BLE mesh definitions.
| typedef void(* BlemeshTxAckFunc)(UINT8 src_id, const UINT8 *data, UINT32 len, BOOL ack_timed_out, ACKREF ack_ref) |
BLE mesh data packet Tx (send) ack function definition.
For data packet transmit functions (blemesh_send_data, blemesh_send_p2p_data), if an ack is required, the transmitter shall pass an ack function pointer like this so that mesh core can send back an ack either when the ack from the destination is received or when the ack from destination didn't come after specified timeout. The ack function argument is as below:
src_id: From which node the ack packet comes from - this is the dst_id in the Tx func data: The ack data packet len: The ack data packet length ack_timed_out: Flag to indicate whetehr the ack is due to timeout ref: The opaque reference data mesh core received from the transmit function. This opaque reference data could be used by the transmitter to link the ack packet with the outgoing packet and is not used by the mesh core.
| void blemesh_1s_timer | ( | void | ) |
1s (one second) timer function to be invoked once a second to provide a timer tick.
Mesh core librray depends on this timer tick for timeing. This timer tick does not have to be very accurate.
Parameters: None
Return: None
| BlemeshResultCode blemesh_add_group | ( | UINT8 | group_id | ) |
Mesh core library function to add this node into the specified group.
Parameters: group: Group ID
Return: Returns the result code. When run out of group space, it shall retrun the error code BLEMESH_RESULT_GENERIC_ERROR.
| BlemeshResultCode blemesh_core_init | ( | BlemeshCalloutFuncs * | funcs | ) |
Initialize the mesh core.
Parameters: funcs: Mesh core callout function struct for functions needed from the mesh application
Return: Returns BLEMESH_RESULT_SUCCESS if mesh core is initialized successfully; otherwise returns the corresponding error code.
| void blemesh_create_node | ( | BOOL | force_reset, |
| const BlemeshConfig * | config, | ||
| BOOL * | node_authenticated | ||
| ) |
Mesh core library function to create the node.
Parameters: forceReset: Flag whether to force reset this node to delete any saved node info.
config: Pointer to the configuration parameter struct. NULL means to use default for all parameters; 0 value member means to use default for that parameter.
nodeAuthenticated: flag returned to indicate whether a node has been authenticated into the mesh network.
Return: None
| BlemeshResultCode blemesh_delete_group | ( | UINT8 | group_id | ) |
Mesh core library function to delete this node from the specified group.
Parameters: group: Group ID
Return: Returns the result code.
| void blemesh_dev_conn_down | ( | void | ) |
Device connection down function call.
Parameters: None
Return: None
| void blemesh_dev_conn_up | ( | void | ) |
Device connection up function call.
Parameters: None
Return: None
| void blemesh_dev_filter_set | ( | const UINT8 * | NodeIDs, |
| UINT8 | count | ||
| ) |
Set list of devices to ignore messages from.
It can be called only with debug version of the library blemesh_deb.a
Parameters: NodeIDs: The array of devices IDs count: Number of devices IDs in the array NodeIDs
Return: Return: None
| UINT32 blemesh_get_lib_version | ( | void | ) |
Mesh core library function to retrieve mesh core library version.
Parameters: None
Return: Returns the 32-bit core library version. The version number is as aa.bb.cccc, where "aa" is the most significant byte of the 32-bit version integer, "bb" is the next byte, and "cccc" is the least significant 16-bit.
| void blemesh_get_neighbor_map | ( | UINT8 * | neighbor_map | ) |
Mesh core library function to return the current neighbor node map.
The neighbor node map is a 256-bit array represented by 32 x UINT8 integers. Each bit position indicates whether the node with that position ID is a neighbor of this node.
Parameters: neighbor_map: 256-bit (32 x UINT8) node map to indicate whether a mesh node is present. The caller need make sure the array buffer is large enough.
Return: None
| UINT8 blemesh_get_node_id | ( | void | ) |
Mesh core library function to return the node ID.
Parameters: None
Return: Returns the 8-bit node ID
| void blemesh_get_node_neighbor_map | ( | UINT8 | dst_id, |
| UINT8 * | neighbor_map, | ||
| void(*)(UINT8 dst_node, UINT8 *neighbor_map, BOOL map_valid) | cb_func | ||
| ) |
Mesh core library function to request for a remote node current neighbor node map.
When the node map is obtained, the callback function is called to notified the caller.
The neighbor node map is a 256-bit array represented by 32 x UINT8 integers. Each bit position indicates whether the node with that position ID is a neighbor of this destination node.
Parameters: dst_node: Destination node ID neighbor_map: 256-bit (32 x UINT8) node map. The called need make sure the array buffer is large enough. cb_func: Callback function to return the node map. Function arguments are as below: dst_node: Destination node ID passed in neighbor_map: 256-bit (32 x UINT8) node map passed in for the result map_valid: TRUE if the map returned is valid; otherwise FALSE. timeout: Timeout in seconds. If zero, it will use the default timeout value (10s).
Return: None
| BOOL blemesh_handle_adv | ( | const UINT8 * | adv_data, |
| UINT32 | adv_len, | ||
| UINT8 | adv_type, | ||
| INT8 | rssi, | ||
| UINT8 * | remote_bda | ||
| ) |
Handle a received adv packet.
Parameters: adv_data: The adv packet data adv_len: The adv packet length adv_type: The adv packet type rssi: The transmit device RSSI
Return: Returns TRUE if the adv packet is handled; otherwise returns FALSE.
| BlemeshResultCode blemesh_send_data | ( | BlemeshPktType | type, |
| const UINT8 * | data, | ||
| UINT32 | data_len, | ||
| BlemeshTxAckFunc | ack_func, | ||
| ACKREF | ack_ref, | ||
| BOOL | local, | ||
| BOOL | retransmitDelay | ||
| ) |
Mesh core library function to send a data packet over the mesh network.
Parameters: type: Data packet type data: Data packet data_len: Data packet length ack_func: The ack callback function if ack is packet is requested. Otherwise set to NULL if no ack required ack_ref: The opaque reference data to be sent back by the ack callback function as a reference for the outgoing packet local: Flag to indicate Local Visibility - nobody shouldn't retransmit it
Data packet struct: BLEMESH_PKT_TYPE_RAW packet: data as it is and mesh will not look into it.
| 1 Byte | 1 Byte | 1 Byte | 1 Byte | 1 Byte | 1 Byte | ......
| 1 Byte | 1-18 Bytes |
Return: Returns result code. This function returns an error code if the packet is unknown or has formating issue etc.
| void blemesh_send_notification | ( | const UINT8 * | data, |
| UINT32 | data_len | ||
| ) |
Send a data packet to host via notofocations.
Should be implemented in the application
Parameters: data: Data packet to send as notification data_len: Length of the data to send
Return: Return: None
| void blemesh_send_p2m_ack | ( | UINT8 | dst_id, |
| const UINT8 * | data, | ||
| UINT32 | data_len, | ||
| UINT8 | ack_ref | ||
| ) |
Mesh core library function to send a point-to-multi-point (P2M) ack packet.
Parameters: dst_id: Destination node ID data: payload data data_len: payload data length ack_ref: Opaque reference data received from the incoming data and sent back as a reference for the ack packet
Return: None
| void blemesh_send_p2p_ack | ( | UINT8 | dst_id, |
| const UINT8 * | data, | ||
| UINT32 | data_len, | ||
| UINT8 | ack_ref | ||
| ) |
Mesh core library function to send a point-to-point (P2P) ack packet.
Parameters: dst_id: Destination node ID data: payload data data_len: payload data length ack_ref: Opaque reference data received from the incoming data and sent back as a reference for the ack packet
Return: None
| BlemeshResultCode blemesh_send_p2p_data | ( | UINT8 | dst_id, |
| UINT32 | dst_node_pkt_cntr, | ||
| const UINT8 * | dst_node_iv, | ||
| const UINT8 * | dst_node_key, | ||
| const UINT8 * | data, | ||
| UINT32 | data_len, | ||
| BlemeshTxAckFunc | ack_func, | ||
| ACKREF | ack_ref | ||
| ) |
Mesh core library function to send a point-to-point data packet over the mesh network.
The data packet could be received directly from a wired interface like in a router, or from a LE link like in a proxy device. After node encryption,
| 1 Byte | 1 Byte | 1-13 Bytes | 4 Bytes |
Parameters: dst_id: Destination node ID dst_node_pkt_cntr: Destination node 4-byte packet counter dst_node_iv: Destination node AES encryption 8-byte IV dst_node_key: Destination node AES encryption 16-byte key data: payload data data_len: payload data length ack_func: The ack callback function if ack is packet is requested. Otherwise set to NULL if no ack required ack_ref: The opaque reference data to be sent back by the ack callback function as a reference for the outgoing packet
Return: Returns result code. This function returns an error code if the packet is unknown or has formating issue etc.
| BlemeshResultCode blemesh_set_node | ( | const BlemeshNodeData * | node_data | ) |
Mesh core library function to authenticate a node by setting the node info.
Parameters: node_data: Pointer to the node data to set for the node.
Return: None Returns the result code to indicate whether the node is authenticated.
| BlemeshResultCode blemesh_start_beaconing | ( | UINT32 | beacon_type, |
| UINT8 * | beacon_adv, | ||
| UINT32 | beacon_adv_len | ||
| ) |
Mesh core library function to enable beaconing when mesh is idle.
This function is to let the mesh start beaconing using the specified adv packet when the device is idle on mesh activity. The beaconing will be stopped when mesh is handling mesh packets, and resumed when it goes back to idle.
This function is useful to enable a device as a proxy device, or enable a mesh device to support iBeacon type applications.
Parameters: beacon_type: Beacon advertisement type as defined in blemesh_util.h beacon_adv: Customized proxy adv packet beacon_adv_len: Customized proxy adv packet length
Return: Returns the result code.
| BlemeshResultCode blemesh_start_mesh | ( | void | ) |
Mesh core library function to start BLE mesh.
This function is to start the BLE mesh function using the specified parameters.
Parameters: None
Return: Returns the result code.
| void blemesh_stop_beaconing | ( | void | ) |
Mesh core library function to stop the beaconing function.
Parameters: None
Return: None
| void blemesh_stop_mesh | ( | void | ) |
Mesh core library function to stop BLE mesh.
This function is to stop the BLE mesh function.
Parameters: None
Return: None
| void blemesh_update_mesh_param | ( | const BlemeshConfig * | config | ) |
Mesh core library function to update the mesh operation parameters.
This function can be called anytime to dynamically update the mesh network operations.
Parameters: config: Pointer to the configuration parameter struct. 0 value member means no change for that member.
Return: Returns the result code.
