1 /** @file
2 * @brief Access layer APIs.
3 */
4
5 /*
6 * Copyright (c) 2017 Intel Corporation
7 *
8 * SPDX-License-Identifier: Apache-2.0
9 */
10 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_MESH_ACCESS_H_
11 #define ZEPHYR_INCLUDE_BLUETOOTH_MESH_ACCESS_H_
12
13 #include <settings/settings.h>
14 #include <sys/util.h>
15 #include <bluetooth/mesh/msg.h>
16
17 /* Internal macros used to initialize array members */
18 #define BT_MESH_KEY_UNUSED_ELT_(IDX, _) BT_MESH_KEY_UNUSED,
19 #define BT_MESH_ADDR_UNASSIGNED_ELT_(IDX, _) BT_MESH_ADDR_UNASSIGNED,
20 #define BT_MESH_MODEL_KEYS_UNUSED \
21 { UTIL_LISTIFY(CONFIG_BT_MESH_MODEL_KEY_COUNT, \
22 BT_MESH_KEY_UNUSED_ELT_) }
23 #define BT_MESH_MODEL_GROUPS_UNASSIGNED \
24 { UTIL_LISTIFY(CONFIG_BT_MESH_MODEL_GROUP_COUNT, \
25 BT_MESH_ADDR_UNASSIGNED_ELT_) }
26
27 /**
28 * @brief Access layer
29 * @defgroup bt_mesh_access Access layer
30 * @ingroup bt_mesh
31 * @{
32 */
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37
38 #define BT_MESH_ADDR_UNASSIGNED 0x0000
39 #define BT_MESH_ADDR_ALL_NODES 0xffff
40 #define BT_MESH_ADDR_PROXIES 0xfffc
41 #define BT_MESH_ADDR_FRIENDS 0xfffd
42 #define BT_MESH_ADDR_RELAYS 0xfffe
43
44 #define BT_MESH_KEY_UNUSED 0xffff
45 #define BT_MESH_KEY_ANY 0xffff
46 #define BT_MESH_KEY_DEV 0xfffe
47 #define BT_MESH_KEY_DEV_LOCAL BT_MESH_KEY_DEV
48 #define BT_MESH_KEY_DEV_REMOTE 0xfffd
49 #define BT_MESH_KEY_DEV_ANY 0xfffc
50
51 #define BT_MESH_ADDR_IS_UNICAST(addr) ((addr) && (addr) < 0x8000)
52 #define BT_MESH_ADDR_IS_GROUP(addr) ((addr) >= 0xc000 && (addr) <= 0xff00)
53 #define BT_MESH_ADDR_IS_VIRTUAL(addr) ((addr) >= 0x8000 && (addr) < 0xc000)
54 #define BT_MESH_ADDR_IS_RFU(addr) ((addr) >= 0xff00 && (addr) <= 0xfffb)
55
56 #define BT_MESH_IS_DEV_KEY(key) (key == BT_MESH_KEY_DEV_LOCAL || \
57 key == BT_MESH_KEY_DEV_REMOTE)
58
59 /** Maximum payload size of an access message (in octets). */
60 #define BT_MESH_APP_SEG_SDU_MAX 12
61 /** Maximum possible payload size of an outgoing access message (in octets). */
62 #define BT_MESH_TX_SDU_MAX (CONFIG_BT_MESH_TX_SEG_MAX * \
63 BT_MESH_APP_SEG_SDU_MAX)
64 /** Maximum possible payload size of an incoming access message (in octets). */
65 #define BT_MESH_RX_SDU_MAX (CONFIG_BT_MESH_RX_SEG_MAX * \
66 BT_MESH_APP_SEG_SDU_MAX)
67
68 /** Helper to define a mesh element within an array.
69 *
70 * In case the element has no SIG or Vendor models the helper
71 * macro BT_MESH_MODEL_NONE can be given instead.
72 *
73 * @param _loc Location Descriptor.
74 * @param _mods Array of models.
75 * @param _vnd_mods Array of vendor models.
76 */
77 #define BT_MESH_ELEM(_loc, _mods, _vnd_mods) \
78 { \
79 .loc = (_loc), \
80 .model_count = ARRAY_SIZE(_mods), \
81 .vnd_model_count = ARRAY_SIZE(_vnd_mods), \
82 .models = (_mods), \
83 .vnd_models = (_vnd_mods), \
84 }
85
86 /** Abstraction that describes a Mesh Element */
87 struct bt_mesh_elem {
88 /** Unicast Address. Set at runtime during provisioning. */
89 uint16_t addr;
90
91 /** Location Descriptor (GATT Bluetooth Namespace Descriptors) */
92 const uint16_t loc;
93 /** The number of SIG models in this element */
94 const uint8_t model_count;
95 /** The number of vendor models in this element */
96 const uint8_t vnd_model_count;
97
98 /** The list of SIG models in this element */
99 struct bt_mesh_model * const models;
100 /** The list of vendor models in this element */
101 struct bt_mesh_model * const vnd_models;
102 };
103
104 /* Foundation Models */
105 #define BT_MESH_MODEL_ID_CFG_SRV 0x0000
106 #define BT_MESH_MODEL_ID_CFG_CLI 0x0001
107 #define BT_MESH_MODEL_ID_HEALTH_SRV 0x0002
108 #define BT_MESH_MODEL_ID_HEALTH_CLI 0x0003
109
110 /* Models from the Mesh Model Specification */
111 #define BT_MESH_MODEL_ID_GEN_ONOFF_SRV 0x1000
112 #define BT_MESH_MODEL_ID_GEN_ONOFF_CLI 0x1001
113 #define BT_MESH_MODEL_ID_GEN_LEVEL_SRV 0x1002
114 #define BT_MESH_MODEL_ID_GEN_LEVEL_CLI 0x1003
115 #define BT_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_SRV 0x1004
116 #define BT_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_CLI 0x1005
117 #define BT_MESH_MODEL_ID_GEN_POWER_ONOFF_SRV 0x1006
118 #define BT_MESH_MODEL_ID_GEN_POWER_ONOFF_SETUP_SRV 0x1007
119 #define BT_MESH_MODEL_ID_GEN_POWER_ONOFF_CLI 0x1008
120 #define BT_MESH_MODEL_ID_GEN_POWER_LEVEL_SRV 0x1009
121 #define BT_MESH_MODEL_ID_GEN_POWER_LEVEL_SETUP_SRV 0x100a
122 #define BT_MESH_MODEL_ID_GEN_POWER_LEVEL_CLI 0x100b
123 #define BT_MESH_MODEL_ID_GEN_BATTERY_SRV 0x100c
124 #define BT_MESH_MODEL_ID_GEN_BATTERY_CLI 0x100d
125 #define BT_MESH_MODEL_ID_GEN_LOCATION_SRV 0x100e
126 #define BT_MESH_MODEL_ID_GEN_LOCATION_SETUPSRV 0x100f
127 #define BT_MESH_MODEL_ID_GEN_LOCATION_CLI 0x1010
128 #define BT_MESH_MODEL_ID_GEN_ADMIN_PROP_SRV 0x1011
129 #define BT_MESH_MODEL_ID_GEN_MANUFACTURER_PROP_SRV 0x1012
130 #define BT_MESH_MODEL_ID_GEN_USER_PROP_SRV 0x1013
131 #define BT_MESH_MODEL_ID_GEN_CLIENT_PROP_SRV 0x1014
132 #define BT_MESH_MODEL_ID_GEN_PROP_CLI 0x1015
133 #define BT_MESH_MODEL_ID_SENSOR_SRV 0x1100
134 #define BT_MESH_MODEL_ID_SENSOR_SETUP_SRV 0x1101
135 #define BT_MESH_MODEL_ID_SENSOR_CLI 0x1102
136 #define BT_MESH_MODEL_ID_TIME_SRV 0x1200
137 #define BT_MESH_MODEL_ID_TIME_SETUP_SRV 0x1201
138 #define BT_MESH_MODEL_ID_TIME_CLI 0x1202
139 #define BT_MESH_MODEL_ID_SCENE_SRV 0x1203
140 #define BT_MESH_MODEL_ID_SCENE_SETUP_SRV 0x1204
141 #define BT_MESH_MODEL_ID_SCENE_CLI 0x1205
142 #define BT_MESH_MODEL_ID_SCHEDULER_SRV 0x1206
143 #define BT_MESH_MODEL_ID_SCHEDULER_SETUP_SRV 0x1207
144 #define BT_MESH_MODEL_ID_SCHEDULER_CLI 0x1208
145 #define BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_SRV 0x1300
146 #define BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_SETUP_SRV 0x1301
147 #define BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_CLI 0x1302
148 #define BT_MESH_MODEL_ID_LIGHT_CTL_SRV 0x1303
149 #define BT_MESH_MODEL_ID_LIGHT_CTL_SETUP_SRV 0x1304
150 #define BT_MESH_MODEL_ID_LIGHT_CTL_CLI 0x1305
151 #define BT_MESH_MODEL_ID_LIGHT_CTL_TEMP_SRV 0x1306
152 #define BT_MESH_MODEL_ID_LIGHT_HSL_SRV 0x1307
153 #define BT_MESH_MODEL_ID_LIGHT_HSL_SETUP_SRV 0x1308
154 #define BT_MESH_MODEL_ID_LIGHT_HSL_CLI 0x1309
155 #define BT_MESH_MODEL_ID_LIGHT_HSL_HUE_SRV 0x130a
156 #define BT_MESH_MODEL_ID_LIGHT_HSL_SAT_SRV 0x130b
157 #define BT_MESH_MODEL_ID_LIGHT_XYL_SRV 0x130c
158 #define BT_MESH_MODEL_ID_LIGHT_XYL_SETUP_SRV 0x130d
159 #define BT_MESH_MODEL_ID_LIGHT_XYL_CLI 0x130e
160 #define BT_MESH_MODEL_ID_LIGHT_LC_SRV 0x130f
161 #define BT_MESH_MODEL_ID_LIGHT_LC_SETUPSRV 0x1310
162 #define BT_MESH_MODEL_ID_LIGHT_LC_CLI 0x1311
163
164 /** Model opcode handler. */
165 struct bt_mesh_model_op {
166 /** OpCode encoded using the BT_MESH_MODEL_OP_* macros */
167 const uint32_t opcode;
168
169 /** Message length. If the message has variable length then this value
170 * indicates minimum message length and should be positive. Handler
171 * function should verify precise length based on the contents of the
172 * message. If the message has fixed length then this value should
173 * be negative. Use BT_MESH_LEN_* macros when defining this value.
174 */
175 const ssize_t len;
176
177 /** @brief Handler function for this opcode.
178 *
179 * @param model Model instance receiving the message.
180 * @param ctx Message context for the message.
181 * @param buf Message buffer containing the message payload, not
182 * including the opcode.
183 *
184 * @return Zero on success or (negative) error code otherwise.
185 */
186 int (*const func)(struct bt_mesh_model *model,
187 struct bt_mesh_msg_ctx *ctx,
188 struct net_buf_simple *buf);
189 };
190
191 #define BT_MESH_MODEL_OP_1(b0) (b0)
192 #define BT_MESH_MODEL_OP_2(b0, b1) (((b0) << 8) | (b1))
193 #define BT_MESH_MODEL_OP_3(b0, cid) ((((b0) << 16) | 0xc00000) | (cid))
194
195 /** Macro for encoding exact message length for fixed-length messages. */
196 #define BT_MESH_LEN_EXACT(len) (-len)
197 /** Macro for encoding minimum message length for variable-length messages. */
198 #define BT_MESH_LEN_MIN(len) (len)
199
200 /** End of the opcode list. Must always be present. */
201 #define BT_MESH_MODEL_OP_END { 0, 0, NULL }
202 /** Helper to define an empty opcode list. */
203 #define BT_MESH_MODEL_NO_OPS ((struct bt_mesh_model_op []) \
204 { BT_MESH_MODEL_OP_END })
205
206 /** Helper to define an empty model array */
207 #define BT_MESH_MODEL_NONE ((struct bt_mesh_model []){})
208
209 /** @def BT_MESH_MODEL_CB
210 *
211 * @brief Composition data SIG model entry with callback functions.
212 *
213 * @param _id Model ID.
214 * @param _op Array of model opcode handlers.
215 * @param _pub Model publish parameters.
216 * @param _user_data User data for the model.
217 * @param _cb Callback structure, or NULL to keep no callbacks.
218 */
219 #define BT_MESH_MODEL_CB(_id, _op, _pub, _user_data, _cb) \
220 { \
221 .id = (_id), \
222 .pub = _pub, \
223 .keys = BT_MESH_MODEL_KEYS_UNUSED, \
224 .groups = BT_MESH_MODEL_GROUPS_UNASSIGNED, \
225 .op = _op, \
226 .cb = _cb, \
227 .user_data = _user_data, \
228 }
229
230 /** @def BT_MESH_MODEL_VND_CB
231 *
232 * @brief Composition data vendor model entry with callback functions.
233 *
234 * @param _company Company ID.
235 * @param _id Model ID.
236 * @param _op Array of model opcode handlers.
237 * @param _pub Model publish parameters.
238 * @param _user_data User data for the model.
239 * @param _cb Callback structure, or NULL to keep no callbacks.
240 */
241 #define BT_MESH_MODEL_VND_CB(_company, _id, _op, _pub, _user_data, _cb) \
242 { \
243 .vnd.company = (_company), \
244 .vnd.id = (_id), \
245 .op = _op, \
246 .pub = _pub, \
247 .keys = BT_MESH_MODEL_KEYS_UNUSED, \
248 .groups = BT_MESH_MODEL_GROUPS_UNASSIGNED, \
249 .user_data = _user_data, \
250 .cb = _cb, \
251 }
252
253
254 /** @def BT_MESH_MODEL
255 *
256 * @brief Composition data SIG model entry.
257 *
258 * @param _id Model ID.
259 * @param _op Array of model opcode handlers.
260 * @param _pub Model publish parameters.
261 * @param _user_data User data for the model.
262 */
263 #define BT_MESH_MODEL(_id, _op, _pub, _user_data) \
264 BT_MESH_MODEL_CB(_id, _op, _pub, _user_data, NULL)
265
266 /** @def BT_MESH_MODEL_VND
267 *
268 * @brief Composition data vendor model entry.
269 *
270 * @param _company Company ID.
271 * @param _id Model ID.
272 * @param _op Array of model opcode handlers.
273 * @param _pub Model publish parameters.
274 * @param _user_data User data for the model.
275 */
276 #define BT_MESH_MODEL_VND(_company, _id, _op, _pub, _user_data) \
277 BT_MESH_MODEL_VND_CB(_company, _id, _op, _pub, _user_data, NULL)
278
279 /** @def BT_MESH_TRANSMIT
280 *
281 * @brief Encode transmission count & interval steps.
282 *
283 * @param count Number of retransmissions (first transmission is excluded).
284 * @param int_ms Interval steps in milliseconds. Must be greater than 0,
285 * less than or equal to 320, and a multiple of 10.
286 *
287 * @return Mesh transmit value that can be used e.g. for the default
288 * values of the configuration model data.
289 */
290 #define BT_MESH_TRANSMIT(count, int_ms) ((count) | (((int_ms / 10) - 1) << 3))
291
292 /** @def BT_MESH_TRANSMIT_COUNT
293 *
294 * @brief Decode transmit count from a transmit value.
295 *
296 * @param transmit Encoded transmit count & interval value.
297 *
298 * @return Transmission count (actual transmissions is N + 1).
299 */
300 #define BT_MESH_TRANSMIT_COUNT(transmit) (((transmit) & (uint8_t)BIT_MASK(3)))
301
302 /** @def BT_MESH_TRANSMIT_INT
303 *
304 * @brief Decode transmit interval from a transmit value.
305 *
306 * @param transmit Encoded transmit count & interval value.
307 *
308 * @return Transmission interval in milliseconds.
309 */
310 #define BT_MESH_TRANSMIT_INT(transmit) ((((transmit) >> 3) + 1) * 10)
311
312 /** @def BT_MESH_PUB_TRANSMIT
313 *
314 * @brief Encode Publish Retransmit count & interval steps.
315 *
316 * @param count Number of retransmissions (first transmission is excluded).
317 * @param int_ms Interval steps in milliseconds. Must be greater than 0 and a
318 * multiple of 50.
319 *
320 * @return Mesh transmit value that can be used e.g. for the default
321 * values of the configuration model data.
322 */
323 #define BT_MESH_PUB_TRANSMIT(count, int_ms) BT_MESH_TRANSMIT(count, \
324 (int_ms) / 5)
325
326 /** @def BT_MESH_PUB_TRANSMIT_COUNT
327 *
328 * @brief Decode Publish Retransmit count from a given value.
329 *
330 * @param transmit Encoded Publish Retransmit count & interval value.
331 *
332 * @return Retransmission count (actual transmissions is N + 1).
333 */
334 #define BT_MESH_PUB_TRANSMIT_COUNT(transmit) BT_MESH_TRANSMIT_COUNT(transmit)
335
336 /** @def BT_MESH_PUB_TRANSMIT_INT
337 *
338 * @brief Decode Publish Retransmit interval from a given value.
339 *
340 * @param transmit Encoded Publish Retransmit count & interval value.
341 *
342 * @return Transmission interval in milliseconds.
343 */
344 #define BT_MESH_PUB_TRANSMIT_INT(transmit) ((((transmit) >> 3) + 1) * 50)
345
346 /** Model publication context.
347 *
348 * The context should primarily be created using the
349 * BT_MESH_MODEL_PUB_DEFINE macro.
350 */
351 struct bt_mesh_model_pub {
352 /** The model the context belongs to. Initialized by the stack. */
353 struct bt_mesh_model *mod;
354
355 uint16_t addr; /**< Publish Address. */
356 uint16_t key:12, /**< Publish AppKey Index. */
357 cred:1, /**< Friendship Credentials Flag. */
358 send_rel:1, /**< Force reliable sending (segment acks) */
359 fast_period:1; /**< Use FastPeriodDivisor */
360
361 uint8_t ttl; /**< Publish Time to Live. */
362 uint8_t retransmit; /**< Retransmit Count & Interval Steps. */
363 uint8_t period; /**< Publish Period. */
364 uint8_t period_div:4, /**< Divisor for the Period. */
365 count:4; /**< Transmissions left. */
366
367 uint32_t period_start; /**< Start of the current period. */
368
369 /** @brief Publication buffer, containing the publication message.
370 *
371 * This will get correctly created when the publication context
372 * has been defined using the BT_MESH_MODEL_PUB_DEFINE macro.
373 *
374 * BT_MESH_MODEL_PUB_DEFINE(name, update, size);
375 */
376 struct net_buf_simple *msg;
377
378 /** @brief Callback for updating the publication buffer.
379 *
380 * When set to NULL, the model is assumed not to support
381 * periodic publishing. When set to non-NULL the callback
382 * will be called periodically and is expected to update
383 * @ref bt_mesh_model_pub.msg with a valid publication
384 * message.
385 *
386 * If the callback returns non-zero, the publication is skipped
387 * and will resume on the next periodic publishing interval.
388 *
389 * @param mod The Model the Publication Context belogs to.
390 *
391 * @return Zero on success or (negative) error code otherwise.
392 */
393 int (*update)(struct bt_mesh_model *mod);
394
395 /** Publish Period Timer. Only for stack-internal use. */
396 struct k_work_delayable timer;
397 };
398
399 /** @def BT_MESH_MODEL_PUB_DEFINE
400 *
401 * Define a model publication context.
402 *
403 * @param _name Variable name given to the context.
404 * @param _update Optional message update callback (may be NULL).
405 * @param _msg_len Length of the publication message.
406 */
407 #define BT_MESH_MODEL_PUB_DEFINE(_name, _update, _msg_len) \
408 NET_BUF_SIMPLE_DEFINE_STATIC(bt_mesh_pub_msg_##_name, _msg_len); \
409 static struct bt_mesh_model_pub _name = { \
410 .msg = &bt_mesh_pub_msg_##_name, \
411 .update = _update, \
412 }
413
414 /** Model callback functions. */
415 struct bt_mesh_model_cb {
416 /** @brief Set value handler of user data tied to the model.
417 *
418 * @sa settings_handler::h_set
419 *
420 * @param model Model to set the persistent data of.
421 * @param name Name/key of the settings item.
422 * @param len_rd The size of the data found in the backend.
423 * @param read_cb Function provided to read the data from the backend.
424 * @param cb_arg Arguments for the read function provided by the
425 * backend.
426 *
427 * @return 0 on success, error otherwise.
428 */
429 int (*const settings_set)(struct bt_mesh_model *model,
430 const char *name, size_t len_rd,
431 settings_read_cb read_cb, void *cb_arg);
432
433 /** @brief Callback called when the mesh is started.
434 *
435 * This handler gets called after the node has been provisioned, or
436 * after all mesh data has been loaded from persistent storage.
437 *
438 * When this callback fires, the mesh model may start its behavior,
439 * and all Access APIs are ready for use.
440 *
441 * @param model Model this callback belongs to.
442 *
443 * @return 0 on success, error otherwise.
444 */
445 int (*const start)(struct bt_mesh_model *model);
446
447 /** @brief Model init callback.
448 *
449 * Called on every model instance during mesh initialization.
450 *
451 * If any of the model init callbacks return an error, the Mesh
452 * subsystem initialization will be aborted, and the error will be
453 * returned to the caller of @ref bt_mesh_init.
454 *
455 * @param model Model to be initialized.
456 *
457 * @return 0 on success, error otherwise.
458 */
459 int (*const init)(struct bt_mesh_model *model);
460
461 /** @brief Model reset callback.
462 *
463 * Called when the mesh node is reset. All model data is deleted on
464 * reset, and the model should clear its state.
465 *
466 * @note If the model stores any persistent data, this needs to be
467 * erased manually.
468 *
469 * @param model Model this callback belongs to.
470 */
471 void (*const reset)(struct bt_mesh_model *model);
472 };
473
474 /** Vendor model ID */
475 struct bt_mesh_mod_id_vnd {
476 /** Vendor's company ID */
477 uint16_t company;
478 /** Model ID */
479 uint16_t id;
480 };
481
482 /** Abstraction that describes a Mesh Model instance */
483 struct bt_mesh_model {
484 union {
485 /** SIG model ID */
486 const uint16_t id;
487 /** Vendor model ID */
488 const struct bt_mesh_mod_id_vnd vnd;
489 };
490
491 /* Internal information, mainly for persistent storage */
492 uint8_t elem_idx; /* Belongs to Nth element */
493 uint8_t mod_idx; /* Is the Nth model in the element */
494 uint16_t flags; /* Model flags for internal bookkeeping */
495
496 /** Model Publication */
497 struct bt_mesh_model_pub * const pub;
498
499 /** AppKey List */
500 uint16_t keys[CONFIG_BT_MESH_MODEL_KEY_COUNT];
501
502 /** Subscription List (group or virtual addresses) */
503 uint16_t groups[CONFIG_BT_MESH_MODEL_GROUP_COUNT];
504
505 /** Opcode handler list */
506 const struct bt_mesh_model_op * const op;
507
508 /** Model callback structure. */
509 const struct bt_mesh_model_cb * const cb;
510
511 #ifdef CONFIG_BT_MESH_MODEL_EXTENSIONS
512 /* Pointer to the next model in a model extension list. */
513 struct bt_mesh_model *next;
514 #endif
515
516 /** Model-specific user data */
517 void *user_data;
518 };
519
520 /** Callback structure for monitoring model message sending */
521 struct bt_mesh_send_cb {
522 /** @brief Handler called at the start of the transmission.
523 *
524 * @param duration The duration of the full transmission.
525 * @param err Error occurring during sending.
526 * @param cb_data Callback data, as passed to the send API.
527 */
528 void (*start)(uint16_t duration, int err, void *cb_data);
529 /** @brief Handler called at the end of the transmission.
530 *
531 * @param err Error occurring during sending.
532 * @param cb_data Callback data, as passed to the send API.
533 */
534 void (*end)(int err, void *cb_data);
535 };
536
537
538 /** Special TTL value to request using configured default TTL */
539 #define BT_MESH_TTL_DEFAULT 0xff
540
541 /** Maximum allowed TTL value */
542 #define BT_MESH_TTL_MAX 0x7f
543
544 /** @brief Send an Access Layer message.
545 *
546 * @param model Mesh (client) Model that the message belongs to.
547 * @param ctx Message context, includes keys, TTL, etc.
548 * @param msg Access Layer payload (the actual message to be sent).
549 * @param cb Optional "message sent" callback.
550 * @param cb_data User data to be passed to the callback.
551 *
552 * @return 0 on success, or (negative) error code on failure.
553 */
554 int bt_mesh_model_send(struct bt_mesh_model *model,
555 struct bt_mesh_msg_ctx *ctx,
556 struct net_buf_simple *msg,
557 const struct bt_mesh_send_cb *cb,
558 void *cb_data);
559
560 /** @brief Send a model publication message.
561 *
562 * Before calling this function, the user needs to ensure that the model
563 * publication message (@ref bt_mesh_model_pub.msg) contains a valid
564 * message to be sent. Note that this API is only to be used for
565 * non-period publishing. For periodic publishing the app only needs
566 * to make sure that @ref bt_mesh_model_pub.msg contains a valid message
567 * whenever the @ref bt_mesh_model_pub.update callback is called.
568 *
569 * @param model Mesh (client) Model that's publishing the message.
570 *
571 * @return 0 on success, or (negative) error code on failure.
572 */
573 int bt_mesh_model_publish(struct bt_mesh_model *model);
574
575 /** @brief Get the element that a model belongs to.
576 *
577 * @param mod Mesh model.
578 *
579 * @return Pointer to the element that the given model belongs to.
580 */
581 struct bt_mesh_elem *bt_mesh_model_elem(struct bt_mesh_model *mod);
582
583 /** @brief Find a SIG model.
584 *
585 * @param elem Element to search for the model in.
586 * @param id Model ID of the model.
587 *
588 * @return A pointer to the Mesh model matching the given parameters, or NULL
589 * if no SIG model with the given ID exists in the given element.
590 */
591 struct bt_mesh_model *bt_mesh_model_find(const struct bt_mesh_elem *elem,
592 uint16_t id);
593
594 /** @brief Find a vendor model.
595 *
596 * @param elem Element to search for the model in.
597 * @param company Company ID of the model.
598 * @param id Model ID of the model.
599 *
600 * @return A pointer to the Mesh model matching the given parameters, or NULL
601 * if no vendor model with the given ID exists in the given element.
602 */
603 struct bt_mesh_model *bt_mesh_model_find_vnd(const struct bt_mesh_elem *elem,
604 uint16_t company, uint16_t id);
605
606 /** @brief Get whether the model is in the primary element of the device.
607 *
608 * @param mod Mesh model.
609 *
610 * @return true if the model is on the primary element, false otherwise.
611 */
bt_mesh_model_in_primary(const struct bt_mesh_model * mod)612 static inline bool bt_mesh_model_in_primary(const struct bt_mesh_model *mod)
613 {
614 return (mod->elem_idx == 0);
615 }
616
617 /** @brief Immediately store the model's user data in persistent storage.
618 *
619 * @param mod Mesh model.
620 * @param vnd This is a vendor model.
621 * @param name Name/key of the settings item. Only
622 * @ref SETTINGS_MAX_DIR_DEPTH bytes will be used at most.
623 * @param data Model data to store, or NULL to delete any model data.
624 * @param data_len Length of the model data.
625 *
626 * @return 0 on success, or (negative) error code on failure.
627 */
628 int bt_mesh_model_data_store(struct bt_mesh_model *mod, bool vnd,
629 const char *name, const void *data,
630 size_t data_len);
631
632 /** @brief Let a model extend another.
633 *
634 * Mesh models may be extended to reuse their functionality, forming a more
635 * complex model. A Mesh model may extend any number of models, in any element.
636 * The extensions may also be nested, ie a model that extends another may
637 * itself be extended.
638 *
639 * A set of models that extend each other form a model extension list.
640 *
641 * All models in an extension list share one subscription list per element. The
642 * access layer will utilize the combined subscription list of all models in an
643 * extension list and element, giving the models extended subscription list
644 * capacity.
645 *
646 * @param extending_mod Mesh model that is extending the base model.
647 * @param base_mod The model being extended.
648 *
649 * @retval 0 Successfully extended the base_mod model.
650 */
651 int bt_mesh_model_extend(struct bt_mesh_model *extending_mod,
652 struct bt_mesh_model *base_mod);
653
654 /** @brief Check if model is extended by another model.
655 *
656 * @param model The model to check.
657 *
658 * @retval true If model is extended by another model, otherwise false
659 */
660 bool bt_mesh_model_is_extended(struct bt_mesh_model *model);
661
662 /** Node Composition */
663 struct bt_mesh_comp {
664 uint16_t cid; /**< Company ID */
665 uint16_t pid; /**< Product ID */
666 uint16_t vid; /**< Version ID */
667
668 size_t elem_count; /**< The number of elements in this device. */
669 struct bt_mesh_elem *elem; /**< List of elements. */
670 };
671
672 #ifdef __cplusplus
673 }
674 #endif
675
676 /**
677 * @}
678 */
679
680 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_ACCESS_H_ */
681
