IV Update Functionality Implementation#

The IV Update procedure described in IV Update Procedure and the IV Index Recovery procedure described in IV Index Recovery Procedure have been implemented in the Bluetooth mesh stack. However, the stack cannot determine how long the remaining sequence numbers might last. The application should determine when a node may run out of sequence numbers and should initiate the IV Update procedure before sequence numbers are exhausted. If a node is absent from a mesh network for a period of time, the application should enable IV index recovery mode to set the IV Index value autonomously.

Secure network beacons are used to carry required information and are transmitted in the primary network. The nodes in the primary network that need to request IV index updates must enable secure network beacon broadcasting. This is usually configured by the provisioner. Note that some Bluetooth mesh mobile applications may not support configuration of the secure network beacon state. The application can call the sl_btmesh_test_set_local_config() API to set the state locally.

The following is a summary of the items that should be included in your system to implement IV Update functionality properly:

  • Secure network beacons enabled on nodes.

  • Code to track time across resets and set the time since the last IV update at booting.

  • Code to determine sequence number exhaustion and trigger an IV index update.

  • Code to check the network IV index and handle IV index recovery mode.

See the Silicon Labs Bluetooth Mesh API Reference Manual for all the BGAPI information.

Tracking Time Across Resets#

The stack uses a timer to calculate the duration required to execute an IV Update or IV Index Recovery procedure. The timer is maintained in RAM and is reset whenever the device resets. This may cause an IV Update or IV Index Recovery procedure to execute later than expected. IV updates would not occur if frequent resets or power cycles are encountered in the application.

The application should track time across resets or power cycles. This is usually done by storing the time in flash memory regularly. The application then should call the following API to set the timer in the stack.

  • sl_btmesh_node_set_iv_update_age()

The stack generates the following event when the IV Update procedure state has changed. If you did not call the sl_btmesh_test_set_ivupdate_state() API to change the state forcefully, this event indicates the IV Update procedure is ongoing (the value of the state is 1) or an IV update has completed (the value of the state is 0). The timer in the stack is reset to 0 when an IV update completes. The application should synchronize the time with the timer on this event when the value of the state is 0.

  • sl_btmesh_evt_node_changed_ivupdate_state_id

Determining Sequence Number Exhaustion#

As described in Sequence Number Increments, the stack uses an interval value to determine sequence number storing and to add to the stored sequence number on a reset. The interval value can be configured by the structure member pstore_write_interval_elem_seq of the __mesh_memory_config variable in sl_btmesh_dcd.c. The value of this setting must be a power of 2. You may decrease the value if the device resets or power cycles regularly.

Every element of a node keeps a sequence number counter. The application should call the following APIs to get the number of remaining sequence numbers or the current sequence number of an element.

  • sl_btmesh_node_get_seq_remaining()

  • sl_btmesh_node_get_element_seqnum()

The maximum value of the sequence number is 0xFFFFFF. The application should know how often messages are transmitted to the network and therefore be able to determine if any element is about to exhaust its available sequence numbers. The application then should request the stack to initiate the IV Update procedure. The application must ensure the available sequence numbers can run for at least 96 hours when initiating the IV Update procedure. This time period can be extended to a safe period due to regular device resets or irregularity of message transmission.

Initiating IV Update#

The application should call the following API to request the stack to initiate the IV Update procedure.

  • sl_btmesh_node_request_ivupdate()

The sl_btmesh_evt_node_changed_ivupdate_state_id event is generated when the IV Update procedure has started or completed. The application can use this event to monitor the IV Update procedure state and the current IV index.

Recovering IV Index#

The application should call the following API to enable the IV index recovery mode.

  • sl_btmesh_node_set_ivrecovery_mode()

The IV index recovery mode should be enabled when the node may have missed IV index updates and need to perform the IV Index Recovery procedure. In this case, the following event is generated. The application should check the received network IV index and the current IV index that come with the event and enable the IV index recovery mode only when the received network IV index is greater than the current IV index and is equal to or less than the current IV index + 42.

  • sl_btmesh_evt_node_ivrecovery_needed_id

If a real time clock is available in the device, the application can also check the IV index increment with the time elapsed. The time since the last IV update should be greater than the IV index increment multiplied by 192 hours minus 96 hours.

The sl_btmesh_evt_node_changed_ivupdate_state_id event is generated when the IV Index Recovery procedure has completed. The application should disable the IV index recovery mode on this event.

IV Update Testing#

There are time limits on the IV Update and IV Index Recovery procedures so testing on Bluetooth mesh applications would be inefficient. The IV Update test mode removes these time limits. The application can call the following API to enable the IV Update test mode.

  • sl_btmesh_test_set_ivupdate_test_mode()

The following APIs may be useful when testing the IV Update functionality.

  • sl_btmesh_test_set_ivupdate_state(): forces the node to transition to the IV Update in Progress state or to the Normal Operation state.

  • sl_btmesh_test_set_iv_index(): changes the node's current IV index to any value.

  • sl_btmesh_test_set_local_config(): changes a state of the Configuration Server model in the node. With the sl_btmesh_node_beacon parameter, enables or disables Secure Network Beacons broadcasting.

  • sl_btmesh_node_set_beacon_reporting(): enables reporting to monitor secure network beacons. This can be used to diagnose the network IV index and the IV Update procedure state.