Contains common defines, structures, and functions used by the Mesh Models. More...

Data Structures
struct	model_transition_t
	Generic Transition parameters for the model messages. More...

struct	tid_tracker_t
	Structure for tracking TID expiry for the models. More...

struct	model_timer_t
	Structure for model timers. More...

Macros
#define	GENERIC_DTT_SERVER_INSTANCES_MAX (0)
	The number of the Generic Default Transition Time Server (independent, root only) instances used by the application.

#define	GENERIC_LEVEL_SERVER_INSTANCES_MAX (0)
	The number of the Generic Level Server (independent, root only) instances used by the application.

#define	GENERIC_ONOFF_SERVER_INSTANCES_MAX (0)
	The number of the Generic OnOff Server (independent, root only) instances used by the application.

#define	LIGHT_LIGHTNESS_SETUP_SERVER_INSTANCES_MAX (0)
	The number of the Light Lightness Setup Server instances used by the application.

#define	LIGHT_LC_SETUP_SERVER_INSTANCES_MAX (0)
	The number of the Light LC Setup Server instances used by the application.

#define	LIGHT_CTL_SETUP_SERVER_INSTANCES_MAX (0)
	The number of the Light CTL Setup Server instances used by the application.

#define	SCENE_SETUP_SERVER_INSTANCES_MAX (0)
	The number of the Scene Setup Server instances used by the application.

#define	MODEL_TRANSITION_TIME_UNKNOWN (UINT32_MAX)
	Transition time value to indicate unknown transition time.

#define	MODEL_ACKNOWLEDGED_TRANSACTION_TIMEOUT (SEC_TO_US(30))
	Transition time value to indicate the default transition time should be used.

#define	TRANSITION_STEP_MIN_MS (45)
	Product-specific transition limitations to align transition data regarding product abilities. More...

#define	TRANSITION_TIME_STEP_100MS_MAX (6200ul)
	Maximum value of transition time (in ms) possible in steps of 100 ms.

#define	TRANSITION_TIME_STEP_1S_MAX (SEC_TO_MS(62ul))
	Maximum value of transition time (in ms) possible in steps of 1 s.

#define	TRANSITION_TIME_STEP_10S_MAX (SEC_TO_MS(620ul))
	Maximum value of transition time (in ms) possible in steps of 10 s.

#define	TRANSITION_TIME_STEP_10M_MAX (MIN_TO_MS(620ul))
	Maximum value of transition time (in ms) possible in steps of 10 min.

#define	TRANSITION_TIME_MAX (0x3E)
	Max value of encoded transition time step value.

#define	TRANSITION_TIME_UNKNOWN (0x3F)
	Unknown encoded transition time value.

#define	TRANSITION_TIME_MAX_MS (TRANSITION_TIME_STEP_10M_MAX)
	Maximum permissible transition time in milliseconds.

#define	DELAY_TIME_STEP_FACTOR_MS (5)
	Delay field step factor in milliseconds.

#define	DELAY_TIME_STEP_MAX (0xFF)
	Maximum encoded value of the delay field.

#define	DELAY_TIME_MAX_MS (DELAY_TIME_STEP_MAX * DELAY_TIME_STEP_FACTOR_MS)
	Maximum permisible delay time in milliseconds.

#define	MODEL_TIMER_TIMEOUT_MIN_TICKS (APP_TIMER_TICKS(1))
	Minimum permissible timeout (1 ms) in RTC ticks for model timer.

#define	MODEL_TIMER_TIMEOUT_MIN_US (MODEL_TIMER_PERIOD_US_GET(MODEL_TIMER_TIMEOUT_MIN_TICKS))
	Minimum permissible timeout in milliseconds for model timer.

#define	MODEL_TIMER_MAX_TIMEOUT_TICKS (APP_TIMER_MAX_CNT_VAL)
	Maximum timout ticks, as per app_timer.h.

#define	MODEL_TIMER_PERIOD_MS_GET(TICKS) ((1000ul * (TICKS)) / APP_TIMER_CLOCK_FREQ)
	Get period in milliseconds for given number of ticks.

#define	MODEL_TIMER_PERIOD_US_GET(TICKS) ((1000ul * 1000ul * (TICKS)) / APP_TIMER_CLOCK_FREQ)
	Get period in microseconds for given number of ticks.

#define	MODEL_TIMER_TICKS_GET_MS(MS_TIME)
	Get number of model timer ticks for the given time period in milliseconds. More...

#define	MODEL_TIMER_TICKS_GET_US(US_TIME)
	Get number of model timer ticks for the given time period in microseconds. More...

Typedefs
typedef void(*	model_timer_cb_t) (void *p_context)
	Timer callback prototype.

typedef uint32_t(*	default_transition_time_value_get_cb_t) (uint16_t element_index)
	Default transition time get callback prototype. More...

Enumerations
enum	model_timer_mode_t { MODEL_TIMER_MODE_SINGLE_SHOT, MODEL_TIMER_MODE_REPEATED }
	Timer modes. More...

Functions
uint32_t	model_transition_time_decode (uint8_t enc_transition_time)
	Gets the decoded value of the transition time in milliseconds. More...

