Hi Inga, I approve of this API, and will be applying it shortly with the noted typo fix. > -----Original Message----- > From: linux-bluetooth-owner@xxxxxxxxxxxxxxx [mailto:linux-bluetooth- > owner@xxxxxxxxxxxxxxx] On Behalf Of Inga Stotland > Sent: Monday, November 19, 2018 11:29 PM > To: linux-bluetooth@xxxxxxxxxxxxxxx > Cc: marcel@xxxxxxxxxxxx; johan.hedberg@xxxxxxxxx; > luiz.dentz@xxxxxxxxx; Gix, Brian <brian.gix@xxxxxxxxx>; Stotland, Inga > <inga.stotland@xxxxxxxxx> > Subject: [PATCH BlueZ v4] doc: Initial Bluetooth Mesh API > > This decribes proposed D-Bus based API for Bluetooth Mesh > implementation. > --- > doc/mesh-api.txt | 512 > +++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 512 insertions(+) > create mode 100644 doc/mesh-api.txt > > diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt new file mode 100644 index > 000000000..eed7ba653 > --- /dev/null > +++ b/doc/mesh-api.txt > @@ -0,0 +1,512 @@ > +BlueZ D-Bus Mesh API description > +******************************** > + > +Mesh Network Hierarchy > +====================== > +Service org.bluez.mesh > +Interface org.bluez.mesh.Network1 > +Object path /org/bluez/mesh > + > +Methods: > + void Join(object app_defined_root, array{byte}[16] uuid) > + > + This is the first method that an application has to call > to become > + a provisioned node on a mesh network. The call will > initiate > + broadcasting of Unprovisioned Device Beacon. > + > + The app_defined_root parameter is a D-Bus object > root path of the > + application that implements > org.bluez.mesh.Application1 interface. > + The application represents a node where child mesh > elements have > + their own objects that implement > org.bluez.mesh.Element1 interface. > + The application hierarchy also contains a provision > agent object > + that implements org.bluez.mesh.ProvisionAgent1 > interface. > + The standard DBus.ObjectManager interface must be > available on the > + app_defined_root path. > + > + The uuid parameter is a 16-byte array that contains > Device UUID. > + > + PossibleErrors: > + org.bluez.mesh.Error.InvalidArguments > + > + void Cancel(void) > + Cancels an outstanding provisioning request initiated > by Join() > + method. > + > + (object node, array{byte, array{(uint16, dict}} configuration) > + Attach(object app_defined_root, uint64 > token) > + > + This is the first method that an application must call to > get access > + to mesh node functionalities. > + > + The app_defined_root parameter is a D-Bus object > root path of the > + application that implements > org.bluez.mesh.Application1 interface. > + The application represents a node where child mesh > elements have > + their own objects that implement > org.bluez.mesh.Element1 interface. > + The standard DBus.ObjectManager interface must be > available on the > + app_defined_root path. > + > + The token parameter is a 64-bit number that has > been assigned to the > + application when it first got provisioned/joined mesh > network, i.e. > + upon receiving JoinComplete() method. The daemon > uses the token to > + verify whether the application is authorized to > assume the mesh > + node identity. > + > + In case of success, the method call returns mesh > node object (see > + Mesh Node Hierarchy section) and current > configuration settings. > + The return value of configuration parameter is an > array, where each > + entry is a structure that contains element > configuration. > + The element configuration structure is organized as > follows: > + > + byte > + > + Element index, identifies the > element to which this > + configuration entry pertians. > + > + array{struct} > + > + Models array where each entry is a > structure with the > + following members: > + > + uint16 > + > + Either a SIG Model > Identifier or, if Vendor key is > + present in model > configuration dictionary, a 16-bit > + vendor-assigned > Model Identifier > + > + dict > + > + A dictionary that > contains model configuration with > + the following keys > defined: > + > + array{uint16} > Bindings > + > + > Indices of application keys bound to > + the > model > + > + uint32 > PublicationPeriod > + > + > Model publication period in milliseconds > + > + uint16 > Vendor > + > + A 16- > bit Bluetooth-assigned Company > + > Identifier of the vendor as defined by > + > Bluetooth SIG > + > + PossibleErrors: > + org.bluez.mesh.Error.InvalidArguments > + org.bluez.mesh.Error.NotFound, > + org.bluez.mesh.Error.Failed > + > + void Leave(uint64 token) > + > + This removes the configuration information about > the mesh node > + identified by the 64-bit token parameter. The token > parameter > + has been obtained as a result of successful Join() > method call. > + > + PossibleErrors: > + org.bluez.mesh.Error.NotFound > + > + > +Mesh Node Hierarchy > +=================== > +Service org.bluez.mesh > +Interface org.bluez.mesh.Node1 > +Object path /org/bluez/mesh/node<xxxx> > + where xxxx is a 4-digit hexadecimal number generated by > meshd daemon > + > +Methods: > + void Send(object element_path, uint16 destination, uint16 > key_index, > + array{byte} > data) > + > + This method is used to send a message originated by > a local model. > + > + The element_path parameter is the object path of an > element from > + a collection of the application elements (see Mesh > Application > + Hierarchy section). > + > + The destination parameter contains the destination > address. This > + destination must be a uint16 to a unicast address, or a > well known > + group address. > + > + The key_index parameter determines which > application key to use for > + encrypting the message. The key_index must be > valid for that > + element, i.e., the application key must be bound to a > model on this > + element. Otherwise, > org.bluez.mesh.Error.NotAuthorized will be > + returned. > + > + The data parameter is an outgoing message to be > encypted by the > + meshd daemon and sent on. > + > + Possible errors: > + org.bluez.mesh.Error.NotAuthorized > + org.bluez.mesh.Error.InvalidArguments > + org.bluez.mesh.Error.NotFound > + > + void Publish(object element_path, uint16 model, array{byte} > data) > + > + This method is used to send a publication originated > by a local > + model. If the model does not exist, or it has no > publication record, > + the method returns > org.bluez.mesh.Error.DoesNotExist error. > + > + The element_path parameter is the object path of an > element from > + a collection of the application elements (see Mesh > Application > + Hierarchy section). > + > + The model parameter contains a model ID, as defined > by the > + Bluetooth SIG. > + > + Since only one Publish record may exist per element- > model, the > + destination and key_index are obtained from the > Publication > + record cached by the daemon. > + > + Possible errors: > + org.bluez.mesh.Error.DoesNotExist > + org.bluez.mesh.Error.InvalidArguments > + > + void VendorPublish(object element_path, uint16 vendor, > uint16 model_id, > + array{byte} > data) > + > + This method is used to send a publication originated > by a local > + vendor model. If the model does not exist, or it has > no publication > + record, the method returns > org.bluez.mesh.Error.DoesNotExist error. > + > + The element_path parameter is the object path of an > element from > + a collection of the application elements (see Mesh > Application > + Hierarchy section). > + > + The vendor parameter is a 16-bit Bluetooth-assigned > Company > + Identifier. > + > + The model_id parameter is a 16-bit vendor-assigned > Model Identifier. > + > + Since only one Publish record may exist per element- > model, the > + destination and key_index are obtained from the > Publication > + record cached by the daemon. > + > + Possible errors: > + org.bluez.mesh.Error.DoesNotExist > + org.bluez.mesh.Error.InvalidArguments > + > +Properties: > + dict Features [read-only] > + > + The dictionary that contains information about > feature support. > + The following keys are defined: > + > + boolean Friend > + > + Indicates the ability to establish a > friendship with a > + Low Power node > + > + boolean LowPower > + > + Indicates support for operating in > Low Power node mode > + > + boolean Proxy > + > + Indicates support for GATT proxy > + > + boolean Relay - indicates support for relaying > messages > + > + If the key is absent from the dictionary, the feature is > not > + supported. Otherwise, true means that the feature is > enabled and > + false means that the feature is disabled. > + > + boolean Beacon [read-only] > + > + This property indicates whether the periodic > beaconing is enabled > + (true) or disabled (false). > + > + uint32 SecondsSinceLastHeard [read-only] > + > + This property may be read at any time to determine > the number of > + seconds since mesh network layer traffic was last > detected on this > + node's network. > + > + > +Mesh Application Hierarchy > +========================== > +Service unique name > +Interface org.bluez.mesh.Application1 > +Object path <app_defined_root> > + > +An application is a collection of elements that host SIG defined and > +vendor specific models. It is expected that an application implements > +org.freedesktop.DBus.ObjectManager interface. > + > +An example mesh application hierarchy may look like this: > + > + -> /com/example > + | - org.freedesktop.DBus.ObjectManager > + | - org.bluez.mesh.Application1 > + | - org.bluez.mesh.Attention1 (optional) > + | > + -> /com/example/agent > + | | - org.bluez.mesh.ProvisionAgent1 > + | > + -> /com/example/ele00 > + | | - org.bluez.mesh.Element1 > + -> /com/example/ele01 > + | | - org.bluez.mesh.Element1 > + ... > + -> /com/example/elexx > + | | - org.bluez.mesh.Element1 > + > +Methods: > + void JoinComplete(uint64 token) > + > + This method is called when the node provisioning > initiated > + by a Join() method call successfully completed. > + > + The token parameter serves as a unique identifier of > the particular > + node. The token must be preserved by the > application in order to > + authenticate itself to the mesh daemon and attach to > the network > + as a mesh node by calling Attach() method or > permanently remove the > + identity of the mesh node by calling Leave() method. > + > + void JoinFailed(string reason) > + > + This method is called when the node provisioning > initiated > + by Join() has failed. > + > + The reason parameter identifies the reason for > provisioning failure. > + The defined values are: "timeout", "bad-pdu", > "confirmation-failed", > + "out-of-resources", "decryption-error", > "unexpected-error", > + "cannot-assign-addresses". > + > +Properties: > + uint16 CompanyID [read-only] > + > + A 16-bit Bluetooth-assigned Company Identifier of > the vendor as > + defined by Bluetooth SIG > + > + uint16 ProductID [read-only] > + > + A 16-bit vendor-assigned product identifier > + > + uint16 VersionID [read-only] > + > + A 16-bit vendor-assigned product version identifier > + > + > +Mesh Element Hierarchy > +====================== > +Service unique name > +Interface org.bluez.mesh.Element1 > +Object path <app_defined_element_path> > + > +Methods: > + void MessageReceived(uint16 source, uint16 key_index, > + boolean > subscription, array{byte} data) > + > + This method is called by meshd daemon when a > message arrives > + addressed to the application. > + > + The source parameter is unicast address of the > remote node-element > + that sent the message. > + > + The key_index parameter indicates which application > key has been > + used to decode the incoming message. The same > key_index should be > + used by the application when sending a response to > this message > + (in case a response is expected). > + > + The subscription parameter is a boolean that is set to > true if > + the message is received as a part of the subscription > (i.e., the > + destination is either a well known group address or a > virtual > + label. > + > + The data parameter is the incoming message. > + > + void UpdateModelConfiguration(uint16 model_id, dict > config) > + > + This method is called by meshd daemon when a > model's configuration > + is updated. > + > + The model_id parameter contains BT SIG Model > Identifier or, if > + Vendor key is present in config dictionary, a 16-bit > + vendor-assigned Model Identifier. > + > + The config parameter is a dictionary with the > following keys > + defined: > + > + array{uint16} Bindings > + > + Indices of application keys bound to > the model > + > + uint32 PublicationPeriod > + > + Model publication period in > milliseconds > + > + uint16 Vendor > + > + A 16-bit Bluetooth-assigned Company > Identifier of the > + vendor as defined by Bluetooth SIG > + > +Properties: > + uint8 Index [read-only] > + > + Element index. It is required that the > application follows > + sequential numbering scheme for the > elements, starting with 0. > + > + array{uint16} Models [read-only] > + > + An array of SIG Model Identifiers. The array > may be empty. > + > + array{(uint16, uint16)} VendorModels [read-only] > + > + An array of pairs (vendor, model ID): > + > + vendor is a 16-bit Bluetooth-assigned > Company Identifier > + of the vendor as defined by > Bluetooth SIG > + > + model ID is a 16-bit vendor-assigned > Model Identifier > + > + The array may be empty. > + > + uint16 Location [read-only, optional] > + > + Location descriptor as defined in the GATT > Bluetooth Namespace > + Descriptors section of the Bluetooth SIG > Assigned Numbers > + > + > +Mesh Attention Hierarchy > +======================== > +Service unique name > +Interface org.bluez.mesh.Attention1 > +Object path freely definable > + > +This is an optional interface that implements health attention timer. > + > +Methods: > + void SetTimer(uint8 element_index, uint16 time) > + > + The element_index parameter is the element's index > within the node > + where the health server model is hosted. > + > + The time parameter indicates how many seconds the > attention state > + shall be on. > + > + PossibleErrors: > + org.bluez.mesh.Error.NotSupported > + > + uint16 GetTimer(uint16 element) > + > + The element parameter is the unicast address within > the node > + where the health server model is hosted. > + > + Returns the number of seconds for how long the > attention action > + remains staying on. > + > + PossibleErrors: > + org.bluez.mesh.Error.NotSupported > + > + > +Provisioning Agent Hierarchy > +============================ > +Service unique name > +Interface org.bluez.mesh.ProvisionAgent Interface name will be org.bluez.mesh.ProvisionAgent1 > +Object path freely definable > + > +Methods: > + array{byte} PrivateKey() > + > + This method is called during provisioning if the > Provisioner > + has requested Out-Of-Band ECC key exchange. The > Private key > + is returned to the Daemon, and the Public Key is > delivered to > + the remote Provisioner using a method that does not > involve > + the Bluetooth Mesh system. The Private Key > returned must be > + 32 octets in size, or the Provisioning procedure will > fail > + and be canceled. > + > + This function will only be called if the Provisioner has > + requested pre-determined keys to be exchanged > Out-of-Band, > + and the local role is Unprovisioned device. > + > + array{byte} PublicKey() > + > + This method is called during provisioning if the local > device > + is the Provisioner, and is requestng Out-Of-Band ECC > key > + exchange. The Public key is returned to the Daemon > + that is the matched pair of the Private key of the > remote > + device. The Public Key returned must be 64 octets in > + size, or the Provisioning procedure will fail and be > canceled. > + > + This function will only be called if the Provisioner has > + requested pre-determined keys to be exchanged > Out-of-Band, > + and the local role is Provisioner. > + > + void DisplayString(string display) > + This method is called when the Daemon has > something important > + for the Agent to Display, but does not require any > additional > + input locally. For instance: "Enter "ABCDE" on remote > device". > + > + void DisplayNumeric(uint8 type, uint32 number) > + > + This method is called when the Daemon has > something important > + for the Agent to Display, but does not require any > additional > + input locally. For instance: "Enter 149264 on remote > device". > + > + The type parameter indicates the display method. An > enumeration > + of "Blink", "Beep", "Vibrate", or "OutNumeric". > + > + The number parameter is the specific value > represented by > + the Prompt. > + > + uint32 PromptNumeric(uint8 type) > + > + This method is called when the Daemon has requires > the user to > + enter a 1-9 digit decimal value. > + > + The type parameter indicates the input method. An > enumeration > + of "Push", "Twist", or "InNumeric". > + > + This agent should prompt the user for specific input. > For instance: > + "Enter value being displayed by remote device". > + > + array{byte} PromptStatic(uint8 type) > + > + This method is called when the Daemon requires a 16 > octet > + byte array, as an Out-of-Band authentication. > + > + The type parameter indicates the input method. An > enumeration > + of "Static", or "InAlpha". > + > + The Static data returned must be 16 octets in size, or > the > + Provisioning procedure will fail and be canceled. If > input is > + an InAlpha String, the printable charactors should be > left > + justified, with trailing 0x00 octets filling the remaining > bytes. > + > + void Cancel() > + > + This method gets called by the daemon to cancel any > existing > + Agent Requests. When called, any pending user input > should be > + canceled. > + > + > +Properties: > + array{string} Capabilities [read-only] > + > + An array of strings with the following allowed > values: > + "blink", "beep", "vibrate", "out- > numeric", "out-alpha", > + "push", "twist", "in-numeric", "in- > alpha", "public-oob", > + "static-oob". > + > + > + array{string} OutOfBandInfo [read-only, optional] > + > + Indicates availability of OOB data. > + An array of strings with the following allowed > values: > + "other", "uri", "machine-code-2d", > "bar-code", "nfc", > + "number", "string", "on-box", "in- > box", "on-paper", > + "in-manual", "on-device" > + > + string URI [read-only, optional] > + > + Uniform Resource Identifier points to out-of- > band (OOB) > + information (e.g., a public key) > + > + > +Mesh Provisioner Hierarchy > +========================== > +<TBD> > -- > 2.17.2
