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, HAS_DEFAULT_VALUE)
	Define a config entry. 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,
			HAS_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, \
 .has_default = HAS_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]	HAS_DEFAULT_VALUE	Flag for indicating that the entry has a default value that it can return before the user explicitly sets it.

Definition at line 103 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 123 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 147 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 204 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 215 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 225 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 184 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 240 of file mesh_config_entry.h.