Bluetooth Mesh Access Layer

Bluetooth Mesh Access Layer. More...

Classes
struct	bt_mesh_elem
struct	bt_mesh_model_pub
struct	bt_mesh_model_cb
struct	bt_mesh_mod_id_vnd
struct	bt_mesh_model
struct	bt_mesh_comp

Macros
#define	BT_MESH_ELEM(_loc, _mods, _vnd_mods)
#define	BT_MESH_LEN_EXACT(len)   (-len)
#define	BT_MESH_LEN_MIN(len)   (len)
#define	BT_MESH_MODEL_NONE   ((struct bt_mesh_model []){})
#define	BT_MESH_MODEL_CB(_id, _op, _pub, _user_data, _cb)
	Composition data SIG model entry with callback functions.
#define	BT_MESH_MODEL_VND_CB(_company, _id, _op, _pub, _user_data, _cb)
	Composition data vendor model entry with callback functions.
#define	BT_MESH_MODEL(_id, _op, _pub, _user_data)    BT_MESH_MODEL_CB(_id, _op, _pub, _user_data, NULL)
	Composition data SIG model entry.
#define	BT_MESH_MODEL_VND(_company, _id, _op, _pub, _user_data)    BT_MESH_MODEL_VND_CB(_company, _id, _op, _pub, _user_data, NULL)
	Composition data vendor model entry.
#define	BT_MESH_TRANSMIT(count, int_ms)   ((count) | (((int_ms / 10) - 1) << 3))
	Encode transmission count & interval steps.
#define	BT_MESH_TRANSMIT_COUNT(transmit)   (((transmit) & (uint8_t)BIT_MASK(3)))
	Decode transmit count from a transmit value.
#define	BT_MESH_TRANSMIT_INT(transmit)   ((((transmit) >> 3) + 1) * 10)
	Decode transmit interval from a transmit value.
#define	BT_MESH_PUB_TRANSMIT(count, int_ms)
	Encode Publish Retransmit count & interval steps.
#define	BT_MESH_PUB_TRANSMIT_COUNT(transmit)   BT_MESH_TRANSMIT_COUNT(transmit)
	Decode Pubhlish Retransmit count from a given value.
#define	BT_MESH_PUB_TRANSMIT_INT(transmit)   ((((transmit) >> 3) + 1) * 50)
	Decode Publish Retransmit interval from a given value.
#define	BT_MESH_TTL_DEFAULT   0xff
#define	BT_MESH_TTL_MAX   0x7f

Functions
int	bt_mesh_model_send (struct bt_mesh_model *model, struct bt_mesh_msg_ctx *ctx, struct os_mbuf *msg, const struct bt_mesh_send_cb *cb, void *cb_data)
	Send an Access Layer message.
int	bt_mesh_model_publish (struct bt_mesh_model *model)
	Send a model publication message.
struct bt_mesh_elem *	bt_mesh_model_elem (struct bt_mesh_model *mod)
	Get the element that a model belongs to.
struct bt_mesh_model *	bt_mesh_model_find (const struct bt_mesh_elem *elem, uint16_t id)
	Find a SIG model.
struct bt_mesh_model *	bt_mesh_model_find_vnd (const struct bt_mesh_elem *elem, uint16_t company, uint16_t id)
	Find a vendor model.
int	bt_mesh_model_data_store (struct bt_mesh_model *mod, bool vnd, const char *name, const void *data, size_t data_len)
	Immediately store the model's user data in persistent storage.
int	bt_mesh_model_extend (struct bt_mesh_model *extending_mod, struct bt_mesh_model *base_mod)
	Let a model extend another.
bool	bt_mesh_model_is_extended (struct bt_mesh_model *model)
	Check if model is extended by another model.

Detailed Description

Bluetooth Mesh Access Layer.

Macro Definition Documentation

BT_MESH_ELEM

#define BT_MESH_ELEM	(		_loc,
			_mods,
			_vnd_mods
	)

Value:

{                                                   \
    .loc              = (_loc),                 \
    .model_count      = ARRAY_SIZE(_mods),      \
    .models           = (_mods),                \
    .vnd_model_count  = ARRAY_SIZE(_vnd_mods),  \
    .vnd_models       = (_vnd_mods),            \
}

Helper to define a mesh element within an array.

In case the element has no SIG or Vendor models the helper macro BT_MESH_MODEL_NONE can be given instead.

Parameters

_loc	Location Descriptor.
_mods	Array of models.
_vnd_mods	Array of vendor models.

BT_MESH_LEN_EXACT

#define BT_MESH_LEN_EXACT

(

len

)

(-len)

Macro for encoding exact message length for fixed-length messages.

BT_MESH_LEN_MIN

#define BT_MESH_LEN_MIN

(

len

)

(len)

