NOTE:
See Building the mesh stack and examples for information on how to download and install the nRF5 SDK.
When using Segger Embedded Studio, resources from nRF5 SDK can be included in an existing mesh project by simply adding code files and include paths to the corresponding SES project file.
When building the nRF5 SDK for Mesh stack using CMake, resources from nRF5 SDK can be included by simply adding code files and include paths to the corresponding CMakeLists.txt file. The SDK_ROOT root symbol is used to refer to the nRF5 SDK installation folder (see e.g. CMakeLists.txt in the Light Switch Server example).
Include the following source files from nRF5 SDK for Mesh in the nRF5 SDK example's project file:
mesh/core/src
mesh/bearer/src
mesh/prov/src
except nrf_mesh_prov_bearer_gatt.cmesh/access/src
mesh/dfu/src
mesh/stack/src
models/foundation/config/src/config_server.c
models/foundation/config/src/composition_data.c
models/foundation/config/src/packed_index_list.c
models/foundation/health/src/health_server.c
external/micro-ecc/uECC.c
examples/common/src/assertion_handler_weak.c
examples/common/src/mesh_provisionee.c
NOTE: If various mesh features are not needed (like e.g. DFU), the corresponding files may simply be omitted from the project file. Then examples/nrf_mesh_weak.c
must be added in their place to provide stubs for the missing API functions.
Add the following folders to the nRF5 SDK example's project include path:
mesh/core/api
mesh/core/include
mesh/bearer/api
mesh/bearer/include
mesh/prov/api
mesh/prov/include
mesh/access/api
mesh/access/include
mesh/dfu/api
mesh/dfu/include
mesh/stack/api
models/foundation/config/include
models/foundation/health/include
external/micro-ecc
examples/common/include
Add the following preprocessor symbols to the nRF5 SDK example's project file:
NRF52_SERIES
NRF_MESH_LOG_ENABLE=NRF_LOG_USES_RTT
(because the logging in the mesh stack relies on RTT)CONFIG_APP_IN_CORE
NOTE: Examples using the simple_hal
module in the mesh stack may need to be updated to use the Nordic nRF5 SDK bsp
module if integrated with the nRF5 SDK. It is possible to use both, but in this case GPIOTE_IRQHandler
must be removed from one of them, and only one of the modules may register callback functions.
If the original Nordic nRF5 SDK example uses the SoftDevice, make sure that the mesh stack is initialized and enabled after the SoftDevice is enabled. In that case, SoftDevice events must be forwarded to the mesh stack. Add the following code to your application:
Flash storage of network configuration is enabled by default in the mesh stack as well as in some of the Nordic nRF5 SDK applications. The flash areas used for this purpose may overlap and cause errors. To allow safe coexistence of the flash storage module Flash manager in the mesh stack and the flash storage module fstorage
in the Nordic nRF5 SDK, add the following code block to nrf_mesh_config_app.h
:
NOTE: If you are adding you own mesh functionality rather than working from an existing mesh example, you also need to add the file nrf_mesh_config_app.h. Copy it from the examples/templates folder in mesh stack repository into your project folder, and remove #error
message at the top of the file. Make other appropriate changes to the file content, like adjusting ACCESS_ELEMENT_COUNT
and ACCESS_MODEL_COUNT
to the required number of elements and models.
Using nRF5 SDK modules such as fstorage
, pstorage
, or ble_flash
for writing to flash may be problematic due to long timeslot
events occupied by the mesh stack. Use the Flash manager module provided by the mesh stack instead.
Furthermore, when writing to flash, ensure to not write or erase areas utilized by the mesh stack modules and the bootloader (if present). By default, the mesh modules utilize the last x
number of pages before the start of the bootloader, if present, or the last x
number of pages of the available flash on the Nordic SoC. The value of x
depends on the configuration of the mesh stack and can be calculated by:
x = 2 + ACCESS_FLASH_PAGE_COUNT + DSM_FLASH_PAGE_COUNT
ACCESS_FLASH_PAGE_COUNT
shall be equal to or greater than
(1 + ((DATA_SIZE) / (FLASH_MANAGER_DATA_PER_PAGE - LARGEST_ENTRY_SIZE)))
where:
DATA_SIZE
is (ALIGN_VAL((sizeof(fm_header_t) + sizeof(access_model_state_data_t)), WORD_SIZE) * ACCESS_MODEL_COUNT) + (ALIGN_VAL((sizeof(fm_header_t) + sizeof(access_flash_subscription_list_t)), WORD_SIZE) * ACCESS_SUBSCRIPTION_LIST_COUNT) + (ALIGN_VAL((sizeof(fm_header_t) + sizeof(uint16_t)), WORD_SIZE) * ACCESS_ELEMENT_COUNT) +
ALIGN_VAL
returns the total field size aligned to WORD boundaries.FLASH_MANAGER_DATA_PER_PAGE
is (PAGE_SIZE - sizeof(flash_manager_metadata_t))
LARGEST_ENTRY_SIZE
is ACCESS_MODEL_STATE_FLASH_SIZE
DSM_FLASH_PAGE_COUNT
shall be equal to or greater than
(1 + ((DATA_SIZE) / (FLASH_MANAGER_DATA_PER_PAGE - LARGEST_ENTRY_SIZE)))
where:
DATA_SIZE
is (ALIGN_VAL((sizeof(fm_header_t) + sizeof(dsm_flash_entry_addr_unicast_t)), WORD_SIZE) + ALIGN_VAL((sizeof(fm_header_t) + sizeof(dsm_flash_entry_addr_nonvirtual_t)), WORD_SIZE) * DSM_NONVIRTUAL_ADDR_MAX + ALIGN_VAL((sizeof(fm_header_t) + sizeof(dsm_flash_entry_addr_virtual_t)), WORD_SIZE) * DSM_VIRTUAL_ADDR_MAX + ALIGN_VAL((sizeof(fm_header_t) + sizeof(dsm_flash_entry_subnet_t)), WORD_SIZE) * DSM_SUBNET_MAX + ALIGN_VAL((sizeof(fm_header_t) + sizeof(dsm_flash_entry_devkey_t)), WORD_SIZE) * DSM_DEVICE_MAX + ALIGN_VAL((sizeof(fm_header_t) + sizeof(dsm_flash_entry_appkey_t)), WORD_SIZE) * DSM_APP_MAX)
FLASH_MANAGER_DATA_PER_PAGE
is (PAGE_SIZE - sizeof(flash_manager_metadata_t))
LARGEST_ENTRY_SIZE
is (sizeof(fm_header_t) + sizeof(dsm_flash_entry_t))
The following are estimated sizes based on the Light switch server example, built using Keil v5 with optimization level O3
for nRF52832.
Definitions
Definition | Value |
---|---|
ACCESS_MODEL_COUNT | 3 |
ACCESS_SUBSCRIPTION_LIST_COUNT | 1 |
ACCESS_ELEMENT_COUNT | 1 |
DSM_NONVIRTUAL_ADDR_MAX | 3 |
DSM_VIRTUAL_ADDR_MAX | 1 |
DSM_SUBNET_MAX | 1 |
DSM_DEVICE_MAX | 1 |
DSM_APP_MAX | 1 |
Base sizes
Structure/union | Size in bytes |
---|---|
fm_header_t | 4 |
access_model_state_data_t | 20 |
access_flash_subscription_list_t | 4 |
dsm_local_unicast_address_t | 4 |
dsm_flash_entry_addr_nonvirtual_t | 2 |
dsm_flash_entry_addr_virtual_t | 16 |
dsm_flash_entry_subnet_t | 36 |
dsm_flash_entry_devkey_t | 20 |
dsm_flash_entry_appkey_t | 36 |
flash_manager_metadata_t | 8 |
dsm_flash_entry_t | 36 |
Results
Count name | Value |
---|---|
ACCESS_FLASH_PAGE_COUNT | 1 |
DSM_FLASH_PAGE_COUNT | 1 |
Total page count | 4 |
The transport layer uses malloc() for its operation. This behavior can be overridden using transport_sar_mem_funcs_set(), otherwise __HEAP_SIZE needs to be defined.
If you are using SES for building the application set the Heap Size to 8192 bytes in the Project Options> Code> Runtime Memory Area settings.
By design, the SoftDevice activity is prioritized over mesh activity. Therefore, you should keep the connection and advertisement intervals used by the SoftDevice as large as possible when using Bluetooth low energy connections. If scanning, keep the scan intervals as long as possible, and the scan windows as short as possible. You should also reduce mesh activity while the SoftDevice is doing fast advertising and continue normal activity after a connection is established.
See Coexistence with nRF5 SDK examples to see how the nRF5 SDK features can be simultaneously used with nRF5 SDK for Mesh.