uint8_t	model_transition_time_encode (uint32_t transition_time)
	Gets the encoded value of the transition time as specified in the Bluetooth Mesh Model Specification (MshMDLv1.0.1) Note that the provided value will be rounded down to the nearest possible representation. More...

bool	model_transition_time_is_valid (uint8_t enc_transition_time)
	Validates the given transition time value. More...

uint32_t	model_delay_decode (uint8_t enc_delay)
	Gets the decoded value of the delay time in milliseconds. More...

uint8_t	model_delay_encode (uint32_t delay)
	Gets the encoded value of the delay time as specified in the Bluetooth Mesh Model Specification (MshMDLv1.0.1). More...

bool	model_tid_validate (tid_tracker_t p_tid_tracker, const access_message_rx_meta_t p_meta, uint32_t message_id, uint8_t tid)
	Checks if the given message parameters represents a new transaction. More...

bool	model_transaction_is_new (tid_tracker_t *p_tid_tracker)
	Checks if given TID tracker instance has recorded a new transaction. More...

uint32_t	model_timer_schedule (model_timer_t *p_timer)
	Schedules a model timer for a given interval. More...

void	model_timer_abort (model_timer_t *p_timer)
	Aborts the currently scheduled timer. More...

uint64_t	model_timer_elapsed_ticks_get (model_timer_t *p_timer)
	Returns the total elapsed rtc ticks since the last call to model_timer_schedule() API. More...

bool	model_timer_is_running (model_timer_t *p_timer)
	Returns whether the specified timer is running. More...

uint32_t	model_timer_create (model_timer_t *p_timer)
	Creates a model timer. More...

Detailed Description

Contains common defines, structures, and functions used by the Mesh Models.

Macro Definition Documentation

◆ TRANSITION_STEP_MIN_MS

#define TRANSITION_STEP_MIN_MS (45)

Product-specific transition limitations to align transition data regarding product abilities.

Definition at line 117 of file model_common.h.

◆ MODEL_TIMER_TICKS_GET_MS

#define MODEL_TIMER_TICKS_GET_MS ( MS_TIME )

Value:

((uint64_t)ROUNDED_DIV((MS_TIME) * (uint64_t)APP_TIMER_CLOCK_FREQ, \

1000 * (APP_TIMER_CONFIG_RTC_FREQUENCY + 1)))

Get number of model timer ticks for the given time period in milliseconds.

Definition at line 152 of file model_common.h.

◆ MODEL_TIMER_TICKS_GET_US

#define MODEL_TIMER_TICKS_GET_US ( US_TIME )

Value:

((uint64_t)ROUNDED_DIV( \
 (US_TIME) * (uint64_t)APP_TIMER_CLOCK_FREQ, \
 1000 * 1000 * (APP_TIMER_CONFIG_RTC_FREQUENCY + 1)))

Get number of model timer ticks for the given time period in microseconds.

Definition at line 156 of file model_common.h.

Typedef Documentation

◆ default_transition_time_value_get_cb_t

typedef uint32_t(* default_transition_time_value_get_cb_t) (uint16_t element_index)

Default transition time get callback prototype.

Parameters

[in] element_index Index of the model element that is requesting default transition time value.

Return values

Returns value of default transition time in milliseconds, zero, if unavailable.

Definition at line 231 of file model_common.h.

Enumeration Type Documentation

◆ model_timer_mode_t

enum model_timer_mode_t

Timer modes.

Enumerator
MODEL_TIMER_MODE_SINGLE_SHOT	The timer will expire only once.
MODEL_TIMER_MODE_REPEATED	The timer will restart each time it expires.

Definition at line 186 of file model_common.h.

Function Documentation

◆ model_transition_time_decode()

uint32_t model_transition_time_decode ( uint8_t enc_transition_time )

Gets the decoded value of the transition time in milliseconds.

Parameters

[in] enc_transition_time Encoded value of the transition time as specified in the Bluetooth Mesh Model Specification (MshMDLv1.0.1).

Returns: Transition time in milliseconds.

◆ model_transition_time_encode()

uint8_t model_transition_time_encode ( uint32_t transition_time )

Gets the encoded value of the transition time as specified in the Bluetooth Mesh Model Specification (MshMDLv1.0.1) Note that the provided value will be rounded down to the nearest possible representation.

Parameters

[in] transition_time Transition time in milliseconds.

Returns: Encoded value of the transition time as specified in the Bluetooth Mesh Model Specification (MshMDLv1.0.1).

◆ model_transition_time_is_valid()

bool model_transition_time_is_valid ( uint8_t enc_transition_time )

Validates the given transition time value.

Parameters

[in] enc_transition_time Encoded transition time value

Return values

True	If encoded transition time is a valid value for the models.
False	If encoded transition time is invalid for the models and cannot be set.

◆ model_delay_decode()

uint32_t model_delay_decode ( uint8_t enc_delay )

Gets the decoded value of the delay time in milliseconds.

Parameters

[in] enc_delay Encoded value of the delay time as specified in the Bluetooth Mesh Model Specification (MshMDLv1.0.1).

