1 /* 2 * Copyright (c) 2020 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_BT_MESH_RPR_CLI_H__ 8 #define ZEPHYR_INCLUDE_BT_MESH_RPR_CLI_H__ 9 10 #include <zephyr/kernel.h> 11 #include <zephyr/bluetooth/mesh/access.h> 12 #include <zephyr/bluetooth/mesh/rpr.h> 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /** 19 * @defgroup bt_mesh_rpr_cli Remote Provisioning Client model 20 * @ingroup bt_mesh 21 * @{ 22 */ 23 24 /** Special value for the @c max_devs parameter of @ref bt_mesh_rpr_scan_start. 25 * 26 * Tells the Remote Provisioning Server not to put restrictions on the max 27 * number of devices reported to the Client. 28 */ 29 #define BT_MESH_RPR_SCAN_MAX_DEVS_ANY 0 30 31 struct bt_mesh_rpr_cli; 32 33 /** 34 * 35 * @brief Remote Provisioning Client model composition data entry. 36 * 37 * @param _cli Pointer to a @ref bt_mesh_rpr_cli instance. 38 */ 39 #define BT_MESH_MODEL_RPR_CLI(_cli) \ 40 BT_MESH_MODEL_CB(BT_MESH_MODEL_ID_REMOTE_PROV_CLI, \ 41 _bt_mesh_rpr_cli_op, NULL, _cli, &_bt_mesh_rpr_cli_cb) 42 43 /** Scan status response */ 44 struct bt_mesh_rpr_scan_status { 45 /** Current scan status */ 46 enum bt_mesh_rpr_status status; 47 /** Current scan state */ 48 enum bt_mesh_rpr_scan scan; 49 /** Max number of devices to report in current scan. */ 50 uint8_t max_devs; 51 /** Seconds remaining of the scan. */ 52 uint8_t timeout; 53 }; 54 55 /** Remote Provisioning Server scanning capabilities */ 56 struct bt_mesh_rpr_caps { 57 /** Max number of scannable devices */ 58 uint8_t max_devs; 59 /** Supports active scan */ 60 bool active_scan; 61 }; 62 63 /** Remote Provisioning Client model instance. */ 64 struct bt_mesh_rpr_cli { 65 /** @brief Scan report callback. 66 * 67 * @param cli Remote Provisioning Client. 68 * @param srv Remote Provisioning Server. 69 * @param unprov Unprovisioned device. 70 * @param adv_data Advertisement data for the unprovisioned device, or 71 * NULL if extended scanning hasn't been enabled. An 72 * empty buffer indicates that the extended scanning 73 * finished without collecting additional information. 74 */ 75 void (*scan_report)(struct bt_mesh_rpr_cli *cli, 76 const struct bt_mesh_rpr_node *srv, 77 struct bt_mesh_rpr_unprov *unprov, 78 struct net_buf_simple *adv_data); 79 80 /* Internal parameters */ 81 82 struct bt_mesh_msg_ack_ctx scan_ack_ctx; 83 struct bt_mesh_msg_ack_ctx prov_ack_ctx; 84 85 struct { 86 struct k_work_delayable timeout; 87 struct bt_mesh_rpr_node srv; 88 uint8_t time; 89 uint8_t tx_pdu; 90 uint8_t rx_pdu; 91 enum bt_mesh_rpr_link_state state; 92 } link; 93 94 struct bt_mesh_model *mod; 95 }; 96 97 /** @brief Get scanning capabilities of Remote Provisioning Server. 98 * 99 * @param cli Remote Provisioning Client. 100 * @param srv Remote Provisioning Server. 101 * @param caps Capabilities response buffer. 102 * 103 * @return 0 on success, or (negative) error code otherwise. 104 */ 105 int bt_mesh_rpr_scan_caps_get(struct bt_mesh_rpr_cli *cli, 106 const struct bt_mesh_rpr_node *srv, 107 struct bt_mesh_rpr_caps *caps); 108 109 /** @brief Get current scanning state of Remote Provisioning Server. 110 * 111 * @param cli Remote Provisioning Client. 112 * @param srv Remote Provisioning Server. 113 * @param status Scan status response buffer. 114 * 115 * @return 0 on success, or (negative) error code otherwise. 116 */ 117 int bt_mesh_rpr_scan_get(struct bt_mesh_rpr_cli *cli, 118 const struct bt_mesh_rpr_node *srv, 119 struct bt_mesh_rpr_scan_status *status); 120 121 /** @brief Start scanning for unprovisioned devices. 122 * 123 * Tells the Remote Provisioning Server to start scanning for unprovisioned 124 * devices. The Server will report back the results through the @ref 125 * bt_mesh_rpr_cli::scan_report callback. 126 * 127 * Use the @c uuid parameter to scan for a specific device, or leave it as NULL 128 * to report all unprovisioned devices. 129 * 130 * The Server will ignore duplicates, and report up to @c max_devs number of 131 * devices. Requesting a @c max_devs number that's higher than the Server's 132 * capability will result in an error. 133 * 134 * @param cli Remote Provisioning Client. 135 * @param srv Remote Provisioning Server. 136 * @param uuid Device UUID to scan for, or NULL to report all devices. 137 * @param timeout Scan timeout in seconds. Must be at least 1 second. 138 * @param max_devs Max number of devices to report, or 0 to report as many as 139 * possible. 140 * @param status Scan status response buffer. 141 * 142 * @return 0 on success, or (negative) error code otherwise. 143 */ 144 int bt_mesh_rpr_scan_start(struct bt_mesh_rpr_cli *cli, 145 const struct bt_mesh_rpr_node *srv, 146 const uint8_t uuid[16], uint8_t timeout, 147 uint8_t max_devs, 148 struct bt_mesh_rpr_scan_status *status); 149 150 /** @brief Start extended scanning for unprovisioned devices. 151 * 152 * Extended scanning supplements regular unprovisioned scanning, by allowing 153 * the Server to report additional data for a specific device. The Remote 154 * Provisioning Server will use active scanning to request a scan 155 * response from the unprovisioned device, if supported. If no UUID is 156 * provided, the Server will report a scan on its own OOB information and 157 * advertising data. 158 * 159 * Use the ad_types array to specify which AD types to include in the scan 160 * report. Some AD types invoke special behavior: 161 * - @ref BT_DATA_NAME_COMPLETE Will report both the complete and the 162 * shortened name. 163 * - @ref BT_DATA_URI If the unprovisioned beacon contains a URI hash, the 164 * Server will extend the scanning to include packets other than 165 * the scan response, to look for URIs matching the URI hash. Only matching 166 * URIs will be reported. 167 * 168 * The following AD types should not be used: 169 * - @ref BT_DATA_NAME_SHORTENED 170 * - @ref BT_DATA_UUID16_SOME 171 * - @ref BT_DATA_UUID32_SOME 172 * - @ref BT_DATA_UUID128_SOME 173 * 174 * Additionally, each AD type should only occur once. 175 * 176 * @param cli Remote Provisioning Client. 177 * @param srv Remote Provisioning Server. 178 * @param uuid Device UUID to start extended scanning for, or NULL to scan 179 * the remote server. 180 * @param timeout Scan timeout in seconds. Valid values from @ref BT_MESH_RPR_EXT_SCAN_TIME_MIN 181 * to @ref BT_MESH_RPR_EXT_SCAN_TIME_MAX. Ignored if UUID is NULL. 182 * @param ad_types List of AD types to include in the scan report. Must contain 1 to 183 * CONFIG_BT_MESH_RPR_AD_TYPES_MAX entries. 184 * @param ad_count Number of AD types in @c ad_types. 185 * 186 * @return 0 on success, or (negative) error code otherwise. 187 */ 188 int bt_mesh_rpr_scan_start_ext(struct bt_mesh_rpr_cli *cli, 189 const struct bt_mesh_rpr_node *srv, 190 const uint8_t uuid[16], uint8_t timeout, 191 const uint8_t *ad_types, size_t ad_count); 192 193 /** @brief Stop any ongoing scanning on the Remote Provisioning Server. 194 * 195 * @param cli Remote Provisioning Client. 196 * @param srv Remote Provisioning Server. 197 * @param status Scan status response buffer. 198 * 199 * @return 0 on success, or (negative) error code otherwise. 200 */ 201 int bt_mesh_rpr_scan_stop(struct bt_mesh_rpr_cli *cli, 202 const struct bt_mesh_rpr_node *srv, 203 struct bt_mesh_rpr_scan_status *status); 204 205 /** @brief Get the current link status of the Remote Provisioning Server. 206 * 207 * @param cli Remote Provisioning Client. 208 * @param srv Remote Provisioning Server. 209 * @param rsp Link status response buffer. 210 * 211 * @return 0 on success, or (negative) error code otherwise. 212 */ 213 int bt_mesh_rpr_link_get(struct bt_mesh_rpr_cli *cli, 214 const struct bt_mesh_rpr_node *srv, 215 struct bt_mesh_rpr_link *rsp); 216 217 /** @brief Close any open link on the Remote Provisioning Server. 218 * 219 * @param cli Remote Provisioning Client. 220 * @param srv Remote Provisioning Server. 221 * @param rsp Link status response buffer. 222 * 223 * @return 0 on success, or (negative) error code otherwise. 224 */ 225 int bt_mesh_rpr_link_close(struct bt_mesh_rpr_cli *cli, 226 const struct bt_mesh_rpr_node *srv, 227 struct bt_mesh_rpr_link *rsp); 228 229 /** @brief Get the current transmission timeout value. 230 * 231 * @return The configured transmission timeout in milliseconds. 232 */ 233 int32_t bt_mesh_rpr_cli_timeout_get(void); 234 235 /** @brief Set the transmission timeout value. 236 * 237 * The transmission timeout controls the amount of time the Remote Provisioning 238 * Client models will wait for a response from the Server. 239 * 240 * @param timeout The new transmission timeout. 241 */ 242 void bt_mesh_rpr_cli_timeout_set(int32_t timeout); 243 244 /** @cond INTERNAL_HIDDEN */ 245 extern const struct bt_mesh_model_op _bt_mesh_rpr_cli_op[]; 246 extern const struct bt_mesh_model_cb _bt_mesh_rpr_cli_cb; 247 /** @endcond */ 248 249 /** @} */ 250 251 #ifdef __cplusplus 252 } 253 #endif 254 255 #endif /* ZEPHYR_INCLUDE_BT_MESH_RPR_CLI_H__ */ 256
