doc/mesh-api.txt

   1 BlueZ D-Bus Mesh API description
   2 ********************************
   3
   4 Mesh Network Hierarchy
   5 ======================
   6 Service         org.bluez.mesh
   7 Interface       org.bluez.mesh.Network1
   8 Object path     /org/bluez/mesh
   9
  10 Methods:
  11         void Join(object app_root, array{byte}[16] uuid)
  12
  13                 This is the first method that an application has to call to
  14                 become a provisioned node on a mesh network. The call will
  15                 initiate broadcasting of Unprovisioned Device Beacon.
  16
  17                 The app_root parameter is a D-Bus object root path of
  18                 the application that implements org.bluez.mesh.Application1
  19                 interface. The application represents a node where child mesh
  20                 elements have their own objects that implement
  21                 org.bluez.mesh.Element1 interface. The application hierarchy
  22                 also contains a provision agent object that implements
  23                 org.bluez.mesh.ProvisionAgent1 interface. The standard
  24                 DBus.ObjectManager interface must be available on the
  25                 app_root path.
  26
  27                 The uuid parameter is a 16-byte array that contains Device UUID.
  28                 This UUID must be unique (at least from the daemon perspective),
  29                 therefore attempting to call this function using already
  30                 registered UUID results in an error.
  31
  32                 PossibleErrors:
  33                         org.bluez.mesh.Error.InvalidArguments
  34                         org.bluez.mesh.Error.AlreadyExists,
  35
  36         void Cancel(void)
  37
  38                 Cancels an outstanding provisioning request initiated by Join()
  39                 method.
  40
  41         object node, array{byte, array{(uint16, dict)}} configuration
  42                         Attach(object app_root, uint64 token)
  43
  44                 This is the first method that an application must call to get
  45                 access to mesh node functionalities.
  46
  47                 The app_root parameter is a D-Bus object root path of
  48                 the application that implements org.bluez.mesh.Application1
  49                 interface. The application represents a node where child mesh
  50                 elements have their own objects that implement
  51                 org.bluez.mesh.Element1 interface. The standard
  52                 DBus.ObjectManager interface must be available on the
  53                 app_root path.
  54
  55                 The token parameter is a 64-bit number that has been assigned to
  56                 the application when it first got provisioned/joined mesh
  57                 network, i.e. upon receiving JoinComplete() method. The daemon
  58                 uses the token to verify whether the application is authorized
  59                 to assume the mesh node identity.
  60
  61                 In case of success, the method call returns mesh node object
  62                 (see Mesh Node Hierarchy section) and current configuration
  63                 settings. The return value of configuration parameter is an
  64                 array, where each entry is a structure that contains element
  65                 configuration. The element configuration structure is organized
  66                 as follows:
  67
  68                 byte
  69
  70                         Element index, identifies the element to which this
  71                         configuration entry pertains.
  72
  73                 array{struct}
  74
  75                         Models array where each entry is a structure with the
  76                         following members:
  77
  78                         uint16
  79
  80                                 Either a SIG Model Identifier or, if Vendor key
  81                                 is present in model configuration dictionary, a
  82                                 16-bit vendor-assigned Model Identifier
  83
  84                         dict
  85
  86                                 A dictionary that contains model configuration
  87                                 with the following keys defined:
  88
  89                                 array{uint16} Bindings
  90
  91                                         Indices of application keys bound to the
  92                                         model
  93
  94                                 uint32 PublicationPeriod
  95
  96                                         Model publication period in milliseconds
  97
  98                                 uint16 Vendor
  99
 100                                         A 16-bit Company ID as defined by the
 101                                         Bluetooth SIG
 102
 103                                 array{variant} Subscriptions
 104
 105                                         Addresses the model is subscribed to.
 106
 107                                         Each address is provided either as
 108                                         uint16 for group addresses, or
 109                                         as array{byte} for virtual labels.
 110
 111                 PossibleErrors:
 112                         org.bluez.mesh.Error.InvalidArguments
 113                         org.bluez.mesh.Error.NotFound,
 114                         org.bluez.mesh.Error.AlreadyExists,
 115                         org.bluez.mesh.Error.Failed
 116
 117         void Leave(uint64 token)
 118
 119                 This removes the configuration information about the mesh node
 120                 identified by the 64-bit token parameter. The token parameter
 121                 has been obtained as a result of successful Join() method call.
 122
 123                 PossibleErrors:
 124                         org.bluez.mesh.Error.InvalidArguments
 125
 126         uint64 token CreateNetwork(object app_root, array{byte}[16] uuid)
 127
 128                 This is the first method that an application calls to become
 129                 a Provisioner node, and a Configuration Client on a newly
 130                 created Mesh Network.
 131
 132                 The app_root parameter is a D-Bus object root path of the
 133                 application that implements org.bluez.mesh.Application1
 134                 interface, and a org.bluez.mesh.Provisioner1 interface. The
 135                 application represents a node where child mesh elements have
 136                 their own objects that implement org.bluez.mesh.Element1
 137                 interface. The application hierarchy also contains a provision
 138                 agent object that implements org.bluez.mesh.ProvisionAgent1
 139                 interface. The standard DBus.ObjectManager interface must be
 140                 available on the app_root path.
 141
 142                 The uuid parameter is a 16-byte array that contains Device UUID.
 143                 This UUID must be unique (at least from the daemon perspective),
 144                 therefore attempting to call this function using already
 145                 registered UUID results in an error.
 146
 147                 The returned token must be preserved by the application in
 148                 order to authenticate itself to the mesh daemon and attach to
 149                 the network as a mesh node by calling Attach() method or
 150                 permanently remove the identity of the mesh node by calling
 151                 Leave() method.
 152
 153                 The other information the bluetooth-meshd daemon will preserve
 154                 about the initial node, is to give it the initial primary
 155                 unicast address (0x0001), and create and assign a net_key as the
 156                 primary network net_index (0x000).
 157
 158                 PossibleErrors:
 159                         org.bluez.mesh.Error.InvalidArguments
 160                         org.bluez.mesh.Error.AlreadyExists,
 161
 162         uint64 token Import(object app_root, array{byte}[16] uuid,
 163                                 array{byte}[16] dev_key,
 164                                 array{byte}[16] net_key, uint16 net_index,
 165                                 dict flags, uint32 iv_index, uint16 unicast)
 166
 167                 This method creates a local mesh node based on node
 168                 configuration that has been generated outside bluetooth-meshd.
 169
 170                 The app_root parameter is a D-Bus object root path of the
 171                 application that implements org.bluez.mesh.Application1
 172                 interface.
 173
 174                 The uuid parameter is a 16-byte array that contains Device UUID.
 175                 This UUID must be unique (at least from the daemon perspective),
 176                 therefore attempting to call this function using already
 177                 registered UUID results in an error.
 178
 179                 The dev_key parameter is the 16-byte value of the dev key of
 180                 the imported mesh node.
 181
 182                 Remaining parameters correspond to provisioning data:
 183
 184                 The net_key and net_index parameters describe the network (or a
 185                 subnet, if net_index is not 0) the imported mesh node belongs
 186                 to.
 187
 188                 The flags parameter is a dictionary containing provisioning
 189                 flags. Supported values are:
 190
 191                         boolean IVUpdate
 192
 193                                 When true, indicates that the network is in the
 194                                 middle of IV Index Update procedure.
 195
 196                         boolean KeyRefresh
 197
 198                                 When true, indicates that the specified net key
 199                                 is in the middle of a key refresh procedure.
 200
 201                 The iv_index parameter is the current IV Index value used by
 202                 the network. This value is known by the provisioner.
 203
 204                 The unicast parameter is the primary unicast address of the
 205                 imported node.
 206
 207                 The returned token must be preserved by the application in
 208                 order to authenticate itself to the mesh daemon and attach to
 209                 the network as a mesh node by calling Attach() method or
 210                 permanently remove the identity of the mesh node by calling
 211                 Leave() method.
 212
 213                 PossibleErrors:
 214                         org.bluez.mesh.Error.InvalidArguments,
 215                         org.bluez.mesh.Error.AlreadyExists,
 216                         org.bluez.mesh.Error.NotSupported,
 217                         org.bluez.mesh.Error.Failed
 218
 219 Mesh Node Hierarchy
 220 ===================
 221 Service         org.bluez.mesh
 222 Interface       org.bluez.mesh.Node1
 223 Object path     /org/bluez/mesh/node<uuid>
 224                 where <uuid> is the Device UUID passed to Join(),
 225                 CreateNetwork() or Import()
 226
 227 Methods:
 228         void Send(object element_path, uint16 destination, uint16 key_index,
 229                                                         array{byte} data)
 230
 231                 This method is used to send a message originated by a local
 232                 model.
 233
 234                 The element_path parameter is the object path of an element from
 235                 a collection of the application elements (see Mesh Application
 236                 Hierarchy section).
 237
 238                 The destination parameter contains the destination address. This
 239                 destination must be a uint16 to a unicast address, or a well
 240                 known group address.
 241
 242                 The key_index parameter determines which application key to use
 243                 for encrypting the message. The key_index must be valid for that
 244                 element, i.e., the application key must be bound to a model on
 245                 this element. Otherwise, org.bluez.mesh.Error.NotAuthorized will
 246                 be returned.
 247
 248                 The data parameter is an outgoing message to be encypted by the
 249                 bluetooth-meshd daemon and sent on.
 250
 251                 Possible errors:
 252                         org.bluez.mesh.Error.NotAuthorized
 253                         org.bluez.mesh.Error.InvalidArguments
 254                         org.bluez.mesh.Error.NotFound
 255
 256         void DevKeySend(object element_path, uint16 destination, boolean remote,
 257                                         uint16 net_index, array{byte} data)
 258
 259                 This method is used to send a message originated by a local
 260                 model encoded with the device key of the remote node.
 261
 262                 The element_path parameter is the object path of an element from
 263                 a collection of the application elements (see Mesh Application
 264                 Hierarchy section).
 265
 266                 The destination parameter contains the destination address. This
 267                 destination must be a uint16 to a unicast address, or a well
 268                 known group address.
 269
 270                 The remote parameter, if true, looks up the device key by the
 271                 destination address in the key database to encrypt the message.
 272                 If remote is true, but requested key does not exist, a NotFound
 273                 error will be returned. If set to false, the local node's
 274                 device key is used.
 275
 276                 The net_index parameter is the subnet index of the network on
 277                 which the message is to be sent.
 278
 279                 The data parameter is an outgoing message to be encypted by the
 280                 meshd daemon and sent on.
 281
 282                 Possible errors:
 283                         org.bluez.mesh.Error.InvalidArguments
 284                         org.bluez.mesh.Error.NotFound
 285
 286         void AddNetKey(object element_path, uint16 destination,
 287                         uint16 subnet_index, uint16 net_index, boolean update)
 288
 289                 This method is used to send add or update network key originated
 290                 by the local configuration client to a remote configuration
 291                 server.
 292
 293                 The element_path parameter is the object path of an element from
 294                 a collection of the application elements (see Mesh Application
 295                 Hierarchy section).
 296
 297                 The destination parameter contains the destination address. This
 298                 destination must be a uint16 to a nodes primary unicast address.
 299
 300                 The subnet_index parameter refers to the subnet index of the
 301                 network that is being added or updated. This key must exist in
 302                 the local key database.
 303
 304                 The net_index parameter is the subnet index of the network on
 305                 which the message is to be sent.
 306
 307                 The update parameter indicates if this is an addition or an
 308                 update. If true, the subnet key must be in the phase 1 state of
 309                 the key update procedure.
 310
 311                 Possible errors:
 312                         org.bluez.mesh.Error.InvalidArguments
 313                         org.bluez.mesh.Error.NotFound
 314
 315         void AddAppKey(object element_path, uint16 destination,
 316                         uint16 app_index, uint16 net_index, boolean update)
 317
 318                 This method is used to send add or update network key originated
 319                 by the local configuration client to a remote configuration
 320                 server.
 321
 322                 The element_path parameter is the object path of an element from
 323                 a collection of the application elements (see Mesh Application
 324                 Hierarchy section).
 325
 326                 The destination parameter contains the destination address. This
 327                 destination must be a uint16 to a nodes primary unicast address.
 328
 329                 The app_index parameter refers to the application key which is
 330                 being added or updated. This key must exist in the local key
 331                 database.
 332
 333                 The net_index parameter is the subnet index of the network on
 334                 which the message is to be sent.
 335
 336                 The update parameter indicates if this is an addition or an
 337                 update. If true, the subnet key must be in the phase 1 state of
 338                 the key update procedure.
 339
 340                 Possible errors:
 341                         org.bluez.mesh.Error.InvalidArguments
 342                         org.bluez.mesh.Error.NotFound
 343
 344         void Publish(object element_path, uint16 model, array{byte} data)
 345
 346                 This method is used to send a publication originated by a local
 347                 model. If the model does not exist, or it has no publication
 348                 record, the method returns org.bluez.mesh.Error.DoesNotExist
 349                 error.
 350
 351                 The element_path parameter is the object path of an element from
 352                 a collection of the application elements (see Mesh Application
 353                 Hierarchy section).
 354
 355                 The model parameter contains a model ID, as defined by the
 356                 Bluetooth SIG.
 357
 358                 Since only one Publish record may exist per element-model, the
 359                 destination and key_index are obtained from the Publication
 360                 record cached by the daemon.
 361
 362                 Possible errors:
 363                         org.bluez.mesh.Error.DoesNotExist
 364                         org.bluez.mesh.Error.InvalidArguments
 365
 366         void VendorPublish(object element_path, uint16 vendor, uint16 model_id,
 367                                                         array{byte} data)
 368
 369                 This method is used to send a publication originated by a local
 370                 vendor model. If the model does not exist, or it has no
 371                 publication record, the method returns
 372                 org.bluez.mesh.Error.DoesNotExist error.
 373
 374                 The element_path parameter is the object path of an element from
 375                 a collection of the application elements (see Mesh Application
 376                 Hierarchy section).
 377
 378                 The vendor parameter is a 16-bit Bluetooth-assigned Company ID.
 379
 380                 The model_id parameter is a 16-bit vendor-assigned Model
 381                 Identifier.
 382
 383                 Since only one Publish record may exist per element-model, the
 384                 destination and key_index are obtained from the Publication
 385                 record cached by the daemon.
 386
 387                 Possible errors:
 388                         org.bluez.mesh.Error.DoesNotExist
 389                         org.bluez.mesh.Error.InvalidArguments
 390
 391 Properties:
 392         dict Features [read-only]
 393
 394                 The dictionary that contains information about feature support.
 395                 The following keys are defined:
 396
 397                 boolean Friend
 398
 399                         Indicates the ability to establish a friendship with a
 400                         Low Power node
 401
 402                 boolean LowPower
 403
 404                         Indicates support for operating in Low Power node mode
 405
 406                 boolean Proxy
 407
 408                         Indicates support for GATT proxy
 409
 410                 boolean Relay
 411                         Indicates support for relaying messages
 412
 413         If a key is absent from the dictionary, the feature is not supported.
 414         Otherwise, true means that the feature is enabled and false means that
 415         the feature is disabled.
 416
 417         boolean Beacon [read-only]
 418
 419                 This property indicates whether the periodic beaconing is
 420                 enabled (true) or disabled (false).
 421
 422         uint8 BeaconFlags [read-only]
 423
 424                 This property may be read at any time to determine the flag
 425                 field setting on sent and received beacons of the primary
 426                 network key.
 427
 428         uint32 IvIndex [read-only]
 429
 430                 This property may be read at any time to determine the IV_Index
 431                 that the current network is on. This information is only useful
 432                 for provisioning.
 433
 434         uint32 SecondsSinceLastHeard [read-only]
 435
 436                 This property may be read at any time to determine the number of
 437                 seconds since mesh network layer traffic was last detected on
 438                 this node's network.
 439
 440         array{uint16} Addresses [read-only]
 441
 442                 This property contains unicast addresses of node's elements.
 443
 444         uint32 SequenceNumber [read-only]
 445
 446                 This property may be read at any time to determine the
 447                 sequence number.
 448
 449 Mesh Provisioning Hierarchy
 450 ============================
 451 Service         org.bluez.mesh
 452 Interface       org.bluez.mesh.Management1
 453 Object path     /org/bluez/mesh/node<uuid>
 454                 where <uuid> is the Device UUID passed to Join(),
 455                 CreateNetwork() or Import()
 456
 457 Methods:
 458         void UnprovisionedScan(dict options)
 459
 460                 This method is used by the application that supports
 461                 org.bluez.mesh.Provisioner1 interface to start listening
 462                 (scanning) for unprovisioned devices in the area.
 463
 464                 The options parameter is a dictionary with the following keys
 465                 defined:
 466
 467                 uint16 Seconds
 468                         Specifies number of seconds for scanning to be active.
 469                         If set to 0 or if this key is not present, then the
 470                         scanning will continue until UnprovisionedScanCancel()
 471                         or AddNode() methods are called.
 472
 473                 Each time a unique unprovisioned beacon is heard, the
 474                 ScanResult() method on the app will be called with the result.
 475
 476                 PossibleErrors:
 477                         org.bluez.mesh.Error.InvalidArguments
 478                         org.bluez.mesh.Error.NotAuthorized
 479                         org.bluez.mesh.Error.Busy
 480
 481         void UnprovisionedScanCancel(void)
 482
 483                 This method is used by the application that supports
 484                 org.bluez.mesh.Provisioner1 interface to stop listening
 485                 (scanning) for unprovisioned devices in the area.
 486
 487                 PossibleErrors:
 488                         org.bluez.mesh.Error.InvalidArguments
 489                         org.bluez.mesh.Error.NotAuthorized
 490
 491         void AddNode(array{byte}[16] uuid, dict options)
 492
 493                 This method is used by the application that supports
 494                 org.bluez.mesh.Provisioner1 interface to add the
 495                 unprovisioned device specified by uuid, to the Network.
 496
 497                 The uuid parameter is a 16-byte array that contains Device UUID
 498                 of the unprovisioned device to be added to the network.
 499
 500                 The options parameter is a dictionary that may contain
 501                 additional configuration info (currently an empty placeholder
 502                 for forward compatibility).
 503
 504                 PossibleErrors:
 505                         org.bluez.mesh.Error.InvalidArguments
 506                         org.bluez.mesh.Error.NotAuthorized
 507
 508         void CreateSubnet(uint16 net_index)
 509
 510                 This method is used by the application to generate and add a new
 511                 network subnet key.
 512
 513                 The net_index parameter is a 12-bit value (0x001-0xFFF)
 514                 specifying which net key to add.
 515
 516                 This call affects the local bluetooth-meshd key database only.
 517
 518                 PossibleErrors:
 519                         org.bluez.mesh.Error.Failed
 520                         org.bluez.mesh.Error.InvalidArguments
 521                         org.bluez.mesh.Error.AlreadyExists
 522
 523         void ImportSubnet(uint16 net_index, array{byte}[16] net_key)
 524
 525                 This method is used by the application to add a network subnet
 526                 key, that was originally generated by a remote Config Client.
 527
 528                 The net_index parameter is a 12-bit value (0x000-0xFFF)
 529                 specifying which net key to add.
 530
 531                 The net_key parameter is the 16-byte value of the net key being
 532                 imported.
 533
 534                 This call affects the local bluetooth-meshd key database only.
 535
 536                 PossibleErrors:
 537                         org.bluez.mesh.Error.Failed
 538                         org.bluez.mesh.Error.InvalidArguments
 539                         org.bluez.mesh.Error.AlreadyExists
 540
 541         void UpdateSubnet(uint16 net_index)
 542
 543                 This method is used by the application to generate a new network
 544                 subnet key, and set it's key refresh state to Phase 1.
 545
 546                 The net_index parameter is a 12-bit value (0x000-0xFFF)
 547                 specifying which net key to update. Note that the subnet must
 548                 exist prior to updating.
 549
 550                 This call affects the local bluetooth-meshd key database only.
 551
 552                 PossibleErrors:
 553                         org.bluez.mesh.Error.Failed
 554                         org.bluez.mesh.Error.InvalidArguments
 555                         org.bluez.mesh.Error.DoesNotExist
 556                         org.bluez.mesh.Error.Busy
 557
 558         void DeleteSubnet(uint16 net_index)
 559
 560                 This method is used by the application that to delete a subnet.
 561
 562                 The net_index parameter is a 12-bit value (0x001-0xFFF)
 563                 specifying which net key to delete. The primary net key (0x000)
 564                 may not be deleted.
 565
 566                 This call affects the local bluetooth-meshd key database only.
 567
 568                 PossibleErrors:
 569                         org.bluez.mesh.Error.InvalidArguments
 570
 571         void SetKeyPhase(uint16 net_index, uint8 phase)
 572                 This method is used to set the master key update phase of the
 573                 given subnet. When finalizing the procedure, it is important
 574                 to CompleteAppKeyUpdate() on all app keys that have been
 575                 updated during the procedure prior to setting phase 3.
 576
 577                 The net_index parameter is a 12-bit value (0x000-0xFFF)
 578                 specifying which subnet phase to set.
 579
 580                 The phase parameter is used to cycle the local key database
 581                 through the phases as defined by the Mesh Profile Specification.
 582                 Allowed values:
 583                         0 - Cancel Key Refresh (May only be called from Phase 1,
 584                                 and should never be called once the new key has
 585                                 started propagating)
 586                         1 - Invalid Argument (see NetKeyUpdate method)
 587                         2 - Go to Phase 2 (May only be called from Phase 1)
 588                         3 - Complete Key Refresh procedure (May only be called
 589                                 from Phase 2)
 590
 591                 This call affects the local bluetooth-meshd key database only.
 592                 It is the responsibility of the application to maintain the key
 593                 refresh phases per the Mesh Profile Specification.
 594
 595                 PossibleErrors:
 596                         org.bluez.mesh.Error.Failed
 597                         org.bluez.mesh.Error.InvalidArguments
 598                         org.bluez.mesh.Error.DoesNotExist
 599
 600         void CreateAppKey(uint16 net_index, uint16 app_index)
 601
 602                 This method is used by the application to generate and add a new
 603                 application key.
 604
 605                 The net_index parameter is a 12-bit value (0x000-0xFFF)
 606                 specifying which net key to bind the application key to.
 607
 608                 The app_index parameter is a 12-bit value (0x000-0xFFF)
 609                 specifying which app key to add.
 610
 611                 This call affects the local bluetooth-meshd key database only.
 612
 613                 PossibleErrors:
 614                         org.bluez.mesh.Error.Failed
 615                         org.bluez.mesh.Error.InvalidArguments
 616                         org.bluez.mesh.Error.AlreadyExists
 617                         org.bluez.mesh.Error.DoesNotExist
 618
 619         void ImportAppKey(uint16 net_index, uint16 app_index,
 620                                                 array{byte}[16] app_key)
 621
 622                 This method is used by the application to add an application
 623                 key, that was originally generated by a remote Config Client.
 624
 625                 The net_index parameter is a 12-bit value (0x000-0xFFF)
 626                 specifying which net key to bind the application key to.
 627
 628                 The app_index parameter is a 12-bit value (0x000-0xFFF)
 629                 specifying which app key to import.
 630
 631                 The app_key parameter is the 16-byte value of the key being
 632                 imported.
 633
 634                 This call affects the local bluetooth-meshd key database only.
 635
 636                 PossibleErrors:
 637                         org.bluez.mesh.Error.Failed
 638                         org.bluez.mesh.Error.InvalidArguments
 639                         org.bluez.mesh.Error.AlreadyExists
 640                         org.bluez.mesh.Error.DoesNotExist
 641
 642         void UpdateAppKey(uint16 app_index)
 643
 644                 This method is used by the application to generate a new
 645                 application key.
 646
 647                 The app_index parameter is a 12-bit value (0x000-0xFFF)
 648                 specifying which app key to update. Note that the subnet that
 649                 the key is bound to must exist and be in Phase 1.
 650
 651                 This call affects the local bluetooth-meshd key database only.
 652
 653                 PossibleErrors:
 654                         org.bluez.mesh.Error.Failed
 655                         org.bluez.mesh.Error.InvalidArguments
 656                         org.bluez.mesh.Error.DoesNotExist
 657                         org.bluez.mesh.Error.Busy
 658
 659         void DeleteAppKey(uint16 app_index)
 660
 661                 This method is used by the application to delete an application
 662                 key.
 663
 664                 The app_index parameter is a 12-bit value (0x000-0xFFF)
 665                 specifying which app key to delete.
 666
 667                 This call affects the local bluetooth-meshd key database only.
 668
 669                 PossibleErrors:
 670                         org.bluez.mesh.Error.InvalidArguments
 671
 672         void ImportRemoteNode(uint16 primary, uint8 count,
 673                                         array{byte}[16] device_key)
 674
 675                 This method is used by the application to import a remote node
 676                 that has been provisioned by an external process.
 677
 678                 The primary parameter specifies the unicast address of the
 679                 the node being imported.
 680
 681                 The count parameter specifies the number of elements that are
 682                 assigned to this remote node.
 683
 684                 The device_key parameter is the access layer key that will be
 685                 will used to decrypt privledged messages from this remote node.
 686
 687                 This call affects the local bluetooth-meshd key database only.
 688
 689                 It is an error to call this with address range overlapping
 690                 with local element addresses.
 691
 692                 PossibleErrors:
 693                         org.bluez.mesh.Error.Failed
 694                         org.bluez.mesh.Error.InvalidArguments
 695
 696         void DeleteRemoteNode(uint16 primary, uint8 count)
 697
 698                 This method is used by the application to delete a remote node
 699                 from the local device key database.
 700
 701                 The primary parameter specifies the unicast address of the
 702                 the node being deleted.
 703
 704                 The count parameter specifies the number of elements that were
 705                 assigned to the remote node.
 706
 707                 This call affects the local bluetooth-meshd key database only.
 708
 709                 It is an error to call this with address range overlapping
 710                 with local element addresses.
 711
 712                 PossibleErrors:
 713                         org.bluez.mesh.Error.InvalidArguments
 714
 715 Mesh Application Hierarchy
 716 ==========================
 717 Service         unique name
 718 Interface       org.bluez.mesh.Application1
 719 Object path     <app_root>
 720
 721 An application is a collection of elements that host SIG defined and vendor
 722 specific models. It is expected that an application implements
 723 org.freedesktop.DBus.ObjectManager interface at app_root path.
 724
 725 An example mesh application hierarchy may look like this:
 726
 727 -> /com/example
 728   |   - org.freedesktop.DBus.ObjectManager
 729   |
 730   -> /com/example/application
 731   |   - org.bluez.mesh.Application1
 732   |   - org.bluez.mesh.Attention1 (optional)
 733   |   - org.bluez.mesh.Provisioner1 (optional,Provisioner)
 734   |
 735   -> /com/example/agent
 736   |   - org.bluez.mesh.ProvisionAgent1
 737   |
 738   -> /com/example/ele00
 739   |   - org.bluez.mesh.Element1
 740   |
 741   -> /com/example/ele01
 742   |   - org.bluez.mesh.Element1
 743   |
 744   ...
 745   -> /com/example/elexx
 746       - org.bluez.mesh.Element1
 747
 748 Methods:
 749         void JoinComplete(uint64 token)
 750
 751                 This method is called when the node provisioning initiated
 752                 by a Join() method call successfully completed.
 753
 754                 The token parameter serves as a unique identifier of the
 755                 particular node. The token must be preserved by the application
 756                 in order to authenticate itself to the mesh daemon and attach to
 757                 the network as a mesh node by calling Attach() method or
 758                 permanently remove the identity of the mesh node by calling
 759                 Leave() method.
 760
 761         void JoinFailed(string reason)
 762
 763                 This method is called when the node provisioning initiated by
 764                 Join() has failed.
 765
 766                 The reason parameter identifies the reason for provisioning
 767                 failure. The defined values are: "timeout", "bad-pdu",
 768                 "confirmation-failed", "out-of-resources", "decryption-error",
 769                 "unexpected-error", "cannot-assign-addresses".
 770
 771 Properties:
 772         uint16 CompanyID [read-only]
 773
 774                 A 16-bit Bluetooth-assigned Company Identifier of the vendor as
 775                 defined by Bluetooth SIG
 776
 777         uint16 ProductID [read-only]
 778
 779                 A 16-bit vendor-assigned product identifier
 780
 781         uint16 VersionID [read-only]
 782
 783                 A 16-bit vendor-assigned product version identifier
 784
 785         uint16 CRPL [read-only, optional]
 786
 787                 A 16-bit minimum number of replay protection list entries
 788
 789
 790 Mesh Element Hierarchy
 791 ======================
 792 Service         unique name
 793 Interface       org.bluez.mesh.Element1
 794 Object path     <app_defined_element_path>
 795
 796 Methods:
 797         void MessageReceived(uint16 source, uint16 key_index,
 798                                         variant destination, array{byte} data)
 799
 800                 This method is called by bluetooth-meshd daemon when a message
 801                 arrives addressed to the application.
 802
 803                 The source parameter is unicast address of the remote
 804                 node-element that sent the message.
 805
 806                 The key_index parameter indicates which application key has been
 807                 used to decode the incoming message. The same key_index should
 808                 be used by the application when sending a response to this
 809                 message (in case a response is expected).
 810
 811                 The destination parameter contains the destination address of
 812                 received message. Underlying variant types are:
 813
 814                 uint16
 815
 816                         Destination is an unicast address, or a well known
 817                         group address
 818
 819                 array{byte}
 820
 821                         Destination is a virtual address label
 822
 823                 The data parameter is the incoming message.
 824
 825         void DevKeyMessageReceived(uint16 source, boolean remote,
 826                                         uint16 net_index, array{byte} data)
 827
 828                 This method is called by meshd daemon when a message arrives
 829                 addressed to the application, which was sent with the remote
 830                 node's device key.
 831
 832                 The source parameter is unicast address of the remote
 833                 node-element that sent the message.
 834
 835                 The remote parameter if true indicates that the device key
 836                 used to decrypt the message was from the sender. False
 837                 indicates that the local nodes device key was used, and the
 838                 message has permissions to modify local states.
 839
 840                 The net_index parameter indicates what subnet the message was
 841                 received on, and if a response is required, the same subnet
 842                 must be used to send the response.
 843
 844                 The data parameter is the incoming message.
 845
 846         void UpdateModelConfiguration(uint16 model_id, dict config)
 847
 848                 This method is called by bluetooth-meshd daemon when a model's
 849                 configuration is updated.
 850
 851                 The model_id parameter contains BT SIG Model Identifier or, if
 852                 Vendor key is present in config dictionary, a 16-bit
 853                 vendor-assigned Model Identifier.
 854
 855                 The config parameter is a dictionary with the following keys
 856                 defined:
 857
 858                 array{uint16} Bindings
 859
 860                         Indices of application keys bound to the model
 861
 862                 uint32 PublicationPeriod
 863
 864                         Model publication period in milliseconds
 865
 866                 uint16 Vendor
 867
 868                         A 16-bit Bluetooth-assigned Company Identifier of the
 869                         vendor as defined by Bluetooth SIG
 870
 871                 array{variant} Subscriptions
 872
 873                         Addresses the model is subscribed to.
 874
 875                         Each address is provided either as uint16 for group
 876                         addresses, or as array{byte} for virtual labels.
 877
 878 Properties:
 879         uint8 Index [read-only]
 880
 881                 Element index. It is required that the application follows
 882                 sequential numbering scheme for the elements, starting with 0.
 883
 884         array{uint16} Models [read-only]
 885
 886                 An array of SIG Model Identifiers. The array may be empty.
 887
 888         array{(uint16, uint16)} VendorModels [read-only]
 889
 890                 An array of pairs (vendor, model ID): vendor is a 16-bit
 891                 Bluetooth-assigned Company ID as defined by Bluetooth SIG.
 892                 model ID is a 16-bit vendor-assigned Model Identifier
 893
 894                 The array may be empty.
 895
 896         uint16 Location [read-only, optional]
 897
 898                 Location descriptor as defined in the GATT Bluetooth Namespace
 899                 Descriptors section of the Bluetooth SIG Assigned Numbers
 900
 901
 902 Mesh Attention Hierarchy
 903 ========================
 904 Service         unique name
 905 Interface       org.bluez.mesh.Attention1
 906 Object path     freely definable
 907
 908 This is an optional interface that implements health attention timer.
 909
 910 Methods:
 911         void SetTimer(uint8 element_index, uint16 time)
 912
 913                 The element_index parameter is the element's index within the
 914                 node where the health server model is hosted.
 915
 916                 The time parameter indicates how many seconds the attention
 917                 state shall be on.
 918
 919                 PossibleErrors:
 920                         org.bluez.mesh.Error.NotSupported
 921
 922         uint16 GetTimer(uint16 element)
 923
 924                 The element parameter is the unicast address within the node
 925                 where the health server model is hosted.
 926
 927                 Returns the number of seconds for how long the attention action
 928                 remains staying on.
 929
 930                 PossibleErrors:
 931                         org.bluez.mesh.Error.NotSupported
 932
 933
 934 Mesh Provisioner Hierarchy
 935 ============================
 936 Service         unique name
 937 Interface       org.bluez.mesh.Provisioner1
 938 Object path     freely definable
 939
 940         void ScanResult(int16 rssi, array{byte} data, dict options)
 941
 942                 The method is called from the bluetooth-meshd daemon when a
 943                 unique UUID has been seen during UnprovisionedScan() for
 944                 unprovsioned devices.
 945
 946                 The rssi parameter is a signed, normalized measurement of the
 947                 signal strength of the recieved unprovisioned beacon.
 948
 949                 The data parameter is a variable length byte array, that may
 950                 have 1, 2 or 3 distinct fields contained in it including the 16
 951                 byte remote device UUID (always), a 16 bit mask of OOB
 952                 authentication flags (optional), and a 32 bit URI hash (if URI
 953                 bit set in OOB mask). Whether these fields exist or not is a
 954                 decision of the remote device.
 955
 956                 The options parameter is a dictionary that may contain
 957                 additional scan result info (currently an empty placeholder for
 958                 forward compatibility).
 959
 960                 If a beacon with a UUID that has already been reported is
 961                 recieved by the daemon, it will be silently discarded unless it
 962                 was recieved at a higher rssi power level.
 963
 964
 965         uint16 net_index, uint16 unicast RequestProvData(uint8 count)
 966
 967                 This method is implemented by a Provisioner capable application
 968                 and is called when the remote device has been fully
 969                 authenticated and confirmed.
 970
 971                 The count parameter is the number of consecutive unicast
 972                 addresses the remote device is requesting.
 973
 974                 Return Parameters are from the Mesh Profile Spec:
 975                 net_index - Subnet index of the net_key
 976                 unicast - Primary Unicast address of the new node
 977
 978                 PossibleErrors:
 979                         org.bluez.mesh.Error.Abort
 980
 981         void AddNodeComplete(array{byte}[16] uuid, uint16 unicast, uint8 count)
 982
 983                 This method is called when the node provisioning initiated
 984                 by an AddNode() method call successfully completed.
 985
 986                 The unicast parameter is the primary address that has been
 987                 assigned to the new node, and the address of it's config server.
 988
 989                 The count parameter is the number of unicast addresses assigned
 990                 to the new node.
 991
 992                 The new node may now be sent messages using the credentials
 993                 supplied by the RequestProvData method.
 994
 995         void AddNodeFailed(array{byte}[16] uuid, string reason)
 996
 997                 This method is called when the node provisioning initiated by
 998                 AddNode() has failed. Depending on how far Provisioning
 999                 proceeded before failing, some cleanup of cached data may be
