BLE Mesh Network (rm_ble_mesh)

Functions
fsp_err_t	RM_BLE_MESH_Open (rm_ble_mesh_ctrl_t *const p_ctrl, rm_ble_mesh_cfg_t const *const p_cfg)
fsp_err_t	RM_BLE_MESH_Close (rm_ble_mesh_ctrl_t *const p_ctrl)
fsp_err_t	RM_BLE_MESH_StartTransitionTimer (rm_ble_mesh_ctrl_t *const p_ctrl, rm_ble_mesh_access_state_transition_t const *const p_transition, uint16_t *const p_transition_time_handle)
fsp_err_t	RM_BLE_MESH_StopTransitionTimer (rm_ble_mesh_ctrl_t *const p_ctrl, uint16_t transition_time_handle)
fsp_err_t	RM_BLE_MESH_GetRemainingTransitionTime (rm_ble_mesh_ctrl_t *const p_ctrl, uint16_t transition_time_handle, uint8_t *const p_remaining_transition_time)
fsp_err_t	RM_BLE_MESH_GetRemainingTransitionTimeWithOffset (rm_ble_mesh_ctrl_t *const p_ctrl, uint16_t transition_time_handle, uint32_t offset_in_ms, uint8_t *const p_remaining_transition_time)
fsp_err_t	RM_BLE_MESH_ConvertTransitionTimeFromMs (rm_ble_mesh_ctrl_t *const p_ctrl, uint32_t transition_time_in_ms, uint8_t *const p_transition_time)
fsp_err_t	RM_BLE_MESH_ConvertTransitionTimeToMs (rm_ble_mesh_ctrl_t *const p_ctrl, uint8_t transition_time, uint32_t *const p_transition_time_in_ms)

Detailed Description

Overview

Bluetooth Mesh defines a managed-flood-based mesh network. Any device in the network can send a message at any time as long as there is a sufficient density of devices that are listening and relaying messages. See sample application document and start up guide for information on how to create a BLE MESH application.

Overview Of Bletooth Mesh

Features

The BLE Mesh middleware has the following features:

• Supports one-to-one and one-to-many message transmission
• Supports relay messages to other nodes
• Supports secure message transmission against the following attack
  • Wiretap attack
  • Man-in-the-middle attack
  • Replay attack
  • Trash-can attack
  • Brute Force Key attack
• Supports following optional features
  • Supports Relay feature
  • Supports Proxy feature
  • Supports Friend feature
  • Supports Low Power feature

Target Devices

The BLE Mesh Network module supports the following devices.

• RA4W1

Configuration

Build Time Configurations for rm_ble_mesh

The following build time configurations are defined in fsp_cfg/rm_ble_mesh_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enable Disable	Default (BSP)	Specify whether to include code for API parameter checking. Valid settings include.

Configurations for Networking > BLE Mesh Network modules > BLE Mesh (rm_ble_mesh)

This module can be added to the Stacks tab via New Stack > Networking > BLE Mesh Network modules > BLE Mesh (rm_ble_mesh).

