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 } event_mesh_network_proxy_added_t;
 145
 146 typedef struct {
 147         oal_status_t status;
 148         bool is_prov;
 149         uint8_t token[8];
 150         oal_uuid_t uuid;
 151 } event_mesh_network_attached_t;
 152
 153 typedef struct {
 154         oal_status_t status;
 155         uint8_t token[8];
 156         oal_uuid_t uuid;
 157 } event_mesh_network_destroyed_t;
 158
 159 typedef struct {
 160         oal_status_t status;
 161         oal_uuid_t net_uuid;
 162         oal_mesh_scan_result_t result;
 163 } event_mesh_scan_result_t;
 164
 165 typedef struct {
 166         oal_status_t status;
 167         oal_uuid_t net_uuid;
 168 } event_mesh_scan_status_t;
 169
 170 typedef struct {
 171         oal_status_t status;
 172         oal_uuid_t net_uuid;
 173         oal_uuid_t dev_uuid;
 174 } event_mesh_provisioning_status_t;
 175
 176 typedef struct {
 177         oal_uuid_t net_uuid;
 178         uint8_t count;
 179 } event_mesh_provisioning_data_requested_t;
 180
 181 typedef struct {
 182         oal_uuid_t net_uuid;
 183         oal_mesh_variant_authentication_e auth_type;
 184         /* MAX length of Auth value is 50 */
 185         char auth_value[50 + 1];
 186 } event_mesh_authentication_requested_t;
 187
 188 typedef struct {
 189         oal_status_t status;
 190         int reason;
 191         oal_uuid_t net_uuid;
 192         oal_uuid_t dev_uuid;
 193         uint16_t unicast;
 194         uint8_t count;
 195 } event_mesh_provisioning_finished_t;
 196
 197 typedef struct {
 198         oal_status_t status;
 199         oal_uuid_t net_uuid;
 200         oal_mesh_key_op_e op;
 201         uint16_t key_idx;
 202 } event_mesh_netkey_operation_t;
 203
 204 typedef struct {
 205         oal_status_t status;
 206         oal_uuid_t net_uuid;
 207         oal_mesh_key_op_e op;
 208         uint16_t net_idx;
 209         uint16_t app_idx;
 210 } event_mesh_appkey_operation_t;
 211
 212 typedef struct {
 213         oal_uuid_t net_uuid;
 214         /* Source means the node which sent the DevKey Message*/
 215         uint16_t source;
 216         bool remote;
 217         uint16_t subnet;
 218         uint16_t data_len;
 219         uint8_t data[OAL_MESH_DEVKEY_MSG_BUF_MAX];
 220 } event_mesh_devkey_message_t;
 221
 222 typedef struct {
 223         oal_uuid_t net_uuid;
 224         bool is_prov;
 225         uint16_t source; /* address of remote element which sent msg */
 226         uint16_t dest; /* address of local element which received msg*/
 227         uint16_t key_idx;
 228         uint16_t data_len;
 229         uint8_t data[OAL_MESH_MSG_BUF_MAX];
 230 } event_mesh_message_t;
 231
 232
 233 /**
 234  * @brief Enables Bluetooth Mesh Stack
 235  *
 236  * @remarks  Application will be able to BLE Mesh features.
 237  * @remarks  Initializes Bluetooth Mesh HAL interface.
 238  *
 239  */
 240 oal_status_t mesh_enable(void);
 241
 242 /**
 243  * @brief Disables Bluetooth Mesh Stack
 244  *
 245  * @remarks  De-Initializes Bluetooth Mesh HAL interface.
 246  * @remarks  Application will not be able to BLE Mesh features.
 247  *
 248  * @pre OAL API should be enabled with mesh_enable().
 249  *
 250  * @see  mesh_enable()
 251  */
 252 oal_status_t mesh_disable(void);
 253
 254 /**
 255  * @brief Register the BLE Mesh Node
 256  *
 257  * @remarks  Application will register the Mesh Provisioner node
 258  * or Device node
 259  *
 260  * @pre OAl API should be enabled with mesh_enable().
 261  *
 262  * @see  mesh_enable()
 263  */
 264 oal_status_t mesh_register_node(oal_mesh_node_t *node,
 265                 GSList *model_list, bool is_provisioner);
 266
 267
 268 /**
 269  * @brief Destroy or leave Network
 270  *
 271  * @remarks Stack will remove the local node entry
 272  *
 273  * @pre OAl API should be enabled with mesh_enable().
 274  *
 275  * @see  mesh_enable()
 276  * @see  mesh_register_node()
 277  */
 278 oal_status_t mesh_network_destroy(oal_uuid_t* network_uuid);
 279
 280 /**
 281  * @brief Cancel ongoing Join Request
 282  *
 283  * @remark Stack will remove the local node entry
 284  *
 285  * @pre OAL API should be enabled with mesh_enable().
 286  *
 287  * @see mesh_enable()
 288  */
 289 oal_status_t mesh_cancel_join(oal_uuid_t* node_uuid);
 290
 291 /**
 292  * @brief Request Stack to release Network resources
 293  *
 294  * @remarks Stack will remove only yhe DBUS resources of local node
 295  *
 296  * @pre OAl API should be enabled with mesh_enable().
 297  *
 298  * @see  mesh_enable()
 299  * @see  mesh_register_node()
 300  */
 301 oal_status_t mesh_network_release(oal_uuid_t* network_uuid);
 302
 303 /**
 304  * @brief Delete Remote Node configuration
 305  *
 306  * @remarks Stack will remove the Remote node entry
 307  *
 308  * @pre OAl API should be enabled with mesh_enable().
 309  *
 310  * @see  mesh_enable()
 311  */
 312 oal_status_t mesh_delete_remote_node(oal_uuid_t* network_uuid,
 313                 uint16_t unicast, uint16_t num_elements);
 314
 315 /**
 316  * @brief UnRegister the BLE Mesh Node
 317  *
 318  * @remarks  Application will unregister the Mesh Provisioner
 319  * node or Device node
 320  *
 321  * @pre OAl API should be enabled with mesh_enable().
 322  *
 323  * @see  mesh_enable()
 324  * @see  mesh_register_node()
 325  */
 326 oal_status_t mesh_deregister_node(oal_mesh_node_t *node);
 327
 328 /**
 329  * @brief Local Network Subnet Operations by Mesh Provisioner Node
 330  *
 331  * @remarks  Application can Create/Delete/Update subnets in
 332  * local key database
 333  *
 334  * @pre OAl API should be enabled with mesh_enable().
 335  *
 336  * @see  mesh_enable()
 337  * @see  mesh_network_subnet_execute()
 338  */
 339 oal_status_t mesh_network_subnet_execute(oal_uuid_t* network_uuid,
 340                 oal_mesh_key_op_e operation, uint16_t net_index);
 341
 342 /**
 343  * @brief Local Network Appkey Operations by Mesh Provisioner Node
 344  *
 345  * @remarks  Application can Create/Delete/Update Appkeys, bound to
 346  * netkeys in local key database
 347  *
 348  * @pre OAl API should be enabled with mesh_enable().
 349  *
 350  * @see  mesh_enable()
 351  * @see  mesh_network_subnet_execute()
 352  * @see  mesh_network_subnet_execute()
 353  */
 354 oal_status_t mesh_network_appkey_execute(oal_uuid_t* network_uuid,
 355                 oal_mesh_key_op_e operation,
 356                         uint16_t net_index, uint16_t app_index);
 357
 358 /**
 359  * @brief Discover unprovisioned device
 360  *
 361  * @remarks  Provisioner application can discover Unprovisioned Device
 362  * beaons which want to Join Mesh network
 363  * @remarks  scan params structure is defined for forward compatibility.
 364  * Currently only single parameter (seconds) is supported
 365  *
 366  * @pre OAl API should be enabled with mesh_enable().
 367  *
 368  * @see  mesh_enable()
 369  * @see  mesh_network_start_scan()
 370  */
 371 oal_status_t mesh_network_start_scan(oal_uuid_t* network_uuid,
 372                 oal_mesh_scan_params_t *params);
 373
 374 /**
 375  * @brief Cancel unprovisionined Device scanning
 376  *
 377  * @see  mesh_enable()
 378  * @see  mesh_network_start_scan()
 379  */
 380 oal_status_t mesh_network_scan_cancel(oal_uuid_t* network_uuid);
 381
 382 /**
 383  * @brief Set Provisioning capabilities
 384  *
 385  * @remarks  Provisioner application should set the capabilities
 386  * before initiating device provision. Provisioning parameters are
 387  * chosen based on combination of provisioner & device's capabilities
 388  *
 389  * @pre OAl API should be enabled with mesh_enable().
 390  *
 391  * @see  mesh_enable()
 392  */
 393 oal_status_t mesh_network_set_provisioning_capabilities(
 394                 oal_uuid_t *network_uuid, oal_mesh_capabilities_t *caps);
 395
 396 /**
 397  * @brief Security provision a device to Mesh Network
 398  *
 399  * @remarks  Provisioner application can provision device after
 400  * scanning for device beacons.
 401  * @remarks  Provisioner application should set the Provisioning
 402  * capabilities before starting provision.
 403  *
 404  * @pre OAl API should be enabled with mesh_enable().
 405  *
 406  * @see  mesh_enable()
 407  * @see  mesh_network_set_provisioning_capabilities()
 408  * @see  mesh_network_provision_device()
 409  */
 410 oal_status_t mesh_network_provision_device(oal_uuid_t* network_uuid,
 411                 oal_uuid_t *dev_uuid);
 412
 413
 414 /**
 415  * @brief Send data for provisioning like NetKey, Primary unicast
 416  *
 417  * @see  mesh_enable()
 418  */
 419 oal_status_t mesh_network_send_provisioning_data(oal_uuid_t* network_uuid,
 420                 uint16_t netkey_idx, uint16_t unicast);
 421
 422 /**
 423  * @brief Send Reply to Ongoing Security Provisioning
 424  *
 425  * @remarks  Tizen supports only one Provisioning or Join
 426  * Call simulatneously.
 427  *
 428  * @pre OAl API should be enabled with mesh_enable().
 429  *
 430  * @see  mesh_enable()
 431  * @see  mesh_network_provision_device()
 432  * @see  cb_mesh_authentication_request()
 433  */
 434 oal_status_t mesh_authentication_reply(oal_mesh_variant_authentication_e type,
 435                 const char* auth_value);
 436
 437 /**
 438  * @brief Cancels an ongoing security provisioning
 439  *
 440  * @remarks  Mesh stack does not support Cancelling Ongoing
 441  * provisiong currently.
 442  *
 443  * @pre OAl API should be enabled with mesh_enable().
 444  *
 445  * @see  mesh_enable()
 446  * @see  mesh_network_provision_device()
 447  */
 448 oal_status_t mesh_provisioning_cancel(oal_uuid_t *local_device_uuid);
 449
 450 /**
 451  * @brief Sends Configuration Client message originated from Local Node
 452  *
 453  * @remarks Local Configuration client can send message to both local
 454  * & remote Configuration Server.
 455  *
 456  * @pre OAl API should be enabled with mesh_enable().
 457  *
 458  * @see  mesh_enable()
 459  * @see  cb_mesh_conf_message()
 460  */
 461 oal_status_t mesh_conf_send_message(oal_uuid_t *network_uuid,
 462                 uint16_t dest, bool is_devkey_remote,
 463                         uint16_t netkey_idx, uint8_t *buf, int len);
 464
 465 /**
 466  * @brief Sends Configuration Client Key (NetKey & AppKey Add/Update)
 467  * messages originated from Local Node
 468  *
 469  * @remarks Local Configuration client can send message to both
 470   * local & remote Configuration Server.
 471  *
 472  * @pre OAl API should be enabled with mesh_enable().
 473  *
 474  * @see  mesh_enable()
 475  * @see  cb_mesh_conf_message()
 476  */
 477 oal_status_t mesh_conf_send_key_message(oal_uuid_t *network_uuid,
 478                 uint16_t dest, bool is_netkey,
 479                         bool is_update, int key_idx, int netkey_idx);
 480
 481
 482 /**
 483  * @brief Sends Application message to be encrypted with appplication key
 484  *
 485  * @remarks These messages are generated by Models, which are
 486  * implemented by Tizen Application.
 487  * @remarks Tizen Mesh Framework will not handle these mesages directly
 488  * and only transport these to and from application.
 489  *
 490  * @pre OAl API should be enabled with mesh_enable().
 491  *
 492  * @see  mesh_enable()
 493  * @see cb_mesh_model_message()
 494  */
 495 oal_status_t mesh_model_send_message(oal_uuid_t *network_uuid,
 496                 uint16_t dest, uint16_t appkey_idx, uint8_t *buf, int len);
 497
 498 #endif /* OAL_MESH_H_ */