Mesh config entry

API for managing mesh configuration entries. More...

Data Structures
struct	mesh_config_entry_id_t
	Mesh config entry identifier. More...
struct	mesh_config_file_params_t
	File parameters for a mesh config file. More...
struct	mesh_config_entry_params_t
	Mesh config entry parameters. More...

Macros
#define	MESH_CONFIG_ENTRY_ID(FILE, RECORD)   (const mesh_config_entry_id_t) {(FILE), (RECORD)}
	Shorthand macro for defining an entry ID. More...
#define	MESH_CONFIG_ENTRY_MAX_SIZE   64
	Entry max size.
#define	MESH_CONFIG_FILE(NAME, FILE_ID, STRATEGY)
	Define a config file. More...
#define	MESH_CONFIG_ENTRY(NAME, ID, MAX_COUNT, ENTRY_SIZE, SET_CB, GET_CB, DELETE_CB, DEFAULT_VALUE)
	Define a config entry. More...
#define	MESH_CONFIG_ENTRY_IMPLEMENTATION(NAME, ID, MAX_COUNT, DATA_TYPE, ENTRY_SANITATION, DEFAULT_VALUE)
	A variation of Mesh config entry that also stores the state. More...
#define	MESH_CONFIG_ENTRY_API_DEFINE(NAME, ID, DATA_TYPE)
	Defines a type safe API wrapper for a configuration entry. More...
#define	MESH_CONFIG_ENTRY_ARRAY_WRAPPER_DECLARE(NAME, ID, DATA_TYPE, INDEX_TYPE, MAX_COUNT)
	Defines type safe wrapper functions for a configuration entry with multiple items. More...

Typedefs
typedef uint32_t(*	mesh_config_entry_set_t) (mesh_config_entry_id_t id, const void *p_entry)
	State owner entry setter callback. More...
typedef void(*	mesh_config_entry_get_t) (mesh_config_entry_id_t id, void *p_entry)
	State owner entry getter callback. More...
typedef void(*	mesh_config_entry_delete_t) (mesh_config_entry_id_t id)
	State owner entry delete callback. More...

Enumerations
enum	mesh_config_strategy_t { MESH_CONFIG_STRATEGY_NON_PERSISTENT, MESH_CONFIG_STRATEGY_CONTINUOUS, MESH_CONFIG_STRATEGY_ON_POWER_DOWN }
	Mesh config entry storage strategy. More...
enum	mesh_config_entry_flags_t { MESH_CONFIG_ENTRY_FLAG_DIRTY = (1 << 0), MESH_CONFIG_ENTRY_FLAG_ACTIVE = (1 << 1), MESH_CONFIG_ENTRY_FLAG_BUSY = (1 << 2) }
	Entry state. More...

Detailed Description

API for managing mesh configuration entries.

Macro Definition Documentation

MESH_CONFIG_ENTRY_ID

#define MESH_CONFIG_ENTRY_ID	(		FILE,
			RECORD
	)		(const mesh_config_entry_id_t) {(FILE), (RECORD)}

Shorthand macro for defining an entry ID.

Defined as a compound literal so it can be used directly as a parameter in function invocations. See https://gcc.gnu.org/onlinedocs/gcc/Compound-Literals.html

Parameters

[in]	FILE	File the entry is in.
[in]	RECORD	Record within the file.

Definition at line 65 of file mesh_config_entry.h.

MESH_CONFIG_FILE

#define MESH_CONFIG_FILE	(		NAME,
			FILE_ID,
			STRATEGY
	)

Value:

static mesh_config_backend_file_t CONCAT_2(NAME, _backend_data); \
 NRF_MESH_SECTION_ITEM_REGISTER_FLASH(mesh_config_files, const mesh_config_file_params_t NAME) = \
 {.id = FILE_ID, .strategy = STRATEGY, .p_backend_data = &CONCAT_2(NAME, _backend_data)}

Define a config file.

Each file has a unique file ID, and contains multiple entries.

Parameters

[in]	NAME	Name of the file parameter variable.
[in]	FILE_ID	Identification number of the file.
[in]	STRATEGY	Storage strategy for the file.

Definition at line 80 of file mesh_config_entry.h.

MESH_CONFIG_ENTRY

#define MESH_CONFIG_ENTRY	(		NAME,
			ID,
			MAX_COUNT,
			ENTRY_SIZE,
			SET_CB,
			GET_CB,
			DELETE_CB,
			DEFAULT_VALUE
	)

Value:

