doc: Bluetooth: Mesh: Fix line width to 100 in mesh docs
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:
parent
977ad483b4
commit
b2c163e108
23 changed files with 1082 additions and 466 deletions
|
@ -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::
|
||||
|
||||
|
|
|
@ -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
|
||||
*************
|
||||
|
|
|
@ -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
|
||||
*************
|
||||
|
|
|
@ -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
|
||||
*************
|
||||
|
|
|
@ -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
|
||||
*************
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
*************
|
||||
|
|
|
@ -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
|
||||
*************
|
||||
|
|
|
@ -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
|
||||
*************
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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
|
||||
*************
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
*************
|
||||
|
|
|
@ -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
|
||||
*************
|
||||
|
|
|
@ -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::
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
File diff suppressed because it is too large
Load diff
|
@ -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
|
||||
*************
|
||||
|
|
|
@ -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
|
||||
*************
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue