michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Bluetooth: Mesh: Fix line width to 100 in mesh docs

Browse source 
From Codying Style guideline:
https://docs.zephyrproject.org/latest/contribute/guidelines.html#coding-style

`The line length is 100 columns or fewer. In the documentation, longer
lines for URL references are an allowed exception.`

Signed-off-by: Pavel Vasilyev <pavel.vasilyev@nordicsemi.no>
This commit is contained in:
Pavel Vasilyev 2023-09-12 10:32:24 +02:00 • committed by Carles Cufí
commit b2c163e108
23 changed files with 1082 additions and 466 deletions
Download patch file Download diff file Expand all files Collapse all files

109
doc/connectivity/bluetooth/api/mesh/blob.rst
View file

@ -3,11 +3,25 @@
BLOB Transfer models
####################
The Binary Large Object (BLOB) Transfer models implement the Bluetooth Mesh Binary Large Object Transfer Model specification version 1.0 and provide functionality for sending large binary objects from a single source to many Target nodes over the Bluetooth mesh network. It is the underlying transport method for the :ref:`bluetooth_mesh_dfu`, but may be used for other object transfer purposes. The implementation is in experimental state.
The Binary Large Object (BLOB) Transfer models implement the Bluetooth Mesh Binary Large Object
Transfer Model specification version 1.0 and provide functionality for sending large binary objects
from a single source to many Target nodes over the Bluetooth mesh network. It is the underlying
transport method for the :ref:`bluetooth_mesh_dfu`, but may be used for other object transfer
purposes. The implementation is in experimental state.
The BLOB Transfer models support transfers of continuous binary objects of up to 4 GB (2 \ :sup:`32` bytes). The BLOB transfer protocol has built-in recovery procedures for packet losses, and sets up checkpoints to ensure that all targets have received all the data before moving on. Data transfer order is not guaranteed.
The BLOB Transfer models support transfers of continuous binary objects of up to 4 GB (2 \ :sup:`32`
bytes). The BLOB transfer protocol has built-in recovery procedures for packet losses, and sets up
checkpoints to ensure that all targets have received all the data before moving on. Data transfer
order is not guaranteed.
BLOB transfers are constrained by the transfer speed and reliability of the underlying mesh network. Under ideal conditions, the BLOBs can be transferred at a rate of up to 1 kbps, allowing a 100 kB BLOB to be transferred in 10-15 minutes. However, network conditions, transfer capabilities and other limiting factors can easily degrade the data rate by several orders of magnitude. Tuning the parameters of the transfer according to the application and network configuration, as well as scheduling it to periods with low network traffic, will offer significant improvements on the speed and reliability of the protocol. However, achieving transfer rates close to the ideal rate is unlikely in actual deployments.
BLOB transfers are constrained by the transfer speed and reliability of the underlying mesh network.
Under ideal conditions, the BLOBs can be transferred at a rate of up to 1 kbps, allowing a 100 kB
BLOB to be transferred in 10-15 minutes. However, network conditions, transfer capabilities and
other limiting factors can easily degrade the data rate by several orders of magnitude. Tuning the
parameters of the transfer according to the application and network configuration, as well as
scheduling it to periods with low network traffic, will offer significant improvements on the speed
and reliability of the protocol. However, achieving transfer rates close to the ideal rate is
unlikely in actual deployments.
There are two BLOB Transfer models:
@ -17,7 +31,8 @@ There are two BLOB Transfer models:
blob_srv
blob_cli
The BLOB Transfer Client is instantiated on the sender node, and the BLOB Transfer Server is instantiated on the receiver nodes.
The BLOB Transfer Client is instantiated on the sender node, and the BLOB Transfer Server is
instantiated on the receiver nodes.
Concepts
********
@ -28,23 +43,44 @@ The BLOB transfer protocol introduces several new concepts to implement the BLOB
BLOBs
=====
BLOBs are binary objects up to 4 GB in size, that can contain any data the application would like to transfer through the mesh network. The BLOBs are continuous data objects, divided into blocks and chunks to make the transfers reliable and easy to process. No limitations are put on the contents or structure of the BLOB, and applications are free to define any encoding or compression they'd like on the data itself.
BLOBs are binary objects up to 4 GB in size, that can contain any data the application would like to
transfer through the mesh network. The BLOBs are continuous data objects, divided into blocks and
chunks to make the transfers reliable and easy to process. No limitations are put on the contents or
structure of the BLOB, and applications are free to define any encoding or compression they'd like
on the data itself.
The BLOB transfer protocol does not provide any built-in integrity checks, encryption or authentication of the BLOB data. However, the underlying encryption of the Bluetooth mesh protocol provides data integrity checks and protects the contents of the BLOB from third parties using network and application level encryption.
The BLOB transfer protocol does not provide any built-in integrity checks, encryption or
authentication of the BLOB data. However, the underlying encryption of the Bluetooth mesh protocol
provides data integrity checks and protects the contents of the BLOB from third parties using
network and application level encryption.
Blocks
------
The binary objects are divided into blocks, typically from a few hundred to several thousand bytes in size. Each block is transmitted separately, and the BLOB Transfer Client ensures that all BLOB Transfer Servers have received the full block before moving on to the next. The block size is determined by the transfer's ``block_size_log`` parameter, and is the same for all blocks in the transfer except the last, which may be smaller. For a BLOB stored in flash memory, the block size is typically a multiple of the flash page size of the Target devices.
The binary objects are divided into blocks, typically from a few hundred to several thousand bytes
in size. Each block is transmitted separately, and the BLOB Transfer Client ensures that all BLOB
Transfer Servers have received the full block before moving on to the next. The block size is
determined by the transfer's ``block_size_log`` parameter, and is the same for all blocks in the
transfer except the last, which may be smaller. For a BLOB stored in flash memory, the block size is
typically a multiple of the flash page size of the Target devices.
Chunks
------
Each block is divided into chunks. A chunk is the smallest data unit in the BLOB transfer, and must fit inside a single Bluetooth mesh access message excluding the opcode (379 bytes or less). The mechanism for transferring chunks depends on the transfer mode.
Each block is divided into chunks. A chunk is the smallest data unit in the BLOB transfer, and must
fit inside a single Bluetooth mesh access message excluding the opcode (379 bytes or less). The
mechanism for transferring chunks depends on the transfer mode.
When operating in Push BLOB Transfer Mode, the chunks are sent as unacknowledged packets from the BLOB Transfer Client to all targeted BLOB Transfer Servers. Once all chunks in a block have been sent, the BLOB Transfer Client asks each BLOB Transfer Server if they're missing any chunks, and resends them. This is repeated until all BLOB Transfer Servers have received all chunks, or the BLOB Transfer Client gives up.
When operating in Push BLOB Transfer Mode, the chunks are sent as unacknowledged packets from the
BLOB Transfer Client to all targeted BLOB Transfer Servers. Once all chunks in a block have been
sent, the BLOB Transfer Client asks each BLOB Transfer Server if they're missing any chunks, and
resends them. This is repeated until all BLOB Transfer Servers have received all chunks, or the BLOB
Transfer Client gives up.
When operating in Pull BLOB Transfer Mode, the BLOB Transfer Server will request a small number of chunks from the BLOB Transfer Client at a time, and wait for the BLOB Transfer Client to send them before requesting more chunks. This repeats until all chunks have been transferred, or the BLOB Transfer Server gives up.
When operating in Pull BLOB Transfer Mode, the BLOB Transfer Server will request a small number of
chunks from the BLOB Transfer Client at a time, and wait for the BLOB Transfer Client to send them
before requesting more chunks. This repeats until all chunks have been transferred, or the BLOB
Transfer Server gives up.
Read more about the transfer modes in :ref:`bluetooth_mesh_blob_transfer_modes` section.
@ -53,16 +89,31 @@ Read more about the transfer modes in :ref:`bluetooth_mesh_blob_transfer_modes`
BLOB streams
============
In the BLOB Transfer models' APIs, the BLOB data handling is separated from the high-level transfer handling. This split allows reuse of different BLOB storage and transfer strategies for different applications. While the high level transfer is controlled directly by the application, the BLOB data itself is accessed through a *BLOB stream*.
In the BLOB Transfer models' APIs, the BLOB data handling is separated from the high-level transfer
handling. This split allows reuse of different BLOB storage and transfer strategies for different
applications. While the high level transfer is controlled directly by the application, the BLOB data
itself is accessed through a *BLOB stream*.
The BLOB stream is comparable to a standard library file stream. Through opening, closing, reading and writing, the BLOB Transfer model gets full access to the BLOB data, whether it's kept in flash, RAM, or on a peripheral. The BLOB stream is opened with an access mode (read or write) before it's used, and the BLOB Transfer models will move around inside the BLOB's data in blocks and chunks, using the BLOB stream as an interface.
The BLOB stream is comparable to a standard library file stream. Through opening, closing, reading
and writing, the BLOB Transfer model gets full access to the BLOB data, whether it's kept in flash,
RAM, or on a peripheral. The BLOB stream is opened with an access mode (read or write) before it's
used, and the BLOB Transfer models will move around inside the BLOB's data in blocks and chunks,
using the BLOB stream as an interface.
Interaction
-----------
Before the BLOB is read or written, the stream is opened by calling its :c:member:`open <bt_mesh_blob_io.open>` callback. When used with a BLOB Transfer Server, the BLOB stream is always opened in write mode, and when used with a BLOB Transfer Client, it's always opened in read mode.
Before the BLOB is read or written, the stream is opened by calling its
:c:member:`open <bt_mesh_blob_io.open>` callback. When used with a BLOB Transfer Server, the BLOB
stream is always opened in write mode, and when used with a BLOB Transfer Client, it's always opened
in read mode.
For each block in the BLOB, the BLOB Transfer model starts by calling :c:member:`block_start <bt_mesh_blob_io.block_start>`. Then, depending on the access mode, the BLOB stream's :c:member:`wr <bt_mesh_blob_io.wr>` or :c:member:`rd <bt_mesh_blob_io.rd>` callback is called repeatedly to move data to or from the BLOB. When the model is done processing the block, it calls :c:member:`block_end <bt_mesh_blob_io.block_end>`. When the transfer is complete, the BLOB stream is closed by calling :c:member:`close <bt_mesh_blob_io.close>`.
For each block in the BLOB, the BLOB Transfer model starts by calling
:c:member:`block_start <bt_mesh_blob_io.block_start>`. Then, depending on the access mode, the BLOB
stream's :c:member:`wr <bt_mesh_blob_io.wr>` or :c:member:`rd <bt_mesh_blob_io.rd>` callback is
called repeatedly to move data to or from the BLOB. When the model is done processing the block, it
calls :c:member:`block_end <bt_mesh_blob_io.block_end>`. When the transfer is complete, the BLOB
stream is closed by calling :c:member:`close <bt_mesh_blob_io.close>`.
Implementations
---------------
@ -78,28 +129,41 @@ The application may implement their own BLOB stream, or use the implementations
Transfer capabilities
=====================
Each BLOB Transfer Server may have different transfer capabilities. The transfer capabilities of each device are controlled through the following configuration options:
Each BLOB Transfer Server may have different transfer capabilities. The transfer capabilities of
each device are controlled through the following configuration options:
* :kconfig:option:`CONFIG_BT_MESH_BLOB_SIZE_MAX`
* :kconfig:option:`CONFIG_BT_MESH_BLOB_BLOCK_SIZE_MIN`
* :kconfig:option:`CONFIG_BT_MESH_BLOB_BLOCK_SIZE_MAX`
* :kconfig:option:`CONFIG_BT_MESH_BLOB_CHUNK_COUNT_MAX`
The :kconfig:option:`CONFIG_BT_MESH_BLOB_CHUNK_COUNT_MAX` option is also used by the BLOB Transfer Client and affects memory consumption by the BLOB Transfer Client model structure.
The :kconfig:option:`CONFIG_BT_MESH_BLOB_CHUNK_COUNT_MAX` option is also used by the BLOB Transfer
Client and affects memory consumption by the BLOB Transfer Client model structure.
To ensure that the transfer can be received by as many servers as possible, the BLOB Transfer Client can retrieve the capabilities of each BLOB Transfer Server before starting the transfer. The client will transfer the BLOB with the highest possible block and chunk size.
To ensure that the transfer can be received by as many servers as possible, the BLOB Transfer Client
can retrieve the capabilities of each BLOB Transfer Server before starting the transfer. The client
will transfer the BLOB with the highest possible block and chunk size.
.. _bluetooth_mesh_blob_transfer_modes:
Transfer modes
==============
BLOBs can be transferred using two transfer modes, Push BLOB Transfer Mode and Pull BLOB Transfer Mode.
In most cases, the transfer should be conducted in Push BLOB Transfer Mode.
BLOBs can be transferred using two transfer modes, Push BLOB Transfer Mode and Pull BLOB Transfer
Mode. In most cases, the transfer should be conducted in Push BLOB Transfer Mode.
In Push BLOB Transfer Mode, the send rate is controlled by the BLOB Transfer Client, which will push all the chunks of each block without any high level flow control. Push BLOB Transfer Mode supports any number of Target nodes, and should be the default transfer mode.
In Push BLOB Transfer Mode, the send rate is controlled by the BLOB Transfer Client, which will push
all the chunks of each block without any high level flow control. Push BLOB Transfer Mode supports
any number of Target nodes, and should be the default transfer mode.
In Pull BLOB Transfer Mode, the BLOB Transfer Server will "pull" the chunks from the BLOB Transfer Client at its own rate. Pull BLOB Transfer Mode can be conducted with multiple Target nodes, and is intended for transferring BLOBs to Target nodes acting as :ref:`bluetooth_mesh_lpn`. When operating in Pull BLOB Transfer Mode, the BLOB Transfer Server will request chunks from the BLOB Transfer Client in small batches, and wait for them all to arrive before requesting more chunks. This process is repeated until the BLOB Transfer Server has received all chunks in a block. Then, the BLOB Transfer Client starts the next block, and the BLOB Transfer Server requests all chunks of that block.
In Pull BLOB Transfer Mode, the BLOB Transfer Server will "pull" the chunks from the BLOB Transfer
Client at its own rate. Pull BLOB Transfer Mode can be conducted with multiple Target nodes, and is
intended for transferring BLOBs to Target nodes acting as :ref:`bluetooth_mesh_lpn`. When operating
in Pull BLOB Transfer Mode, the BLOB Transfer Server will request chunks from the BLOB Transfer
Client in small batches, and wait for them all to arrive before requesting more chunks. This process
is repeated until the BLOB Transfer Server has received all chunks in a block. Then, the BLOB
Transfer Client starts the next block, and the BLOB Transfer Server requests all chunks of that
block.
.. _bluetooth_mesh_blob_timeout:
@ -107,7 +171,8 @@ In Pull BLOB Transfer Mode, the BLOB Transfer Server will "pull" the chunks from
Transfer timeout
================
The timeout of the BLOB transfer is based on a Timeout Base value. Both client and server use the same Timeout Base value, but they calculate timeout differently.
The timeout of the BLOB transfer is based on a Timeout Base value. Both client and server use the
same Timeout Base value, but they calculate timeout differently.
The BLOB Transfer Server uses the following formula to calculate the BLOB transfer timeout::

54
doc/connectivity/bluetooth/api/mesh/blob_cli.rst
View file

