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