Macro for encoding minimum message length for variable-length messages.

BT_MESH_MODEL

#define BT_MESH_MODEL	(		_id,
			_op,
			_pub,
			_user_data
	)		BT_MESH_MODEL_CB(_id, _op, _pub, _user_data, NULL)

Composition data SIG model entry.

Parameters

_id	Model ID.
_op	Array of model opcode handlers.
_pub	Model publish parameters.
_user_data	User data for the model.

BT_MESH_MODEL_CB

#define BT_MESH_MODEL_CB	(		_id,
			_op,
			_pub,
			_user_data,
			_cb
	)

Value:

{                                                                            \
    .id = (_id),                                                         \
    .op = _op,                                                           \
    .keys = { [0 ... (CONFIG_BT_MESH_MODEL_KEY_COUNT - 1)] =             \
            BT_MESH_KEY_UNUSED },                                \
    .pub = _pub,                                                         \
    .groups = { [0 ... (CONFIG_BT_MESH_MODEL_GROUP_COUNT - 1)] =         \
            BT_MESH_ADDR_UNASSIGNED },                           \
    .user_data = _user_data,                                             \
    .cb = _cb,                                                           \
}

Composition data SIG model entry with callback functions.

Parameters

_id	Model ID.
_op	Array of model opcode handlers.
_pub	Model publish parameters.
_user_data	User data for the model.
_cb	Callback structure, or NULL to keep no callbacks.

BT_MESH_MODEL_NONE

#define BT_MESH_MODEL_NONE   ((struct bt_mesh_model []){})

Helper to define an empty model array

BT_MESH_MODEL_VND

#define BT_MESH_MODEL_VND	(		_company,
			_id,
			_op,
			_pub,
			_user_data
	)		BT_MESH_MODEL_VND_CB(_company, _id, _op, _pub, _user_data, NULL)

Composition data vendor model entry.

Parameters

_company	Company ID.
_id	Model ID.
_op	Array of model opcode handlers.
_pub	Model publish parameters.
_user_data	User data for the model.

BT_MESH_MODEL_VND_CB

#define BT_MESH_MODEL_VND_CB	(		_company,
			_id,
			_op,
			_pub,
			_user_data,
			_cb
	)

Value:

{                                                                            \
    .vnd.company = (_company),                                           \
    .vnd.id = (_id),                                                     \
    .op = _op,                                                           \
    .pub = _pub,                                                         \
    .keys = { [0 ... (CONFIG_BT_MESH_MODEL_KEY_COUNT - 1)] =             \
            BT_MESH_KEY_UNUSED },                                \
    .groups = { [0 ... (CONFIG_BT_MESH_MODEL_GROUP_COUNT - 1)] =         \
            BT_MESH_ADDR_UNASSIGNED },                           \
    .user_data = _user_data,                                             \
    .cb = _cb,                                                           \
}

Composition data vendor model entry with callback functions.

Parameters

_company	Company ID.
_id	Model ID.
_op	Array of model opcode handlers.
_pub	Model publish parameters.
_user_data	User data for the model.
_cb	Callback structure, or NULL to keep no callbacks.

BT_MESH_PUB_TRANSMIT

#define BT_MESH_PUB_TRANSMIT	(		count,
			int_ms
	)

Value:

                                 BT_MESH_TRANSMIT(count,           \
                                 (int_ms) / 5)

Encode Publish Retransmit count & interval steps.

Parameters

count	Number of retransmissions (first transmission is excluded).
int_ms	Interval steps in milliseconds. Must be greater than 0 and a multiple of 50.

Returns

Mesh transmit value that can be used e.g. for the default values of the configuration model data.

BT_MESH_PUB_TRANSMIT_COUNT

#define BT_MESH_PUB_TRANSMIT_COUNT

(

transmit

)

BT_MESH_TRANSMIT_COUNT(transmit)

Decode Pubhlish Retransmit count from a given value.

Parameters

transmit

Encoded Publish Retransmit count & interval value.

Returns

Retransmission count (actual transmissions is N + 1).

BT_MESH_PUB_TRANSMIT_INT

#define BT_MESH_PUB_TRANSMIT_INT

(

transmit

)

((((transmit) >> 3) + 1) * 50)

Decode Publish Retransmit interval from a given value.

Parameters

transmit

Encoded Publish Retransmit count & interval value.

Returns

Transmission interval in milliseconds.

BT_MESH_TRANSMIT

#define BT_MESH_TRANSMIT	(		count,
			int_ms
	)		((count) | (((int_ms / 10) - 1) << 3))

Encode transmission count & interval steps.

Parameters

count	Number of retransmissions (first transmission is excluded).
int_ms	Interval steps in milliseconds. Must be greater than 0, less than or equal to 320, and a multiple of 10.

Returns