@ -3,7 +3,9 @@
BLOB Transfer Client
####################
The Binary Large Object (BLOB) Transfer Client is the sender of the BLOB transfer. It supports sending BLOBs of any size to any number of Target nodes, in both Push BLOB Transfer Mode and Pull BLOB Transfer Mode.
The Binary Large Object (BLOB) Transfer Client is the sender of the BLOB transfer. It supports
sending BLOBs of any size to any number of Target nodes, in both Push BLOB Transfer Mode and Pull
BLOB Transfer Mode.
Usage
*****
@ -30,7 +32,10 @@ The BLOB Transfer Client is instantiated on an element with a set of event handl
Transfer context
================
Both the transfer capabilities retrieval procedure and the BLOB transfer uses an instance of a :c:type:`bt_mesh_blob_cli_inputs` to determine how to perform the transfer. The BLOB Transfer Client Inputs structure must at least be initialized with a list of targets, an application key and a time to live (TTL) value before it is used in a procedure:
Both the transfer capabilities retrieval procedure and the BLOB transfer uses an instance of a
:c:type:`bt_mesh_blob_cli_inputs` to determine how to perform the transfer. The BLOB Transfer Client
Inputs structure must at least be initialized with a list of targets, an application key and a time
to live (TTL) value before it is used in a procedure:
.. code-block:: c
@ -55,14 +60,28 @@ Note that all BLOB Transfer Servers in the transfer must be bound to the chosen
Group address
-------------
The application may additionally specify a group address in the context structure. If the group is not :c:macro:`BT_MESH_ADDR_UNASSIGNED`, the messages in the transfer will be sent to the group address, instead of being sent individually to each Target node. Mesh Manager must ensure that all Target nodes having the BLOB Transfer Server model subscribe to this group address.
The application may additionally specify a group address in the context structure. If the group is
not :c:macro:`BT_MESH_ADDR_UNASSIGNED`, the messages in the transfer will be sent to the group
address, instead of being sent individually to each Target node. Mesh Manager must ensure that all
Target nodes having the BLOB Transfer Server model subscribe to this group address.
Using group addresses for transferring the BLOBs can generally increase the transfer speed, as the BLOB Transfer Client sends each message to all Target nodes at the same time. However, sending large, segmented messages to group addresses in Bluetooth mesh is generally less reliable than sending them to unicast addresses, as there is no transport layer acknowledgment mechanism for groups. This can lead to longer recovery periods at the end of each block, and increases the risk of losing Target nodes. Using group addresses for BLOB transfers will generally only pay off if the list of Target nodes is extensive, and the effectiveness of each addressing strategy will vary heavily between different deployments and the size of the chunks.
Using group addresses for transferring the BLOBs can generally increase the transfer speed, as the
BLOB Transfer Client sends each message to all Target nodes at the same time. However, sending
large, segmented messages to group addresses in Bluetooth mesh is generally less reliable than
sending them to unicast addresses, as there is no transport layer acknowledgment mechanism for
groups. This can lead to longer recovery periods at the end of each block, and increases the risk of
losing Target nodes. Using group addresses for BLOB transfers will generally only pay off if the
list of Target nodes is extensive, and the effectiveness of each addressing strategy will vary
heavily between different deployments and the size of the chunks.
Transfer timeout
----------------
If a Target node fails to respond to an acknowledged message within the BLOB Transfer Client's time limit, the Target node is dropped from the transfer. The application can reduce the chances of this by giving the BLOB Transfer Client extra time through the context structure. The extra time may be set in 10-second increments, up to 182 hours, in addition to the base time of 20 seconds. The wait time scales automatically with the transfer TTL.
If a Target node fails to respond to an acknowledged message within the BLOB Transfer Client's time
limit, the Target node is dropped from the transfer. The application can reduce the chances of this
by giving the BLOB Transfer Client extra time through the context structure. The extra time may be
set in 10-second increments, up to 182 hours, in addition to the base time of 20 seconds. The wait
time scales automatically with the transfer TTL.
Note that the BLOB Transfer Client only moves forward with the transfer in following cases:
@ -75,18 +94,33 @@ Increasing the wait time will increase this delay.
BLOB transfer capabilities retrieval
====================================
It is generally recommended to retrieve BLOB transfer capabilities before starting a transfer. The procedure populates the transfer capabilities from all Target nodes with the most liberal set of parameters that allows all Target nodes to participate in the transfer. Any Target nodes that fail to respond, or respond with incompatible transfer parameters, will be dropped.
It is generally recommended to retrieve BLOB transfer capabilities before starting a transfer. The
procedure populates the transfer capabilities from all Target nodes with the most liberal set of
parameters that allows all Target nodes to participate in the transfer. Any Target nodes that fail
to respond, or respond with incompatible transfer parameters, will be dropped.
Target nodes are prioritized according to their order in the list of Target nodes. If a Target node is found to be incompatible with any of the previous Target nodes, for instance by reporting a non-overlapping block size range, it will be dropped. Lost Target nodes will be reported through the :c:member:`lost_target <bt_mesh_blob_cli_cb.lost_target>` callback.
Target nodes are prioritized according to their order in the list of Target nodes. If a Target node
is found to be incompatible with any of the previous Target nodes, for instance by reporting a
non-overlapping block size range, it will be dropped. Lost Target nodes will be reported through the
:c:member:`lost_target <bt_mesh_blob_cli_cb.lost_target>` callback.
The end of the procedure is signalled through the :c:member:`caps <bt_mesh_blob_cli_cb.caps>` callback, and the resulting capabilities can be used to determine the block and chunk sizes required for the BLOB transfer.
The end of the procedure is signalled through the :c:member:`caps <bt_mesh_blob_cli_cb.caps>`
callback, and the resulting capabilities can be used to determine the block and chunk sizes required
for the BLOB transfer.
BLOB transfer
=============
The BLOB transfer is started by calling :c:func:`bt_mesh_blob_cli_send` function, which (in addition to the aforementioned transfer inputs) requires a set of transfer parameters and a BLOB stream instance. The transfer parameters include the 64-bit BLOB ID, the BLOB size, the transfer mode, the block size in logarithmic representation and the chunk size. The BLOB ID is application defined, but must match the BLOB ID the BLOB Transfer Servers have been started with.
The BLOB transfer is started by calling :c:func:`bt_mesh_blob_cli_send` function, which (in addition
to the aforementioned transfer inputs) requires a set of transfer parameters and a BLOB stream
instance. The transfer parameters include the 64-bit BLOB ID, the BLOB size, the transfer mode, the
block size in logarithmic representation and the chunk size. The BLOB ID is application defined, but
must match the BLOB ID the BLOB Transfer Servers have been started with.
The transfer runs until it either completes successfully for at least one Target node, or it is cancelled. The end of the transfer is communicated to the application through the :c:member:`end <bt_mesh_blob_cli_cb.end>` callback. Lost Target nodes will be reported through the :c:member:`lost_target <bt_mesh_blob_cli_cb.lost_target>` callback.
The transfer runs until it either completes successfully for at least one Target node, or it is
cancelled. The end of the transfer is communicated to the application through the :c:member:`end
<bt_mesh_blob_cli_cb.end>` callback. Lost Target nodes will be reported through the
:c:member:`lost_target <bt_mesh_blob_cli_cb.lost_target>` callback.
API reference
*************

17
doc/connectivity/bluetooth/api/mesh/blob_flash.rst
View file

@ -3,21 +3,30 @@
BLOB Flash
##########
The BLOB Flash Readers and Writers implement BLOB reading to and writing from flash partitions defined in the :ref:`flash map <flash_map_api>`.
The BLOB Flash Readers and Writers implement BLOB reading to and writing from flash partitions
defined in the :ref:`flash map <flash_map_api>`.
BLOB Flash Reader
*****************
The BLOB Flash Reader interacts with the BLOB Transfer Client to read BLOB data directly from flash. It must be initialized by calling :c:func:`bt_mesh_blob_flash_rd_init` before being passed to the BLOB Transfer Client. Each BLOB Flash Reader only supports one transfer at the time.
The BLOB Flash Reader interacts with the BLOB Transfer Client to read BLOB data directly from flash.
It must be initialized by calling :c:func:`bt_mesh_blob_flash_rd_init` before being passed to the
BLOB Transfer Client. Each BLOB Flash Reader only supports one transfer at the time.
BLOB Flash Writer
*****************
The BLOB Flash Writer interacts with the BLOB Transfer Server to write BLOB data directly to flash. It must be initialized by calling :c:func:`bt_mesh_blob_flash_rd_init` before being passed to the BLOB Transfer Server. Each BLOB Flash Writer only supports one transfer at the time, and requires a block size that is a multiple of the flash page size. If a transfer is started with a block size lower than the flash page size, the transfer will be rejected.
The BLOB Flash Writer interacts with the BLOB Transfer Server to write BLOB data directly to flash.
It must be initialized by calling :c:func:`bt_mesh_blob_flash_rd_init` before being passed to the
BLOB Transfer Server. Each BLOB Flash Writer only supports one transfer at the time, and requires a
block size that is a multiple of the flash page size. If a transfer is started with a block size
lower than the flash page size, the transfer will be rejected.
The BLOB Flash Writer copies chunk data into a buffer to accommodate chunks that are unaligned with the flash write block size. The buffer data is padded with ``0xff`` if either the start or length of the chunk is unaligned.
The BLOB Flash Writer copies chunk data into a buffer to accommodate chunks that are unaligned with
the flash write block size. The buffer data is padded with ``0xff`` if either the start or length of
the chunk is unaligned.
API Reference
*************

52
doc/connectivity/bluetooth/api/mesh/blob_srv.rst
View file

@ -3,14 +3,22 @@
BLOB Transfer Server
####################
The Binary Large Object (BLOB) Transfer Server model implements reliable receiving of large binary objects. It serves as the backend of the :ref:`bluetooth_mesh_dfu_srv`, but can also be used for receiving other binary images.
The Binary Large Object (BLOB) Transfer Server model implements reliable receiving of large binary
objects. It serves as the backend of the :ref:`bluetooth_mesh_dfu_srv`, but can also be used for
receiving other binary images.
BLOBs
*****
As described in :ref:`bluetooth_mesh_blob`, the binary objects transferred by the BLOB Transfer models are divided into blocks, which are divided into chunks. As the transfer is controlled by the BLOB Transfer Client model, the BLOB Transfer Server must allow blocks to come in any order. The chunks within a block may also come in any order, but all chunks in a block must be received before the next block is started.
As described in :ref:`bluetooth_mesh_blob`, the binary objects transferred by the BLOB Transfer
models are divided into blocks, which are divided into chunks. As the transfer is controlled by the
BLOB Transfer Client model, the BLOB Transfer Server must allow blocks to come in any order. The
chunks within a block may also come in any order, but all chunks in a block must be received before
the next block is started.
The BLOB Transfer Server keeps track of the received blocks and chunks, and will process each block and chunk only once. The BLOB Transfer Server also ensures that any missing chunks are resent by the BLOB Transfer Client.
The BLOB Transfer Server keeps track of the received blocks and chunks, and will process each block
and chunk only once. The BLOB Transfer Server also ensures that any missing chunks are resent by the
BLOB Transfer Client.
Usage
*****
@ -31,9 +39,16 @@ The BLOB Transfer Server is instantiated on an element with a set of event handl
BT_MESH_MODEL_BLOB_SRV(&blob_srv),
};
A BLOB Transfer Server is capable of receiving a single BLOB transfer at a time. Before the BLOB Transfer Server can receive a transfer, it must be prepared by the user. The transfer ID must be passed to the BLOB Transfer Server through the :c:func:`bt_mesh_blob_srv_recv` function before the transfer is started by the BLOB Transfer Client. The ID must be shared between the BLOB Transfer Client and the BLOB Transfer Server through some higher level procedure, like a vendor specific transfer management model.
A BLOB Transfer Server is capable of receiving a single BLOB transfer at a time. Before the BLOB
Transfer Server can receive a transfer, it must be prepared by the user. The transfer ID must be
passed to the BLOB Transfer Server through the :c:func:`bt_mesh_blob_srv_recv` function before the
transfer is started by the BLOB Transfer Client. The ID must be shared between the BLOB Transfer
Client and the BLOB Transfer Server through some higher level procedure, like a vendor specific
transfer management model.
Once the transfer has been set up on the BLOB Transfer Server, it's ready for receiving the BLOB. The application is notified of the transfer progress through the event handler callbacks, and the BLOB data is sent to the BLOB stream.
Once the transfer has been set up on the BLOB Transfer Server, it's ready for receiving the BLOB.
The application is notified of the transfer progress through the event handler callbacks, and the
BLOB data is sent to the BLOB stream.
The interaction between the BLOB Transfer Server, BLOB stream and application is shown below:
@ -46,21 +61,36 @@ The interaction between the BLOB Transfer Server, BLOB stream and application is
Transfer suspension
*******************
The BLOB Transfer Server keeps a running timer during the transfer, that is reset on every received message. If the BLOB Transfer Client does not send a message before the transfer timer expires, the transfer is suspended by the BLOB Transfer Server.
The BLOB Transfer Server keeps a running timer during the transfer, that is reset on every received
message. If the BLOB Transfer Client does not send a message before the transfer timer expires, the
transfer is suspended by the BLOB Transfer Server.
The BLOB Transfer Server notifies the user of the suspension by calling the :c:member:`suspended <bt_mesh_blob_srv_cb.suspended>` callback. If the BLOB Transfer Server is in the middle of receiving a block, this block is discarded.
The BLOB Transfer Server notifies the user of the suspension by calling the :c:member:`suspended
<bt_mesh_blob_srv_cb.suspended>` callback. If the BLOB Transfer Server is in the middle of receiving
a block, this block is discarded.
The BLOB Transfer Client may resume a suspended transfer by starting a new block transfer. The BLOB Transfer Server notifies the user by calling the :c:member:`resume <bt_mesh_blob_srv_cb.resume>` callback.
The BLOB Transfer Client may resume a suspended transfer by starting a new block transfer. The BLOB
Transfer Server notifies the user by calling the :c:member:`resume <bt_mesh_blob_srv_cb.resume>`
callback.
Transfer recovery
*****************
The state of the BLOB transfer is stored persistently. If a reboot occurs, the BLOB Transfer Server will attempt to recover the transfer. When the Bluetooth mesh subsystem is started (for instance by calling :c:func:`bt_mesh_init`), the BLOB Transfer Server will check for aborted transfers, and call the :c:member:`recover <bt_mesh_blob_srv_cb.recover>` callback if there is any. In the recover callback, the user must provide a BLOB stream to use for the rest of the transfer. If the recover callback doesn't return successfully or does not provide a BLOB stream, the transfer is abandoned. If no recover callback is implemented, transfers are always abandoned after a reboot.
The state of the BLOB transfer is stored persistently. If a reboot occurs, the BLOB Transfer Server
will attempt to recover the transfer. When the Bluetooth mesh subsystem is started (for instance by
calling :c:func:`bt_mesh_init`), the BLOB Transfer Server will check for aborted transfers, and call
the :c:member:`recover <bt_mesh_blob_srv_cb.recover>` callback if there is any. In the recover
callback, the user must provide a BLOB stream to use for the rest of the transfer. If the recover
callback doesn't return successfully or does not provide a BLOB stream, the transfer is abandoned.
If no recover callback is implemented, transfers are always abandoned after a reboot.
After a transfer is successfully recovered, the BLOB Transfer Server enters the suspended state. It will stay suspended until the BLOB Transfer Client resumes the transfer, or the user cancels it.
After a transfer is successfully recovered, the BLOB Transfer Server enters the suspended state. It
will stay suspended until the BLOB Transfer Client resumes the transfer, or the user cancels it.
.. note::
The BLOB Transfer Client sending the transfer must support transfer recovery for the transfer to complete. If the BLOB Transfer Client has already given up the transfer, the BLOB Transfer Server will stay suspended until the application calls :c:func:`bt_mesh_blob_srv_cancel`.
The BLOB Transfer Client sending the transfer must support transfer recovery for the transfer to
complete. If the BLOB Transfer Client has already given up the transfer, the BLOB Transfer Server
will stay suspended until the application calls :c:func:`bt_mesh_blob_srv_cancel`.
API reference
*************