Configuration	Options	Default	Description
General
Name	Name Must Be a Valid C Symbol	g_rm_ble_mesh0	Module name.
Channel Number	Invalid Channel Number	0	Select channel corresponding to the channel number of the hardware.
Bearer
Network Interface Number	Invalid Network Interface Number	2	Network interfaces number.
Provisioning Interface Number	Invalid Provisioning Interface Number	2	Provisioning interfaces number.
Provisioning
Unprovisioned Device Beacon Timeout in Milliseconds	Invalid Unprovisioned Device Beacon Timeout in Milliseconds	200	Unprovisioned device beacon timeout in milliseconds.
Network
Network Cache Size	Invalid Network Cache Size	10	Network cache size.
Network Sequence Number Cache Size	Invalid Network Sequence Number Cache Size	32	Network sequence number cache size.
Maximum Number of Subnet	Invalid Maximum Number of Subnets	4	Maximum number of subnets
Maximum Number of Device Key	Invalid Maximum Number of Device Keys	4	Maximum number of device keys.
Proxy Filter List Size	Invalid Proxy Filter List Size	2	Maximum number of addresses present in each proxy filter list.
Network Sequence Number Block Size	Invalid Network Sequence Number Block Size	2048	The distance between the network sequence numbers, for every persistent storage write.
Network Transmit Count for Network Packets	Invalid Network Transmit Count for Network Packets	1	Network transmit count for network packets.
Network Interval Steps for Network Packets	Invalid Network Interval Steps for Network Packets	4	Network interval steps for network packets.
Network Transmit Count for Relayed Packets	Invalid Network Transmit Count for Relayed Packets	0	Network transmit count for relayed packets.
Network Interval Steps for Relayed Packets	Invalid Network Interval Steps for Relayed Packets	9	Network interval steps for relayed packets.
Proxy ADV Network ID Timeout for Each Subnet in Milliseconds.	Invalid Proxy ADV Network ID Timeout	100	Proxy ADV network ID timeout for each subnet in milliseconds.
Proxy ADV Node Identity Timeout for Each Subnet in Milliseconds	Invalid Proxy ADV Node Identity Timeout for Each Subnet in Milliseconds	300	Proxy ADV node identity timeout for each subnet in milliseconds.
Proxy ADV Node Identity Overall Time Period in Seconds	Invalid Proxy ADV Node Identity Overall Time Period in Seconds	60	Proxy ADV node identity overall time period in seconds.
Maximum Number of Queued Messages for Transmission	Invalid Maximum Number of Queued Messages for Transmission	64	Maximum number of queued messages for transmission.
Transport
Maximum Number of LPN	Invalid Maximum Number of LPNs	1	Maximum number of LPNs.
Replay Protection Cache Size	Invalid Replay Protection Cache Size	10	Replay protection cache size.
Reassembled Cache Size	Invalid Reassembled Cache Size	8	Reassembled cach size.
Friend Poll Retry Count	Invalid Friend Poll Retry Count	10	Friend poll retry count.
Maximum Number of Segmentation and Reassembly Context	Invalid Maximum Number of Segmentation and Reassembly Context	8	Number of segmentation and reassembly contexts.
Lower Transport Segment Transmission Timeout in Milliseconds	Invalid Lower Transport Segment Transmission Timeout in Milliseconds	300	Lower transport segment transmission timeout in milliseconds.
Lower Transport Segment Re-Transmission Count	Invalid Lower Transport Segment Re-Transmission Count	2	Lower transport segment re-transmission count.
Lower Transport Acknowledgement Timeout in Milliseconds	Invalid Lower Transport Acknowledgement Timeout in Milliseconds	200	Lower transport acknowledgement timeout in milliseconds.
Lower Transport Incomplete Timeout in Seconds	Invalid Lower Transport Incomplete Timeout in Seconds	20	Lower transport incomplete timeout in seconds.
Friendship Receive Window	Invalid Friendship Receive Window	100	Friendship receive window.
Maximum Number of Friend Message Queue	Invalid Maximum Number of Friend Messages Queue	15	Maximum number of messages that the friend is capabale to queue for a single Low Power Node.
Maximum Number of Friend Subscription List	Invalid Maximum Number of Friend Subscription List	8	Maximum number of subscription addresses that the friend is capable to store for a single Low Power Node.
Friend Clear Confirmation Timeout in Milliseconds	Invalid Friend Clear Confirmation Timeout in Milliseconds	1000	Friend clear confirmation timeout in milliseconds.
Friend Clear Retry Count	Invalid Friend Clear Retry Count	5	Friend clear retry count.
Friendship Retry Timeout in Milliseconds	Invalid Friendship Retry Timeout in Milliseconds	1200	Friendship retry timeout in milliseconds.
Access
Maximum Number of Element	Invalid Maximum Number of Element	4	Maximum number of elements.
Maximum Number of Model	Invalid Maximum Number of Model	60	Maximum number of models.
Maximum Number of Application	Invalid Maximum Number of Application	8	Maximum number of applications (keys) the device can store information about.
Maximum Number of Virtual Address	Invalid Maximum Number of Virtual Address	8	Maximum number of virtual addresses the device can store information about.
Maximum Number of Non-Virtual Address	Invalid Maximum Number of Non-Virtual Address	8	Maximum number of non-virtual addresses the device can store information about.
Maximum Number of Transition Timers	Invalid Maximum Number of Transition Timers	5	Maximum number of transition timers.
Maximum Number of Periodic Step Timers	Invalid Maximum Number of Periodic Step Timers	5	Maximum number of periodic step timers.
Foundation
Config Server Secure Network Beacon Interval	Invalid Config Server Secure Network Beacon Interval	10	Config server secure network beacon interval.
Maximum Number of Health Server Instance	Invalid Maximum Number of Health Server Instance	2	Maximum number of health server instances.
Model
Maximum Number of Light Lightness Controller Server Instance	Invalid Maximum Number of Light Lightness Controller Server Instance	1	Maximum number of light lightness controller server instances.
ID
Company ID	Invalid Company ID	0x0036	Company ID.
Product ID	Invalid Product ID	0x0001	Product ID.
Vendor ID	Invalid Vendor ID	0x0100	Vendor ID.
Platform
Platform > Storage
Block Number	Invalid Block Number	5	Block number.
Platform > Memory Pool
Memory Pool Size	Invalid Memory Pool Size	0x4000	Memory pool size.
Platform > Logging
Packet Bitfield	Network Lower Trans Upper Trans Access		Specifies if this is included in the packet_bitfield mask.
Module Info Bitfield	Network Lower Trans Upper Trans Access		Specifies if this is included in the module information bitfield mask.
Generic Log Bitfield	Network Lower Trans Upper Trans Access		Specifies if this is included in the generic log bitfield mask.
function	Name Must Be a Valid C Symbol	NULL