1000                 required.
1001
1002                 The reason parameter identifies the reason for provisioning
1003                 failure. The defined values are: "aborted", "timeout",
1004                 "bad-pdu", "confirmation-failed", "out-of-resources",
1005                 "decryption-error", "unexpected-error",
1006                 "cannot-assign-addresses".
1007
1008 Provisioning Agent Hierarchy
1009 ============================
1010 Service         unique name
1011 Interface       org.bluez.mesh.ProvisionAgent1
1012 Object path     freely definable
1013
1014 Methods:
1015         array{byte} PrivateKey()
1016
1017                 This method is called during provisioning if the Provisioner
1018                 has requested Out-Of-Band ECC key exchange. The Private key is
1019                 returned to the Daemon, and the Public Key is delivered to the
1020                 remote Provisioner using a method that does not involve the
1021                 Bluetooth Mesh system. The Private Key returned must be 32
1022                 octets in size, or the Provisioning procedure will fail and be
1023                 canceled.
1024
1025                 This function will only be called if the Provisioner has
1026                 requested pre-determined keys to be exchanged Out-of-Band, and
1027                 the local role is Unprovisioned device.
1028
1029         array{byte} PublicKey()
1030
1031                 This method is called during provisioning if the local device is
1032                 the Provisioner, and is requestng Out-Of-Band ECC key exchange.
1033                 The Public key is returned to the Daemon that is the matched
1034                 pair of the Private key of the remote device. The Public Key
1035                 returned must be 64 octets in size, or the Provisioning
1036                 procedure will fail and be canceled.
1037
1038                 This function will only be called if the Provisioner has
1039                 requested pre-determined keys to be exchanged Out-of-Band, and
1040                 the local role is Provisioner.
1041
1042         void DisplayString(string value)
1043
1044                 This method is called when the Daemon has something important
1045                 for the Agent to Display, but does not require any additional
1046                 input locally. For instance: "Enter "ABCDE" on remote device".
1047
1048         void DisplayNumeric(string type, uint32 number)
1049
1050                 This method is called when the Daemon has something important
1051                 for the Agent to Display, but does not require any additional
1052                 input locally. For instance: "Enter 14939264 on remote device".
1053
1054                 The type parameter indicates the display method. Allowed values
1055                 are:
1056                         "blink" - Locally blink LED
1057                         "beep" - Locally make a noise
1058                         "vibrate" - Locally vibrate
1059                         "out-numeric" - Display value to enter remotely
1060                         "push" - Request pushes on remote button
1061                         "twist" - Request twists on remote knob
1062
1063                 The number parameter is the specific value represented by the
1064                 Prompt.
1065
1066         uint32 PromptNumeric(string type)
1067
1068                 This method is called when the Daemon requests the user to
1069                 enter a decimal value between 1-99999999.
1070
1071                 The type parameter indicates the input method. Allowed values
1072                 are:
1073                         "blink" - Enter times remote LED blinked
1074                         "beep" - Enter times remote device beeped
1075                         "vibrate" - Enter times remote device vibrated
1076                         "in-numeric" - Enter remotely displayed value
1077                         "push" - Push local button remotely requested times
1078                         "twist" - Twist local knob remotely requested times
1079
1080
1081                 This agent should prompt the user for specific input. For
1082                 instance: "Enter value being displayed by remote device".
1083
1084         array{byte}[16] PromptStatic(string type)
1085
1086                 This method is called when the Daemon requires a 16 octet byte
1087                 array, as an Out-of-Band authentication.
1088
1089                 The type parameter indicates the input method. Allowed values
1090                 are:
1091                         "static-oob" - return 16 octet array
1092                         "in-alpha" - return 16 octet alpha array
1093
1094                 The Static data returned must be 16 octets in size, or the
1095                 Provisioning procedure will fail and be canceled. If input type
1096                 is "in-alpha", the printable characters should be
1097                 left-justified, with trailing 0x00 octets filling the remaining
1098                 bytes.
1099
1100         void Cancel()
1101
1102                 This method gets called by the daemon to cancel any existing
1103                 Agent Requests. When called, any pending user input should be
1104                 canceled, and any display requests removed.
1105
1106
1107 Properties:
1108         array{string} Capabilities [read-only]
1109
1110                 An array of strings with the following allowed values:
1111                         "blink"
1112                         "beep"
1113                         "vibrate"
1114                         "out-numeric"
1115                         "out-alpha"
1116                         "push"
1117                         "twist"
1118                         "in-numeric"
1119                         "in-alpha"
1120                         "static-oob"
1121                         "public-oob"
1122
1123         array{string} OutOfBandInfo [read-only, optional]
1124
1125                 Indicates availability of OOB data. An array of strings with the
1126                 following allowed values:
1127                         "other"
1128                         "uri"
1129                         "machine-code-2d"
1130                         "bar-code"
1131                         "nfc"
1132                         "number"
1133                         "string"
1134                         "on-box"
1135                         "in-box"
1136                         "on-paper",
1137                         "in-manual"
1138                         "on-device"
1139
1140         string URI [read-only, optional]
1141
1142                 Uniform Resource Identifier points to out-of-band (OOB)
1143                 information (e.g., a public key)