25
doc/connectivity/bluetooth/api/mesh/dfd_srv.rst
View file

@ -3,20 +3,35 @@
Firmware Distribution Server
############################
The Firmware Distribution Server model implements the Distributor role for the :ref:`bluetooth_mesh_dfu` subsystem. It extends the :ref:`bluetooth_mesh_blob_srv`, which it uses to receive the firmware image binary from the Initiator node. It also instantiates a :ref:`bluetooth_mesh_dfu_cli`, which it uses to distribute firmware updates throughout the mesh network.
The Firmware Distribution Server model implements the Distributor role for the
:ref:`bluetooth_mesh_dfu` subsystem. It extends the :ref:`bluetooth_mesh_blob_srv`, which it uses to
receive the firmware image binary from the Initiator node. It also instantiates a
:ref:`bluetooth_mesh_dfu_cli`, which it uses to distribute firmware updates throughout the mesh
network.
.. note::
Currently, the Firmware Distribution Server supports out-of-band (OOB) retrieval of firmware images over SMP service only.
Currently, the Firmware Distribution Server supports out-of-band (OOB) retrieval of firmware
images over SMP service only.
The Firmware Distribution Server does not have an API of its own, but relies on a Firmware Distribution Client model on a different device to give it information and trigger image distribution and upload.
The Firmware Distribution Server does not have an API of its own, but relies on a Firmware
Distribution Client model on a different device to give it information and trigger image
distribution and upload.
Firmware slots
**************
The Firmware Distribution Server is capable of storing multiple firmware images for distribution. Each slot contains a separate firmware image with metadata, and can be distributed to other mesh nodes in the network in any order. The contents, format and size of the firmware images are vendor specific, and may contain data from other vendors. The application should never attempt to execute or modify them.
The Firmware Distribution Server is capable of storing multiple firmware images for distribution.
Each slot contains a separate firmware image with metadata, and can be distributed to other mesh
nodes in the network in any order. The contents, format and size of the firmware images are vendor
specific, and may contain data from other vendors. The application should never attempt to execute
or modify them.
The slots are managed remotely by a Firmware Distribution Client, which can both upload new slots and delete old ones. The application is notified of changes to the slots through the Firmware Distribution Server's callbacks (:cpp:type:`bt_mesh_fd_srv_cb`). While the metadata for each firmware slot is stored internally, the application must provide a :ref:`bluetooth_mesh_blob_stream` for reading and writing the firmware image.
The slots are managed remotely by a Firmware Distribution Client, which can both upload new slots
and delete old ones. The application is notified of changes to the slots through the Firmware
Distribution Server's callbacks (:cpp:type:`bt_mesh_fd_srv_cb`). While the metadata for each
firmware slot is stored internally, the application must provide a :ref:`bluetooth_mesh_blob_stream`
for reading and writing the firmware image.
API reference
*************

238
doc/connectivity/bluetooth/api/mesh/dfu.rst
View file