Clock Configuration

Note

System clock (ICLK): 8 MHz or more

Peripheral module clock A (PCLKA): 8MHz or more

The BLE Protocol Stack is optimized for ICLK and PCLKA frequencies of 32 MHz.

It is recommended that the clock be set so that the ICLK and PCLKA frequencies are 32MHz in order to get the best performance from the BLE.

Pin Configuration

This module does not use I/O pins.

Usage Notes

Mesh System Architecture

Purpose of each layer is,

Model layer

Model is a standardized typical functionality so that nodes perform operations in accordance with application scenario.

Foundation Model layer

Foundation Models are models to configure and manage operations of elements.

Access layer

The access layer defines how higher layer applications can use the upper transport layer.

Upper transport layer

The upper transport layer encrypts, decrypts, and authenticates application data and is designed to provide confidentiality of access messages.

Lower transport layer

The lower transport layer defines how upper transport layer messages are segmented and reassembled into multiple Lower Transport PDUs to deliver large upper transport layer messages to other nodes.

Network layer

The network layer defines how transport messages are addressed towards one or more elements.

Bearer layer

The bearer layer defines how network messages are transported between nodes.

Device Life Cycle

The device not joined in the mesh network is an Unprovisioned Device and the device joined in the mesh network is called a Node.

• Unprovisioned Device
  Unprovisioned device cannot send or receive mesh messages. However, it will advertise its presence to the provisioner. By the provisioner, Unprovisioned Devices are invited to join the mesh network and become nodes(Provisioning).
• Node
  Nodes can send and receive mesh messages. It is managed by the configuration client through the mesh network, which configures how the nodes communicate. The configuration client can also remove a Node from the mesh network, which will return the node to an Unprovisioned Device.

To communicate with other nodes by using Models, each node needs Configuration. By Configuration process, information required for Model operation such as Application Keys, Publish Address, Subscription Address is configured. Following shows a typical lifecycle of a node.

Device Life Cycle Image

