Bluetooth Mesh Standalone Updater#
Bluetooth Mesh Standalone Updater.
The Standalone Updater combines the functionality of a local Distribution Server and an external Distribution Client. It uses an Update Client and MBT Client model internally to distribute firmware images to Target Nodes.
The Standalone Updater is not a model per se. It achieves the same functionality as a Distribution Client controlling a Distribution Server via the local loopback interface, but without the ovearhead of any message handling.
Modules#
sl_btmesh_evt_fw_standalone_updater_dist_state_changed
sl_btmesh_evt_fw_standalone_updater_node_failed
Functions#
Macros#
Function Documentation#
sl_btmesh_fw_standalone_updater_init#
sl_status_t sl_btmesh_fw_standalone_updater_init (uint16_t elem_index, uint16_t max_node_list_size)
| [in] | elem_index | Standalone Updater element index (that is, the element index of the Update Client and MBT Client) |
| [in] | max_node_list_size | Maximum number of nodes that can be updated simultaneously |
Initializes the Standalone Updater. Before initializing the Standalone Updater, the Update Client and MBT Client models on the same element must be initialized.
The Distribution Server is not supported on the same element at the same time.
Returns
SL_STATUS_OK if successful. Error code otherwise.
19826 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_deinit#
sl_status_t sl_btmesh_fw_standalone_updater_deinit (uint16_t elem_index)
| [in] | elem_index | Element index |
Deinitializes the Standalone Updater. The corresponding Update Client and MBT Client models can be deinitialized before or after this model.
Returns
SL_STATUS_OK if successful. Error code otherwise.
19839 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_setup#
sl_status_t sl_btmesh_fw_standalone_updater_setup (uint16_t elem_index, uint32_t fw_size, sl_bt_uuid_64_t blob_id, size_t fwid_len, const uint8_t * fwid)
| [in] | elem_index | Element index |
| [in] | fw_size | Firmware image size |
| [in] | blob_id | BLOB ID to use for the image |
| [in] | fwid_len | Length of data in |
| [in] | fwid | Firmware ID of the firmware image |
Set up parameters for a firmware distribution
Returns
SL_STATUS_OK if successful. Error code otherwise.
19854 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_set_metadata#
sl_status_t sl_btmesh_fw_standalone_updater_set_metadata (uint16_t elem_index, size_t metadata_len, const uint8_t * metadata)
| [in] | elem_index | Element index |
| [in] | metadata_len | Length of data in |
| [in] | metadata | Metadata of the image. May be zero-length. |
Set the metadata of the image to be distributed. Should be called after the sl_btmesh_fw_standalone_updater_setup command. Cannot be called after the distribution is started.
Returns
SL_STATUS_OK if successful. Error code otherwise.
19873 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_set_multicast_threshold#
sl_status_t sl_btmesh_fw_standalone_updater_set_multicast_threshold (uint16_t elem_index, uint16_t multicast_threshold)
| [in] | elem_index | Element index |
| [in] | multicast_threshold | This value will be passed to the MBT Client. If the number of servers for any step exceeds or is equal to this number, the group address will be used. Otherwise, servers will be looped through one by one. Value of 0 disables the feature. |
Set the multicast threshold value.
Returns
SL_STATUS_OK if successful. Error code otherwise.
19890 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_add_receiver#
sl_status_t sl_btmesh_fw_standalone_updater_add_receiver (uint16_t elem_index, uint16_t address, uint8_t fw_index)
| [in] | elem_index | Element index |
| [in] | address | Address of the Target Node |
| [in] | fw_index | Index of the firmware on the Target Node to update |
Add a receiver to the distribution
Returns
SL_STATUS_OK if successful. Error code otherwise.
19904 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_delete_all_receivers#
sl_status_t sl_btmesh_fw_standalone_updater_delete_all_receivers (uint16_t elem_index)
| [in] | elem_index | Element index |
Clears the list of receivers
Returns
SL_STATUS_OK if successful. Error code otherwise.
19917 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_start#
sl_status_t sl_btmesh_fw_standalone_updater_start (uint16_t elem_index, uint16_t dist_appkey_index, uint8_t dist_ttl, uint16_t dist_timeout_base, uint8_t transfer_mode, uint16_t group_address, uuid_128 virtual_address)
| [in] | elem_index | Element index |
| [in] | dist_appkey_index | Application key index to use when communicating with the Target Nodes |
| [in] | dist_ttl | The time-to-live value to use when communicating with the Target Nodes. Valid values: 0, range:[2-127] and 255. |
| [in] | dist_timeout_base | The Timeout Base value to use in the firmware image BLOB Transfer and Update Client operations |
| [in] | transfer_mode | 1 = use Push Mode, 2 = use Pull Mode (typically for LPNs) |
| [in] | group_address | Group address to use. Zero to only use unicast. |
| [in] | virtual_address | If the group address is a VA hash, this needs to contain the full virtual address label UUID. Otherwise, the value of this field will be ignored. |
Start the firmware image distribution. The command sl_btmesh_fw_standalone_updater_execute_distribution_step is used to progress through the procedures.
The Receivers List must have been populated via the sl_btmesh_fw_standalone_updater_add_receiver command. The distribution parameters must have been set via the sl_btmesh_fw_standalone_updater_setup and sl_btmesh_fw_standalone_updater_set_metadata commands.
Returns
SL_STATUS_OK if successful. Error code otherwise.
Events
19952 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_execute_distribution_step#
sl_status_t sl_btmesh_fw_standalone_updater_execute_distribution_step (uint16_t elem_index)
| [in] | elem_index | Element index |
Execute the next action for the distribution state machine. Must be repeated by the application if the Target Nodes do not respond in a timely manner. Calling this function sends out the necessary messages to all nodes that have not responded. Note that the distribution step dist_step_transferring_image is executed via the MBT Client API, and thus the command does not need to be called in that state.
Returns
SL_STATUS_OK if successful. Error code otherwise.
19974 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_apply#
sl_status_t sl_btmesh_fw_standalone_updater_apply (uint16_t elem_index)
| [in] | elem_index | Element index |
Enter the apply step after the distribution is in the "verification complete" step. The Standalone Updater can proceed to the apply step immediately after the verification is complete. This state transition exists only for keeping the API as similar as possible to the Distribution Server. The execute_distribution_step command must be called to send out the Update Apply messages.
Returns
SL_STATUS_OK if successful. Error code otherwise.
19990 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_get_state#
sl_status_t sl_btmesh_fw_standalone_updater_get_state (uint16_t elem_index, uint8_t * state, uint16_t * total_nodes, uint16_t * num_active_nodes)
| [in] | elem_index | Element index |
| [out] | state | Current state of the distribution |
| [out] | total_nodes | Number of nodes originally in the Receivers List |
| [out] | num_active_nodes | Number of active nodes |
Get the current state of the distribution process. If an error is returned, the other return values should be ignored.
Returns
SL_STATUS_OK if successful. Error code otherwise.
20005 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_get_node_status_by_index#
sl_status_t sl_btmesh_fw_standalone_updater_get_node_status_by_index (uint16_t elem_index, uint16_t entry_index, uint16_t * address, uint8_t * retrieved_phase, uint8_t * update_server_status, uint8_t * mbt_server_status, uint8_t * transfer_progress, uint8_t * fw_index)
| [in] | elem_index | Element index |
| [in] | entry_index | Node entry index |
| [out] | address | Address of the Update Server |
| [out] | retrieved_phase | Enum sl_btmesh_fw_dist_server_dist_node_phase_t. Phase of the Update Server |
| [out] | update_server_status | Enum sl_btmesh_fw_update_server_update_status_t. Last Update Status message received from the Update Server |
| [out] | mbt_server_status | Enum sl_btmesh_mbt_server_status_t. Last Transfer Status message received from the BLOB Transfer Server |
| [out] | transfer_progress | 0-100, percentage of BLOB Transfer octets delivered and confirmed |
| [out] | fw_index | Index of the firmware being updated |
Retrieve information about the ongoing update on a node
Returns
SL_STATUS_OK if successful. Error code otherwise.
20031 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_get_node_status_by_address#
sl_status_t sl_btmesh_fw_standalone_updater_get_node_status_by_address (uint16_t elem_index, uint16_t node_address, uint16_t * address, uint8_t * retrieved_phase, uint8_t * update_server_status, uint8_t * mbt_server_status, uint8_t * transfer_progress, uint8_t * fw_index)
| [in] | elem_index | Element index |
| [in] | node_address | Node mesh address |
| [out] | address | Address of the Update Server |
| [out] | retrieved_phase | Enum sl_btmesh_fw_dist_server_dist_node_phase_t. Phase of the Update Server |
| [out] | update_server_status | Enum sl_btmesh_fw_update_server_update_status_t. Last Update Status message received from the Update Server |
| [out] | mbt_server_status | Enum sl_btmesh_mbt_server_status_t. Last Transfer Status message received from the BLOB Transfer Server |
| [out] | transfer_progress | 0-100, percentage of BLOB Transfer octets delivered and confirmed |
| [out] | fw_index | Index of the firmware being updated |
Retrieve information about the ongoing update by a node address
Returns
SL_STATUS_OK if successful. Error code otherwise.
20061 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.hsl_btmesh_fw_standalone_updater_cancel#
sl_status_t sl_btmesh_fw_standalone_updater_cancel (uint16_t elem_index)
| [in] | elem_index | Element index |
Cancel a distribution process and clear any information about receivers. If the current distribution was not started, or it is completed or failed, a transition to the idle state will be made immediately. If the receivers need to be informed about the cancellation, a transition to the cancelling state will be made. The sl_btmesh_fw_standalone_updater_execute_distribution_step function should be called to send out the cancellation messages to the receivers.
Returns
SL_STATUS_OK if successful. Error code otherwise.
20085 of file /mnt/raid/workspaces/ws.CkeUHbuKC/overlay/gsdk/protocol/bluetooth/build_release/btmesh_api/mesh_hal_gecko/inc/sl_btmesh_api.h