@ -3,11 +3,17 @@
Device Firmware Update (DFU)
############################
Bluetooth mesh supports the distribution of firmware images across a mesh network. The Bluetooth mesh DFU subsystem implements the Bluetooth Mesh Device Firmware Update Model specification version 1.0. The implementation is in experimental state.
Bluetooth mesh supports the distribution of firmware images across a mesh network. The Bluetooth
mesh DFU subsystem implements the Bluetooth Mesh Device Firmware Update Model specification version
1.0. The implementation is in experimental state.
Bluetooth mesh DFU implements a distribution mechanism for firmware images, and does not put any restrictions on the size, format or usage of the images. The primary design goal of the subsystem is to provide the qualifiable parts of the Bluetooth mesh DFU specification, and leave the usage, firmware validation and deployment to the application.
Bluetooth mesh DFU implements a distribution mechanism for firmware images, and does not put any
restrictions on the size, format or usage of the images. The primary design goal of the subsystem is
to provide the qualifiable parts of the Bluetooth mesh DFU specification, and leave the usage,
firmware validation and deployment to the application.
The DFU specification is implemented in the Zephyr Bluetooth mesh DFU subsystem as three separate models:
The DFU specification is implemented in the Zephyr Bluetooth mesh DFU subsystem as three separate
models:
.. toctree::
:maxdepth: 1
@ -22,29 +28,50 @@ Overview
DFU roles
=========
The Bluetooth mesh DFU subsystem defines three different roles the mesh nodes have to assume in the distribution of firmware images:
The Bluetooth mesh DFU subsystem defines three different roles the mesh nodes have to assume in the
distribution of firmware images:
Target node
Target node is the receiver and user of the transferred firmware images. All its functionality is implemented by the :ref:`bluetooth_mesh_dfu_srv` model. A transfer may be targeting any number of Target nodes, and they will all be updated concurrently.
Target node is the receiver and user of the transferred firmware images. All its functionality is
implemented by the :ref:`bluetooth_mesh_dfu_srv` model. A transfer may be targeting any number of
Target nodes, and they will all be updated concurrently.
Distributor
The Distributor role serves two purposes in the DFU process. First, it's acting as the Target node in the Upload Firmware procedure, then it distributes the uploaded image to other Target nodes as the Distributor. The Distributor does not select the parameters of the transfer, but relies on an Initiator to give it a list of Target nodes and transfer parameters. The Distributor functionality is implemented in two models, :ref:`bluetooth_mesh_dfd_srv` and :ref:`bluetooth_mesh_dfu_cli`. The :ref:`bluetooth_mesh_dfd_srv` is responsible for communicating with the Initiator, and the :ref:`bluetooth_mesh_dfu_cli` is responsible for distributing the image to the Target nodes.
The Distributor role serves two purposes in the DFU process. First, it's acting as the Target
node in the Upload Firmware procedure, then it distributes the uploaded image to other Target
nodes as the Distributor. The Distributor does not select the parameters of the transfer, but
relies on an Initiator to give it a list of Target nodes and transfer parameters. The Distributor
functionality is implemented in two models, :ref:`bluetooth_mesh_dfd_srv` and
:ref:`bluetooth_mesh_dfu_cli`. The :ref:`bluetooth_mesh_dfd_srv` is responsible for communicating
with the Initiator, and the :ref:`bluetooth_mesh_dfu_cli` is responsible for distributing the
image to the Target nodes.
Initiator
The Initiator role is typically implemented by the same device that implements the Bluetooth mesh :ref:`Provisioner <bluetooth_mesh_provisioning>` and :ref:`Configurator <bluetooth_mesh_models_cfg_cli>` roles. The Initiator needs a full overview of the potential Target nodes and their firmware, and will control (and initiate) all firmware updates. The Initiator role is not implemented in the Zephyr Bluetooth mesh DFU subsystem.
The Initiator role is typically implemented by the same device that implements the Bluetooth mesh
:ref:`Provisioner <bluetooth_mesh_provisioning>` and :ref:`Configurator
<bluetooth_mesh_models_cfg_cli>` roles. The Initiator needs a full overview of the potential
Target nodes and their firmware, and will control (and initiate) all firmware updates. The
Initiator role is not implemented in the Zephyr Bluetooth mesh DFU subsystem.
.. figure:: images/dfu_roles_mesh.svg
:align: center
:alt: Graphic overview of the DFU roles mesh nodes can have during the process of image distribution
:alt: Graphic overview of the DFU roles mesh nodes can have during the process of image
distribution
DFU roles and the associated Bluetooth mesh models
Bluetooth mesh applications may combine the DFU roles in any way they'd like, and even take on multiple instances of the same role by instantiating the models on separate elements. For instance, the Distributor and Initiator role can be combined by instantiating the :ref:`bluetooth_mesh_dfu_cli` on the Initiator node and calling its API directly.
Bluetooth mesh applications may combine the DFU roles in any way they'd like, and even take on
multiple instances of the same role by instantiating the models on separate elements. For instance,
the Distributor and Initiator role can be combined by instantiating the
:ref:`bluetooth_mesh_dfu_cli` on the Initiator node and calling its API directly.
It's also possible to combine the Initiator and Distributor devices into a single device, and replace the Firmware Distribution Server model with a proprietary mechanism that will access the Firmware Update Client model directly, e.g. over a serial protocol.
It's also possible to combine the Initiator and Distributor devices into a single device, and
replace the Firmware Distribution Server model with a proprietary mechanism that will access the
Firmware Update Client model directly, e.g. over a serial protocol.
.. note::
All DFU models instantiate one or more :ref:`bluetooth_mesh_blob`, and may need to be spread over multiple elements for certain role combinations.
All DFU models instantiate one or more :ref:`bluetooth_mesh_blob`, and may need to be spread over
multiple elements for certain role combinations.
Stages
======
@ -52,28 +79,63 @@ Stages
The Bluetooth mesh DFU process is designed to act in three stages:
Upload stage
First, the image is uploaded to a Distributor in a mesh network by an external entity, such as a phone or gateway (the Initiator). During the Upload stage, the Initiator transfers the firmware image and all its metadata to the Distributor node inside the mesh network. The Distributor stores the firmware image and its metadata persistently, and awaits further instructions from the Initiator. The time required to complete the upload process depends on the size of the image. After the upload completes, the Initiator can disconnect from the network during the much more time-consuming Distribution stage. Once the firmware has been uploaded to the Distributor, the Initiator may trigger the Distribution stage at any time.
First, the image is uploaded to a Distributor in a mesh network by an external entity, such as a
phone or gateway (the Initiator). During the Upload stage, the Initiator transfers the firmware
image and all its metadata to the Distributor node inside the mesh network. The Distributor
stores the firmware image and its metadata persistently, and awaits further instructions from the
Initiator. The time required to complete the upload process depends on the size of the image.
After the upload completes, the Initiator can disconnect from the network during the much more
time-consuming Distribution stage. Once the firmware has been uploaded to the Distributor, the
Initiator may trigger the Distribution stage at any time.
Firmware Capability Check stage (optional)
Before starting the Distribution stage, the Initiator may optionally check if Target nodes can accept the new firmware. Nodes that do not respond, or respond that they can't receive the new firmware, are excluded from the firmware distribution process.
Before starting the Distribution stage, the Initiator may optionally check if Target nodes can
accept the new firmware. Nodes that do not respond, or respond that they can't receive the new
firmware, are excluded from the firmware distribution process.
Distribution stage
Before the firmware image can be distributed, the Initiator transfers the list of Target nodes and their designated firmware image index to the Distributor. Next, it tells the Distributor to start the firmware distributon process, which runs in the background while the Initiator and the mesh network perform other duties. Once the firmware image has been transferred to the Target nodes, the Distributor may ask them to apply the firmware image immediately and report back with their status and new firmware IDs.
Before the firmware image can be distributed, the Initiator transfers the list of Target nodes
and their designated firmware image index to the Distributor. Next, it tells the Distributor to
start the firmware distributon process, which runs in the background while the Initiator and the
mesh network perform other duties. Once the firmware image has been transferred to the Target
nodes, the Distributor may ask them to apply the firmware image immediately and report back with
their status and new firmware IDs.
Firmware images
===============
All updatable parts of a mesh node's firmware should be represented as a firmware image. Each Target node holds a list of firmware images, each of which should be independently updatable and identifiable.
All updatable parts of a mesh node's firmware should be represented as a firmware image. Each Target
node holds a list of firmware images, each of which should be independently updatable and
identifiable.
Firmware images are represented as a BLOB (the firmware itself) with the following additional information attached to it:
Firmware images are represented as a BLOB (the firmware itself) with the following additional
information attached to it:
Firmware ID
The firmware ID is used to identify a firmware image. The Initiator node may ask the Target nodes for a list of its current firmware IDs to determine whether a newer version of the firmware is available. The format of the firmware ID is vendor specific, but generally, it should include enough information for an Initiator node with knowledge of the format to determine the type of image as well as its version. The firmware ID is optional, and its max length is determined by :kconfig:option:`CONFIG_BT_MESH_DFU_FWID_MAXLEN`.
The firmware ID is used to identify a firmware image. The Initiator node may ask the Target nodes
for a list of its current firmware IDs to determine whether a newer version of the firmware is
available. The format of the firmware ID is vendor specific, but generally, it should include
enough information for an Initiator node with knowledge of the format to determine the type of
image as well as its version. The firmware ID is optional, and its max length is determined by
:kconfig:option:`CONFIG_BT_MESH_DFU_FWID_MAXLEN`.
Firmware metadata
The firmware metadata is used by the Target node to determine whether it should accept an incoming firmware update, and what the effect of the update would be. The metadata format is vendor specific, and should contain all information the Target node needs to verify the image, as well as any preparation the Target node has to make before the image is applied. Typical metadata information can be image signatures, changes to the node's Composition Data and the format of the BLOB. The Target node may perform a metadata check before accepting incoming transfers to determine whether the transfer should be started. The firmware metadata can be discarded by the Target node after the metadata check, as other nodes will never request the metadata from the Target node. The firmware metadata is optional, and its maximum length is determined by :kconfig:option:`CONFIG_BT_MESH_DFU_METADATA_MAXLEN`.
The firmware metadata is used by the Target node to determine whether it should accept an
incoming firmware update, and what the effect of the update would be. The metadata format is
vendor specific, and should contain all information the Target node needs to verify the image, as
well as any preparation the Target node has to make before the image is applied. Typical metadata
information can be image signatures, changes to the node's Composition Data and the format of the
BLOB. The Target node may perform a metadata check before accepting incoming transfers to
determine whether the transfer should be started. The firmware metadata can be discarded by the
Target node after the metadata check, as other nodes will never request the metadata from the
Target node. The firmware metadata is optional, and its maximum length is determined by
:kconfig:option:`CONFIG_BT_MESH_DFU_METADATA_MAXLEN`.
The Bluetooth mesh DFU subsystem in Zephyr provides its own metadata format (:c:struct:`bt_mesh_dfu_metadata`) together with a set of related functions that can be used by an end product. The support for it is enabled using the :kconfig:option:`CONFIG_BT_MESH_DFU_METADATA` option. The format of the metadata is presented in the table below.
The Bluetooth mesh DFU subsystem in Zephyr provides its own metadata format
(:c:struct:`bt_mesh_dfu_metadata`) together with a set of related functions that can be used by
an end product. The support for it is enabled using the
:kconfig:option:`CONFIG_BT_MESH_DFU_METADATA` option. The format of the metadata is presented in
the table below.
+------------------------+--------------+----------------------------------------+
| Field | Size (Bytes) | Description |
@ -109,7 +171,14 @@ Firmware metadata
+------------------------+--------------+----------------------------------------+
Firmware URI
The firmware URI gives the Initiator information about where firmware updates for the image can be found. The URI points to an online resource the Initiator can interact with to get new versions of the firmware. This allows Initiators to perform updates for any node in the mesh network by interacting with the web server pointed to in the URI. The URI must point to a resource using the ``http`` or ``https`` schemes, and the targeted web server must behave according to the Firmware Check Over HTTPS procedure defined by the specification. The firmware URI is optional, and its max length is determined by :kconfig:option:`CONFIG_BT_MESH_DFU_URI_MAXLEN`.
The firmware URI gives the Initiator information about where firmware updates for the image can
be found. The URI points to an online resource the Initiator can interact with to get new
versions of the firmware. This allows Initiators to perform updates for any node in the mesh
network by interacting with the web server pointed to in the URI. The URI must point to a
resource using the ``http`` or ``https`` schemes, and the targeted web server must behave
according to the Firmware Check Over HTTPS procedure defined by the specification. The firmware
URI is optional, and its max length is determined by
:kconfig:option:`CONFIG_BT_MESH_DFU_URI_MAXLEN`.
.. note::
@ -118,18 +187,30 @@ Firmware URI
Firmware effect
---------------
A new image may have the Composition Data Page 0 different from the one allocated on a Target node. This may have an effect on the provisioning data of the node and how the Distributor finalizes the DFU. Depending on the availability of the Remote Provisioning Server model on the old and new image, the device may either boot up unprovisioned after applying the new firmware or require to be re-provisioned. The complete list of available options is defined in :c:enum:`bt_mesh_dfu_effect`:
A new image may have the Composition Data Page 0 different from the one allocated on a Target node.
This may have an effect on the provisioning data of the node and how the Distributor finalizes the
DFU. Depending on the availability of the Remote Provisioning Server model on the old and new image,
the device may either boot up unprovisioned after applying the new firmware or require to be
re-provisioned. The complete list of available options is defined in :c:enum:`bt_mesh_dfu_effect`:
:c:enum:`BT_MESH_DFU_EFFECT_NONE`
The device stays provisioned after the new firmware is programmed. This effect is chosen if the composition data of the new firmware doesn't change.
The device stays provisioned after the new firmware is programmed. This effect is chosen if the
composition data of the new firmware doesn't change.
:c:enum:`BT_MESH_DFU_EFFECT_COMP_CHANGE_NO_RPR`
This effect is chosen when the composition data changes and the device doesn't support the remote provisioning. The new composition data takes place only after re-provisioning.
This effect is chosen when the composition data changes and the device doesn't support the remote
provisioning. The new composition data takes place only after re-provisioning.
:c:enum:`BT_MESH_DFU_EFFECT_COMP_CHANGE`
This effect is chosen when the composition data changes and the device supports the remote provisioning. In this case, the device stays provisioned and the new composition data takes place after re-provisioning using the Remote Provisioning models.
This effect is chosen when the composition data changes and the device supports the remote
provisioning. In this case, the device stays provisioned and the new composition data takes place
after re-provisioning using the Remote Provisioning models.
:c:enum:`BT_MESH_DFU_EFFECT_UNPROV`
This effect is chosen if the composition data in the new firmware changes, the device doesn't support the remote provisioning, and the new composition data takes effect after applying the firmware.
This effect is chosen if the composition data in the new firmware changes, the device doesn't
support the remote provisioning, and the new composition data takes effect after applying the
firmware.
When the Target node receives the Firmware Update Firmware Metadata Check message, the Firmware Update Server model calls the :c:member:`bt_mesh_dfu_srv_cb.check` callback, the application can then process the metadata and provide the effect value.
When the Target node receives the Firmware Update Firmware Metadata Check message, the Firmware
Update Server model calls the :c:member:`bt_mesh_dfu_srv_cb.check` callback, the application can
then process the metadata and provide the effect value.
DFU procedures
@ -137,9 +218,12 @@ DFU procedures
The DFU protocol is implemented as a set of procedures that must be performed in a certain order.
The Initiator controls the Upload stage of the DFU protocol, and all Distributor side handling of the upload subprocedures is implemented in the :ref:`bluetooth_mesh_dfd_srv`.
The Initiator controls the Upload stage of the DFU protocol, and all Distributor side handling of
the upload subprocedures is implemented in the :ref:`bluetooth_mesh_dfd_srv`.
The Distribution stage is controlled by the Distributor, as implemented by the :ref:`bluetooth_mesh_dfu_cli`. The Target node implements all handling of these procedures in the :ref:`bluetooth_mesh_dfu_srv`, and notifies the application through a set of callbacks.
The Distribution stage is controlled by the Distributor, as implemented by the
:ref:`bluetooth_mesh_dfu_cli`. The Target node implements all handling of these procedures in the
:ref:`bluetooth_mesh_dfu_srv`, and notifies the application through a set of callbacks.
.. figure:: images/dfu_stages_procedures_mesh.svg
:align: center
@ -150,14 +234,23 @@ The Distribution stage is controlled by the Distributor, as implemented by the :
Uploading the firmware
======================
The Upload Firmware procedure uses the :ref:`bluetooth_mesh_blob` to transfer the firmware image from the Initiator to the Distributor. The Upload Firmware procedure works in two steps:
The Upload Firmware procedure uses the :ref:`bluetooth_mesh_blob` to transfer the firmware image
from the Initiator to the Distributor. The Upload Firmware procedure works in two steps:
1. The Initiator generates a BLOB ID, and sends it to the Distributor's Firmware Distribution Server along with the firmware information and other input parameters of the BLOB transfer. The Firmware Distribution Server stores the information, and prepares its BLOB Transfer Server for the incoming transfer before it responds with a status message to the Initiator.
#. The Initiator's BLOB Transfer Client model transfers the firmware image to the Distributor's BLOB Transfer Server, which stores the image in a predetermined flash partition.
1. The Initiator generates a BLOB ID, and sends it to the Distributor's Firmware Distribution Server
along with the firmware information and other input parameters of the BLOB transfer. The Firmware
Distribution Server stores the information, and prepares its BLOB Transfer Server for the
incoming transfer before it responds with a status message to the Initiator.
#. The Initiator's BLOB Transfer Client model transfers the firmware image to the Distributor's BLOB
Transfer Server, which stores the image in a predetermined flash partition.
When the BLOB transfer finishes, the firmware image is ready for distribution. The Initiator may upload several firmware images to the Distributor, and ask it to distribute them in any order or at any time. Additional procedures are available for querying and deleting firmware images from the Distributor.
When the BLOB transfer finishes, the firmware image is ready for distribution. The Initiator may
upload several firmware images to the Distributor, and ask it to distribute them in any order or at
any time. Additional procedures are available for querying and deleting firmware images from the
Distributor.
The following Distributor's capabilities related to firmware images can be configured using the configuration options:
The following Distributor's capabilities related to firmware images can be configured using the
configuration options:
* :kconfig:option:`CONFIG_BT_MESH_DFU_SLOT_CNT`: Amount of image slots available on the device.
* :kconfig:option:`CONFIG_BT_MESH_DFD_SRV_SLOT_MAX_SIZE`: Maximum allowed size for each image.
@ -166,52 +259,97 @@ The following Distributor's capabilities related to firmware images can be confi
Populating the Distributor's receivers list
===========================================
Before the Distributor can start distributing the firmware image, it needs a list of Target nodes to send the image to. The Initiator gets the full list of Target nodes either by querying the potential targets directly, or through some external authority. The Initiator uses this information to populate the Distributor's receivers list with the address and relevant firmware image index of each Target node. The Initiator may send one or more Firmware Distribution Receivers Add messages to build the Distributor's receivers list, and a Firmware Distribution Receivers Delete All message to clear it.
Before the Distributor can start distributing the firmware image, it needs a list of Target nodes to
send the image to. The Initiator gets the full list of Target nodes either by querying the potential
targets directly, or through some external authority. The Initiator uses this information to
populate the Distributor's receivers list with the address and relevant firmware image index of each
Target node. The Initiator may send one or more Firmware Distribution Receivers Add messages to
build the Distributor's receivers list, and a Firmware Distribution Receivers Delete All message to
clear it.
The maximum number of receivers that can be added to the Distributor is configured through the :kconfig:option:`CONFIG_BT_MESH_DFD_SRV_TARGETS_MAX` configuration option.
The maximum number of receivers that can be added to the Distributor is configured through the
:kconfig:option:`CONFIG_BT_MESH_DFD_SRV_TARGETS_MAX` configuration option.
Initiating the distribution
===========================
Once the Distributor has stored a firmware image and received a list of Target nodes, the Initiator may initiate the distribution procedure. The BLOB transfer parameters for the distribution are passed to the Distributor along with an update policy. The update policy decides whether the Distributor should request that the firmware is applied on the Target nodes or not. The Distributor stores the transfer parameters and starts distributing the firmware image to its list of Target nodes.
Once the Distributor has stored a firmware image and received a list of Target nodes, the Initiator
may initiate the distribution procedure. The BLOB transfer parameters for the distribution are
passed to the Distributor along with an update policy. The update policy decides whether the
Distributor should request that the firmware is applied on the Target nodes or not. The Distributor
stores the transfer parameters and starts distributing the firmware image to its list of Target
nodes.
Firmware distribution
---------------------
The Distributor's Firmware Update Client model uses its BLOB Transfer Client model's broadcast subsystem to communicate with all Target nodes. The firmware distribution is performed with the following steps:
The Distributor's Firmware Update Client model uses its BLOB Transfer Client model's broadcast
subsystem to communicate with all Target nodes. The firmware distribution is performed with the
following steps:
1. The Distributor's Firmware Update Client model generates a BLOB ID and sends it to each Target node's Firmware Update Server model, along with the other BLOB transfer parameters, the Target node firmware image index and the firmware image metadata. Each Target node performs a metadata check and prepares their BLOB Transfer Server model for the transfer, before sending a status response to the Firmware Update Client, indicating if the firmware update will have any effect on the Bluetooth mesh state of the node.
1. The Distributor's Firmware Update Client model generates a BLOB ID and sends it to each Target
node's Firmware Update Server model, along with the other BLOB transfer parameters, the Target
node firmware image index and the firmware image metadata. Each Target node performs a metadata
check and prepares their BLOB Transfer Server model for the transfer, before sending a status
response to the Firmware Update Client, indicating if the firmware update will have any effect on
the Bluetooth mesh state of the node.
#. The Distributor's BLOB Transfer Client model transfers the firmware image to all Target nodes.
#. Once the BLOB transfer has been received, the Target nodes' applications verify that the firmware is valid by performing checks such as signature verification or image checksums against the image metadata.
#. The Distributor's Firmware Update Client model queries all Target nodes to ensure that they've all verified the firmware image.
#. Once the BLOB transfer has been received, the Target nodes' applications verify that the firmware
is valid by performing checks such as signature verification or image checksums against the image
metadata.
#. The Distributor's Firmware Update Client model queries all Target nodes to ensure that they've
all verified the firmware image.
If the distribution procedure completed with at least one Target node reporting that the image has been received and verified, the distribution procedure is considered successful.
If the distribution procedure completed with at least one Target node reporting that the image has
been received and verified, the distribution procedure is considered successful.
.. note::
The firmware distribution procedure only fails if *all* Target nodes are lost. It is up to the Initiator to request a list of failed Target nodes from the Distributor and initiate additional attempts to update the lost Target nodes after the current attempt is finished.
The firmware distribution procedure only fails if *all* Target nodes are lost. It is up to the
Initiator to request a list of failed Target nodes from the Distributor and initiate additional
attempts to update the lost Target nodes after the current attempt is finished.
Suspending the distribution
---------------------------
The Initiator can also request the Distributor to suspend the firmware distribution. In this case, the Distributor will stop sending any messages to Target nodes. When the firmware distribution is resumed, the Distributor will continue sending the firmware from the last successfully transferred block.
The Initiator can also request the Distributor to suspend the firmware distribution. In this case,
the Distributor will stop sending any messages to Target nodes. When the firmware distribution is
resumed, the Distributor will continue sending the firmware from the last successfully transferred
block.
Applying the firmware image
===========================
If the Initiator requested it, the Distributor can initiate the Apply Firmware on Target Node procedure on all Target nodes that successfully received and verified the firmware image. The Apply Firmware on Target Node procedure takes no parameters, and to avoid ambiguity, it should be performed before a new transfer is initiated. The Apply Firmware on Target Node procedure consists of the following steps:
If the Initiator requested it, the Distributor can initiate the Apply Firmware on Target Node
procedure on all Target nodes that successfully received and verified the firmware image. The Apply
Firmware on Target Node procedure takes no parameters, and to avoid ambiguity, it should be
performed before a new transfer is initiated. The Apply Firmware on Target Node procedure consists
of the following steps:
1. The Distributor's Firmware Update Client model instructs all Target nodes that have verified the firmware image to apply it. The Target nodes' Firmware Update Server models respond with a status message before calling their application's ``apply`` callback.
#. The Target node's application performs any preparations needed before applying the transfer, such as storing a snapshot of the Composition Data or clearing its configuration.
#. The Target node's application swaps the current firmware with the new image and updates its firmware image list with the new firmware ID.
#. The Distributor's Firmware Update Client model requests the full list of firmware images from each Target node, and scans through the list to make sure that the new firmware ID has replaced the old.
1. The Distributor's Firmware Update Client model instructs all Target nodes that have verified the
firmware image to apply it. The Target nodes' Firmware Update Server models respond with a status
message before calling their application's ``apply`` callback.
#. The Target node's application performs any preparations needed before applying the transfer, such
as storing a snapshot of the Composition Data or clearing its configuration.
#. The Target node's application swaps the current firmware with the new image and updates its
firmware image list with the new firmware ID.
#. The Distributor's Firmware Update Client model requests the full list of firmware images from
each Target node, and scans through the list to make sure that the new firmware ID has replaced
the old.
.. note::
During the metadata check in the distribution procedure, the Target node may have reported that it will become unprovisioned after the firmware image is applied. In this case, the Distributor's Firmware Update Client model will send a request for the full firmware image list, and expect no response.
During the metadata check in the distribution procedure, the Target node may have reported that
it will become unprovisioned after the firmware image is applied. In this case, the Distributor's
Firmware Update Client model will send a request for the full firmware image list, and expect no
response.
Cancelling the distribution
===========================
The firmware distribution can be cancelled at any time by the Initiator. In this case, the Distributor starts the cancelling procedure by sending a cancelling message to all Target nodes. The Distributor waits for the response from all Target nodes. Once all Target nodes have replied, or the request has timed out, the distribution procedure is cancelled. After this the distribution procedure can be started again from the ``Firmware distribution`` section.
The firmware distribution can be cancelled at any time by the Initiator. In this case, the
Distributor starts the cancelling procedure by sending a cancelling message to all Target nodes. The
Distributor waits for the response from all Target nodes. Once all Target nodes have replied, or the
request has timed out, the distribution procedure is cancelled. After this the distribution
procedure can be started again from the ``Firmware distribution`` section.
API reference

4
doc/connectivity/bluetooth/api/mesh/dfu_cli.rst
View file

@ -3,7 +3,9 @@
Firmware Update Client
######################
The Firmware Update Client is responsible for distributing firmware updates through the mesh network. The Firmware Update Client uses the :ref:`bluetooth_mesh_blob_cli` as a transport for its transfers.
The Firmware Update Client is responsible for distributing firmware updates through the mesh
network. The Firmware Update Client uses the :ref:`bluetooth_mesh_blob_cli` as a transport for its
transfers.
API reference

65
doc/connectivity/bluetooth/api/mesh/dfu_srv.rst
View file