Newly introduced device is provisioned by Provisioner and joins a network. Furthermore, this device is configured by Configuration Client and becomes to be able to communicate with other nodes with Mesh Model. Generally, Configuration Client is a smart phone or other mobile computing device. Configuration Client removes a node from a network by sending Config Node Reset message. Besides, Configuration Client updates encryption keys used in the network, and the removed node becomes unable to communicate with other nodes.

Examples

BLE_MESH Basic Example

This is a basic example of minimal use of the BLE_MESH in an application.

License and Copyright Notice

Mesh library includes crackle. The license and copyright of crackle are as follows.

BSD 2-Clause License

Copyright (c) 2013-2018, Mike Ryan
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Data Structures
struct	rm_ble_mesh_instance_ctrl_t

---

Data Structure Documentation

rm_ble_mesh_instance_ctrl_t

struct rm_ble_mesh_instance_ctrl_t

RM_BLE_MESH_BEARER private control block. DO NOT MODIFY. Initialization occurs when RM_BLE_MESH_BEARER_Open() is called.

Function Documentation

RM_BLE_MESH_Open()

fsp_err_t RM_BLE_MESH_Open	(	rm_ble_mesh_ctrl_t *const	p_ctrl,
		rm_ble_mesh_cfg_t const *const	p_cfg
	)

Open ble mesh middleware. API to initialize Mesh Stack. This is the first API that the application should call before any other API. This function initializes all the internal stack modules and data structures.

Implements rm_ble_mesh_api_t::open.

Example:

    /* Open the module. */
    err = RM_BLE_MESH_Open(&g_ble_mesh0_ctrl, &g_ble_mesh0_cfg);

Return values

FSP_SUCCESS	Module opened successfully.
FSP_ERR_ASSERTION	Pointer to control block or configuration structure is NULL.
FSP_ERR_ALREADY_OPEN	Module is already open.

RM_BLE_MESH_Close()

fsp_err_t RM_BLE_MESH_Close

(

rm_ble_mesh_ctrl_t *const

p_ctrl

)

Close ble mesh middleware. API to turn off Bluetooth Hardware. This API should be called after RM_BLE_MESH_Open.

Implements rm_ble_mesh_api_t::close.

Example:

    /* Close the module. */
    err = RM_BLE_MESH_Close(&g_ble_mesh0_ctrl);

Return values

FSP_SUCCESS	Module successfully closed.
FSP_ERR_ASSERTION	The parameter p_ctrl is NULL.
FSP_ERR_NOT_OPEN	Module is not open.

RM_BLE_MESH_StartTransitionTimer()

fsp_err_t RM_BLE_MESH_StartTransitionTimer	(	rm_ble_mesh_ctrl_t *const	p_ctrl,
		rm_ble_mesh_access_state_transition_t const *const	p_transition,
		uint16_t *const	p_transition_time_handle
	)

To start transition timer. API to start a transition timer.

Implements rm_ble_mesh_api_t::startTransitionTimer.

Example:

    /* Start transition timer. */
    err = RM_BLE_MESH_StartTransitionTimer(&g_ble_mesh0_ctrl, &transition, &transition_time_handle);

Return values

FSP_SUCCESS	Operation succeeded.
FSP_ERR_ASSERTION	The parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTER	The parameter p_transition is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_OUT_OF_MEMORY	Memory allocation is failed.
FSP_ERR_OVERFLOW	TX queue is full.

RM_BLE_MESH_StopTransitionTimer()

fsp_err_t RM_BLE_MESH_StopTransitionTimer	(	rm_ble_mesh_ctrl_t *const	p_ctrl,
		uint16_t	transition_time_handle
	)

To stop transition timer. API to stop a transition timer.

Implements rm_ble_mesh_api_t::stopTransitionTimer.

Example:

    /* Stop transition timer. */
    err = RM_BLE_MESH_StopTransitionTimer(&g_ble_mesh0_ctrl, transition_time_handle);

Return values

FSP_SUCCESS	Operation succeeded.
FSP_ERR_ASSERTION	The parameter p_ctrl is NULL.
FSP_ERR_NOT_OPEN	Module is not open.

