Message API

The Bluetooth Mesh message API provides set of structures, macros and functions used for preparing message buffers, managing message and acknowledged message contexts.

API reference

group bt_mesh_msg

Bluetooth Mesh Message API.

Defines

BT_MESH_MIC_SHORT

Length of a short Mesh MIC.

BT_MESH_MIC_LONG

Length of a long Mesh MIC.

BT_MESH_MODEL_OP_LEN(_op)

Helper to determine the length of an opcode.

Parameters

  • _op – Opcode.

BT_MESH_MODEL_BUF_LEN(_op, _payload_len)

Helper for model message buffer length.

Returns the length of a Mesh model message buffer, including the opcode length and a short MIC.

Parameters

  • _op – Opcode of the message.

  • _payload_len – Length of the model payload.

BT_MESH_MODEL_BUF_LEN_LONG_MIC(_op, _payload_len)

Helper for model message buffer length.

Returns the length of a Mesh model message buffer, including the opcode length and a long MIC.

Parameters

  • _op – Opcode of the message.

  • _payload_len – Length of the model payload.

BT_MESH_MODEL_BUF_DEFINE(_buf, _op, _payload_len)

Define a Mesh model message buffer using NET_BUF_SIMPLE_DEFINE.

Parameters

  • _buf – Buffer name.

  • _op – Opcode of the message.

  • _payload_len – Length of the model message payload.

Functions

void bt_mesh_model_msg_init(struct net_buf_simple *msg, uint32_t opcode)

Initialize a model message.

Clears the message buffer contents, and encodes the given opcode. The message buffer will be ready for filling in payload data.

Parameters

  • msg – Message buffer.

  • opcode – Opcode to encode.

static inline void bt_mesh_msg_ack_ctx_init(struct bt_mesh_msg_ack_ctx *ack)

Initialize an acknowledged message context.

Initializes semaphore used for synchronization between bt_mesh_msg_ack_ctx_wait and bt_mesh_msg_ack_ctx_rx calls. Call this function before using bt_mesh_msg_ack_ctx.

Parameters

  • ack – Acknowledged message context to initialize.

static inline void bt_mesh_msg_ack_ctx_reset(struct bt_mesh_msg_ack_ctx *ack)

Reset the synchronization semaphore in an acknowledged message context.

This function aborts call to bt_mesh_msg_ack_ctx_wait.

Parameters

  • ack – Acknowledged message context to be reset.

void bt_mesh_msg_ack_ctx_clear(struct bt_mesh_msg_ack_ctx *ack)

Clear parameters of an acknowledged message context.

This function clears the opcode, remote address and user data set by bt_mesh_msg_ack_ctx_prepare.

Parameters

  • ack – Acknowledged message context to be cleared.

int bt_mesh_msg_ack_ctx_prepare(struct bt_mesh_msg_ack_ctx *ack, uint32_t op, uint16_t dst, void *user_data)

Prepare an acknowledged message context for the incoming message to wait.

This function sets the opcode, remote address of the incoming message and stores the user data. Use this function before calling bt_mesh_msg_ack_ctx_wait.

Parameters

  • ack – Acknowledged message context to prepare.

  • op – The message OpCode.

  • dst – Destination address of the message.

  • user_data – User data for the acknowledged message context.

Returns

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

static inline bool bt_mesh_msg_ack_ctx_busy(struct bt_mesh_msg_ack_ctx *ack)

Check if the acknowledged message context is initialized with an opcode.

Parameters

  • ack – Acknowledged message context.

Returns

true if the acknowledged message context is initialized with an opcode, false otherwise.

int bt_mesh_msg_ack_ctx_wait(struct bt_mesh_msg_ack_ctx *ack, k_timeout_t timeout)

Wait for a message acknowledge.

This function blocks execution until bt_mesh_msg_ack_ctx_rx is called or by timeout.

Parameters

  • ack – Acknowledged message context of the message to wait for.

  • timeout – Wait timeout.

Returns

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

static inline void bt_mesh_msg_ack_ctx_rx(struct bt_mesh_msg_ack_ctx *ack)

Mark a message as acknowledged.

This function unblocks call to bt_mesh_msg_ack_ctx_wait.

Parameters

  • ack – Context of a message to be acknowledged.

bool bt_mesh_msg_ack_ctx_match(const struct bt_mesh_msg_ack_ctx *ack, uint32_t op, uint16_t addr, void **user_data)

Check if an opcode and address of a message matches the expected one.

Parameters

  • ack – Acknowledged message context to be checked.

  • op – OpCode of the incoming message.

  • addr – Source address of the incoming message.

  • user_data – If not NULL, returns a user data stored in the acknowledged message context by bt_mesh_msg_ack_ctx_prepare.

Returns

true if the incoming message matches the expected one, false otherwise.

struct bt_mesh_msg_ctx
#include <msg.h>

Message sending context.

Public Members

uint16_t net_idx

NetKey Index of the subnet to send the message on.

uint16_t app_idx

AppKey Index to encrypt the message with.

uint16_t addr

Remote address.

uint16_t recv_dst

Destination address of a received message. Not used for sending.

int8_t recv_rssi

RSSI of received packet. Not used for sending.

uint8_t recv_ttl

Received TTL value. Not used for sending.

bool send_rel

Force sending reliably by using segment acknowledgment

uint8_t send_ttl

TTL, or BT_MESH_TTL_DEFAULT for default TTL.

struct bt_mesh_msg_ack_ctx
#include <msg.h>

Acknowledged message context for tracking the status of model messages pending a response.

Public Members

struct k_sem sem

Sync semaphore.

uint32_t op

Opcode we’re waiting for.

uint16_t dst

Address of the node that should respond.

void *user_data

User specific parameter.