@ -3,21 +3,33 @@
Firmware Update Server
######################
The Firmware Update Server model implements the Target node functionality of the :ref:`bluetooth_mesh_dfu` subsystem. It extends the :ref:`bluetooth_mesh_blob_srv`, which it uses to receive the firmware image binary from the Distributor node.
The Firmware Update Server model implements the Target node functionality of the
:ref:`bluetooth_mesh_dfu` subsystem. It extends the :ref:`bluetooth_mesh_blob_srv`, which it uses to
receive the firmware image binary from the Distributor node.
Together with the extended BLOB Transfer Server model, the Firmware Update Server model implements all the required functionality for receiving firmware updates over the mesh network, but does not provide any functionality for storing, applying or verifying the images.
Together with the extended BLOB Transfer Server model, the Firmware Update Server model implements
all the required functionality for receiving firmware updates over the mesh network, but does not
provide any functionality for storing, applying or verifying the images.
Firmware images
***************
The Firmware Update Server holds a list of all the updatable firmware images on the device. The full list shall be passed to the server through the ``_imgs`` parameter in :c:macro:`BT_MESH_DFU_SRV_INIT`, and must be populated before the Bluetooth mesh subsystem is started. Each firmware image in the image list must be independently updatable, and should have its own firmware ID.
The Firmware Update Server holds a list of all the updatable firmware images on the device. The full
list shall be passed to the server through the ``_imgs`` parameter in
:c:macro:`BT_MESH_DFU_SRV_INIT`, and must be populated before the Bluetooth mesh subsystem is
started. Each firmware image in the image list must be independently updatable, and should have its
own firmware ID.
For instance, a device with an upgradable bootloader, an application and a peripheral chip with firmware update capabilities could have three entries in the firmware image list, each with their own separate firmware ID.
For instance, a device with an upgradable bootloader, an application and a peripheral chip with
firmware update capabilities could have three entries in the firmware image list, each with their
own separate firmware ID.
Receiving transfers
*******************
The Firmware Update Server model uses a BLOB Transfer Server model on the same element to transfer the binary image. The interaction between the Firmware Update Server, BLOB Transfer Server and application is described below:
The Firmware Update Server model uses a BLOB Transfer Server model on the same element to transfer
the binary image. The interaction between the Firmware Update Server, BLOB Transfer Server and
application is described below:
.. figure:: images/dfu_srv.svg
:align: center
@ -28,40 +40,61 @@ The Firmware Update Server model uses a BLOB Transfer Server model on the same e
Transfer check
==============
The transfer check is an optional pre-transfer check the application can perform on incoming firmware image metadata. The Firmware Update Server performs the transfer check by calling the :c:member:`check <bt_mesh_dfu_srv_cb.check>` callback.
The transfer check is an optional pre-transfer check the application can perform on incoming
firmware image metadata. The Firmware Update Server performs the transfer check by calling the
:c:member:`check <bt_mesh_dfu_srv_cb.check>` callback.
The result of the transfer check is a pass/fail status return and the expected :c:type:`bt_mesh_dfu_effect`. The DFU effect return parameter will be communicated back to the Distributor, and should indicate what effect the firmware update will have on the mesh state of the device. If the transfer will cause the device to change its Composition Data or become unprovisioned, this should be communicated through the effect parameter of the metadata check.
The result of the transfer check is a pass/fail status return and the expected
:c:type:`bt_mesh_dfu_effect`. The DFU effect return parameter will be communicated back to the
Distributor, and should indicate what effect the firmware update will have on the mesh state of the
device. If the transfer will cause the device to change its Composition Data or become
unprovisioned, this should be communicated through the effect parameter of the metadata check.
Start
=====
The Start procedure prepares the application for the incoming transfer. It'll contain information about which image is being updated, as well as the update metadata.
The Start procedure prepares the application for the incoming transfer. It'll contain information
about which image is being updated, as well as the update metadata.
The Firmware Update Server :c:member:`start <bt_mesh_dfu_srv_cb.start>` callback must return a pointer to the BLOB Writer the BLOB Transfer Server will send the BLOB to.
The Firmware Update Server :c:member:`start <bt_mesh_dfu_srv_cb.start>` callback must return a
pointer to the BLOB Writer the BLOB Transfer Server will send the BLOB to.
BLOB transfer
=============
After the setup stage, the Firmware Update Server prepares the BLOB Transfer Server for the incoming transfer. The entire firmware image is transferred to the BLOB Transfer Server, which passes the image to its assigned BLOB Writer.
After the setup stage, the Firmware Update Server prepares the BLOB Transfer Server for the incoming
transfer. The entire firmware image is transferred to the BLOB Transfer Server, which passes the
image to its assigned BLOB Writer.
At the end of the BLOB transfer, the Firmware Update Server calls its :c:member:`end <bt_mesh_dfu_srv_cb.end>` callback.
At the end of the BLOB transfer, the Firmware Update Server calls its
:c:member:`end <bt_mesh_dfu_srv_cb.end>` callback.
Image verification
==================
After the BLOB transfer has finished, the application should verify the image in any way it can to ensure that it is ready for being applied.
Once the image has been verified, the application calls :c:func:`bt_mesh_dfu_srv_verified`.
After the BLOB transfer has finished, the application should verify the image in any way it can to
ensure that it is ready for being applied. Once the image has been verified, the application calls
:c:func:`bt_mesh_dfu_srv_verified`.
If the image can't be verified, the application calls :c:func:`bt_mesh_dfu_srv_rejected`.
Applying the image
==================
Finally, if the image was verified, the Distributor may instruct the Firmware Update Server to apply the transfer. This is communicated to the application through the :c:member:`apply <bt_mesh_dfu_srv_cb.apply>` callback. The application should swap the image and start running with the new firmware. The firmware image table should be updated to reflect the new firmware ID of the updated image.
Finally, if the image was verified, the Distributor may instruct the Firmware Update Server to apply
the transfer. This is communicated to the application through the :c:member:`apply
<bt_mesh_dfu_srv_cb.apply>` callback. The application should swap the image and start running with
the new firmware. The firmware image table should be updated to reflect the new firmware ID of the
updated image.
When the transfer applies to the mesh application itself, the device might have to reboot as part of the swap. This restart can be performed from inside the apply callback, or done asynchronously. After booting up with the new firmware, the firmware image table should be updated before the Bluetooth mesh subsystem is started.
When the transfer applies to the mesh application itself, the device might have to reboot as part of
the swap. This restart can be performed from inside the apply callback, or done asynchronously.
After booting up with the new firmware, the firmware image table should be updated before the
Bluetooth mesh subsystem is started.
The Distributor will read out the firmware image table to confirm that the transfer was successfully applied. If the metadata check indicated that the device would become unprovisioned, the Target node is not required to respond to this check.
The Distributor will read out the firmware image table to confirm that the transfer was successfully
applied. If the metadata check indicated that the device would become unprovisioned, the Target node
is not required to respond to this check.
API reference
*************

16
doc/connectivity/bluetooth/api/mesh/lcd_cli.rst
View file

@ -3,14 +3,20 @@
Large Composition Data Client
#############################
The Large Composition Data Client model is a foundation model defined by the Bluetooth
mesh specification. The model is optional, and is enabled through the :kconfig:option:`CONFIG_BT_MESH_LARGE_COMP_DATA_CLI` option.
The Large Composition Data Client model is a foundation model defined by the Bluetooth mesh
specification. The model is optional, and is enabled through the
:kconfig:option:`CONFIG_BT_MESH_LARGE_COMP_DATA_CLI` option.
The Large Composition Data Client model was introduced in the Bluetooth Mesh Protocol Specification version 1.1, and supports the functionality of reading pages of Composition Data that do not fit in a Config Composition Data Status message and reading the metadata of the model instances on a node that supports the :ref:`bluetooth_mesh_lcd_srv` model.
The Large Composition Data Client model was introduced in the Bluetooth Mesh Protocol Specification
version 1.1, and supports the functionality of reading pages of Composition Data that do not fit in
a Config Composition Data Status message and reading the metadata of the model instances on a node
that supports the :ref:`bluetooth_mesh_lcd_srv` model.
The Large Composition Data Client model communicates with a Large Composition Data Server model using the device key of the node containing the target Large Composition Data Server model instance.
The Large Composition Data Client model communicates with a Large Composition Data Server model
using the device key of the node containing the target Large Composition Data Server model instance.
If present, the Large Composition Data Client model must only be instantiated on the primary element.
If present, the Large Composition Data Client model must only be instantiated on the primary
element.
API reference
*************

31
doc/connectivity/bluetooth/api/mesh/lcd_srv.rst
View file

@ -3,24 +3,33 @@
Large Composition Data Server
#############################
The Large Composition Data Server model is a foundation model defined by the Bluetooth
mesh specification. The model is optional, and is enabled through the :kconfig:option:`CONFIG_BT_MESH_LARGE_COMP_DATA_SRV` option.
The Large Composition Data Server model is a foundation model defined by the Bluetooth mesh
specification. The model is optional, and is enabled through the
:kconfig:option:`CONFIG_BT_MESH_LARGE_COMP_DATA_SRV` option.
The Large Composition Data Server model was introduced in the Bluetooth Mesh Protocol Specification version 1.1, and is used to support
the functionality of exposing pages of Composition Data that do not fit in a Config Composition Data Status message and to expose metadata of the model instances.
The Large Composition Data Server model was introduced in the Bluetooth Mesh Protocol Specification
version 1.1, and is used to support the functionality of exposing pages of Composition Data that do
not fit in a Config Composition Data Status message and to expose metadata of the model instances.
The Large Composition Data Server does not have an API of its own and relies on a :ref:`bluetooth_mesh_lcd_cli` to control it.
The model only accepts messages encrypted with the node's device key.
The Large Composition Data Server does not have an API of its own and relies on a
:ref:`bluetooth_mesh_lcd_cli` to control it. The model only accepts messages encrypted with the
node's device key.
If present, the Large Composition Data Server model must only be instantiated on the primary element.
If present, the Large Composition Data Server model must only be instantiated on the primary
element.
Models metadata
===============
The Large Composition Data Server model allows each model to have a list of model's specific metadata that can be read by the Large Composition Data Client model.
The metadata list can be associated with the :c:struct:`bt_mesh_model` through the :c:member:`bt_mesh_model.metadata` field.
The metadata list consists of one or more entries defined by the :c:struct:`bt_mesh_models_metadata_entry` structure. Each entry contains the length and ID of the metadata, and a pointer to the raw data.
Entries can be created using the :c:macro:`BT_MESH_MODELS_METADATA_ENTRY` macro. The :c:macro:`BT_MESH_MODELS_METADATA_END` macro marks the end of the metadata list and must always be present. If the model has no metadata, the helper macro :c:macro:`BT_MESH_MODELS_METADATA_NONE` can be used instead.
The Large Composition Data Server model allows each model to have a list of model's specific
metadata that can be read by the Large Composition Data Client model. The metadata list can be
associated with the :c:struct:`bt_mesh_model` through the :c:member:`bt_mesh_model.metadata` field.
The metadata list consists of one or more entries defined by the
:c:struct:`bt_mesh_models_metadata_entry` structure. Each entry contains the length and ID of the
metadata, and a pointer to the raw data. Entries can be created using the
:c:macro:`BT_MESH_MODELS_METADATA_ENTRY` macro. The :c:macro:`BT_MESH_MODELS_METADATA_END` macro
marks the end of the metadata list and must always be present. If the model has no metadata, the
helper macro :c:macro:`BT_MESH_MODELS_METADATA_NONE` can be used instead.
API reference
*************

23
doc/connectivity/bluetooth/api/mesh/od_cli.rst
View file

@ -3,15 +3,18 @@
On-Demand Private Proxy Client
##############################
The On-Demand Private Proxy Client model is a foundation model defined by the Bluetooth
mesh specification. The model is optional, and is enabled with the :kconfig:option:`CONFIG_BT_MESH_OD_PRIV_PROXY_CLI` option.
The On-Demand Private Proxy Client model is a foundation model defined by the Bluetooth mesh
specification. The model is optional, and is enabled with the
:kconfig:option:`CONFIG_BT_MESH_OD_PRIV_PROXY_CLI` option.
The On-Demand Private Proxy Client model was introduced in the Bluetooth Mesh Protocol
Specification version 1.1, and is used to set and retrieve the On-Demand Private GATT Proxy state. The state defines
how long a node will advertise Mesh Proxy Service with Private Network Identity type after it receives a Solicitation PDU.
The On-Demand Private Proxy Client model was introduced in the Bluetooth Mesh Protocol Specification
version 1.1, and is used to set and retrieve the On-Demand Private GATT Proxy state. The state
defines how long a node will advertise Mesh Proxy Service with Private Network Identity type after
it receives a Solicitation PDU.
The On-Demand Private Proxy Client model communicates with an On-Demand Private Proxy Server model
using the device key of the node containing the target On-Demand Private Proxy Server model instance.
using the device key of the node containing the target On-Demand Private Proxy Server model
instance.
If present, the On-Demand Private Proxy Client model must only be instantiated on the primary
element.
@ -19,9 +22,11 @@ element.
Configurations
**************
The On-Demand Private Proxy Client model behavior can be configured with the transmission timeout option :kconfig:option:`CONFIG_BT_MESH_OD_PRIV_PROXY_CLI_TIMEOUT`.
The :kconfig:option:`CONFIG_BT_MESH_OD_PRIV_PROXY_CLI_TIMEOUT` controls how long the Client waits for a state response message to arrive
in milliseconds. This value can be changed at runtime using :c:func:`bt_mesh_od_priv_proxy_cli_timeout_set`.
The On-Demand Private Proxy Client model behavior can be configured with the transmission timeout
option :kconfig:option:`CONFIG_BT_MESH_OD_PRIV_PROXY_CLI_TIMEOUT`. The
:kconfig:option:`CONFIG_BT_MESH_OD_PRIV_PROXY_CLI_TIMEOUT` controls how long the Client waits for a
state response message to arrive in milliseconds. This value can be changed at runtime using
:c:func:`bt_mesh_od_priv_proxy_cli_timeout_set`.
API reference

18
doc/connectivity/bluetooth/api/mesh/od_srv.rst
View file

@ -3,19 +3,19 @@
On-Demand Private Proxy Server
##############################
The On-Demand Private Proxy Server model is a foundation model defined by the Bluetooth
mesh specification. It is enabled with the :kconfig:option:`CONFIG_BT_MESH_OD_PRIV_PROXY_SRV` option.
The On-Demand Private Proxy Server model is a foundation model defined by the Bluetooth mesh
specification. It is enabled with the :kconfig:option:`CONFIG_BT_MESH_OD_PRIV_PROXY_SRV` option.
The On-Demand Private Proxy Server model was introduced in the Bluetooth Mesh Protocol
Specification version 1.1, and supports the configuration of advertising with Private Network Identity type of a node
that is a recipient of Solicitation PDUs by managing its On-Demand Private GATT Proxy state.
The On-Demand Private Proxy Server model was introduced in the Bluetooth Mesh Protocol Specification
version 1.1, and supports the configuration of advertising with Private Network Identity type of a
node that is a recipient of Solicitation PDUs by managing its On-Demand Private GATT Proxy state.
When enabled, the :ref:`bluetooth_mesh_srpl_srv` is also enabled. The On-Demand Private Proxy Server is dependent on the
:ref:`bluetooth_mesh_models_priv_beacon_srv` to be present on the node.
When enabled, the :ref:`bluetooth_mesh_srpl_srv` is also enabled. The On-Demand Private Proxy Server
is dependent on the :ref:`bluetooth_mesh_models_priv_beacon_srv` to be present on the node.
The On-Demand Private Proxy Server does not have an API of its own, and relies on a
:ref:`bluetooth_mesh_od_cli` to control it. The On-Demand Private Proxy Server
model only accepts messages encrypted with the node's device key.
:ref:`bluetooth_mesh_od_cli` to control it. The On-Demand Private Proxy Server model only accepts
messages encrypted with the node's device key.
If present, the On-Demand Private Proxy Server model must only be instantiated on the primary
element.

23
doc/connectivity/bluetooth/api/mesh/op_agg_cli.rst
View file