RM_BLE_MESH_GetRemainingTransitionTime()

fsp_err_t RM_BLE_MESH_GetRemainingTransitionTime	(	rm_ble_mesh_ctrl_t *const	p_ctrl,
		uint16_t	transition_time_handle,
		uint8_t *const	p_remaining_transition_time
	)

To get remaining Transition Time. API to get remaining Transition Time.

Implements rm_ble_mesh_api_t::getRemainingTransitionTime.

Example:

    /* Get remaining transition time. */
    err = RM_BLE_MESH_GetRemainingTransitionTime(&g_ble_mesh0_ctrl, transition_time_handle, &remaining_transition_time);

Return values

FSP_SUCCESS	Operation succeeded.
FSP_ERR_ASSERTION	The parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTER	The parameter p_remaining_transition_time is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_UNDERFLOW	TX queue is empty.
FSP_ERR_NOT_FOUND	Input parameter is not found.

RM_BLE_MESH_GetRemainingTransitionTimeWithOffset()

fsp_err_t RM_BLE_MESH_GetRemainingTransitionTimeWithOffset	(	rm_ble_mesh_ctrl_t *const	p_ctrl,
		uint16_t	transition_time_handle,
		uint32_t	offset_in_ms,
		uint8_t *const	p_remaining_transition_time
	)

To get remaining Transition Time, with offset. API to get remaining Transition Time with offset in ms.

Implements rm_ble_mesh_api_t::getRemainingTransitionTimeWithOffset.

Example:

    /* Get remaining transition time with offset. */
    err = RM_BLE_MESH_GetRemainingTransitionTimeWithOffset(&g_ble_mesh0_ctrl,
                                                           transition_time_handle,
                                                           offset_in_ms,
                                                           &remaining_transition_time);

Return values

FSP_SUCCESS	Operation succeeded.
FSP_ERR_ASSERTION	The parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTER	The parameter p_remaining_transition_time is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_UNDERFLOW	TX queue is empty.
FSP_ERR_NOT_FOUND	Input parameter is not found.

RM_BLE_MESH_ConvertTransitionTimeFromMs()

fsp_err_t RM_BLE_MESH_ConvertTransitionTimeFromMs	(	rm_ble_mesh_ctrl_t *const	p_ctrl,
		uint32_t	transition_time_in_ms,
		uint8_t *const	p_transition_time
	)

To convert transition time from milisecond. API to convert transition timer in milisecond to Generic Default Transition Time state format.

Implements rm_ble_mesh_api_t::convertTransitionTimeFromMs.

Example:

    /* Convert transition time from milliseconds. */
    err = RM_BLE_MESH_ConvertTransitionTimeFromMs(&g_ble_mesh0_ctrl, transition_time_in_ms, &transition_time);

Return values

FSP_SUCCESS	Operation succeeded.
FSP_ERR_ASSERTION	The parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTER	The parameter p_transition_time is NULL.
FSP_ERR_NOT_OPEN	Module is not open.

RM_BLE_MESH_ConvertTransitionTimeToMs()

fsp_err_t RM_BLE_MESH_ConvertTransitionTimeToMs	(	rm_ble_mesh_ctrl_t *const	p_ctrl,
		uint8_t	transition_time,
		uint32_t *const	p_transition_time_in_ms
	)

To convert transition time to milisecond. API to convert Generic Default Transition Time state format to required transition time value in miliseconds.

Implements rm_ble_mesh_api_t::convertTransitionTimeToMs.

Example:

    /* Convert transition time to milliseconds. */
    err = RM_BLE_MESH_ConvertTransitionTimeToMs(&g_ble_mesh0_ctrl, transition_time, &transition_time_in_ms);

Return values

FSP_SUCCESS	Operation succeeded.
FSP_ERR_ASSERTION	The parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTER	The parameter p_transition_time_in_ms is NULL.
FSP_ERR_NOT_OPEN	Module is not open.