NRF_MESH_STATIC_ASSERT((ENTRY_SIZE) <= MESH_CONFIG_ENTRY_MAX_SIZE); \
 NRF_MESH_STATIC_ASSERT((MAX_COUNT) > 0); \
 static mesh_config_entry_flags_t m_##NAME##_state[MAX_COUNT]; \
 NRF_MESH_SECTION_ITEM_REGISTER_FLASH(mesh_config_entries, \
 const mesh_config_entry_params_t m_##NAME##_params) = \
 {.p_id = &(ID), \
 .entry_size = ENTRY_SIZE, \
 .p_default = DEFAULT_VALUE, \
 .max_count = MAX_COUNT, \
 .callbacks = {SET_CB, GET_CB, DELETE_CB}, \
 .p_state = m_##NAME##_state}

Define a config entry.

Each config entry represents a single state, identified by a unique id. The framework will call the provided get and set callbacks to access the live representation of the state.

The config entry will get registered at link time.

Parameters

[in]	NAME	Name of the entry and its variables
[in]	ID	Unique mesh configuration id
[in]	MAX_COUNT	Max number of entries
[in]	ENTRY_SIZE	Size of each entry
[in]	SET_CB	Callback to call when setting the value. Cannot be NULL.
[in]	GET_CB	Callback to call to read out the value. Cannot be NULL.
[in]	DELETE_CB	Callback to call to delete the value or NULL.
[in]	DEFAULT_VALUE	Pointer to a default value to return if the entry hasn't been set, or NULL if no default value is available

Definition at line 103 of file mesh_config_entry.h.

MESH_CONFIG_ENTRY_IMPLEMENTATION

#define MESH_CONFIG_ENTRY_IMPLEMENTATION	(		NAME,
			ID,
			MAX_COUNT,
			DATA_TYPE,
			ENTRY_SANITATION,
			DEFAULT_VALUE
	)

Value:

static DATA_TYPE m_##NAME[(MAX_COUNT)]; \
 static uint32_t NAME##_set(mesh_config_entry_id_t id, const void * p_entry_param) \
 { \
 const DATA_TYPE * p_entry = p_entry_param; \
 bool params_are_valid = (ENTRY_SANITATION); \
 if (params_are_valid) \
 { \
 memcpy(&m_##NAME[id.record - (ID).record], p_entry, sizeof(DATA_TYPE)); \
 return NRF_SUCCESS; \
 } \
 else \
 { \
 return NRF_ERROR_INVALID_DATA; \
 } \
 } \
 static void NAME##_get(mesh_config_entry_id_t id, void * p_entry) \
 { \
 memcpy(p_entry, &m_##NAME[id.record - (ID).record], sizeof(DATA_TYPE)); \
 } \
 MESH_CONFIG_ENTRY(NAME, (ID), (MAX_COUNT), sizeof(DATA_TYPE), NAME##_set, NAME##_get, NULL, DEFAULT_VALUE)

A variation of Mesh config entry that also stores the state.

Instantiates a static variable to store the data in, as well as generic setter and getter functions to operate on the data. The user can define an entry sanitation expression that is expected to evaluate to true if the entry is valid and false if it carries an illegal value.

Entry sanitation example:

IS_IN_RANGE(p_entry->tx_interval, 0, TX_INTERVAL_MAX)

Parameters

[in]	NAME	Name of the entry and its variables
[in]	ID	Unique mesh configuration id
[in]	MAX_COUNT	Max number of entries
[in]	DATA_TYPE	The data type of the state.
[in]	ENTRY_SANITATION	Boolean expression used to validate an entry. The entry is instantiated as a constant pointer of type DATA_TYPE named p_entry.
[in]	DEFAULT_VALUE	Pointer to the default value for this entry, or NULL if the entry is invalid until set.

Definition at line 137 of file mesh_config_entry.h.

MESH_CONFIG_ENTRY_API_DEFINE

#define MESH_CONFIG_ENTRY_API_DEFINE	(		NAME,
			ID,
			DATA_TYPE
	)

Value:

uint32_t NAME##_set(const DATA_TYPE * p_entry) \
 { \
 return mesh_config_entry_set((ID), p_entry); \
 } \
 uint32_t NAME##_get(DATA_TYPE * p_entry) \
 { \
 return mesh_config_entry_get((ID), p_entry); \
 } \
 uint32_t NAME##_delete(void) \
 { \
 return mesh_config_entry_delete((ID)); \
 }

Defines a type safe API wrapper for a configuration entry.

Parameters

[in]	NAME	Name of the API. The functions will be NAME_get() and similar.
[in]	ID	Entry id
[in]	DATA_TYPE	Data type of the state.

Definition at line 166 of file mesh_config_entry.h.

MESH_CONFIG_ENTRY_ARRAY_WRAPPER_DECLARE

#define MESH_CONFIG_ENTRY_ARRAY_WRAPPER_DECLARE	(		NAME,
			ID,
			DATA_TYPE,
			INDEX_TYPE,
			MAX_COUNT
	)

Value:

uint32_t NAME##_set(INDEX_TYPE index, const DATA_TYPE * p_entry) \
 { \
 if (index >= (MAX_COUNT)) return NRF_ERROR_INVALID_PARAM; \
 mesh_config_entry_id_t id = ID; \
 id.record += (uint16_t) index; \
 return mesh_config_entry_set(id, p_entry); \
 } \
 uint32_t NAME##_get(INDEX_TYPE index, DATA_TYPE * p_entry) \
 { \
 if (index >= (MAX_COUNT)) return NRF_ERROR_INVALID_PARAM; \
 mesh_config_entry_id_t id = ID; \
 id.record += (uint16_t) index; \
 return mesh_config_entry_get(id, p_entry); \
 } \
 uint32_t NAME##_delete(INDEX_TYPE index) \
 { \
 if (index >= (MAX_COUNT)) return NRF_ERROR_INVALID_PARAM; \
 mesh_config_entry_id_t id = ID; \
 id.record += (uint16_t) index; \
 return mesh_config_entry_delete(id); \
 }

Defines type safe wrapper functions for a configuration entry with multiple items.

Parameters

[in]	NAME	Base names of the API functions.
[in]	ID	Base entry id.
[in]	DATA_TYPE	Data type of the state.
[in]	INDEX_TYPE	Type of the index variable. Must be cast-able to uint16_t.
[in]	MAX_COUNT	Maximum number of items in the entry.

Definition at line 190 of file mesh_config_entry.h.

Typedef Documentation

mesh_config_entry_set_t

typedef uint32_t(* mesh_config_entry_set_t) (mesh_config_entry_id_t id, const void *p_entry)

State owner entry setter callback.

The callback will only be called with IDs within the boundaries specified through Mesh config entry. If the callback returns successfully, a subsequent get-callback must return data that is identical to the data passed in this callback. If the callback returns unsuccessfully, the entry data must remain unchanged.

Parameters

[in]	id	Entry ID to set.
[in]	p_entry	Entry data to set. Never NULL.

Return values

NRF_SUCCESS	The entry was successfully set.
NRF_ERROR_INVALID_DATA	The entry data is invalid, and should be discarded.

Definition at line 247 of file mesh_config_entry.h.

mesh_config_entry_get_t

typedef void(* mesh_config_entry_get_t) (mesh_config_entry_id_t id, void *p_entry)

State owner entry getter callback.

The callback will only be called on entries that have been set through the state owner's set-callback. The entry data returned through p_entry must be identical to the data set in the previous set-callback.

Parameters

[in]	id	Entry ID to get data of.
[in,out]	p_entry	Pointer to entry buffer to copy into.

Definition at line 258 of file mesh_config_entry.h.

mesh_config_entry_delete_t

typedef void(* mesh_config_entry_delete_t) (mesh_config_entry_id_t id)

State owner entry delete callback.

The callback will only be called on entries that have been set through the state owner's set-callback. The state owner cannot prevent users from deleting entries.

Parameters

[in]

id

Entry ID to be deleted.

Definition at line 268 of file mesh_config_entry.h.

Enumeration Type Documentation

mesh_config_strategy_t

enum mesh_config_strategy_t

Mesh config entry storage strategy.

Defines when the entry should be stored to persistent storage.

Enumerator
MESH_CONFIG_STRATEGY_NON_PERSISTENT	Not stored persistently.
MESH_CONFIG_STRATEGY_CONTINUOUS	Stored as soon as possible after each change.
MESH_CONFIG_STRATEGY_ON_POWER_DOWN	Stored when device is about to power down.

Definition at line 227 of file mesh_config_entry.h.

mesh_config_entry_flags_t

enum mesh_config_entry_flags_t

Entry state.

Enumerator
MESH_CONFIG_ENTRY_FLAG_DIRTY	The backend and frontend representation of the entry is not in sync.
MESH_CONFIG_ENTRY_FLAG_ACTIVE	The entry is set to a valid value.
MESH_CONFIG_ENTRY_FLAG_BUSY	The backend is currently processing the entry.

Definition at line 283 of file mesh_config_entry.h.