@ -3,24 +3,25 @@
Opcodes Aggregator Client
#########################
The Opcodes Aggregator Client model is a foundation model defined by the Bluetooth
mesh specification. It is an optional model, enabled with the :kconfig:option:`CONFIG_BT_MESH_OP_AGG_CLI` option.
The Opcodes Aggregator Client model is a foundation model defined by the Bluetooth mesh
specification. It is an optional model, enabled with the :kconfig:option:`CONFIG_BT_MESH_OP_AGG_CLI`
option.
The Opcodes Aggregator Client model is introduced in the Bluetooth Mesh Protocol
Specification version 1.1, and is used to support the functionality of dispatching
a sequence of access layer messages to nodes supporting the :ref:`bluetooth_mesh_models_op_agg_srv` model.
The Opcodes Aggregator Client model is introduced in the Bluetooth Mesh Protocol Specification
version 1.1, and is used to support the functionality of dispatching a sequence of access layer
messages to nodes supporting the :ref:`bluetooth_mesh_models_op_agg_srv` model.
The Opcodes Aggregator Client model communicates with an Opcodes Aggregator Server model
using the device key of the target node or the application keys configured by the Configuration Client.
The Opcodes Aggregator Client model communicates with an Opcodes Aggregator Server model using the
device key of the target node or the application keys configured by the Configuration Client.
If present, the Opcodes Aggregator Client model must only be instantiated on the primary element.
The Opcodes Aggregator Client model is implicitly bound to the device key on initialization. It
should be bound to the same application keys as the client models that are used to produce the sequence of
messages.
should be bound to the same application keys as the client models that are used to produce the
sequence of messages.
To be able to aggregate a message from a client model, it should support an asynchronous
API, for example through callbacks.
To be able to aggregate a message from a client model, it should support an asynchronous API, for
example through callbacks.
API reference
*************

3
doc/connectivity/bluetooth/api/mesh/op_agg_srv.rst
View file

@ -4,7 +4,8 @@ Opcodes Aggregator Server
#########################
The Opcodes Aggregator Server model is a foundation model defined by the Bluetooth
mesh specification. It is an optional model, enabled with the :kconfig:option:`CONFIG_BT_MESH_OP_AGG_SRV` option.
mesh specification. It is an optional model, enabled with the
:kconfig:option:`CONFIG_BT_MESH_OP_AGG_SRV` option.
The Opcodes Aggregator Server model is introduced in the Bluetooth Mesh Protocol
Specification version 1.1, and is used to support the functionality of processing

51
doc/connectivity/bluetooth/api/mesh/proxy.rst
View file

@ -3,11 +3,10 @@
Proxy
#####
The Proxy feature allows legacy devices like phones to access the Bluetooth
mesh network through GATT. The Proxy feature is only compiled in if the
:kconfig:option:`CONFIG_BT_MESH_GATT_PROXY` option is set. The Proxy feature state is
controlled by the :ref:`bluetooth_mesh_models_cfg_srv`, and the initial value
can be set with :c:member:`bt_mesh_cfg_srv.gatt_proxy`.
The Proxy feature allows legacy devices like phones to access the Bluetooth mesh network through
GATT. The Proxy feature is only compiled in if the :kconfig:option:`CONFIG_BT_MESH_GATT_PROXY`
option is set. The Proxy feature state is controlled by the :ref:`bluetooth_mesh_models_cfg_srv`,
and the initial value can be set with :c:member:`bt_mesh_cfg_srv.gatt_proxy`.
Nodes with the Proxy feature enabled can advertise with Network Identity and Node Identity,
which is controlled by the :ref:`bluetooth_mesh_models_cfg_cli`.
@ -17,8 +16,8 @@ The GATT Proxy state indicates if the Proxy feature is supported.
Private Proxy
*************
A node supporting the Proxy feature and the :ref:`bluetooth_mesh_models_priv_beacon_srv` model can advertise with
Private Network Identity and Private Node Identity types, which is controlled by the
A node supporting the Proxy feature and the :ref:`bluetooth_mesh_models_priv_beacon_srv` model can
advertise with Private Network Identity and Private Node Identity types, which is controlled by the
:ref:`bluetooth_mesh_models_priv_beacon_cli`. By advertising with this set of identification types,
the node allows the legacy device to connect to the network over GATT while maintaining the
privacy of the network.
@ -28,28 +27,32 @@ The Private GATT Proxy state indicates whether the Private Proxy functionality i
Proxy Solicitation
******************
In the case where both GATT Proxy and Private GATT Proxy states are disabled on a node, a legacy device cannot
connect to it. A node supporting the :ref:`bluetooth_mesh_od_srv` may however be
In the case where both GATT Proxy and Private GATT Proxy states are disabled on a node, a legacy
device cannot connect to it. A node supporting the :ref:`bluetooth_mesh_od_srv` may however be
solicited to advertise connectable advertising events without enabling the Private GATT Proxy state.
To solicit the node, the legacy device can send a Solicitation PDU by calling the :func:`bt_mesh_proxy_solicit` function.
To enable this feature, the client must to be compiled with the :kconfig:option:`CONFIG_BT_MESH_PROXY_SOLICITATION`
option set.
To solicit the node, the legacy device can send a Solicitation PDU by calling the
:func:`bt_mesh_proxy_solicit` function. To enable this feature, the client must to be compiled with
the :kconfig:option:`CONFIG_BT_MESH_PROXY_SOLICITATION` option set.
Solicitation PDUs are non-mesh, non-connectable, undirected advertising messages
containing Proxy Solicitation UUID, encrypted with the network key of the subnet that the legacy device
wants to connect to. The PDU contains the source address of the legacy device and a sequence number. The
sequence number is maintained by the legacy device and is incremented for every new Solicitation PDU sent.
Solicitation PDUs are non-mesh, non-connectable, undirected advertising messages containing Proxy
Solicitation UUID, encrypted with the network key of the subnet that the legacy device wants to
connect to. The PDU contains the source address of the legacy device and a sequence number. The
sequence number is maintained by the legacy device and is incremented for every new Solicitation PDU
sent.
Each node supporting the Solicitation PDU reception holds its own Solicitation Replay Protection List (SRPL).
The SRPL protects the solicitation mechanism from replay attacks by storing solicitation sequence number (SSEQ)
and solicitation source (SSRC) pairs of valid Solicitation PDUs processed by the node. The delay between updating the
SRPL and storing the change to the persistent storage is defined by :kconfig:option:`CONFIG_BT_MESH_RPL_STORE_TIMEOUT`.
Each node supporting the Solicitation PDU reception holds its own Solicitation Replay Protection
List (SRPL). The SRPL protects the solicitation mechanism from replay attacks by storing
solicitation sequence number (SSEQ) and solicitation source (SSRC) pairs of valid Solicitation PDUs
processed by the node. The delay between updating the SRPL and storing the change to the persistent
storage is defined by :kconfig:option:`CONFIG_BT_MESH_RPL_STORE_TIMEOUT`.
The Solicitation PDU RPL Configuration models, :ref:`bluetooth_mesh_srpl_cli` and
:ref:`bluetooth_mesh_srpl_srv`, provide the functionality of saving and clearing SRPL entries.
A node that supports the Solicitation PDU RPL Configuration Client model can clear a section of the SRPL on the target by calling the :func:`bt_mesh_sol_pdu_rpl_clear` function.
Communication between the Solicitation PDU RPL Configuration Client and Server is encrypted using the application key, therefore,
the Solicitation PDU RPL Configuration Client can be instantiated on any device in the network.
:ref:`bluetooth_mesh_srpl_srv`, provide the functionality of saving and clearing SRPL entries. A
node that supports the Solicitation PDU RPL Configuration Client model can clear a section of the
SRPL on the target by calling the :func:`bt_mesh_sol_pdu_rpl_clear` function. Communication between
the Solicitation PDU RPL Configuration Client and Server is encrypted using the application key,
therefore, the Solicitation PDU RPL Configuration Client can be instantiated on any device in the
network.
When the node receives the Solicitation PDU and successfully authenticates it, it will start
advertising connectable advertisements with the Private Network Identity type. The duration of the

66
doc/connectivity/bluetooth/api/mesh/rpr_cli.rst
View file