Returns: delay time in milliseconds.

◆ model_delay_encode()

uint8_t model_delay_encode ( uint32_t delay )

Gets the encoded value of the delay time as specified in the Bluetooth Mesh Model Specification (MshMDLv1.0.1).

Note that the provided value will be rounded down to the nearest possible representation.

Parameters

[in] delay Delay time in milliseconds.

Returns: Encoded value of the delay time as specified in the Bluetooth Mesh Model Specification (MshMDLv1.0.1).

◆ model_tid_validate()

bool model_tid_validate	(	tid_tracker_t *	p_tid_tracker,
		const access_message_rx_meta_t *	p_meta,
		uint32_t	message_id,
		uint8_t	tid
	)

Checks if the given message parameters represents a new transaction.

The transaction is considered either new or same as previous in the context of a given message ID, TID, access meta data (source address and destination address) and timeout of 6 seconds as specified by Bluetooth Mesh Model Specification (MshMDLv1.0.1). This API is used by the model interfaces to reject duplicate transactions.

Note: User application should use model_transaction_is_new() API to check is the received message callback represents a new transaction.

Parameters

[in]	p_tid_tracker	Pointer to the tid tracker structure.
[in]	p_meta	Access message metadata containing source and destination addresses.
[in]	message_id	Any kind of unique identifier (e.g opcode) for a given type of message.
[in]	tid	Received TID value.

Return values

True	If transaction is new.
False	If transaction is same as the previous transaction.

◆ model_transaction_is_new()

bool model_transaction_is_new ( tid_tracker_t * p_tid_tracker )

Checks if given TID tracker instance has recorded a new transaction.

This API can be used by the user application to determine if the received message callback represents a new transaction.

Note: The model_tid_validate API is always called by the model interface internally to keep tid_tracker_t context updated.

Parameters

[in] p_tid_tracker Pointer to the tid tracker structure.

Return values

True	If transaction is new.
False	If transaction is same as the previous transaction.

◆ model_timer_schedule()

uint32_t model_timer_schedule ( model_timer_t * p_timer )

Schedules a model timer for a given interval.

This API uses APP_TIMER internally for the managing timeouts. The timing resolution is equal to the resolution offered by period corresponding to APP_TIMER_CLOCK_FREQ. The minimum allowed timeout in ticks is specified by MODEL_TIMER_TIMEOUT_MIN_TICKS.

Parameters

[in] p_timer Pointer to the model_timer_t structure.

Return values

NRF_SUCCESS	If the timer was successfully scheduled.
NRF_ERROR_NULL	If `p_timer` or the timer callback is null.
NRF_ERROR_INVALID_PARAM	If specified timout is too short.

◆ model_timer_abort()

void model_timer_abort ( model_timer_t * p_timer )

Aborts the currently scheduled timer.

Parameters

[in] p_timer Pointer to the model_timer_t structure

◆ model_timer_elapsed_ticks_get()

uint64_t model_timer_elapsed_ticks_get ( model_timer_t * p_timer )

Returns the total elapsed rtc ticks since the last call to model_timer_schedule() API.

Parameters

[in] p_timer Pointer to the model_timer_t structure.

Return values

0	If timer is not running.
ticks	Total elapsed rtc ticks, since the last call to model_timer_schedule() API.

◆ model_timer_is_running()

bool model_timer_is_running ( model_timer_t * p_timer )

Returns whether the specified timer is running.

If the current mode is MODEL_TIMER_MODE_REPEATED, returns true until model_timer_abort is called. If the current mode is MODLE_TIMER_MODE_SINGLE_SHOT, returns false after the timeout completes. The behavior also applies when this function is called from within the timer callback.

Parameters

[in] p_timer Pointer to the model_timer_t structure.

Return values

true	If the timer is running
false	If the timer is not running

◆ model_timer_create()

uint32_t model_timer_create ( model_timer_t * p_timer )

Creates a model timer.

This model timer implementation uses App Timer which is based on RTC. The timing parameters of this model timer are specified in number of ticks.

Parameters

[in] p_timer Pointer to model_timer_t structure.

Return values

NRF_SUCCESS	If the timer was successfully created.
NRF_ERROR_NULL	If p_timer is NULL.
NRF_ERROR_INVALID_PARAM	If a parameter was invalid.
NRF_ERROR_INVALID_STATE	If the application timer module has not been initialized or the timer is running.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ TRANSITION_STEP_MIN_MS

◆ MODEL_TIMER_TICKS_GET_MS

◆ MODEL_TIMER_TICKS_GET_US

Typedef Documentation

◆ default_transition_time_value_get_cb_t

Enumeration Type Documentation

◆ model_timer_mode_t

Function Documentation

◆ model_transition_time_decode()

◆ model_transition_time_encode()

◆ model_transition_time_is_valid()

◆ model_delay_decode()

◆ model_delay_encode()

◆ model_tid_validate()

◆ model_transaction_is_new()

◆ model_timer_schedule()

◆ model_timer_abort()

◆ model_timer_elapsed_ticks_get()

◆ model_timer_is_running()

◆ model_timer_create()