Mesh transmit value that can be used e.g. for the default values of the configuration model data.

BT_MESH_TRANSMIT_COUNT

#define BT_MESH_TRANSMIT_COUNT

(

transmit

)

(((transmit) & (uint8_t)BIT_MASK(3)))

Decode transmit count from a transmit value.

Parameters

transmit

Encoded transmit count & interval value.

Returns

Transmission count (actual transmissions is N + 1).

BT_MESH_TRANSMIT_INT

#define BT_MESH_TRANSMIT_INT

(

transmit

)

((((transmit) >> 3) + 1) * 10)

Decode transmit interval from a transmit value.

Parameters

transmit

Encoded transmit count & interval value.

Returns

Transmission interval in milliseconds.

BT_MESH_TTL_DEFAULT

#define BT_MESH_TTL_DEFAULT   0xff

Special TTL value to request using configured default TTL

BT_MESH_TTL_MAX

#define BT_MESH_TTL_MAX   0x7f

Maximum allowed TTL value

Function Documentation

bt_mesh_model_data_store()

int bt_mesh_model_data_store	(	struct bt_mesh_model *	mod,
		bool	vnd,
		const char *	name,
		const void *	data,
		size_t	data_len
	)

Immediately store the model's user data in persistent storage.

Parameters

mod	Mesh model.
vnd	This is a vendor model.
name	Name/key of the settings item. Only SETTINGS_MAX_DIR_DEPTH bytes will be used at most.
data	Model data to store, or NULL to delete any model data.
data_len	Length of the model data.

Returns

0 on success, or (negative) error code on failure.

bt_mesh_model_elem()

struct bt_mesh_elem * bt_mesh_model_elem

(

struct bt_mesh_model *

mod

)

Get the element that a model belongs to.

Parameters

mod	Mesh model.

Returns

Pointer to the element that the given model belongs to.

bt_mesh_model_extend()

int bt_mesh_model_extend	(	struct bt_mesh_model *	extending_mod,
		struct bt_mesh_model *	base_mod
	)

Let a model extend another.

Mesh models may be extended to reuse their functionality, forming a more complex model. A Mesh model may extend any number of models, in any element. The extensions may also be nested, ie a model that extends another may itself be extended.

A set of models that extend each other form a model extension list.

All models in an extension list share one subscription list per element. The access layer will utilize the combined subscription list of all models in an extension list and element, giving the models extended subscription list capacity.

Parameters

extending_mod	Mesh model that is extending the base model.
base_mod	The model being extended.

Return values

0	Successfully extended the base_mod model.

bt_mesh_model_find()

struct bt_mesh_model * bt_mesh_model_find	(	const struct bt_mesh_elem *	elem,
		uint16_t	id
	)

Find a SIG model.

Parameters

elem	Element to search for the model in.
id	Model ID of the model.

Returns

A pointer to the Mesh model matching the given parameters, or NULL if no SIG model with the given ID exists in the given element.

bt_mesh_model_find_vnd()

struct bt_mesh_model * bt_mesh_model_find_vnd	(	const struct bt_mesh_elem *	elem,
		uint16_t	company,
		uint16_t	id
	)

Find a vendor model.

Parameters

elem	Element to search for the model in.
company	Company ID of the model.
id	Model ID of the model.

Returns

A pointer to the Mesh model matching the given parameters, or NULL if no vendor model with the given ID exists in the given element.

bt_mesh_model_is_extended()

bool bt_mesh_model_is_extended

(

struct bt_mesh_model *

model

)

Check if model is extended by another model.

Parameters

model

The model to check.

Return values

true	If model is extended by another model, otherwise false

bt_mesh_model_publish()

int bt_mesh_model_publish

(

struct bt_mesh_model *

model

)

Send a model publication message.

Before calling this function, the user needs to ensure that the model publication message (bt_mesh_model_pub::msg) contains a valid message to be sent. Note that this API is only to be used for non-period publishing. For periodic publishing the app only needs to make sure that bt_mesh_model_pub::msg contains a valid message whenever the bt_mesh_model_pub::update callback is called.

Parameters

model

Mesh (client) Model that's publishing the message.

Returns

0 on success, or (negative) error code on failure.

bt_mesh_model_send()

int bt_mesh_model_send	(	struct bt_mesh_model *	model,
		struct bt_mesh_msg_ctx *	ctx,
		struct os_mbuf *	msg,
		const struct bt_mesh_send_cb *	cb,
		void *	cb_data
	)

Send an Access Layer message.

Parameters

model	Mesh (client) Model that the message belongs to.
ctx	Message context, includes keys, TTL, etc.
msg	Access Layer payload (the actual message to be sent).
cb	Optional "message sent" callback.
cb_data	User data to be passed to the callback.

Returns

0 on success, or (negative) error code on failure.