/** @file * @brief Runtime configuration APIs. */ /* * Copyright (c) 2020 Nordic Semiconductor * * SPDX-License-Identifier: Apache-2.0 */ #ifndef ZEPHYR_INCLUDE_BLUETOOTH_MESH_CFG_H_ #define ZEPHYR_INCLUDE_BLUETOOTH_MESH_CFG_H_ #include #include #include /** * @brief Runtime Configuration * @defgroup bt_mesh_cfg Runtime Configuration * @ingroup bt_mesh * @{ */ #ifdef __cplusplus extern "C" { #endif /** Bluetooth mesh feature states */ enum bt_mesh_feat_state { /** Feature is supported, but disabled. */ BT_MESH_FEATURE_DISABLED, /** Feature is supported and enabled. */ BT_MESH_FEATURE_ENABLED, /** Feature is not supported, and cannot be enabled. */ BT_MESH_FEATURE_NOT_SUPPORTED, }; /* Key Refresh Phase */ #define BT_MESH_KR_NORMAL 0x00 #define BT_MESH_KR_PHASE_1 0x01 #define BT_MESH_KR_PHASE_2 0x02 #define BT_MESH_KR_PHASE_3 0x03 /* Legacy feature defines */ #define BT_MESH_RELAY_DISABLED BT_MESH_FEATURE_DISABLED #define BT_MESH_RELAY_ENABLED BT_MESH_FEATURE_ENABLED #define BT_MESH_RELAY_NOT_SUPPORTED BT_MESH_FEATURE_NOT_SUPPORTED #define BT_MESH_BEACON_DISABLED BT_MESH_FEATURE_DISABLED #define BT_MESH_BEACON_ENABLED BT_MESH_FEATURE_ENABLED #define BT_MESH_GATT_PROXY_DISABLED BT_MESH_FEATURE_DISABLED #define BT_MESH_GATT_PROXY_ENABLED BT_MESH_FEATURE_ENABLED #define BT_MESH_GATT_PROXY_NOT_SUPPORTED BT_MESH_FEATURE_NOT_SUPPORTED #define BT_MESH_FRIEND_DISABLED BT_MESH_FEATURE_DISABLED #define BT_MESH_FRIEND_ENABLED BT_MESH_FEATURE_ENABLED #define BT_MESH_FRIEND_NOT_SUPPORTED BT_MESH_FEATURE_NOT_SUPPORTED #define BT_MESH_NODE_IDENTITY_STOPPED BT_MESH_FEATURE_DISABLED #define BT_MESH_NODE_IDENTITY_RUNNING BT_MESH_FEATURE_ENABLED #define BT_MESH_NODE_IDENTITY_NOT_SUPPORTED BT_MESH_FEATURE_NOT_SUPPORTED /** @brief Enable or disable sending of the Secure Network Beacon. * * @param beacon New Secure Network Beacon state. */ void bt_mesh_beacon_set(bool beacon); /** @brief Get the current Secure Network Beacon state. * * @returns Whether the Secure Network Beacon feature is enabled. */ bool bt_mesh_beacon_enabled(void); /** @brief Set the default TTL value. * * The default TTL value is used when no explicit TTL value is set. Models will * use the default TTL value when @ref bt_mesh_msg_ctx::send_ttl is * @ref BT_MESH_TTL_DEFAULT. * * @param default_ttl The new default TTL value. Valid values are 0x00 and 0x02 * to @ref BT_MESH_TTL_MAX. * * @retval 0 Successfully set the default TTL value. * @retval -EINVAL Invalid TTL value. */ int bt_mesh_default_ttl_set(uint8_t default_ttl); /** @brief Get the current default TTL value. * * @return The current default TTL value. */ uint8_t bt_mesh_default_ttl_get(void); /** @brief Set the Network Transmit parameters. * * The Network Transmit parameters determine the parameters local messages are * transmitted with. * * @see BT_MESH_TRANSMIT * * @param xmit New Network Transmit parameters. Use @ref BT_MESH_TRANSMIT for * encoding. */ void bt_mesh_net_transmit_set(uint8_t xmit); /** @brief Get the current Network Transmit parameters. * * The @ref BT_MESH_TRANSMIT_COUNT and @ref BT_MESH_TRANSMIT_INT macros can be * used to decode the Network Transmit parameters. * * @return The current Network Transmit parameters. */ uint8_t bt_mesh_net_transmit_get(void); /** @brief Configure the Relay feature. * * Enable or disable the Relay feature, and configure the parameters to * transmit relayed messages with. * * Support for the Relay feature must be enabled through the * @c CONFIG_BT_MESH_RELAY configuration option. * * @see BT_MESH_TRANSMIT * * @param relay New Relay feature state. Must be one of * @ref BT_MESH_FEATURE_ENABLED and * @ref BT_MESH_FEATURE_DISABLED. * @param xmit New Relay retransmit parameters. Use @ref BT_MESH_TRANSMIT for * encoding. * * @retval 0 Successfully changed the Relay configuration. * @retval -ENOTSUP The Relay feature is not supported. * @retval -EINVAL Invalid parameter. * @retval -EALREADY Already using the given parameters. */ int bt_mesh_relay_set(enum bt_mesh_feat_state relay, uint8_t xmit); /** @brief Get the current Relay feature state. * * @returns The Relay feature state. */ enum bt_mesh_feat_state bt_mesh_relay_get(void); /** @brief Get the current Relay Retransmit parameters. * * The @ref BT_MESH_TRANSMIT_COUNT and @ref BT_MESH_TRANSMIT_INT macros can be * used to decode the Relay Retransmit parameters. * * @return The current Relay Retransmit parameters, or 0 if relay is not * supported. */ uint8_t bt_mesh_relay_retransmit_get(void); /** @brief Enable or disable the GATT Proxy feature. * * Support for the GATT Proxy feature must be enabled through the * @c CONFIG_BT_MESH_GATT_PROXY configuration option. * * @note The GATT Proxy feature only controls a Proxy node's ability to relay * messages to the mesh network. A node that supports GATT Proxy will * still advertise Connectable Proxy beacons, even if the feature is * disabled. The Proxy feature can only be fully disabled through compile * time configuration. * * @param gatt_proxy New GATT Proxy state. Must be one of * @ref BT_MESH_FEATURE_ENABLED and * @ref BT_MESH_FEATURE_DISABLED. * * @retval 0 Successfully changed the GATT Proxy feature state. * @retval -ENOTSUP The GATT Proxy feature is not supported. * @retval -EINVAL Invalid parameter. * @retval -EALREADY Already in the given state. */ int bt_mesh_gatt_proxy_set(enum bt_mesh_feat_state gatt_proxy); /** @brief Get the current GATT Proxy state. * * @returns The GATT Proxy feature state. */ enum bt_mesh_feat_state bt_mesh_gatt_proxy_get(void); /** @brief Enable or disable the Friend feature. * * Any active friendships will be terminated immediately if the Friend feature * is disabled. * * Support for the Friend feature must be enabled through the * @c CONFIG_BT_MESH_FRIEND configuration option. * * @param friendship New Friend feature state. Must be one of * @ref BT_MESH_FEATURE_ENABLED and * @ref BT_MESH_FEATURE_DISABLED. * * @retval 0 Successfully changed the Friend feature state. * @retval -ENOTSUP The Friend feature is not supported. * @retval -EINVAL Invalid parameter. * @retval -EALREADY Already in the given state. */ int bt_mesh_friend_set(enum bt_mesh_feat_state friendship); /** @brief Get the current Friend state. * * @returns The Friend feature state. */ enum bt_mesh_feat_state bt_mesh_friend_get(void); /** * @brief Subnet Configuration * @defgroup bt_mesh_cfg_subnet Subnet Configuration * @{ */ /** @brief Add a Subnet. * * Adds a subnet with the given network index and network key to the list of * known Subnets. All messages sent on the given Subnet will be processed by * this node, and the node may send and receive Network Beacons on the given * Subnet. * * @param net_idx Network index. * @param key Root network key of the Subnet. All other keys are derived * from this. * * @retval STATUS_SUCCESS The Subnet was successfully added. * @retval STATUS_INSUFF_RESOURCES No room for this Subnet. * @retval STATUS_UNSPECIFIED The Subnet couldn't be created for some reason. */ uint8_t bt_mesh_subnet_add(uint16_t net_idx, const uint8_t key[16]); /** @brief Update the given Subnet. * * Starts the Key Refresh procedure for this Subnet by adding a second set of * encryption keys. The Subnet will continue sending with the old key (but * receiving messages using both) until the Subnet enters Key Refresh phase 2. * * This allows a network configurator to replace old network and application * keys for the entire network, effectively removing access for all nodes that * aren't given the new keys. * * @param net_idx Network index. * @param key New root network key of the Subnet. * * @retval STATUS_SUCCESS The Subnet was updated with a second key. * @retval STATUS_INVALID_NETKEY The NetIdx is unknown. * @retval STATUS_IDX_ALREADY_STORED The @c key value is the same as the * current key. * @retval STATUS_CANNOT_UPDATE The Subnet cannot be updated for some reason. */ uint8_t bt_mesh_subnet_update(uint16_t net_idx, const uint8_t key[16]); /** @brief Delete a Subnet. * * Removes the Subnet with the given network index from the node. The node will * stop sending Network Beacons with the given Subnet, and can no longer * process messages on this Subnet. * * All Applications bound to this Subnet are also deleted. * * @param net_idx Network index. * * @retval STATUS_SUCCESS The Subnet was deleted. * @retval STATUS_INVALID_NETKEY The NetIdx is unknown. */ uint8_t bt_mesh_subnet_del(uint16_t net_idx); /** @brief Check whether a Subnet is known. * * @param net_idx Network index * * @return true if a Subnet with the given index exists, false otherwise. */ bool bt_mesh_subnet_exists(uint16_t net_idx); /** @brief Set the Subnet's Key Refresh phase. * * The Key Refresh procedure is started by updating the Subnet keys through * @ref bt_mesh_subnet_update. This puts the Subnet in Key Refresh Phase 1. * Once all nodes have received the new Subnet key, Key Refresh Phase 2 can be * activated through this function to start transmitting with the new network * key. Finally, to revoke the old key, set the Key Refresh Phase to 3. This * removes the old keys from the node, and returns the Subnet back to normal * single-key operation with the new key set. * * @param net_idx Network index. * @param phase Pointer to the new Key Refresh phase. Will return the actual * Key Refresh phase after updating. * * @retval STATUS_SUCCESS The Key Refresh phase of the Subnet was successfully * changed. * @retval STATUS_INVALID_NETKEY The NetIdx is unknown. * @retval STATUS_CANNOT_UPDATE The given phase change is invalid. */ uint8_t bt_mesh_subnet_kr_phase_set(uint16_t net_idx, uint8_t *phase); /** @brief Get the Subnet's Key Refresh phase. * * @param net_idx Network index. * @param phase Pointer to the Key Refresh variable to fill. * * @retval STATUS_SUCCESS Successfully populated the @c phase variable. * @retval STATUS_INVALID_NETKEY The NetIdx is unknown. */ uint8_t bt_mesh_subnet_kr_phase_get(uint16_t net_idx, uint8_t *phase); /** @brief Set the Node Identity state of the Subnet. * * The Node Identity state of a Subnet determines whether the Subnet advertises * connectable Node Identity beacons for Proxy Clients to connect to. * Once started, the Node Identity beacon runs for 60 seconds, or until it is * stopped. * * This function serves the same purpose as @ref bt_mesh_proxy_identity_enable, * but only acts on a single Subnet. * * GATT Proxy support must be enabled through * @kconfig{CONFIG_BT_MESH_GATT_PROXY}. * * @param net_idx Network index. * @param node_id New Node Identity state, must be either @ref * BT_MESH_FEATURE_ENABLED or @ref BT_MESH_FEATURE_DISABLED. * * @retval STATUS_SUCCESS Successfully set the Node Identity state of the * Subnet. * @retval STATUS_INVALID_NETKEY The NetIdx is unknown. * @retval STATUS_FEAT_NOT_SUPP The Node Identity feature is not supported. * @retval STATUS_CANNOT_SET Couldn't set the Node Identity state. */ uint8_t bt_mesh_subnet_node_id_set(uint16_t net_idx, enum bt_mesh_feat_state node_id); /** @brief Get the Node Identity state of the Subnet. * * @param net_idx Network index. * @param node_id Node Identity variable to fill. * * @retval STATUS_SUCCESS Successfully populated the @c node_id variable. * @retval STATUS_INVALID_NETKEY The NetIdx is unknown. */ uint8_t bt_mesh_subnet_node_id_get(uint16_t net_idx, enum bt_mesh_feat_state *node_id); /** @brief Get a list of all known Subnet indexes. * * Builds a list of all known Subnet indexes in the @c net_idxs array. * If the @c net_idxs array is smaller than the list of known Subnets, this * function fills all available entries and returns @c -ENOMEM. In this * case, the next @c max entries of the list can be read out by calling * @code * bt_mesh_subnets_get(list, max, max); * @endcode * * Note that any changes to the Subnet list between calls to this function * could change the order and number of entries in the list. * * @param net_idxs Array to fill. * @param max Max number of indexes to return. * @param skip Number of indexes to skip. Enables batched processing of the * list. * * @return The number of indexes added to the @c net_idxs array, or @c -ENOMEM * if the number of known Subnets exceeds the @c max parameter. */ ssize_t bt_mesh_subnets_get(uint16_t net_idxs[], size_t max, off_t skip); /** * @} */ /** * @brief Application Configuration * @defgroup bt_mesh_cfg_app Application Configuration * @{ */ /** @brief Add an Application key. * * Adds the Application with the given index to the list of known applications. * Allows the node to send and receive model messages encrypted with this * Application key. * * Every Application is bound to a specific Subnet. The node must know the * Subnet the Application is bound to before it can add the Application. * * @param app_idx Application index. * @param net_idx Network index the Application is bound to. * @param key Application key value. * * @retval STATUS_SUCCESS The Application was successfully added. * @retval STATUS_INVALID_NETKEY The NetIdx is unknown. * @retval STATUS_INSUFF_RESOURCES There's no room for storing this * Application. * @retval STATUS_INVALID_BINDING This AppIdx is already bound to another * Subnet. * @retval STATUS_IDX_ALREADY_STORED This AppIdx is already stored with a * different key value. * @retval STATUS_CANNOT_SET Cannot set the Application key for some reason. */ uint8_t bt_mesh_app_key_add(uint16_t app_idx, uint16_t net_idx, const uint8_t key[16]); /** @brief Update an Application key. * * Update an Application with a second Application key, as part of the * Key Refresh procedure of the bound Subnet. The node will continue * transmitting with the old application key (but receiving on both) until the * Subnet enters Key Refresh phase 2. Once the Subnet enters Key Refresh phase * 3, the old application key will be deleted. * * @note The Application key can only be updated if the bound Subnet is in Key * Refresh phase 1. * * @param app_idx Application index. * @param net_idx Network index the Application is bound to, or * @ref BT_MESH_KEY_ANY to skip the binding check. * @param key New key value. * * @retval STATUS_SUCCESS The Application key was successfully updated. * @retval STATUS_INVALID_NETKEY The NetIdx is unknown. * @retval STATUS_INVALID_BINDING This AppIdx is not bound to the given NetIdx. * @retval STATUS_CANNOT_UPDATE The Application key cannot be updated for some * reason. * @retval STATUS_IDX_ALREADY_STORED This AppIdx is already updated with a * different key value. */ uint8_t bt_mesh_app_key_update(uint16_t app_idx, uint16_t net_idx, const uint8_t key[16]); /** @brief Delete an Application key. * * All models bound to this application will remove this binding. * All models publishing with this application will stop publishing. * * @param app_idx Application index. * @param net_idx Network index. * * @retval STATUS_SUCCESS The Application key was successfully deleted. * @retval STATUS_INVALID_NETKEY The NetIdx is unknown. * @retval STATUS_INVALID_BINDING This AppIdx is not bound to the given NetIdx. */ uint8_t bt_mesh_app_key_del(uint16_t app_idx, uint16_t net_idx); /** @brief Check if an Application key is known. * * @param app_idx Application index. * * @return true if the Application is known, false otherwise. */ bool bt_mesh_app_key_exists(uint16_t app_idx); /** @brief Get a list of all known Application key indexes. * * Builds a list of all Application indexes for the given network index in the * @c app_idxs array. If the @c app_idxs array cannot fit all bound * Applications, this function fills all available entries and returns @c * -ENOMEM. In this case, the next @c max entries of the list can be read out * by calling * @code * bt_mesh_app_keys_get(net_idx, list, max, max); * @endcode * * Note that any changes to the Application key list between calls to this * function could change the order and number of entries in the list. * * @param net_idx Network Index to get the Applications of, or @ref * BT_MESH_KEY_ANY to get all Applications. * @param app_idxs Array to fill. * @param max Max number of indexes to return. * @param skip Number of indexes to skip. Enables batched processing of the * list. * * @return The number of indexes added to the @c app_idxs array, or @c -ENOMEM * if the number of known Applications exceeds the @c max parameter. */ ssize_t bt_mesh_app_keys_get(uint16_t net_idx, uint16_t app_idxs[], size_t max, off_t skip); /** * @} */ #ifdef __cplusplus } #endif /** * @} */ #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_CFG_H_ */