@ -9,7 +9,9 @@ mesh specification. It is enabled with the
The Remote Provisioning Client model is introduced in the Bluetooth Mesh Protocol
Specification version 1.1.
This model provides functionality to remotely provision devices into a mesh network, and perform Node Provisioning Protocol Interface procedures by interacting with mesh nodes that support the :ref:`bluetooth_mesh_models_rpr_srv` model.
This model provides functionality to remotely provision devices into a mesh network, and perform
Node Provisioning Protocol Interface procedures by interacting with mesh nodes that support the
:ref:`bluetooth_mesh_models_rpr_srv` model.
The Remote Provisioning Client model communicates with a Remote Provisioning Server model
using the device key of the node containing the target Remote Provisioning Server model instance.
@ -20,7 +22,9 @@ element.
Scanning
********
The scanning procedure is used to scan for unprovisioned devices located nearby the Remote Provisioning Server. The Remote Provisioning Client starts a scan procedure by using the :c:func:`bt_mesh_rpr_scan_start` call:
The scanning procedure is used to scan for unprovisioned devices located nearby the Remote
Provisioning Server. The Remote Provisioning Client starts a scan procedure by using the
:c:func:`bt_mesh_rpr_scan_start` call:
.. code-block:: C
@ -49,21 +53,24 @@ The scanning procedure is used to scan for unprovisioned devices located nearby
bt_mesh_rpr_scan_start(&rpr_cli, &srv, uuid, timeout, max_devs, &status);
The above example shows pseudo code for starting a scan procedure on the target Remote Provisioning Server node. This
procedure will start a ten-second, multiple-device scanning where the generated scan report will contain
a maximum of three unprovisioned devices. If the UUID argument was specified, the same procedure would
only scan for the device with the corresponding UUID. After the procedure completes, the
server sends the scan report that will be handled in the client's :c:member:`bt_mesh_rpr_cli.scan_report` callback.
The above example shows pseudo code for starting a scan procedure on the target Remote Provisioning
Server node. This procedure will start a ten-second, multiple-device scanning where the generated
scan report will contain a maximum of three unprovisioned devices. If the UUID argument was
specified, the same procedure would only scan for the device with the corresponding UUID. After the
procedure completes, the server sends the scan report that will be handled in the client's
:c:member:`bt_mesh_rpr_cli.scan_report` callback.
Additionally, the Remote Provisioning Client model also supports extended scanning with the
:c:func:`bt_mesh_rpr_scan_start_ext` call. Extended scanning supplements regular scanning by allowing the
Remote Provisioning Server to report additional data for a specific device. The Remote Provisioning Server will use active scanning to request
a scan response from the unprovisioned device if it is supported by the unprovisioned device.
:c:func:`bt_mesh_rpr_scan_start_ext` call. Extended scanning supplements regular scanning by
allowing the Remote Provisioning Server to report additional data for a specific device. The Remote
Provisioning Server will use active scanning to request a scan response from the unprovisioned
device if it is supported by the unprovisioned device.
Provisioning
************
The Remote Provisioning Client starts a provisioning procedure by using the :c:func:`bt_mesh_provision_remote` call:
The Remote Provisioning Client starts a provisioning procedure by using the
:c:func:`bt_mesh_provision_remote` call:
.. code-block:: C
@ -81,25 +88,27 @@ The Remote Provisioning Client starts a provisioning procedure by using the :c:f
bt_mesh_provision_remote(&rpr_cli, &srv, uuid, net_idx, addr);
The above example shows pseudo code for remotely provisioning a device through a Remote Provisioning Server node. This
procedure will attempt to provision the device with the corresponding UUID, and assign the address 0x0006
to its primary element using the network key located at index zero.
The above example shows pseudo code for remotely provisioning a device through a Remote Provisioning
Server node. This procedure will attempt to provision the device with the corresponding UUID, and
assign the address 0x0006 to its primary element using the network key located at index zero.
.. note::
During the remote provisioning, the same :c:struct:`bt_mesh_prov` callbacks are triggered as for ordinary
provisioning. See section :ref:`bluetooth_mesh_provisioning` for further details.
During the remote provisioning, the same :c:struct:`bt_mesh_prov` callbacks are triggered as for
ordinary provisioning. See section :ref:`bluetooth_mesh_provisioning` for further details.
Re-provisioning
***************
In addition to scanning and provisioning functionality, the Remote Provisioning Client also provides means to
reconfigure node addresses, device keys and Composition Data on devices that support the
:ref:`bluetooth_mesh_models_rpr_srv` model. This is provided through the Node Provisioning Protocol Interface
(NPPI) which supports the following three procedures:
In addition to scanning and provisioning functionality, the Remote Provisioning Client also provides
means to reconfigure node addresses, device keys and Composition Data on devices that support the
:ref:`bluetooth_mesh_models_rpr_srv` model. This is provided through the Node Provisioning Protocol
Interface (NPPI) which supports the following three procedures:
* Device Key Refresh procedure: Used to change the device key of the Target node without a need to reconfigure the node.
* Device Key Refresh procedure: Used to change the device key of the Target node without a need to
reconfigure the node.
* Node Address Refresh procedure: Used to change the node’s device key and unicast address.
* Node Composition Refresh procedure: Used to change the device key of the node, and to add or delete models or features of the node.
* Node Composition Refresh procedure: Used to change the device key of the node, and to add or
delete models or features of the node.
The three NPPI procedures can be initiated with the :c:func:`bt_mesh_reprovision_remote` call:
@ -117,12 +126,13 @@ The three NPPI procedures can be initiated with the :c:func:`bt_mesh_reprovision
bt_mesh_reprovision_remote(&rpr_cli, &srv, new_addr, composition_changed);
The above example shows pseudo code for triggering a Node Address Refresh procedure on the Target node.
The specific procedure is not chosen directly, but rather through the other parameters that are inputted.
In the example we can see that the current unicast address of the Target is 0x0006, while the new address is
set to 0x0009. If the two addresses were the same, and the ``composition_changed`` flag was set to true, this code
would instead trigger a Node Composition Refresh procedure. If the two addresses were the same, and
the ``composition_changed`` flag was set to false, this code would trigger a Device Key Refresh procedure.
The above example shows pseudo code for triggering a Node Address Refresh procedure on the Target
node. The specific procedure is not chosen directly, but rather through the other parameters that
are inputted. In the example we can see that the current unicast address of the Target is 0x0006,
while the new address is set to 0x0009. If the two addresses were the same, and the
``composition_changed`` flag was set to true, this code would instead trigger a Node Composition
Refresh procedure. If the two addresses were the same, and the ``composition_changed`` flag was set
to false, this code would trigger a Device Key Refresh procedure.
API reference
*************

6
doc/connectivity/bluetooth/api/mesh/rpr_srv.rst
View file

@ -17,9 +17,9 @@ model only accepts messages encrypted with the node's device key.
If present, the Remote Provisioning Server model must be instantiated on the primary element.
Note that after refreshing the device key, node address or Composition Data through a Node Provisioning Protocol
Interface (NPPI) procedure, the :c:member:`bt_mesh_prov.reprovisioned` callback is triggered. See section
:ref:`bluetooth_mesh_models_rpr_cli` for further details.
Note that after refreshing the device key, node address or Composition Data through a Node
Provisioning Protocol Interface (NPPI) procedure, the :c:member:`bt_mesh_prov.reprovisioned`
callback is triggered. See section :ref:`bluetooth_mesh_models_rpr_cli` for further details.
API reference
*************

220
doc/connectivity/bluetooth/api/mesh/sar_cfg.rst
View file

@ -3,38 +3,42 @@
Segmentation and reassembly (SAR)
#################################
Segmentation and reassembly (SAR) provides a way of handling larger upper transport layer messages in a
mesh network, with a purpose of enhancing the Bluetooth mesh throughput. The segmentation and
Segmentation and reassembly (SAR) provides a way of handling larger upper transport layer messages
in a mesh network, with a purpose of enhancing the Bluetooth mesh throughput. The segmentation and
reassembly mechanism is used by the lower transport layer.
The lower transport layer defines how the upper transport layer PDUs are segmented and reassembled into multiple Lower Transport PDUs,
and sends them to the lower transport layer on a peer device.
If the Upper Transport PDU fits, it is sent in a single Lower Transport PDU.
For longer packets, which do not fit into a single Lower Transport PDU, the lower transport layer performs segmentation, splitting the Upper Transport
The lower transport layer defines how the upper transport layer PDUs are segmented and reassembled
into multiple Lower Transport PDUs, and sends them to the lower transport layer on a peer device.
If the Upper Transport PDU fits, it is sent in a single Lower Transport PDU. For longer packets,
which do not fit into a single Lower Transport PDU, the lower transport layer performs segmentation,
splitting the Upper Transport
PDU into multiple segments.
The lower transport layer on the receiving device reassembles the segments into a single Upper Transport PDU before passing it
up the stack. Delivery of a segmented message is acknowledged by the lower transport layer of the receiving node, while an unsegmented message
delivery is not acknowledged.
However, an Upper Transport PDU that fits into one Lower Transport PDU can also be sent as a single-segment segmented message when acknowledgment
by the lower transport layer is required.
Set the ``send rel`` flag (see :c:struct:`bt_mesh_msg_ctx`) to use the reliable message transmission and acknowledge single-segment segmented messages.
The lower transport layer on the receiving device reassembles the segments into a single Upper
Transport PDU before passing it up the stack. Delivery of a segmented message is acknowledged by the
lower transport layer of the receiving node, while an unsegmented message delivery is not
acknowledged. However, an Upper Transport PDU that fits into one Lower Transport PDU can also be
sent as a single-segment segmented message when acknowledgment by the lower transport layer is
required. Set the ``send rel`` flag (see :c:struct:`bt_mesh_msg_ctx`) to use the reliable message
transmission and acknowledge single-segment segmented messages.
The transport layer is able to transport up to 32 segments with its SAR mechanism, with a maximum message (PDU) size of 384 octets.
To configure message size for the Bluetooth mesh stack, use the following Kconfig options:
The transport layer is able to transport up to 32 segments with its SAR mechanism, with a maximum
message (PDU) size of 384 octets. To configure message size for the Bluetooth mesh stack, use the
following Kconfig options:
* :kconfig:option:`CONFIG_BT_MESH_RX_SEG_MAX` to set the maximum number of segments in an incoming message.
* :kconfig:option:`CONFIG_BT_MESH_TX_SEG_MAX` to set the maximum number of segments in an outgoing message.
The Kconfig options :kconfig:option:`CONFIG_BT_MESH_TX_SEG_MSG_COUNT` and :kconfig:option:`CONFIG_BT_MESH_RX_SEG_MSG_COUNT` define how many
outgoing and incoming segmented messages can be processed simultaneously. When more than one segmented message is sent to the same destination,
the messages are queued and sent one at a time.
The Kconfig options :kconfig:option:`CONFIG_BT_MESH_TX_SEG_MSG_COUNT` and
:kconfig:option:`CONFIG_BT_MESH_RX_SEG_MSG_COUNT` define how many outgoing and incoming segmented
messages can be processed simultaneously. When more than one segmented message is sent to the same
destination, the messages are queued and sent one at a time.
Incoming and outgoing segmented messages share the same pool for allocation of their segments. This pool size is configured through the
:kconfig:option:`CONFIG_BT_MESH_SEG_BUFS` Kconfig option.
Both incoming and outgoing messages allocate segments at the start of the transaction.
The outgoing segmented message releases its segments one by one as soon as they are acknowledged by the receiver, while the incoming message releases
the segments first after the message is fully received.
Incoming and outgoing segmented messages share the same pool for allocation of their segments. This
pool size is configured through the :kconfig:option:`CONFIG_BT_MESH_SEG_BUFS` Kconfig option.
Both incoming and outgoing messages allocate segments at the start of the transaction. The outgoing
segmented message releases its segments one by one as soon as they are acknowledged by the receiver,
while the incoming message releases the segments first after the message is fully received.
Keep this in mind when defining the size of the buffers.
SAR does not impose extra overhead on the access layer payload per segment.
@ -46,17 +50,19 @@ The current stable stack implementation allows you to configure the following SA
When sending a segmented message to a unicast address, the unacknowledged segments are repeated
the :kconfig:option:`CONFIG_BT_MESH_TX_SEG_RETRANS_COUNT` number of times before the transmission
is considered as failed. The same option configures a number of retransmissions to a group or virtual
address, but the transmission always succeedes after retransmitting all segments the configured
number of times.
is considered as failed. The same option configures a number of retransmissions to a group or
virtual address, but the transmission always succeedes after retransmitting all segments the
configured number of times.
The timeout between each retransmission to a unicast address is configured by the Kconfig option
:kconfig:option:`CONFIG_BT_MESH_TX_SEG_RETRANS_TIMEOUT_UNICAST`. The timeout between each retransmission
to a group or a virtual address is configured by the Kconfig option :kconfig:option:`CONFIG_BT_MESH_TX_SEG_RETRANS_TIMEOUT_GROUP`.
:kconfig:option:`CONFIG_BT_MESH_TX_SEG_RETRANS_TIMEOUT_UNICAST`. The timeout between each
retransmission to a group or a virtual address is configured by the Kconfig option
:kconfig:option:`CONFIG_BT_MESH_TX_SEG_RETRANS_TIMEOUT_GROUP`.
The time before sending a Segment Acknowledgment message is controlled by the Kconfig options
:kconfig:option:`CONFIG_BT_MESH_SEG_ACK_BASE_TIMEOUT`, :kconfig:option:`CONFIG_BT_MESH_SEG_ACK_PER_HOP_TIMEOUT`
and :kconfig:option:`CONFIG_BT_MESH_SEG_ACK_PER_SEGMENT_TIMEOUT`, and is defined as:
:kconfig:option:`CONFIG_BT_MESH_SEG_ACK_BASE_TIMEOUT`,
:kconfig:option:`CONFIG_BT_MESH_SEG_ACK_PER_HOP_TIMEOUT` and
:kconfig:option:`CONFIG_BT_MESH_SEG_ACK_PER_SEGMENT_TIMEOUT`, and is defined as:
.. math::
\begin{aligned}
@ -68,48 +74,57 @@ and :kconfig:option:`CONFIG_BT_MESH_SEG_ACK_PER_SEGMENT_TIMEOUT`, and is defined
Segmentation and reassembly (SAR) Configuration models
======================================================
With Bluetooth Mesh Protocol Specification version 1.1, it became possible to configure SAR behavior, such as intervals,
timers and retransmission counters, over a mesh network using SAR Configuration models:
With Bluetooth Mesh Protocol Specification version 1.1, it became possible to configure SAR
behavior, such as intervals, timers and retransmission counters, over a mesh network using SAR
Configuration models:
* :ref:`bluetooth_mesh_sar_cfg_cli`
* :ref:`bluetooth_mesh_sar_cfg_srv`
The following SAR behavior applies regardless of the presence of a SAR Configuration Server on a node.
The following SAR behavior applies regardless of the presence of a SAR Configuration Server on a
node.
Transmission of segments is separated by a segment transmission interval (see the `SAR Segment Interval Step`_ state).
Other configurable time intervals and delays available for the segmentation and reassembly are:
Transmission of segments is separated by a segment transmission interval (see the
`SAR Segment Interval Step`_ state). Other configurable time intervals and delays available for the
segmentation and reassembly are:
* Interval between unicast retransmissions (see the states `SAR Unicast Retransmissions Interval Step`_ and `SAR Unicast Retransmissions Interval Increment`_).
* Interval between multicast retransmissions (see the `SAR Multicast Retransmissions Interval Step`_ state).
* Segment reception interval (see the `SAR Receiver Segment Interval Step`_ state).
* Acknowledgment delay increment (see the `SAR Acknowledgment Delay Increment`_ state).
When the last segment marked as unacknowledged is transmitted, the lower transport layer starts a retransmissions timer.
The initial value of the SAR Unicast Retransmissions timer depends on the value of the TTL field of the message.
If the TTL field value is greater than ``0``, the initial value for the timer is set according to the following formula:
When the last segment marked as unacknowledged is transmitted, the lower transport layer starts a
retransmissions timer. The initial value of the SAR Unicast Retransmissions timer depends on the
value of the TTL field of the message. If the TTL field value is greater than ``0``, the initial
value for the timer is set according to the following formula:
.. math::
unicast~retransmissions~interval~step + unicast~retransmissions~interval~increment \times (TTL - 1)
If the TTL field value is ``0``, the initial value of the timer is set to the unicast retransmissions interval step.
If the TTL field value is ``0``, the initial value of the timer is set to the unicast
retransmissions interval step.
The initial value of the SAR Multicast Retransmissions timer is set to the multicast retransmissions interval.
The initial value of the SAR Multicast Retransmissions timer is set to the multicast retransmissions
interval.
When the lower transport layer receives a message segment, it starts a SAR Discard timer.
The discard timer tells how long the lower transport layer waits before discarding the segmented message the segment belongs to.
The initial value of the SAR Discard timer is the discard timeout value indicated by the `SAR Discard Timeout`_ state.
When the lower transport layer receives a message segment, it starts a SAR Discard timer. The
discard timer tells how long the lower transport layer waits before discarding the segmented message
the segment belongs to. The initial value of the SAR Discard timer is the discard timeout value
indicated by the `SAR Discard Timeout`_ state.
SAR Acknowledgment timer holds the time before a Segment Acknowledgment message is sent for a received segment.
The initial value of the SAR Acknowledgment timer is calculated using the following formula:
SAR Acknowledgment timer holds the time before a Segment Acknowledgment message is sent for a
received segment. The initial value of the SAR Acknowledgment timer is calculated using the
following formula:
.. math::
min(SegN + 0.5 , acknowledgment~delay~increment) \times segment~reception~interval
The ``SegN`` field value identifies the total number of segments the Upper Transport PDU is segmented into.
The ``SegN`` field value identifies the total number of segments the Upper Transport PDU is
segmented into.
Four counters are related to SAR behavior:
@ -117,8 +132,9 @@ Four counters are related to SAR behavior:
* Multicast retransmissions count (see `SAR Multicast Retransmissions Count`_ state)
* Acknowledgment retransmissions count (see `SAR Acknowledgment Retransmissions Count`_ state)
If the number of segments in the transmission is higher than the value of the `SAR Segments Threshold`_ state, Segment Acknowledgment messages are
retransmitted using the value of the `SAR Acknowledgment Retransmissions Count`_ state.
If the number of segments in the transmission is higher than the value of the
`SAR Segments Threshold`_ state, Segment Acknowledgment messages are retransmitted using the value
of the `SAR Acknowledgment Retransmissions Count`_ state.
.. _bt_mesh_sar_cfg_states:
@ -130,8 +146,8 @@ There are two states defined related to segmentation and reassembly:
* SAR Transmitter state
* SAR Receiver state
The SAR Transmitter state is a composite state that controls the number and timing of transmissions of segmented messages.
It includes the following states:
The SAR Transmitter state is a composite state that controls the number and timing of transmissions
of segmented messages. It includes the following states:
* SAR Segment Interval Step
* SAR Unicast Retransmissions Count
@ -141,8 +157,9 @@ It includes the following states:
* SAR Multicast Retransmissions Count
* SAR Multicast Retransmissions Interval Step
The SAR Receiver state is a composite state that controls the number and timing of Segment Acknowledgment transmissions and the discarding of reassembly of a segmented message.
It includes the following states:
The SAR Receiver state is a composite state that controls the number and timing of Segment
Acknowledgment transmissions and the discarding of reassembly of a segmented message. It includes
the following states:
* SAR Segments Threshold
* SAR Discard Timeout
@ -153,11 +170,11 @@ It includes the following states:
SAR Segment Interval Step
-------------------------
SAR Segment Interval Step state holds a value that controls the interval between transmissions of segments of a segmented message.
The interval is measured in milliseconds.
SAR Segment Interval Step state holds a value that controls the interval between transmissions of
segments of a segmented message. The interval is measured in milliseconds.
Use the :kconfig:option:`CONFIG_BT_MESH_SAR_TX_SEG_INT_STEP` Kconfig option to set the default value.
Segment transmission interval is then calculated using the following formula:
Use the :kconfig:option:`CONFIG_BT_MESH_SAR_TX_SEG_INT_STEP` Kconfig option to set the default
value. Segment transmission interval is then calculated using the following formula:
.. math::
@ -167,24 +184,29 @@ Segment transmission interval is then calculated using the following formula:
SAR Unicast Retransmissions Count
---------------------------------
SAR Unicast Retransmissions Count holds a value that defines the maximum number of retransmissions of a segmented message to a unicast destination.
Use the :kconfig:option:`CONFIG_BT_MESH_SAR_TX_UNICAST_RETRANS_COUNT` Kconfig option to set the default value for this state.
SAR Unicast Retransmissions Count holds a value that defines the maximum number of retransmissions
of a segmented message to a unicast destination. Use the
:kconfig:option:`CONFIG_BT_MESH_SAR_TX_UNICAST_RETRANS_COUNT` Kconfig option to set the default
value for this state.
SAR Unicast Retransmissions Without Progress Count
--------------------------------------------------
This state holds a value that defines the maximum number of retransmissions of a segmented message to a unicast address that will be sent if no acknowledgment
was received during the timeout, or if an acknowledgment with already confirmed segments was received.
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_TX_UNICAST_RETRANS_WITHOUT_PROG_COUNT` to set the maximum number of retransmissions.
This state holds a value that defines the maximum number of retransmissions of a segmented message
to a unicast address that will be sent if no acknowledgment was received during the timeout, or if
an acknowledgment with already confirmed segments was received. Use the Kconfig option
:kconfig:option:`CONFIG_BT_MESH_SAR_TX_UNICAST_RETRANS_WITHOUT_PROG_COUNT` to set the maximum number
of retransmissions.
SAR Unicast Retransmissions Interval Step
-----------------------------------------
The value of this state controls the interval step used for delaying the retransmissions of unacknowledged segments of a segmented message to a unicast address.
The interval step is measured in milliseconds.
The value of this state controls the interval step used for delaying the retransmissions of
unacknowledged segments of a segmented message to a unicast address. The interval step is measured
in milliseconds.
Use the :kconfig:option:`CONFIG_BT_MESH_SAR_TX_UNICAST_RETRANS_INT_STEP` Kconfig option to set the default value.
This value is then used to calculate the interval step using the following formula:
Use the :kconfig:option:`CONFIG_BT_MESH_SAR_TX_UNICAST_RETRANS_INT_STEP` Kconfig option to set the
default value. This value is then used to calculate the interval step using the following formula:
.. math::
@ -194,11 +216,13 @@ This value is then used to calculate the interval step using the following formu
SAR Unicast Retransmissions Interval Increment
----------------------------------------------
SAR Unicast Retransmissions Interval Increment holds a value that controls the interval increment used for delaying the retransmissions of unacknowledged
segments of a segmented message to a unicast address. The increment is measured in milliseconds.
SAR Unicast Retransmissions Interval Increment holds a value that controls the interval increment
used for delaying the retransmissions of unacknowledged segments of a segmented message to a unicast
address. The increment is measured in milliseconds.
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_TX_UNICAST_RETRANS_INT_INC` to set the default value.
The Kconfig option value is used to calculate the increment using the following formula:
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_TX_UNICAST_RETRANS_INT_INC` to set the
default value. The Kconfig option value is used to calculate the increment using the following
formula:
.. math::
@ -208,17 +232,19 @@ The Kconfig option value is used to calculate the increment using the following
SAR Multicast Retransmissions Count
-----------------------------------
The state holds a value that controls the total number of retransmissions of a segmented message to a multicast address.
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_TX_MULTICAST_RETRANS_COUNT` to set the total number of retransmissions.
The state holds a value that controls the total number of retransmissions of a segmented message to
a multicast address. Use the Kconfig option
:kconfig:option:`CONFIG_BT_MESH_SAR_TX_MULTICAST_RETRANS_COUNT` to set the total number of
retransmissions.
SAR Multicast Retransmissions Interval Step
-------------------------------------------
This state holds a value that controls the interval between retransmissions of all segments in a segmented message to a multicast address.
The interval is measured in milliseconds.
This state holds a value that controls the interval between retransmissions of all segments in a
segmented message to a multicast address. The interval is measured in milliseconds.
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_TX_MULTICAST_RETRANS_INT` to set the default value that is used to calculate the interval
using the following formula:
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_TX_MULTICAST_RETRANS_INT` to set the
default value that is used to calculate the interval using the following formula:
.. math::
@ -228,9 +254,10 @@ using the following formula:
SAR Discard Timeout
-------------------
The value of this state defines the time in seconds that the lower transport layer waits after receiving segments of a segmented message
before discarding that segmented message. Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_RX_DISCARD_TIMEOUT` to set the
default value. The discard timeout will be calculated using the following formula:
The value of this state defines the time in seconds that the lower transport layer waits after
receiving segments of a segmented message before discarding that segmented message. Use the Kconfig
option :kconfig:option:`CONFIG_BT_MESH_SAR_RX_DISCARD_TIMEOUT` to set the default value. The discard
timeout will be calculated using the following formula:
.. math::
@ -240,38 +267,47 @@ default value. The discard timeout will be calculated using the following formul
SAR Acknowledgment Delay Increment
----------------------------------
This state holds a value that controls the delay increment of an interval used for delaying the transmission of an acknowledgment message after receiving a new segment.
The increment is measured in segments.
This state holds a value that controls the delay increment of an interval used for delaying the
transmission of an acknowledgment message after receiving a new segment. The increment is measured
in segments.
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_RX_ACK_DELAY_INC` to set the default value. The increment value is calculated to be
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_RX_ACK_DELAY_INC` to set the default
value. The increment value is calculated to be
:math:`\verb|CONFIG_BT_MESH_SAR_RX_ACK_DELAY_INC| + 1.5`.
SAR Segments Threshold
----------------------
SAR Segments Threshold state holds a value that defines a threshold in number of segments of a segmented message for acknowledgment retransmissions.
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_RX_SEG_THRESHOLD` to set the threshold.
SAR Segments Threshold state holds a value that defines a threshold in number of segments of a
segmented message for acknowledgment retransmissions. Use the Kconfig option
:kconfig:option:`CONFIG_BT_MESH_SAR_RX_SEG_THRESHOLD` to set the threshold.
When the number of segments of a segmented message is above this threshold, the stack will additionally retransmit every acknowledgment message the
number of times given by the value of :kconfig:option:`CONFIG_BT_MESH_SAR_RX_ACK_RETRANS_COUNT`.
When the number of segments of a segmented message is above this threshold, the stack will
additionally retransmit every acknowledgment message the number of times given by the value of
:kconfig:option:`CONFIG_BT_MESH_SAR_RX_ACK_RETRANS_COUNT`.
SAR Acknowledgment Retransmissions Count
----------------------------------------
The SAR Acknowledgment Retransmissions Count state controls the number of retransmissions of Segment Acknowledgment messages sent by the lower transport layer.
It gives the total number of retranmissions of an acknowledgment message that the stack will additionally send when the size of segments in a
segmented message is above the :kconfig:option:`CONFIG_BT_MESH_SAR_RX_SEG_THRESHOLD` value.
The SAR Acknowledgment Retransmissions Count state controls the number of retransmissions of Segment
Acknowledgment messages sent by the lower transport layer. It gives the total number of
retranmissions of an acknowledgment message that the stack will additionally send when the size of
segments in a segmented message is above the :kconfig:option:`CONFIG_BT_MESH_SAR_RX_SEG_THRESHOLD`
value.
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_RX_ACK_RETRANS_COUNT` to set the default value for this state.
The maximum number of transmissions of a Segment Acknowledgment message is :math:`\verb|CONFIG_BT_MESH_SAR_RX_ACK_RETRANS_COUNT| + 1`.
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_RX_ACK_RETRANS_COUNT` to set the default
value for this state. The maximum number of transmissions of a Segment Acknowledgment message is
:math:`\verb|CONFIG_BT_MESH_SAR_RX_ACK_RETRANS_COUNT| + 1`.
SAR Receiver Segment Interval Step
----------------------------------
The SAR Receiver Segment Interval Step defines the segments reception interval step used for delaying the transmission of an acknowledgment message after receiving a new segment.
The interval is measured in milliseconds.
The SAR Receiver Segment Interval Step defines the segments reception interval step used for
delaying the transmission of an acknowledgment message after receiving a new segment. The interval
is measured in milliseconds.
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_RX_SEG_INT_STEP` to set the default value and calculate the interval using the following formula:
Use the Kconfig option :kconfig:option:`CONFIG_BT_MESH_SAR_RX_SEG_INT_STEP` to set the default value
and calculate the interval using the following formula:
.. math::

