diff --git a/include/bluetooth/mesh/access.h b/include/bluetooth/mesh/access.h index ddd6e366bf3..56ab576ef5a 100644 --- a/include/bluetooth/mesh/access.h +++ b/include/bluetooth/mesh/access.h @@ -58,16 +58,19 @@ extern "C" { /** Abstraction that describes a Mesh Element */ struct bt_mesh_elem { - /* Unicast Address. Set at runtime during provisioning. */ + /** Unicast Address. Set at runtime during provisioning. */ u16_t addr; - /* Location Descriptor (GATT Bluetooth Namespace Descriptors) */ + /** Location Descriptor (GATT Bluetooth Namespace Descriptors) */ const u16_t loc; - + /** The number of SIG models in this element */ const u8_t model_count; + /** The number of vendor models in this element */ const u8_t vnd_model_count; + /** The list of SIG models in this element */ struct bt_mesh_model * const models; + /** The list of vendor models in this element */ struct bt_mesh_model * const vnd_models; }; @@ -160,13 +163,19 @@ struct bt_mesh_msg_ctx { /** Model opcode handler. */ struct bt_mesh_model_op { - /* OpCode encoded using the BT_MESH_MODEL_OP_* macros */ + /** OpCode encoded using the BT_MESH_MODEL_OP_* macros */ const u32_t opcode; - /* Minimum required message length */ + /** Minimum required message length */ const size_t min_len; - /* Message handler for the opcode */ + /** @brief Handler function for this opcode. + * + * @param model Model instance receiving the message. + * @param ctx Message context for the message. + * @param buf Message buffer containing the message payload, not + * including the opcode. + */ void (*const func)(struct bt_mesh_model *model, struct bt_mesh_msg_ctx *ctx, struct net_buf_simple *buf); @@ -176,7 +185,9 @@ struct bt_mesh_model_op { #define BT_MESH_MODEL_OP_2(b0, b1) (((b0) << 8) | (b1)) #define BT_MESH_MODEL_OP_3(b0, cid) ((((b0) << 16) | 0xc00000) | (cid)) +/** End of the opcode list. Must always be present. */ #define BT_MESH_MODEL_OP_END { 0, 0, NULL } +/** Helper to define an empty opcode list. */ #define BT_MESH_MODEL_NO_OPS ((struct bt_mesh_model_op []) \ { BT_MESH_MODEL_OP_END }) @@ -190,58 +201,58 @@ struct bt_mesh_model_op { /** @def BT_MESH_MODEL_OP_LEN * - * @brief Helper to determine the length of an opcode. + * @brief Helper to determine the length of an opcode. * - * @param _op Opcode. + * @param _op Opcode. */ #define BT_MESH_MODEL_OP_LEN(_op) ((_op) <= 0xff ? 1 : (_op) <= 0xffff ? 2 : 3) /** @def BT_MESH_MODEL_BUF_LEN * - * @brief Helper for model message buffer length. + * @brief Helper for model message buffer length. * - * Returns the length of a Mesh model message buffer, including the opcode - * length and a short MIC. + * Returns the length of a Mesh model message buffer, including the opcode + * length and a short MIC. * - * @param _op Opcode of the message. - * @param _payload_len Length of the model payload. + * @param _op Opcode of the message. + * @param _payload_len Length of the model payload. */ #define BT_MESH_MODEL_BUF_LEN(_op, _payload_len) \ (BT_MESH_MODEL_OP_LEN(_op) + (_payload_len) + BT_MESH_MIC_SHORT) /** @def BT_MESH_MODEL_BUF_LEN_LONG_MIC * - * @brief Helper for model message buffer length. + * @brief Helper for model message buffer length. * - * Returns the length of a Mesh model message buffer, including the opcode - * length and a long MIC. + * Returns the length of a Mesh model message buffer, including the opcode + * length and a long MIC. * - * @param _op Opcode of the message. - * @param _payload_len Length of the model payload. + * @param _op Opcode of the message. + * @param _payload_len Length of the model payload. */ #define BT_MESH_MODEL_BUF_LEN_LONG_MIC(_op, _payload_len) \ (BT_MESH_MODEL_OP_LEN(_op) + (_payload_len) + BT_MESH_MIC_LONG) /** @def BT_MESH_MODEL_BUF_DEFINE * - * @brief Define a Mesh model message buffer using @ref NET_BUF_SIMPLE_DEFINE. + * @brief Define a Mesh model message buffer using @ref NET_BUF_SIMPLE_DEFINE. * - * @param _buf Buffer name. - * @param _op Opcode of the message. - * @param _payload_len Length of the model message payload. + * @param _buf Buffer name. + * @param _op Opcode of the message. + * @param _payload_len Length of the model message payload. */ #define BT_MESH_MODEL_BUF_DEFINE(_buf, _op, _payload_len) \ NET_BUF_SIMPLE_DEFINE(_buf, BT_MESH_MODEL_BUF_LEN(_op, (_payload_len))) /** @def BT_MESH_MODEL_CB * - * @brief Composition data SIG model entry with callback functions. + * @brief Composition data SIG model entry with callback functions. * - * @param _id Model ID. - * @param _op Array of model opcode handlers. - * @param _pub Model publish parameters. - * @param _user_data User data for the model. - * @param _cb Callback structure, or NULL to keep no callbacks. + * @param _id Model ID. + * @param _op Array of model opcode handlers. + * @param _pub Model publish parameters. + * @param _user_data User data for the model. + * @param _cb Callback structure, or NULL to keep no callbacks. */ #define BT_MESH_MODEL_CB(_id, _op, _pub, _user_data, _cb) \ { \ @@ -258,14 +269,14 @@ struct bt_mesh_model_op { /** @def BT_MESH_MODEL_VND_CB * - * @brief Composition data vendor model entry with callback functions. + * @brief Composition data vendor model entry with callback functions. * - * @param _company Company ID. - * @param _id Model ID. - * @param _op Array of model opcode handlers. - * @param _pub Model publish parameters. - * @param _user_data User data for the model. - * @param _cb Callback structure, or NULL to keep no callbacks. + * @param _company Company ID. + * @param _id Model ID. + * @param _op Array of model opcode handlers. + * @param _pub Model publish parameters. + * @param _user_data User data for the model. + * @param _cb Callback structure, or NULL to keep no callbacks. */ #define BT_MESH_MODEL_VND_CB(_company, _id, _op, _pub, _user_data, _cb) \ { \ @@ -284,25 +295,25 @@ struct bt_mesh_model_op { /** @def BT_MESH_MODEL * - * @brief Composition data SIG model entry. + * @brief Composition data SIG model entry. * - * @param _id Model ID. - * @param _op Array of model opcode handlers. - * @param _pub Model publish parameters. - * @param _user_data User data for the model. + * @param _id Model ID. + * @param _op Array of model opcode handlers. + * @param _pub Model publish parameters. + * @param _user_data User data for the model. */ #define BT_MESH_MODEL(_id, _op, _pub, _user_data) \ BT_MESH_MODEL_CB(_id, _op, _pub, _user_data, NULL) /** @def BT_MESH_MODEL_VND * - * @brief Composition data vendor model entry. + * @brief Composition data vendor model entry. * - * @param _company Company ID. - * @param _id Model ID. - * @param _op Array of model opcode handlers. - * @param _pub Model publish parameters. - * @param _user_data User data for the model. + * @param _company Company ID. + * @param _id Model ID. + * @param _op Array of model opcode handlers. + * @param _pub Model publish parameters. + * @param _user_data User data for the model. */ #define BT_MESH_MODEL_VND(_company, _id, _op, _pub, _user_data) \ BT_MESH_MODEL_VND_CB(_company, _id, _op, _pub, _user_data, NULL) @@ -344,9 +355,9 @@ struct bt_mesh_model_op { * * @brief Encode Publish Retransmit count & interval steps. * - * @param count Number of retransmissions (first transmission is excluded). - * @param int_ms Interval steps in milliseconds. Must be greater than 0 - * and a multiple of 50. + * @param count Number of retransmissions (first transmission is excluded). + * @param int_ms Interval steps in milliseconds. Must be greater than 0 and a + * multiple of 50. * * @return Mesh transmit value that can be used e.g. for the default * values of the configuration model data. @@ -442,15 +453,15 @@ struct bt_mesh_model_pub { struct bt_mesh_model_cb { /** @brief Set value handler of user data tied to the model. * - * @sa settings_handler::h_set + * @sa settings_handler::h_set * - * @param model Model to set the persistent data of. - * @param len_rd The size of the data found in the backend. - * @param read_cb Function provided to read the data from the backend. - * @param cb_arg Arguments for the read function provided by the - * backend. + * @param model Model to set the persistent data of. + * @param len_rd The size of the data found in the backend. + * @param read_cb Function provided to read the data from the backend. + * @param cb_arg Arguments for the read function provided by the + * backend. * - * @return 0 on success, error otherwise. + * @return 0 on success, error otherwise. */ int (*const settings_set)(struct bt_mesh_model *model, size_t len_rd, settings_read_cb read_cb, @@ -458,33 +469,33 @@ struct bt_mesh_model_cb { /** @brief Callback called when all settings have been loaded. * - * This handler gets called after the settings have been loaded in - * full. + * This handler gets called after the settings have been loaded in + * full. * - * @sa settings_handler::h_commit + * @sa settings_handler::h_commit * - * @param model Model this callback belongs to. + * @param model Model this callback belongs to. * - * @return 0 on success, error otherwise. + * @return 0 on success, error otherwise. */ int (*const settings_commit)(struct bt_mesh_model *model); /** @brief Model init callback. * - * Called on every model instance during mesh initialization. + * Called on every model instance during mesh initialization. * - * @param model Model to be initialized. + * @param model Model to be initialized. * - * @return 0 on success, error otherwise. + * @return 0 on success, error otherwise. */ int (*const init)(struct bt_mesh_model *model); /** @brief Model reset callback. * - * Called when the mesh node is reset. All model data is deleted on - * reset, and the model should clear its state. + * Called when the mesh node is reset. All model data is deleted on + * reset, and the model should clear its state. * - * @param model Model this callback belongs to. + * @param model Model this callback belongs to. */ void (*const reset)(struct bt_mesh_model *model); }; @@ -492,10 +503,12 @@ struct bt_mesh_model_cb { /** Abstraction that describes a Mesh Model instance */ struct bt_mesh_model { union { + /** SIG model ID */ const u16_t id; + /** Vendor model ID */ struct { - u16_t company; - u16_t id; + u16_t company; /**< Vendor's company ID */ + u16_t id; /**< Model ID */ } vnd; }; @@ -504,18 +517,19 @@ struct bt_mesh_model { u8_t mod_idx; /* Is the Nth model in the element */ u16_t flags; /* Model flags for internal bookkeeping */ - /* Model Publication */ + /** Model Publication */ struct bt_mesh_model_pub * const pub; - /* AppKey List */ + /** AppKey List */ u16_t keys[CONFIG_BT_MESH_MODEL_KEY_COUNT]; - /* Subscription List (group or virtual addresses) */ + /** Subscription List (group or virtual addresses) */ u16_t groups[CONFIG_BT_MESH_MODEL_GROUP_COUNT]; + /** Opcode handler list */ const struct bt_mesh_model_op * const op; - /* Model callback structure. */ + /** Model callback structure. */ const struct bt_mesh_model_cb * const cb; #ifdef CONFIG_BT_MESH_MODEL_EXTENSIONS @@ -524,15 +538,36 @@ struct bt_mesh_model { /* Pointer to the first model this model extends. */ struct bt_mesh_model *extends; #endif - /* Model-specific user data */ + /** Model-specific user data */ void *user_data; }; +/** Callback structure for monitoring model message sending */ struct bt_mesh_send_cb { + /** @brief Handler called at the start of the transmission. + * + * @param duration The duration of the full transmission. + * @param err Error occurring during sending. + * @param cb_data Callback data, as passed to the send API. + */ void (*start)(u16_t duration, int err, void *cb_data); + /** @brief Handler called at the end of the transmission. + * + * @param err Error occurring during sending. + * @param cb_data Callback data, as passed to the send API. + */ void (*end)(int err, void *cb_data); }; + +/** @brief 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. + * + * @param msg Message buffer. + * @param opcode Opcode to encode. + */ void bt_mesh_model_msg_init(struct net_buf_simple *msg, u32_t opcode); /** Special TTL value to request using configured default TTL */ @@ -541,16 +576,15 @@ void bt_mesh_model_msg_init(struct net_buf_simple *msg, u32_t opcode); /** Maximum allowed TTL value */ #define BT_MESH_TTL_MAX 0x7f -/** - * @brief Send an Access Layer message. +/** @brief Send an Access Layer message. * - * @param model Mesh (client) Model that the message belongs to. - * @param ctx Message context, includes keys, TTL, etc. - * @param msg Access Layer payload (the actual message to be sent). - * @param cb Optional "message sent" callback. - * @param cb_data User data to be passed to the callback. + * @param model Mesh (client) Model that the message belongs to. + * @param ctx Message context, includes keys, TTL, etc. + * @param msg Access Layer payload (the actual message to be sent). + * @param cb Optional "message sent" callback. + * @param cb_data User data to be passed to the callback. * - * @return 0 on success, or (negative) error code on failure. + * @return 0 on success, or (negative) error code on failure. */ int bt_mesh_model_send(struct bt_mesh_model *model, struct bt_mesh_msg_ctx *ctx, @@ -558,59 +592,57 @@ int bt_mesh_model_send(struct bt_mesh_model *model, const struct bt_mesh_send_cb *cb, void *cb_data); -/** - * @brief Send a model publication message. +/** @brief Send a model publication message. * - * Before calling this function, the user needs to ensure that the model - * publication message (@ref 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 @ref bt_mesh_model_pub.msg contains a valid message - * whenever the @ref bt_mesh_model_pub.update callback is called. + * Before calling this function, the user needs to ensure that the model + * publication message (@ref 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 @ref bt_mesh_model_pub.msg contains a valid message + * whenever the @ref bt_mesh_model_pub.update callback is called. * - * @param model Mesh (client) Model that's publishing the message. + * @param model Mesh (client) Model that's publishing the message. * - * @return 0 on success, or (negative) error code on failure. + * @return 0 on success, or (negative) error code on failure. */ int bt_mesh_model_publish(struct bt_mesh_model *model); -/** - * @brief Get the element that a model belongs to. +/** @brief Get the element that a model belongs to. * - * @param mod Mesh model. + * @param mod Mesh model. * - * @return Pointer to the element that the given model belongs to. + * @return Pointer to the element that the given model belongs to. */ struct bt_mesh_elem *bt_mesh_model_elem(struct bt_mesh_model *mod); /** @brief Find a SIG model. * - * @param elem Element to search for the model in. - * @param id Model ID of the model. + * @param elem Element to search for the model in. + * @param id Model ID of the model. * - * @return 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. + * @return 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. */ struct bt_mesh_model *bt_mesh_model_find(const struct bt_mesh_elem *elem, u16_t id); /** @brief Find a vendor model. * - * @param elem Element to search for the model in. - * @param company Company ID of the model. - * @param id Model ID of the model. + * @param elem Element to search for the model in. + * @param company Company ID of the model. + * @param id Model ID of the model. * - * @return 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. + * @return 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. */ struct bt_mesh_model *bt_mesh_model_find_vnd(const struct bt_mesh_elem *elem, u16_t company, u16_t id); /** @brief Get whether the model is in the primary element of the device. * - * @param mod Mesh model. + * @param mod Mesh model. * - * @return true if the model is on the primary element, false otherwise. + * @return true if the model is on the primary element, false otherwise. */ static inline bool bt_mesh_model_in_primary(const struct bt_mesh_model *mod) { @@ -619,48 +651,48 @@ static inline bool bt_mesh_model_in_primary(const struct bt_mesh_model *mod) /** @brief Immediately store the model's user data in persistent storage. * - * @param mod Mesh model. - * @param vnd This is a vendor model. - * @param data Model data to store, or NULL to delete any model data. - * @param data_len Length of the model data. + * @param mod Mesh model. + * @param vnd This is a vendor model. + * @param data Model data to store, or NULL to delete any model data. + * @param data_len Length of the model data. * - * @return 0 on success, or (negative) error code on failure. + * @return 0 on success, or (negative) error code on failure. */ int bt_mesh_model_data_store(struct bt_mesh_model *mod, bool vnd, const void *data, size_t data_len); /** @brief 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. Extensions may not be cyclical, and a model can only be extended - * by one other model. + * 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. Extensions may not be cyclical, and a model can only be + * extended by one other model. * - * A set of models that extend each other form a model extension tree. + * A set of models that extend each other form a model extension tree. * - * All models in an extension tree share one subscription list per element. The - * access layer will utilize the combined subscription list of all models in an - * extension tree and element, giving the models extended subscription list - * capacity. + * All models in an extension tree share one subscription list per element. The + * access layer will utilize the combined subscription list of all models in an + * extension tree and element, giving the models extended subscription list + * capacity. * - * @param[in] mod Mesh model. - * @param[in] base_mod The model being extended. + * @param mod Mesh model. + * @param base_mod The model being extended. * - * @retval 0 Successfully extended the base_mod model. - * @retval -EALREADY The base_mod model is already extended. + * @retval 0 Successfully extended the base_mod model. + * @retval -EALREADY The base_mod model is already extended. */ int bt_mesh_model_extend(struct bt_mesh_model *mod, struct bt_mesh_model *base_mod); /** Node Composition */ struct bt_mesh_comp { - u16_t cid; - u16_t pid; - u16_t vid; + u16_t cid; /**< Company ID */ + u16_t pid; /**< Product ID */ + u16_t vid; /**< Version ID */ - size_t elem_count; - struct bt_mesh_elem *elem; + size_t elem_count; /**< The number of elements in this device. */ + struct bt_mesh_elem *elem; /**< List of elements. */ }; #ifdef __cplusplus diff --git a/include/bluetooth/mesh/cfg_cli.h b/include/bluetooth/mesh/cfg_cli.h index 84fc7802dfb..f85eb7934e1 100644 --- a/include/bluetooth/mesh/cfg_cli.h +++ b/include/bluetooth/mesh/cfg_cli.h @@ -23,56 +23,235 @@ extern "C" { /** Mesh Configuration Client Model Context */ struct bt_mesh_cfg_cli { + /** Composition data model entry pointer. */ struct bt_mesh_model *model; + /* Internal parameters for tracking message responses. */ struct k_sem op_sync; u32_t op_pending; void *op_param; }; -extern const struct bt_mesh_model_op bt_mesh_cfg_cli_op[]; -extern const struct bt_mesh_model_cb bt_mesh_cfg_cli_cb; - +/** @def BT_MESH_MODEL_CFG_CLI + * + * @brief Generic Configuration Client model composition data entry. + * + * @param cli_data Pointer to a @ref bt_mesh_cfg_cli instance. + */ #define BT_MESH_MODEL_CFG_CLI(cli_data) \ BT_MESH_MODEL_CB(BT_MESH_MODEL_ID_CFG_CLI, bt_mesh_cfg_cli_op, NULL, \ cli_data, &bt_mesh_cfg_cli_cb) +/** @brief Get the target node's composition data. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param page Composition data page, or 0xff to request the first available + * page. + * @param status Status response parameter. + * @param comp Composition data buffer to fill. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_comp_data_get(u16_t net_idx, u16_t addr, u8_t page, u8_t *status, struct net_buf_simple *comp); +/** @brief Get the target node's network beacon state. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param status Status response parameter, returns one of + * @ref BT_MESH_BEACON_DISABLED or @ref BT_MESH_BEACON_ENABLED + * on success. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_beacon_get(u16_t net_idx, u16_t addr, u8_t *status); +/** @brief Set the target node's network beacon state. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param val New network beacon state, should be one of + * @ref BT_MESH_BEACON_DISABLED or @ref BT_MESH_BEACON_ENABLED. + * @param status Status response parameter. Returns one of + * @ref BT_MESH_BEACON_DISABLED or @ref BT_MESH_BEACON_ENABLED + * on success. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_beacon_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *status); +/** @brief Get the target node's Time To Live value. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param ttl TTL response buffer. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_ttl_get(u16_t net_idx, u16_t addr, u8_t *ttl); +/** @brief Set the target node's Time To Live value. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param val New Time To Live value. + * @param ttl TTL response buffer. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_ttl_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *ttl); +/** @brief Get the target node's Friend feature status. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param status Status response parameter. Returns one of + * @ref BT_MESH_FRIEND_DISABLED, @ref BT_MESH_FRIEND_ENABLED or + * @ref BT_MESH_FRIEND_NOT_SUPPORTED on success. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_friend_get(u16_t net_idx, u16_t addr, u8_t *status); +/** @brief Set the target node's Friend feature state. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param val New Friend feature state. Should be one of + * @ref BT_MESH_FRIEND_DISABLED or + * @ref BT_MESH_FRIEND_ENABLED. + * @param status Status response parameter. Returns one of + * @ref BT_MESH_FRIEND_DISABLED, @ref BT_MESH_FRIEND_ENABLED or + * @ref BT_MESH_FRIEND_NOT_SUPPORTED on success. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_friend_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *status); +/** @brief Get the target node's Proxy feature state. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param status Status response parameter. Returns one of + * @ref BT_MESH_GATT_PROXY_DISABLED, + * @ref BT_MESH_GATT_PROXY_ENABLED or + * @ref BT_MESH_GATT_PROXY_NOT_SUPPORTED on success. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_gatt_proxy_get(u16_t net_idx, u16_t addr, u8_t *status); +/** @brief Set the target node's Proxy feature state. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param val New Proxy feature state. Must be one of + * @ref BT_MESH_GATT_PROXY_DISABLED or + * @ref BT_MESH_GATT_PROXY_ENABLED. + * @param status Status response parameter. Returns one of + * @ref BT_MESH_GATT_PROXY_DISABLED, + * @ref BT_MESH_GATT_PROXY_ENABLED or + * @ref BT_MESH_GATT_PROXY_NOT_SUPPORTED on success. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_gatt_proxy_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *status); +/** @brief Get the target node's Relay feature state. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param status Status response parameter. Returns one of + * @ref BT_MESH_RELAY_DISABLED, @ref BT_MESH_RELAY_ENABLED or + * @ref BT_MESH_RELAY_NOT_SUPPORTED on success. + * @param transmit Transmit response parameter. Returns the encoded relay + * transmission parameters on success. Decoded with + * @ref BT_MESH_TRANSMIT_COUNT and @ref BT_MESH_TRANSMIT_INT. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_relay_get(u16_t net_idx, u16_t addr, u8_t *status, u8_t *transmit); +/** @brief Set the target node's Relay parameters. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param new_relay New relay state. Must be one of + * @ref BT_MESH_RELAY_DISABLED or + * @ref BT_MESH_RELAY_ENABLED. + * @param new_transmit New encoded relay transmit parameters. + * @see BT_MESH_TRANSMIT. + * @param status Status response parameter. Returns one of + * @ref BT_MESH_RELAY_DISABLED, @ref BT_MESH_RELAY_ENABLED + * or @ref BT_MESH_RELAY_NOT_SUPPORTED on success. + * @param transmit Transmit response parameter. Returns the encoded relay + * transmission parameters on success. Decoded with + * @ref BT_MESH_TRANSMIT_COUNT and + * @ref BT_MESH_TRANSMIT_INT. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_relay_set(u16_t net_idx, u16_t addr, u8_t new_relay, u8_t new_transmit, u8_t *status, u8_t *transmit); +/** @brief Add a network key to the target node. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param key_net_idx Network key index. + * @param net_key Network key. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_net_key_add(u16_t net_idx, u16_t addr, u16_t key_net_idx, const u8_t net_key[16], u8_t *status); +/** @brief Add an application key to the target node. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param key_net_idx Network key index the application key belongs to. + * @param key_app_idx Application key index. + * @param app_key Application key. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_app_key_add(u16_t net_idx, u16_t addr, u16_t key_net_idx, u16_t key_app_idx, const u8_t app_key[16], u8_t *status); +/** @brief Bind an application to a SIG model on the target node. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param mod_app_idx Application index to bind. + * @param mod_id Model ID. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_app_bind(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_app_idx, u16_t mod_id, u8_t *status); +/** @brief Bind an application to a vendor model on the target node. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param mod_app_idx Application index to bind. + * @param mod_id Model ID. + * @param cid Company ID of the model. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_app_bind_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_app_idx, u16_t mod_id, u16_t cid, u8_t *status); @@ -119,111 +298,439 @@ int bt_mesh_cfg_mod_app_bind_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, */ #define BT_MESH_PUB_PERIOD_10MIN(steps) (((steps) & BIT_MASK(6)) | (3 << 6)) +/** Model publication configuration parameters. */ struct bt_mesh_cfg_mod_pub { + /** Publication destination address. */ u16_t addr; + /** Application index to publish with. */ u16_t app_idx; + /** Friendship credential flag. */ bool cred_flag; + /** Time To Live to publish with. */ u8_t ttl; + /** + * Encoded publish period. + * @see BT_MESH_PUB_PERIOD_100MS, BT_MESH_PUB_PERIOD_SEC, + * BT_MESH_PUB_PERIOD_10SEC, + * BT_MESH_PUB_PERIOD_10MIN + */ u8_t period; + /** + * Encoded transmit parameters. + * @see BT_MESH_TRANSMIT + */ u8_t transmit; }; +/** @brief Get publish parameters for a SIG model on the target node. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param mod_id Model ID. + * @param pub Publication parameter return buffer. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_pub_get(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, struct bt_mesh_cfg_mod_pub *pub, u8_t *status); +/** @brief Get publish parameters for a vendor model on the target node. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param mod_id Model ID. + * @param cid Company ID of the model. + * @param pub Publication parameter return buffer. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_pub_get_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, u16_t cid, struct bt_mesh_cfg_mod_pub *pub, u8_t *status); +/** @brief Set publish parameters for a SIG model on the target node. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param mod_id Model ID. + * @param pub Publication parameters. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_pub_set(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, struct bt_mesh_cfg_mod_pub *pub, u8_t *status); +/** @brief Set publish parameters for a vendor model on the target node. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param mod_id Model ID. + * @param cid Company ID of the model. + * @param pub Publication parameters. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_pub_set_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, u16_t cid, struct bt_mesh_cfg_mod_pub *pub, u8_t *status); +/** @brief Add a group address to a SIG model's subscription list. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param sub_addr Group address to add to the subscription list. + * @param mod_id Model ID. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_add(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u8_t *status); +/** @brief Add a group address to a vendor model's subscription list. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param sub_addr Group address to add to the subscription list. + * @param mod_id Model ID. + * @param cid Company ID of the model. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_add_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u16_t cid, u8_t *status); +/** @brief Delete a group address in a SIG model's subscription list. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param sub_addr Group address to add to the subscription list. + * @param mod_id Model ID. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_del(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u8_t *status); +/** @brief Delete a group address in a vendor model's subscription list. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param sub_addr Group address to add to the subscription list. + * @param mod_id Model ID. + * @param cid Company ID of the model. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_del_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u16_t cid, u8_t *status); +/** @brief Overwrite all addresses in a SIG model's subscription list with a + * group address. + * + * Deletes all subscriptions in the model's subscription list, and adds a + * single group address instead. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param sub_addr Group address to add to the subscription list. + * @param mod_id Model ID. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_overwrite(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u8_t *status); +/** @brief Overwrite all addresses in a vendor model's subscription list with a + * group address. + * + * Deletes all subscriptions in the model's subscription list, and adds a + * single group address instead. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param sub_addr Group address to add to the subscription list. + * @param mod_id Model ID. + * @param cid Company ID of the model. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_overwrite_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u16_t cid, u8_t *status); +/** @brief Add a virtual address to a SIG model's subscription list. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param label Virtual address label to add to the subscription list. + * @param mod_id Model ID. + * @param virt_addr Virtual address response parameter. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_va_add(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t *virt_addr, u8_t *status); +/** @brief Add a virtual address to a vendor model's subscription list. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param label Virtual address label to add to the subscription list. + * @param mod_id Model ID. + * @param cid Company ID of the model. + * @param virt_addr Virtual address response parameter. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_va_add_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t cid, u16_t *virt_addr, u8_t *status); +/** @brief Delete a virtual address in a SIG model's subscription list. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param label Virtual address parameter to add to the subscription list. + * @param mod_id Model ID. + * @param virt_addr Virtual address response parameter. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_va_del(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t *virt_addr, u8_t *status); +/** @brief Delete a virtual address in a vendor model's subscription list. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param label Virtual address label to add to the subscription list. + * @param mod_id Model ID. + * @param cid Company ID of the model. + * @param virt_addr Virtual address response parameter. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_va_del_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t cid, u16_t *virt_addr, u8_t *status); +/** @brief Overwrite all addresses in a SIG model's subscription list with a + * virtual address. + * + * Deletes all subscriptions in the model's subscription list, and adds a + * single group address instead. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param label Virtual address label to add to the subscription list. + * @param mod_id Model ID. + * @param virt_addr Virtual address response parameter. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_va_overwrite(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t *virt_addr, u8_t *status); +/** @brief Overwrite all addresses in a vendor model's subscription list with a + * virtual address. + * + * Deletes all subscriptions in the model's subscription list, and adds a + * single group address instead. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param elem_addr Element address the model is in. + * @param label Virtual address label to add to the subscription list. + * @param mod_id Model ID. + * @param cid Company ID of the model. + * @param virt_addr Virtual address response parameter. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_mod_sub_va_overwrite_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t cid, u16_t *virt_addr, u8_t *status); +/** Heartbeat subscription configuration parameters. */ struct bt_mesh_cfg_hb_sub { + /** Source address to receive Heartbeat messages from. */ u16_t src; + /** Destination address to receive Heartbeat messages on. */ u16_t dst; + /** + * Logarithmic subscription period to keep listening for. + * The decoded subscription period is (1 << (period - 1)), or 0 if + * period is 0. + */ u8_t period; + /** + * Logarithmic Heartbeat subscription receive count. + * The decoded Heartbeat count is (1 << (count - 1)) if count is + * between 1 and 0xfe, 0 if count is 0 and 0xffff if count is 0xff. + * + * Ignored in Heartbeat subscription set. + */ u8_t count; + /** + * Minimum hops in received messages, ie the shortest registered path + * from the publishing node to the subscribing node. A Heartbeat + * received from an immediate neighbor has hop count = 1. + * + * Ignored in Heartbeat subscription set. + */ u8_t min; + /** + * Maximum hops in received messages, ie the longest registered path + * from the publishing node to the subscribing node. A Heartbeat + * received from an immediate neighbor has hop count = 1. + * + * Ignored in Heartbeat subscription set. + */ u8_t max; }; +/** @brief Set the target node's Heartbeat subscription parameters. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param sub New Heartbeat subscription parameters. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_hb_sub_set(u16_t net_idx, u16_t addr, struct bt_mesh_cfg_hb_sub *sub, u8_t *status); +/** @brief Get the target node's Heartbeta subscription parameters. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param sub Heartbeat subscription parameter return buffer. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_hb_sub_get(u16_t net_idx, u16_t addr, struct bt_mesh_cfg_hb_sub *sub, u8_t *status); +/** Heartbeat publication configuration parameters. */ struct bt_mesh_cfg_hb_pub { + /** Heartbeat destination address. */ u16_t dst; + /** + * Logarithmic Heartbeat count. Decoded as (1 << (count - 1)) if count + * is between 1 and 0x11, 0 if count is 0, or "indefinitely" if count is + * 0xff. + * + * When used in Heartbeat publication set, this parameter denotes the + * number of Heartbeat messages to send. + * + * When returned from Heartbeat publication get, this parameter denotes + * the number of Heartbeat messages remaining to be sent. + */ u8_t count; + /** + * Logarithmic Heartbeat publication transmit interval in seconds. + * Decoded as (1 << (period - 1)) if period is between 1 and 0x11. + * If period is 0, Heartbeat publication is disabled. + */ u8_t period; + /** Publication message Time To Live value. */ u8_t ttl; + /** + * Bitmap of features that trigger Heartbeat publications. + * Legal values are @ref BT_MESH_FEAT_RELAY, + * @ref BT_MESH_FEAT_PROXY, @ref BT_MESH_FEAT_FRIEND and + * @ref BT_MESH_FEAT_LOW_POWER + */ u16_t feat; + /** Network index to publish with. */ u16_t net_idx; }; +/** @brief Set the target node's Heartbeat publication parameters. + * + * @note The target node must already have received the specified network key. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param pub New Heartbeat publication parameters. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_hb_pub_set(u16_t net_idx, u16_t addr, const struct bt_mesh_cfg_hb_pub *pub, u8_t *status); +/** @brief Get the target node's Heartbeat publication parameters. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node address. + * @param pub Heartbeat publication parameter return buffer. + * @param status Status response parameter. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_cfg_hb_pub_get(u16_t net_idx, u16_t addr, struct bt_mesh_cfg_hb_pub *pub, u8_t *status); +/** @brief Get the current transmission timeout value. + * + * @return The configured transmission timeout. + */ s32_t bt_mesh_cfg_cli_timeout_get(void); + +/** @brief Set the transmission timeout value. + * + * @param timeout The new transmission timeout. + */ void bt_mesh_cfg_cli_timeout_set(s32_t timeout); +/** @cond INTERNAL_HIDDEN */ +extern const struct bt_mesh_model_op bt_mesh_cfg_cli_op[]; +extern const struct bt_mesh_model_cb bt_mesh_cfg_cli_cb; +/** @endcond */ + #ifdef __cplusplus } #endif diff --git a/include/bluetooth/mesh/cfg_srv.h b/include/bluetooth/mesh/cfg_srv.h index 06b5d46b044..d53a4fad9d5 100644 --- a/include/bluetooth/mesh/cfg_srv.h +++ b/include/bluetooth/mesh/cfg_srv.h @@ -23,50 +23,96 @@ extern "C" { /** Mesh Configuration Server Model Context */ struct bt_mesh_cfg_srv { + /** Composition data model entry pointer. */ struct bt_mesh_model *model; - u8_t net_transmit; /* Network Transmit state */ - u8_t relay; /* Relay Mode state */ - u8_t relay_retransmit; /* Relay Retransmit state */ - u8_t beacon; /* Secure Network Beacon state */ - u8_t gatt_proxy; /* GATT Proxy state */ - u8_t frnd; /* Friend state */ - u8_t default_ttl; /* Default TTL */ + u8_t net_transmit; /**< Network Transmit state */ + u8_t relay; /**< Relay Mode state */ + u8_t relay_retransmit; /**< Relay Retransmit state */ + u8_t beacon; /**< Secure Network Beacon state */ + u8_t gatt_proxy; /**< GATT Proxy state */ + u8_t frnd; /**< Friend state */ + u8_t default_ttl; /**< Default TTL */ - /* Heartbeat Publication */ + /** Heartbeat Publication parameters */ struct bt_mesh_hb_pub { struct k_delayed_work timer; + /** Destination address. */ u16_t dst; + /** Remaining publish count. */ u16_t count; + /** Logarithmic publish interval in seconds. */ u8_t period; + /** Time To Live value. */ u8_t ttl; + /** + * Bitmap of features that trigger a Heartbeat publication if + * they change. Legal values are + * @ref BT_MESH_FEAT_RELAY, @ref BT_MESH_FEAT_PROXY, + * @ref BT_MESH_FEAT_FRIEND and @ref BT_MESH_FEAT_LOW_POWER. + */ u16_t feat; + /** Network index used for publishing. */ u16_t net_idx; } hb_pub; - /* Heartbeat Subscription */ + /** Heartbeat Subscription parameters. */ struct bt_mesh_hb_sub { + /** Subscription period exipration timestamp. */ s64_t expiry; - + /** Source address to receive Heartbeats from. */ u16_t src; + /** Destination address to received Heartbeats on. */ u16_t dst; + /** The number of received Heartbeat messages so far. */ u16_t count; + /** + * Minimum hops in received messages, ie the shortest registered + * path from the publishing node to the subscribing node. A + * Heartbeat received from an immediate neighbor has hop + * count = 1. + */ u8_t min_hops; + /** + * Maximum hops in received messages, ie the longest registered + * path from the publishing node to the subscribing node. A + * Heartbeat received from an immediate neighbor has hop + * count = 1. + */ u8_t max_hops; - /* Optional subscription tracking function */ + /** @brief Optional Heartbeat subscription tracking callback. + * + * Gets called on every received Heartbeat. + * + * @param hops The number of hops the Heartbeat was received + * with. + * @param feat The feature set of the publishing node. The + * value is a bitmap of @ref BT_MESH_FEAT_RELAY, + * @ref BT_MESH_FEAT_PROXY, + * @ref BT_MESH_FEAT_FRIEND and + * @ref BT_MESH_FEAT_LOW_POWER. + */ void (*func)(u8_t hops, u16_t feat); } hb_sub; }; -extern const struct bt_mesh_model_op bt_mesh_cfg_srv_op[]; -extern const struct bt_mesh_model_cb bt_mesh_cfg_srv_cb; - +/** @def BT_MESH_MODEL_CFG_SRV + * + * @brief Generic Configuration Server model composition data entry. + * + * @param srv_data Pointer to a @ref bt_mesh_cfg_srv instance. + */ #define BT_MESH_MODEL_CFG_SRV(srv_data) \ BT_MESH_MODEL_CB(BT_MESH_MODEL_ID_CFG_SRV, bt_mesh_cfg_srv_op, NULL, \ srv_data, &bt_mesh_cfg_srv_cb) +/** @cond INTERNAL_HIDDEN */ +extern const struct bt_mesh_model_op bt_mesh_cfg_srv_op[]; +extern const struct bt_mesh_model_cb bt_mesh_cfg_srv_cb; +/** @endcond */ + #ifdef __cplusplus } #endif diff --git a/include/bluetooth/mesh/health_cli.h b/include/bluetooth/mesh/health_cli.h index 80701abcb19..e8e41667792 100644 --- a/include/bluetooth/mesh/health_cli.h +++ b/include/bluetooth/mesh/health_cli.h @@ -23,53 +23,183 @@ extern "C" { /** Mesh Health Client Model Context */ struct bt_mesh_health_cli { + /** Composition data model entry pointer. */ struct bt_mesh_model *model; + /** @brief Optional callback for Health Current Status messages. + * + * Handles received Health Current Status messages from a Health + * server. The @c fault array represents all faults that are + * currently present in the server's element. + * + * @see bt_mesh_health_faults + * + * @param cli Health client that received the status message. + * @param addr Address of the sender. + * @param test_id Identifier of a most recently performed test. + * @param cid Company Identifier of the node. + * @param faults Array of faults. + * @param fault_count Number of faults in the fault array. + */ void (*current_status)(struct bt_mesh_health_cli *cli, u16_t addr, u8_t test_id, u16_t cid, u8_t *faults, size_t fault_count); + /* Internal parameters for tracking message responses. */ struct k_sem op_sync; u32_t op_pending; void *op_param; }; -extern const struct bt_mesh_model_op bt_mesh_health_cli_op[]; -extern const struct bt_mesh_model_cb bt_mesh_health_cli_cb; +/** @def BT_MESH_MODEL_HEALTH_CLI + * + * @brief Generic Health Client model composition data entry. + * + * @param cli_data Pointer to a @ref bt_mesh_health_cli instance. + */ #define BT_MESH_MODEL_HEALTH_CLI(cli_data) \ BT_MESH_MODEL_CB(BT_MESH_MODEL_ID_HEALTH_CLI, bt_mesh_health_cli_op, \ NULL, cli_data, &bt_mesh_health_cli_cb) +/** @brief Set Health client model instance to use for communication. + * + * @param model Health Client model instance from the composition data. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_health_cli_set(struct bt_mesh_model *model); +/** @brief Get the registered fault state for the given Company ID. + * + * @see bt_mesh_health_faults + * + * @param net_idx Network index to encrypt with. + * @param addr Target node element address. + * @param app_idx Application index to encrypt with. + * @param cid Company ID to get the registered faults of. + * @param test_id Test ID response buffer. + * @param faults Fault array response buffer. + * @param fault_count Fault count response buffer. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_health_fault_get(u16_t net_idx, u16_t addr, u16_t app_idx, u16_t cid, u8_t *test_id, u8_t *faults, size_t *fault_count); +/** @brief Clear the registered faults for the given Company ID. + * + * @see bt_mesh_health_faults + * + * @param net_idx Network index to encrypt with. + * @param addr Target node element address. + * @param app_idx Application index to encrypt with. + * @param cid Company ID to clear the registered faults for. + * @param test_id Test ID response buffer. + * @param faults Fault array response buffer. + * @param fault_count Fault count response buffer. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_health_fault_clear(u16_t net_idx, u16_t addr, u16_t app_idx, u16_t cid, u8_t *test_id, u8_t *faults, size_t *fault_count); +/** @brief Invoke a self-test procedure for the given Company ID. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node element address. + * @param app_idx Application index to encrypt with. + * @param cid Company ID to invoke the test for. + * @param test_id Test ID response buffer. + * @param faults Fault array response buffer. + * @param fault_count Fault count response buffer. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_health_fault_test(u16_t net_idx, u16_t addr, u16_t app_idx, u16_t cid, u8_t test_id, u8_t *faults, size_t *fault_count); +/** @brief Get the target node's Health fast period divisor. + * + * The health period divisor is used to increase the publish rate when a fault + * is registered. Normally, the Health server will publish with the period in + * the configured publish parameters. When a fault is registered, the publish + * period is divided by (1 << divisor). For example, if the target node's + * Health server is configured to publish with a period of 16 seconds, and the + * Health fast period divisor is 5, the Health server will publish with an + * interval of 500 ms when a fault is registered. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node element address. + * @param app_idx Application index to encrypt with. + * @param divisor Health period divisor response buffer. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_health_period_get(u16_t net_idx, u16_t addr, u16_t app_idx, u8_t *divisor); +/** @brief Set the target node's Health fast period divisor. + * + * @copydetails bt_mesh_health_period_get + * + * @param net_idx Network index to encrypt with. + * @param addr Target node element address. + * @param app_idx Application index to encrypt with. + * @param divisor New Health period divisor. + * @param updated_divisor Health period divisor response buffer. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_health_period_set(u16_t net_idx, u16_t addr, u16_t app_idx, u8_t divisor, u8_t *updated_divisor); +/** @brief Get the current attention timer value. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node element address. + * @param app_idx Application index to encrypt with. + * @param attention Attention timer response buffer, measured in seconds. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_health_attention_get(u16_t net_idx, u16_t addr, u16_t app_idx, u8_t *attention); +/** @brief Set the attention timer. + * + * @param net_idx Network index to encrypt with. + * @param addr Target node element address. + * @param app_idx Application index to encrypt with. + * @param attention New attention timer time, in seconds. + * @param updated_attention Attention timer response buffer, measured in + * seconds. + * + * @return 0 on success, or (negative) error code on failure. + */ int bt_mesh_health_attention_set(u16_t net_idx, u16_t addr, u16_t app_idx, u8_t attention, u8_t *updated_attention); +/** @brief Get the current transmission timeout value. + * + * @return The configured transmission timeout. + */ s32_t bt_mesh_health_cli_timeout_get(void); + +/** @brief Set the transmission timeout value. + * + * @param timeout The new transmission timeout. + */ void bt_mesh_health_cli_timeout_set(s32_t timeout); +/** @cond INTERNAL_HIDDEN */ +extern const struct bt_mesh_model_op bt_mesh_health_cli_op[]; +extern const struct bt_mesh_model_cb bt_mesh_health_cli_cb; +/** @endcond */ + #ifdef __cplusplus } #endif diff --git a/include/bluetooth/mesh/health_srv.h b/include/bluetooth/mesh/health_srv.h index e06ead93a32..029e398de52 100644 --- a/include/bluetooth/mesh/health_srv.h +++ b/include/bluetooth/mesh/health_srv.h @@ -23,27 +23,114 @@ extern "C" { /** Callback function for the Health Server model */ struct bt_mesh_health_srv_cb { - /* Fetch current faults */ + /** @brief Callback for fetching current faults. + * + * Fault values may either be defined by the specification, or by a + * vendor. Vendor specific faults should be interpreted in the context + * of the accompanying Company ID. Specification defined faults may be + * reported for any Company ID, and the same fault may be presented + * for multiple Company IDs. + * + * All faults shall be associated with at least one Company ID, + * representing the device vendor or some other vendor whose vendor + * specific fault values are used. + * + * If there are multiple Company IDs that have active faults, + * return only the faults associated with one of them at the time. + * To report faults for multiple Company IDs, interleave which Company + * ID is reported for each call. + * + * @param model Health Server model instance to get faults of. + * @param test_id Test ID response buffer. + * @param company_id Company ID response buffer. + * @param faults Array to fill with current faults. + * @param fault_count The number of faults the fault array can fit. + * Should be updated to reflect the number of faults + * copied into the array. + * + * @return 0 on success, or (negative) error code otherwise. + */ int (*fault_get_cur)(struct bt_mesh_model *model, u8_t *test_id, u16_t *company_id, u8_t *faults, u8_t *fault_count); - /* Fetch registered faults */ + /** @brief Callback for fetching all registered faults. + * + * Registered faults are all past and current faults since the last + * call to @c fault_clear. Only faults associated with the given + * Company ID should be reported. + * + * Fault values may either be defined by the specification, or by a + * vendor. Vendor specific faults should be interpreted in the context + * of the accompanying Company ID. Specification defined faults may be + * reported for any Company ID, and the same fault may be presented + * for multiple Company IDs. + * + * @param model Health Server model instance to get faults of. + * @param company_id Company ID to get faults for. + * @param test_id Test ID response buffer. + * @param faults Array to fill with registered faults. + * @param fault_count The number of faults the fault array can fit. + * Should be updated to reflect the number of faults + * copied into the array. + * + * @return 0 on success, or (negative) error code otherwise. + */ int (*fault_get_reg)(struct bt_mesh_model *model, u16_t company_id, u8_t *test_id, u8_t *faults, u8_t *fault_count); - /* Clear registered faults */ + /** @brief Clear all registered faults associated with the given Company + * ID. + * + * @param model Health Server model instance to clear faults of. + * @param company_id Company ID to clear faults for. + * + * @return 0 on success, or (negative) error code otherwise. + */ int (*fault_clear)(struct bt_mesh_model *model, u16_t company_id); - /* Run a specific test */ + /** @brief Run a self-test. + * + * The Health server may support up to 256 self-tests for each Company + * ID. The behavior for all test IDs are vendor specific, and should be + * interpreted based on the accompanying Company ID. Test failures + * should result in changes to the fault array. + * + * @param model Health Server model instance to run test for. + * @param test_id Test ID to run. + * @param company_id Company ID to run test for. + * + * @return 0 if the test execution was started successfully, or + * (negative) error code otherwise. Note that the fault array will not + * be reported back to the client if the test execution didn't start. + */ int (*fault_test)(struct bt_mesh_model *model, u8_t test_id, u16_t company_id); - /* Attention on */ + /** @brief Start calling attention to the device. + * + * The attention state is used to map an element address to a + * physical device. When this callback is called, the device should + * start some physical procedure meant to call attention to itself, + * like blinking, buzzing, vibrating or moving. If there are multiple + * Health server instances on the device, the attention state should + * also help identify the specific element the server is in. + * + * The attention calling behavior should continue until the @c attn_off + * callback is called. + * + * @param model Health Server model to start the attention state of. + */ void (*attn_on)(struct bt_mesh_model *model); - /* Attention off */ + /** @brief Stop the attention state. + * + * Any physical activity started to call attention to the device should + * be stopped. + * + * @param model + */ void (*attn_off)(struct bt_mesh_model *model); }; @@ -51,7 +138,7 @@ struct bt_mesh_health_srv_cb { * * A helper to define a health publication context * - * @param _name Name given to the publication context variable. + * @param _name Name given to the publication context variable. * @param _max_faults Maximum number of faults the element can have. */ #define BT_MESH_HEALTH_PUB_DEFINE(_name, _max_faults) \ @@ -59,22 +146,16 @@ struct bt_mesh_health_srv_cb { /** Mesh Health Server Model Context */ struct bt_mesh_health_srv { + /** Composition data model entry pointer. */ struct bt_mesh_model *model; - /* Optional callback struct */ + /** Optional callback struct */ const struct bt_mesh_health_srv_cb *cb; - /* Attention Timer state */ + /** Attention Timer state */ struct k_delayed_work attn_timer; }; -int bt_mesh_fault_update(struct bt_mesh_elem *elem); - -/** @cond INTERNAL_HIDDEN */ -extern const struct bt_mesh_model_op bt_mesh_health_srv_op[]; -extern const struct bt_mesh_model_cb bt_mesh_health_srv_cb; -/** @endcond */ - /** @def BT_MESH_MODEL_HEALTH_SRV * * Define a new health server model. Note that this API needs to be @@ -91,6 +172,23 @@ extern const struct bt_mesh_model_cb bt_mesh_health_srv_cb; BT_MESH_MODEL_CB(BT_MESH_MODEL_ID_HEALTH_SRV, bt_mesh_health_srv_op, \ pub, srv, &bt_mesh_health_srv_cb) +/** @brief Notify the stack that the fault array state of the given element has + * changed. + * + * This prompts the Health server on this element to publish the current fault + * array if periodic publishing is disabled. + * + * @param elem Element to update the fault state of. + * + * @return 0 on success, or (negative) error code otherwise. + */ +int bt_mesh_fault_update(struct bt_mesh_elem *elem); + +/** @cond INTERNAL_HIDDEN */ +extern const struct bt_mesh_model_op bt_mesh_health_srv_op[]; +extern const struct bt_mesh_model_cb bt_mesh_health_srv_cb; +/** @endcond */ + #ifdef __cplusplus } #endif diff --git a/include/bluetooth/mesh/main.h b/include/bluetooth/mesh/main.h index 82944d7c7a6..492f79dec5d 100644 --- a/include/bluetooth/mesh/main.h +++ b/include/bluetooth/mesh/main.h @@ -21,6 +21,7 @@ extern "C" { #endif +/** Available Provisioning output authentication actions. */ typedef enum { BT_MESH_NO_OUTPUT = 0, BT_MESH_BLINK = BIT(0), @@ -30,6 +31,7 @@ typedef enum { BT_MESH_DISPLAY_STRING = BIT(4), } bt_mesh_output_action_t; +/** Available Provisioning input authentication actions. */ typedef enum { BT_MESH_NO_INPUT = 0, BT_MESH_PUSH = BIT(0), @@ -38,11 +40,13 @@ typedef enum { BT_MESH_ENTER_STRING = BIT(3), } bt_mesh_input_action_t; +/** Available Provisioning bearers. */ typedef enum { BT_MESH_PROV_ADV = BIT(0), BT_MESH_PROV_GATT = BIT(1), } bt_mesh_prov_bearer_t; +/** Out of Band information location. */ typedef enum { BT_MESH_PROV_OOB_OTHER = BIT(0), BT_MESH_PROV_OOB_URI = BIT(1), @@ -84,7 +88,7 @@ struct bt_mesh_prov { /** Supported Output OOB Actions */ u16_t output_actions; - /* Maximum size of Input OOB supported */ + /** Maximum size of Input OOB supported */ u8_t input_size; /** Supported Input OOB Actions */ u16_t input_actions; @@ -130,21 +134,21 @@ struct bt_mesh_prov { /** @brief The other device finished their OOB input. * - * This callback notifies the application that it should stop - * displaying its output OOB value, as the other party finished their - * OOB input. + * This callback notifies the application that it should stop + * displaying its output OOB value, as the other party finished their + * OOB input. */ void (*input_complete)(void); /** @brief Unprovisioned beacon has been received. * - * This callback notifies the application that an unprovisioned - * beacon has been received. + * This callback notifies the application that an unprovisioned + * beacon has been received. * - * @param uuid UUID - * @param oob_info OOB Information - * @param uri_hash Pointer to URI Hash value. NULL if no hash was - * present in the beacon. + * @param uuid UUID + * @param oob_info OOB Information + * @param uri_hash Pointer to URI Hash value. NULL if no hash was + * present in the beacon. */ void (*unprovisioned_beacon)(u8_t uuid[16], bt_mesh_prov_oob_info_t oob_info, @@ -175,7 +179,7 @@ struct bt_mesh_prov { * assigned the specified NetKeyIndex and primary element address. * * @param net_idx NetKeyIndex given during provisioning. - * @param addr Primary element address. + * @param addr Primary element address. */ void (*complete)(u16_t net_idx, u16_t addr); @@ -185,8 +189,8 @@ struct bt_mesh_prov { * been successfully completed, and that a node has been assigned * the specified NetKeyIndex and primary element address. * - * @param net_idx NetKeyIndex given during provisioning. - * @param addr Primary element address. + * @param net_idx NetKeyIndex given during provisioning. + * @param addr Primary element address. * @param num_elem Number of elements that this node has. */ void (*node_added)(u16_t net_idx, u16_t addr, u8_t num_elem); @@ -265,13 +269,13 @@ int bt_mesh_provision(const u8_t net_key[16], u16_t net_idx, /** @brief Provision a Mesh Node using PB-ADV * - * @param uuid UUID - * @param net_idx Network Key Index - * @param addr Address to assign to remote device. If addr is 0, the lowest - * available address will be chosen. - * @param attention_duration The attention duration to be send to remote device + * @param uuid UUID + * @param net_idx Network Key Index + * @param addr Address to assign to remote device. If addr is 0, + * the lowest available address will be chosen. + * @param attention_duration The attention duration to be send to remote device * - * @return Zero on success or (negative) error code otherwise. + * @return Zero on success or (negative) error code otherwise. */ int bt_mesh_provision_adv(const u8_t uuid[16], u16_t net_idx, u16_t addr, u8_t attention_duration); diff --git a/include/bluetooth/mesh/proxy.h b/include/bluetooth/mesh/proxy.h index a255d3085a2..4971ad6f0e8 100644 --- a/include/bluetooth/mesh/proxy.h +++ b/include/bluetooth/mesh/proxy.h @@ -21,14 +21,13 @@ extern "C" { #endif -/** - * @brief Enable advertising with Node Identity. +/** @brief Enable advertising with Node Identity. * - * This API requires that GATT Proxy support has been enabled. Once called - * each subnet will start advertising using Node Identity for the next - * 60 seconds. + * This API requires that GATT Proxy support has been enabled. Once called + * each subnet will start advertising using Node Identity for the next + * 60 seconds. * - * @return 0 on success, or (negative) error code on failure. + * @return 0 on success, or (negative) error code on failure. */ int bt_mesh_proxy_identity_enable(void);