DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org A43A620671
From:   "Gix, Brian" <brian.gix@intel.com>
To:     "Stotland, Inga" <inga.stotland@intel.com>,
        "linux-bluetooth@vger.kernel.org" <linux-bluetooth@vger.kernel.org>
CC:     "marcel@holtmann.org" <marcel@holtmann.org>,
        "johan.hedberg@gmail.com" <johan.hedberg@gmail.com>,
        "luiz.dentz@gmail.com" <luiz.dentz@gmail.com>,
        "Stotland, Inga" <inga.stotland@intel.com>
Subject: RE: [PATCH BlueZ v4] doc: Initial Bluetooth Mesh API
Thread-Topic: [PATCH BlueZ v4] doc: Initial Bluetooth Mesh API
Thread-Index: AQHUgKLDA2d0U+LsxUO15qKQJ4stpKVauF9A
Date:   Wed, 21 Nov 2018 21:01:24 +0000
Message-ID: <DEBB0CAA2616974FAE35E4B560B9A4375C136C43@ORSMSX103.amr.corp.intel.com>
References: <20181120072905.26306-1-inga.stotland@intel.com>
In-Reply-To: <20181120072905.26306-1-inga.stotland@intel.com>
Accept-Language: en-US
Content-Language: en-US
dlp-product: dlpe-windows
dlp-version: 11.0.400.15
dlp-reaction: no-action
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 8BIT
MIME-Version: 1.0
Sender: linux-bluetooth-owner@vger.kernel.org
Precedence: bulk

Hi Inga,

I approve of this API, and will be applying it shortly with the noted typo fix.

> -----Original Message-----
> From: linux-bluetooth-owner@vger.kernel.org [mailto:linux-bluetooth-
> owner@vger.kernel.org] On Behalf Of Inga Stotland
> Sent: Monday, November 19, 2018 11:29 PM
> To: linux-bluetooth@vger.kernel.org
> Cc: marcel@holtmann.org; johan.hedberg@gmail.com;
> luiz.dentz@gmail.com; Gix, Brian <brian.gix@intel.com>; Stotland, Inga
> <inga.stotland@intel.com>
> 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