29
doc/connectivity/bluetooth/api/mesh/sar_cfg_cli.rst
View file

@ -3,26 +3,33 @@
SAR Configuration Client
########################
The SAR Configuration Client model is a foundation model defined by the Bluetooth mesh specification.
It is an optional model, enabled with the :kconfig:option:`CONFIG_BT_MESH_SAR_CFG_CLI` configuration option.
The SAR Configuration Client model is a foundation model defined by the Bluetooth mesh
specification. It is an optional model, enabled with the
:kconfig:option:`CONFIG_BT_MESH_SAR_CFG_CLI` configuration option.
The SAR Configuration Client model is introduced in the Bluetooth Mesh Protocol Specification version 1.1,
and it supports the configuration of the lower transport layer behavior of a node that supports the :ref:`bluetooth_mesh_sar_cfg_srv` model.
The SAR Configuration Client model is introduced in the Bluetooth Mesh Protocol Specification
version 1.1, and it supports the configuration of the lower transport layer behavior of a node that
supports the :ref:`bluetooth_mesh_sar_cfg_srv` model.
The model can send messages to query or change the states supported by the SAR Configuration Server (SAR Transmitter and SAR Receiver) using SAR Configuration messages.
The model can send messages to query or change the states supported by the SAR Configuration Server
(SAR Transmitter and SAR Receiver) using SAR Configuration messages.
The SAR Transmitter procedure is used to determine and configure the SAR Transmitter state of a SAR Configuration Server.
Function calls :c:func:`bt_mesh_sar_cfg_cli_transmitter_get` and :c:func:`bt_mesh_sar_cfg_cli_transmitter_set` are used to get and set the SAR Transmitter state
The SAR Transmitter procedure is used to determine and configure the SAR Transmitter state of a SAR
Configuration Server. Function calls :c:func:`bt_mesh_sar_cfg_cli_transmitter_get` and
:c:func:`bt_mesh_sar_cfg_cli_transmitter_set` are used to get and set the SAR Transmitter state
of the Target node respectively.
The SAR Receiver procedure is used to determine and configure the SAR Receiver state of a SAR Configuration Server.
Function calls :c:func:`bt_mesh_sar_cfg_cli_receiver_get` and :c:func:`bt_mesh_sar_cfg_cli_receiver_set` are used to get and set the SAR Receiver state of the
The SAR Receiver procedure is used to determine and configure the SAR Receiver state of a SAR
Configuration Server. Function calls :c:func:`bt_mesh_sar_cfg_cli_receiver_get` and
:c:func:`bt_mesh_sar_cfg_cli_receiver_set` are used to get and set the SAR Receiver state of the
Target node respectively.
For more information about the two states, see :ref:`bt_mesh_sar_cfg_states`.
An element can send any SAR Configuration Client message at any time to query or change the states supported by the SAR Configuration Server model of a peer node.
The SAR Configuration Client model only accepts messages encrypted with the device key of the node supporting the SAR Configuration Server model.
An element can send any SAR Configuration Client message at any time to query or change the states
supported by the SAR Configuration Server model of a peer node. The SAR Configuration Client model
only accepts messages encrypted with the device key of the node supporting the SAR Configuration
Server model.
If present, the SAR Configuration Client model must only be instantiated on the primary element.

15
doc/connectivity/bluetooth/api/mesh/sar_cfg_srv.rst
View file

@ -3,11 +3,13 @@
SAR Configuration Server
########################
The SAR Configuration Server model is a foundation model defined by the Bluetooth mesh specification.
It is an optional model, enabled with the :kconfig:option:`CONFIG_BT_MESH_SAR_CFG_SRV` configuration option.
The SAR Configuration Server model is a foundation model defined by the Bluetooth mesh
specification. It is an optional model, enabled with the
:kconfig:option:`CONFIG_BT_MESH_SAR_CFG_SRV` configuration option.
The SAR Configuration Server model is introduced in the Bluetooth Mesh Protocol Specification version 1.1,
and it supports the configuration of the :ref:`segmentation and reassembly (SAR) <bluetooth_mesh_sar_cfg>` behavior of a Bluetooth mesh node.
The SAR Configuration Server model is introduced in the Bluetooth Mesh Protocol Specification
version 1.1, and it supports the configuration of the
:ref:`segmentation and reassembly (SAR) <bluetooth_mesh_sar_cfg>` behavior of a Bluetooth mesh node.
The model defines a set of states and messages for the SAR configuration.
The SAR Configuration Server model defines two states, SAR Transmitter state and SAR Receiver state.
@ -15,8 +17,9 @@ For more information about the two states, see :ref:`bt_mesh_sar_cfg_states`.
The model also supports the SAR Transmitter and SAR Receiver get and set messages.
The SAR Configuration Server model does not have an API of its own, but relies on a :ref:`bluetooth_mesh_sar_cfg_cli` to control it.
The SAR Configuration Server model only accepts messages encrypted with the node’s device key.
The SAR Configuration Server model does not have an API of its own, but relies on a
:ref:`bluetooth_mesh_sar_cfg_cli` to control it. The SAR Configuration Server model only accepts
messages encrypted with the node’s device key.
If present, the SAR Configuration Server model must only be instantiated on the primary element.

447
doc/connectivity/bluetooth/api/mesh/shell.rst
View file

File diff suppressed because it is too large Load diff

20
doc/connectivity/bluetooth/api/mesh/srpl_cli.rst
View file

@ -4,14 +4,16 @@ Solicitation PDU RPL Configuration Client
#########################################
The Solicitation PDU RPL Configuration Client model is a foundation model defined by the Bluetooth
mesh specification. The model is optional, and is enabled through the :kconfig:option:`CONFIG_BT_MESH_SOL_PDU_RPL_CLI` option.
mesh specification. The model is optional, and is enabled through the
:kconfig:option:`CONFIG_BT_MESH_SOL_PDU_RPL_CLI` option.
The Solicitation PDU RPL Configuration Client model was introduced in the Bluetooth Mesh Protocol
Specification version 1.1, and supports the functionality of removing addresses from the solicitation
replay protection list (SRPL) of a node that supports the :ref:`bluetooth_mesh_srpl_srv` model.
Specification version 1.1, and supports the functionality of removing addresses from the
solicitation replay protection list (SRPL) of a node that supports the
:ref:`bluetooth_mesh_srpl_srv` model.
The Solicitation PDU RPL Configuration Client model communicates with a Solicitation PDU RPL Configuration Server model
using the application keys configured by the Configuration Client.
The Solicitation PDU RPL Configuration Client model communicates with a Solicitation PDU RPL
Configuration Server model using the application keys configured by the Configuration Client.
If present, the Solicitation PDU RPL Configuration Client model must only be instantiated on the
primary element.
@ -19,9 +21,11 @@ primary element.
Configurations
**************
The Solicitation PDU RPL Configuration Client model behavior can be configured with the transmission timeout option :kconfig:option:`CONFIG_BT_MESH_SOL_PDU_RPL_CLI_TIMEOUT`.
The :kconfig:option:`CONFIG_BT_MESH_SOL_PDU_RPL_CLI_TIMEOUT` controls how long the Solicitation PDU RPL Configuration Client waits
for a response message to arrive in milliseconds. This value can be changed at runtime using :c:func:`bt_mesh_sol_pdu_rpl_cli_timeout_set`.
The Solicitation PDU RPL Configuration Client model behavior can be configured with the transmission
timeout option :kconfig:option:`CONFIG_BT_MESH_SOL_PDU_RPL_CLI_TIMEOUT`. The
:kconfig:option:`CONFIG_BT_MESH_SOL_PDU_RPL_CLI_TIMEOUT` controls how long the Solicitation PDU RPL
Configuration Client waits for a response message to arrive in milliseconds. This value can be
changed at runtime using :c:func:`bt_mesh_sol_pdu_rpl_cli_timeout_set`.
API reference
*************

16
doc/connectivity/bluetooth/api/mesh/srpl_srv.rst
View file

@ -7,12 +7,14 @@ The Solicitation PDU RPL Configuration Server model is a foundation model define
mesh specification. The model is enabled if the node has the :ref:`bluetooth_mesh_od_srv` enabled.
The Solicitation PDU RPL Configuration Server model was introduced in the Bluetooth Mesh Protocol
Specification version 1.1, and manages the Solicitation Replay Protection List (SRPL) saved on the device.
The SRPL is used to reject Solicitation PDUs that are already processed by a node. When a valid Solicitation PDU message is
successfully processed by a node, the SSRC field and SSEQ field of the message are stored in the node's SRPL.
Specification version 1.1, and manages the Solicitation Replay Protection List (SRPL) saved on the
device. The SRPL is used to reject Solicitation PDUs that are already processed by a node. When a
valid Solicitation PDU message is successfully processed by a node, the SSRC field and SSEQ field
of the message are stored in the node's SRPL.
The Solicitation PDU RPL Configuration Server does not have an API of its own, and relies on a :ref:`bluetooth_mesh_srpl_cli` to control it.
The model only accepts messages encrypted with an application key as configured by the Configuration Client.
The Solicitation PDU RPL Configuration Server does not have an API of its own, and relies on a
:ref:`bluetooth_mesh_srpl_cli` to control it. The model only accepts messages encrypted with an
application key as configured by the Configuration Client.
If present, the Solicitation PDU RPL Configuration Server model must only be instantiated on the
primary element.
@ -20,7 +22,9 @@ primary element.
Configurations
**************
For the Solicitation PDU RPL Configuration Server model, the :kconfig:option:`CONFIG_BT_MESH_PROXY_SRPL_SIZE` option can be configured to set the size of the SRPL.
For the Solicitation PDU RPL Configuration Server model, the
:kconfig:option:`CONFIG_BT_MESH_PROXY_SRPL_SIZE` option can be configured to set the size of the
SRPL.
API reference
*************