bt-oal/include/oal-mesh.h

   1 /*
   2  * Open Adaptation Layer (OAL)
   3  *
   4  * Copyright (c) 2019 -2020 Samsung Electronics Co., Ltd All Rights Reserved.
   5  *
   6  * @author: Anupam Roy <anupam.r@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22 #ifndef OAL_MESH_H_
  23 #define OAL_MESH_H_
  24
  25 #include <oal-manager.h>
  26
  27 /* Start of BLE Mesh structures and enum declarations */
  28
  29 #define OAL_MESH_DEVKEY_MSG_BUF_MAX 2048
  30
  31 /* Mesh Key Operation Enums (For Appkey & NetKey) */
  32 typedef enum {
  33         OAL_MESH_KEY_ADD = 0,
  34         OAL_MESH_KEY_UPDATE,
  35         OAL_MESH_KEY_DELETE
  36 } oal_mesh_key_op_e;
  37
  38 /* Mesh Authentication types */
  39 typedef enum {
  40         /*< Output authentication request types */
  41         OAL_MESH_AUTH_ALPHANUMERIC_DISPLAY = 0,
  42         OAL_MESH_AUTH_NUMERIC_DISPLAY,
  43         OAL_MESH_AUTH_PUSH_COUNT_DISPLAY,
  44         OAL_MESH_AUTH_TWIST_COUNT_DISPLAY,
  45
  46         /*< Input authentication request types */
  47         OAL_MESH_AUTH_REQ_ALPHANUMERIC_INPUT,
  48         OAL_MESH_AUTH_REQ_NUMERIC_INPUT,
  49         OAL_MESH_AUTH_REQ_BLINK_COUNT_INPUT,
  50         OAL_MESH_AUTH_REQ_BEEP_COUNT_INPUT,
  51         OAL_MESH_AUTH_REQ_VIBRATE_COUNT_INPUT,
  52
  53         /**< OOB Key Inputs */
  54         OAL_MESH_AUTH_REQ_OOB_PUBLIC_KEY_INPUT,
  55         OAL_MESH_AUTH_REQ_OOB_STATIC_KEY_INPUT
  56 } oal_mesh_variant_authentication_e;
  57
  58  /* Mesh Enumerations of 2 octet OUT OOB Actions */
  59 typedef enum {
  60         OAL_MESH_OUT_OOB_METHOD_BLINK            = 0x01,
  61         OAL_MESH_OUT_OOB_METHOD_BEEP             = 0x02,
  62         OAL_MESH_OUT_OOB_METHOD_VIBRATE          = 0x04,
  63         OAL_MESH_OUT_OOB_METHOD_NUMERIC          = 0x08,
  64         OAL_MESH_OUT_OOB_METHOD_ALPHANUMERIC     = 0x10,
  65         /* bit 5 ~ 15 : RFU */
  66 } oal_mesh_output_oob_action_e;
  67
  68  /* Mesh Enumerations of 2 octet IN OOB Actions */
  69 typedef enum {
  70         OAL_MESH_IN_OOB_METHOD_PUSH              = 0x01,
  71         OAL_MESH_IN_OOB_METHOD_TWIST             = 0x02,
  72         OAL_MESH_IN_OOB_METHOD_NUMERIC           = 0x04,
  73         OAL_MESH_IN_OOB_METHOD_ALPHANUMERIC      = 0x08,
  74         /* bit 4 ~ 15 : RFU */
  75 } oal_mesh_input_oob_action_e;
  76
  77 /* Mesh strcuture of Mesh Provisioning Capabilities */
  78 typedef struct {
  79         /**< Indicates Public Key for ECC Key exchange, can be fetched OOB */
  80         bool public_oob;
  81         /**< Indicates Static Key for authentication, can be fetched OOB */
  82         bool static_oob;
  83         /**< Indicates support for bitmap combination of OUT-OOB actions */
  84         oal_mesh_output_oob_action_e out_oob;
  85         /**< Indicates support for bitmap combination of IN-OOB actions */
  86         oal_mesh_input_oob_action_e  in_oob;
  87 } oal_mesh_capabilities_t;
  88
  89 /* Mesh  Unprovisioned Device Scan result */
  90 typedef struct {
  91         int rssi;
  92         oal_uuid_t dev_uuid;
  93         /* 2-octet OOB info */
  94         uint8_t oob_info[2];
  95         /* 4-octet URI Hash info */
  96         uint8_t uri_hash[4];
  97 } oal_mesh_scan_result_t;
  98
  99 /* Mesh Scan Parameters */
 100 typedef struct {
 101         uint32_t seconds;
 102         /* Structure may be expanded in future to support more scan parameters*/
 103 } oal_mesh_scan_params_t;
 104
 105 /* Mesh Node Properties */
 106 typedef struct {
 107         uint16_t companyid;
 108         uint16_t vendorid;
 109         uint16_t versionid;
 110         uint16_t crpl;
 111         int relay;
 112         int frnd;
 113         int proxy;
 114         int lpn;
 115 } oal_mesh_vendor_info_t;
 116
 117 /* Mesh Model: 2 bytes for BT SIG Model & 4 bytes for Vendor Model */
 118 typedef struct {
 119         uint16_t elem_index;
 120         uint32_t model_id;
 121 } oal_mesh_model_t;
 122
 123 /* Mesh Element structure */
 124 typedef struct {
 125         uint16_t index;
 126         uint16_t num_models;
 127 } oal_mesh_element_t;
 128
 129 /* Mesh Node structure */
 130 typedef struct {
 131         oal_mesh_vendor_info_t vendor_info;
 132         uint16_t num_elements;
 133         uint16_t primary_unicast;
 134         oal_uuid_t uuid;
 135         union {
 136                 uint8_t u8[8];
 137                 uint64_t u64;
 138         } token;
 139 } oal_mesh_node_t;
 140
 141 typedef struct {
 142         oal_status_t status;
 143         uint8_t token[8];
 144         oal_uuid_t uuid;
 145 } event_mesh_network_attached_t;
 146
 147 typedef struct {
 148         oal_status_t status;
 149         oal_uuid_t net_uuid;
 150         oal_mesh_scan_result_t result;
 151 } event_mesh_scan_result_t;
 152
 153 typedef struct {
 154         oal_status_t status;
 155         oal_uuid_t net_uuid;
 156 } event_mesh_scan_status_t;
 157
 158 typedef struct {
 159         oal_status_t status;
 160         oal_uuid_t net_uuid;
 161         oal_uuid_t dev_uuid;
 162 } event_mesh_provisioning_status_t;
 163
 164 typedef struct {
 165         oal_uuid_t net_uuid;
 166         uint8_t count;
 167 } event_mesh_provisioning_data_requested_t;
 168
 169 typedef struct {
 170         oal_uuid_t net_uuid;
 171         oal_mesh_variant_authentication_e auth_type;
 172         /* MAX length of Auth value is 50 */
 173         char auth_value[50 + 1];
 174 } event_mesh_authentication_requested_t;
 175
 176 typedef struct {
 177         oal_status_t status;
 178         int reason;
 179         oal_uuid_t net_uuid;
 180         oal_uuid_t dev_uuid;
 181         uint16_t unicast;
 182         uint8_t count;
 183 } event_mesh_provisioning_finished_t;
 184
 185 typedef struct {
 186         oal_status_t status;
 187         oal_uuid_t net_uuid;
 188         oal_mesh_key_op_e op;
 189         uint16_t key_idx;
 190 } event_mesh_netkey_operation_t;
 191
 192 typedef struct {
 193         oal_status_t status;
 194         oal_uuid_t net_uuid;
 195         oal_mesh_key_op_e op;
 196         uint16_t net_idx;
 197         uint16_t app_idx;
 198 } event_mesh_appkey_operation_t;
 199
 200 typedef struct {
 201         oal_uuid_t net_uuid;
 202         /* Source means the node which sent the DevKey Message*/
 203         uint16_t source;
 204         bool remote;
 205         uint16_t subnet;
 206         uint16_t data_len;
 207         uint8_t data[OAL_MESH_DEVKEY_MSG_BUF_MAX];
 208 } event_mesh_devkey_message_t;
 209
 210 /**
 211  * @brief Enables Bluetooth Mesh Stack
 212  *
 213  * @remarks  Application will be able to BLE Mesh features.
 214  * @remarks  Initializes Bluetooth Mesh HAL interface.
 215  *
 216  */
 217 oal_status_t mesh_enable(void);
 218
 219 /**
 220  * @brief Disables Bluetooth Mesh Stack
 221  *
 222  * @remarks  De-Initializes Bluetooth Mesh HAL interface.
 223  * @remarks  Application will not be able to BLE Mesh features.
 224  *
 225  * @pre OAL API should be enabled with mesh_enable().
 226  *
 227  * @see  mesh_enable()
 228  */
 229 oal_status_t mesh_disable(void);
 230
 231 /**
 232  * @brief Register the BLE Mesh Node
 233  *
 234  * @remarks  Application will register the Mesh Provisioner node
 235  * or Device node
 236  *
 237  * @pre OAl API should be enabled with mesh_enable().
 238  *
 239  * @see  mesh_enable()
 240  */
 241 oal_status_t mesh_register_node(oal_mesh_node_t *node,
 242                 GSList *model_list, bool is_provisioner);
 243
 244 /**
 245  * @brief UnRegister the BLE Mesh Node
 246  *
 247  * @remarks  Application will unregister the Mesh Provisioner
 248  * node or Device node
 249  *
 250  * @pre OAl API should be enabled with mesh_enable().
 251  *
 252  * @see  mesh_enable()
 253  * @see  mesh_register_node()
 254  */
 255 oal_status_t mesh_deregister_node(oal_mesh_node_t *node);
 256
 257 /**
 258  * @brief Local Network Subnet Operations by Mesh Provisioner Node
 259  *
 260  * @remarks  Application can Create/Delete/Update subnets in
 261  * local key database
 262  *
 263  * @pre OAl API should be enabled with mesh_enable().
 264  *
 265  * @see  mesh_enable()
 266  * @see  mesh_network_subnet_execute()
 267  */
 268 oal_status_t mesh_network_subnet_execute(oal_uuid_t* network_uuid,
 269                 oal_mesh_key_op_e operation, uint16_t net_index);
 270
 271 /**
 272  * @brief Local Network Appkey Operations by Mesh Provisioner Node
 273  *
 274  * @remarks  Application can Create/Delete/Update Appkeys, bound to
 275  * netkeys in local key database
 276  *
 277  * @pre OAl API should be enabled with mesh_enable().
 278  *
 279  * @see  mesh_enable()
 280  * @see  mesh_network_subnet_execute()
 281  * @see  mesh_network_subnet_execute()
 282  */
 283 oal_status_t mesh_network_appkey_execute(oal_uuid_t* network_uuid,
 284                 oal_mesh_key_op_e operation,
 285                         uint16_t net_index, uint16_t app_index);
 286
 287 /**
 288  * @brief Discover unprovisioned device
 289  *
 290  * @remarks  Provisioner application can discover Unprovisioned Device
 291  * beaons which want to Join Mesh network
 292  * @remarks  scan params structure is defined for forward compatibility.
 293  * Currently only single parameter (seconds) is supported
 294  *
 295  * @pre OAl API should be enabled with mesh_enable().
 296  *
 297  * @see  mesh_enable()
 298  * @see  mesh_network_start_scan()
 299  */
 300 oal_status_t mesh_network_start_scan(oal_uuid_t* network_uuid,
 301                 oal_mesh_scan_params_t *params);
 302
 303 /**
 304  * @brief Cancel unprovisionined Device scanning
 305  *
 306  * @see  mesh_enable()
 307  * @see  mesh_network_start_scan()
 308  */
 309 oal_status_t mesh_network_scan_cancel(oal_uuid_t* network_uuid);
 310
 311 /**
 312  * @brief Set Provisioning capabilities
 313  *
 314  * @remarks  Provisioner application should set the capabilities
 315  * before initiating device provision. Provisioning parameters are
 316  * chosen based on combination of provisioner & device's capabilities
 317  *
 318  * @pre OAl API should be enabled with mesh_enable().
 319  *
 320  * @see  mesh_enable()
 321  */
 322 oal_status_t mesh_network_set_provisioning_capabilities(
 323                 oal_uuid_t *network_uuid, oal_mesh_capabilities_t *caps);
 324
 325 /**
 326  * @brief Security provision a device to Mesh Network
 327  *
 328  * @remarks  Provisioner application can provision device after
 329  * scanning for device beacons.
 330  * @remarks  Provisioner application should set the Provisioning
 331  * capabilities before starting provision.
 332  *
 333  * @pre OAl API should be enabled with mesh_enable().
 334  *
 335  * @see  mesh_enable()
 336  * @see  mesh_network_set_provisioning_capabilities()
 337  * @see  mesh_network_provision_device()
 338  */
 339 oal_status_t mesh_network_provision_device(oal_uuid_t* network_uuid,
 340                 oal_uuid_t *dev_uuid);
 341
 342
 343 /**
 344  * @brief Send data for provisioning like NetKey, Primary unicast
 345  *
 346  * @see  mesh_enable()
 347  */
 348 oal_status_t mesh_network_send_provisioning_data(oal_uuid_t* network_uuid,
 349                 uint16_t netkey_idx, uint16_t unicast);
 350
 351 /**
 352  * @brief Send Reply to Ongoing Security Provisioning
 353  *
 354  * @remarks  Tizen supports only one Provisioning or Join
 355  * Call simulatneously.
 356  *
 357  * @pre OAl API should be enabled with mesh_enable().
 358  *
 359  * @see  mesh_enable()
 360  * @see  mesh_network_provision_device()
 361  * @see  cb_mesh_authentication_request()
 362  */
 363 oal_status_t mesh_authentication_reply(oal_mesh_variant_authentication_e type,
 364                 const char* auth_value);
 365
 366 /**
 367  * @brief Cancels an ongoing security provisioning
 368  *
 369  * @remarks  Mesh stack does not support Cancelling Ongoing
 370  * provisiong currently.
 371  *
 372  * @pre OAl API should be enabled with mesh_enable().
 373  *
 374  * @see  mesh_enable()
 375  * @see  mesh_network_provision_device()
 376  */
 377 oal_status_t mesh_provisioning_cancel(oal_uuid_t *local_device_uuid);
 378
 379 /**
 380  * @brief Sends Configuration Client message originated from Local Node
 381  *
 382  * @remarks Local Configuration client can send message to both local
 383  * & remote Configuration Server.
 384  *
 385  * @pre OAl API should be enabled with mesh_enable().
 386  *
 387  * @see  mesh_enable()
 388  * @see  cb_mesh_conf_message()
 389  */
 390 oal_status_t mesh_conf_send_message(oal_uuid_t *network_uuid,
 391                 uint16_t dest, bool is_devkey_remote,
 392                         uint16_t netkey_idx, uint8_t *buf, int len);
 393
 394 /**
 395  * @brief Sends Configuration Client Key (NetKey & AppKey Add/Update)
 396  * messages originated from Local Node
 397  *
 398  * @remarks Local Configuration client can send message to both
 399   * local & remote Configuration Server.
 400  *
 401  * @pre OAl API should be enabled with mesh_enable().
 402  *
 403  * @see  mesh_enable()
 404  * @see  cb_mesh_conf_message()
 405  */
 406 oal_status_t mesh_conf_send_key_message(oal_uuid_t *network_uuid,
 407                 uint16_t dest, bool is_netkey,
 408                         bool is_update, int key_idx, int netkey_idx);
 409
 410
 411 /**
 412  * @brief Sends Application message to be encrypted with appplication key
 413  *
 414  * @remarks These messages are generated by Models, which are
 415  * implemenetd by Tizen Application.
 416  * @remarks Tizen Mesh Framework will not handle these mesages directly
 417  * and only transport these to and from application.
 418  *
 419  * @pre OAl API should be enabled with mesh_enable().
 420  *
 421  * @see  mesh_enable()
 422  * @see cb_mesh_model_message()
 423  */
 424 oal_status_t mesh_model_send_message(oal_uuid_t *network_uuid,
 425                 uint16_t dest, int appkey_idx,
 426                         int netkey_idx, uint8_t *buf, int len);
 427
 428 #endif /* OAL_MESH_H_ */