Re: [PATCH BlueZ v4 1/4] mesh: Add ImportLocalNode api documentation

["Stotland, Inga" <inga.stotland@intel.com>]

[-- Attachment #1: Type: text/plain, Size: 5400 bytes --]

Hi Jakub,

On Tue, 2019-07-09 at 12:15 +0200, Jakub Witowski wrote:
> This updates the mesh-api.txt with new ImportLocalNode() API.
> ---
>  doc/mesh-api.txt | 104 ++++++++++++++++++++++++++++++++++++++++++---
> --
>  1 file changed, 93 insertions(+), 11 deletions(-)
> 
> diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt
> index 893a1a6c0..f2ba164a9 100644
> --- a/doc/mesh-api.txt
> +++ b/doc/mesh-api.txt
> @@ -151,16 +151,36 @@ Methods:
>  			org.bluez.mesh.Error.InvalidArguments
>  			org.bluez.mesh.Error.AlreadyExists,
>  
> -	 uint64 token ImportLocalNode(string json_data)
> +	uint64 token ImportLocalNode(object app_root, array{byte}[16]
> uuid,
> +							string
> data_type, array{byte} import_data)
>  
>  		This method creates a local mesh node based on node
>  		configuration that has been generated outside
> bluetooth-meshd.
>  
> -		The json_data parameter is a full JSON representation
> of a node
> -		configuration file. The format must conform to the
> schema
> -		defined in "Mesh Node Configuration Schema" section.
> Any
> -		included token will be ignored in favor of a locally
> generated
> -		token value.
> +		The app_root parameter is a D-Bus object root path of
> the
> +		application that implements org.bluez.mesh.Application1
> +		interface, and a org.bluez.mesh.Provisioner1 interface.

"the application that implements org.bluez.mesh.Application1 interface"
I don't think that supporting Provisioner1 interface is a requirement?

> +
> +		The data_type parameter defines the import_data type.
> Supported
> +		data_type parameters:

"The following values are supported:"

> +			- “json”
> +
> +		The import_data parameter can be either:
> +			- Simplified representation of node
> configuration with
> +			  provisioning data only
> +			- Full representation of node configuration
> with both
> +			  provisioning and composition data
> +
> +		sequenceNumber parameter int the import_data is
> optional.
> +
> +		The format must conform to the schema defined in
> +		"Mesh Node Configuration Examples" section. Any
> included token will
> +		be ignored in favor of a locally generated token value.
> If
> +		import_data contains composition data (determined by
> the presence of
> +		Elements) it is validated against composition data
> provided by
> +		the application. Otherwise, new node is created based
> on
> +		composition data provided by the application using
> provisioning data
> +		from import_data parameter.
>  


The description of import_data parameter needs to be re-written.
The above description is too skewed towards JSON format and imo is more
detiled than needed.

we definitely need to mention that the interpretation of the
import_data parameter depends on the value of data_type. Then we can
say that "for the case when data_type has value "json", the import_data
contains a string that describes node configuration in JSOn notation,
following the <TBD> schema. See the examples at the end of this
documents."  



>  		The returned token must be preserved by the application
> in
>  		order to authenticate itself to the mesh daemon and
> attach to
> @@ -173,8 +193,8 @@ Methods:
>  
>  		PossibleErrors:
>  			org.bluez.mesh.Error.InvalidArguments,
> -			org.bluez.mesh.Error.AlreadyExists
> -			org.bluez.mesh.Error.NotFound,
> +			org.bluez.mesh.Error.AlreadyExists,
> +			org.bluez.mesh.Error.NotSupported,
>  			org.bluez.mesh.Error.Failed
>  
>  Mesh Node Hierarchy
> @@ -1061,6 +1081,68 @@ Properties:
>  		Uniform Resource Identifier points to out-of-band (OOB)
>  		information (e.g., a public key)
>  
> -Mesh Node Configuration Schema
> -==============================
> -<TBD>


Line break
> +Mesh Node Configuration Examples
> +================================
> +Example of Json format for ImportLocalNode():


Minimum required configuration:
> +	{
> +		"IVindex":0,
> +		"IVupdate":0,
> +		"unicastAddress":"0012",
> +		"deviceKey":"7daa45cd1e9e11a4b86eeef7d01efa11",
> +		"netKeys":[
		"sequenceNumber":15
No sequence number

> +		{
> +			"index":"0000",
> +			"key":"2ddfef86d67144c394428ea3078f86f9",
> +			"keyRefresh":0
> +		}]
> +	}
> +
> +	Import full node operation:
> +	{
> +		"cid":"fee5",
> +		"crpl":"2710",
> +		"relay":{
> +			"mode":"disabled",
> +			"count":0,
> +			"interval":0
> +		},
> +		"lowPower":"unsupported",
> +		"friend":"unsupported",
> +		"proxy":"unsupported",
> +		"beacon":"disabled",
> +		"defaultTTL":255,
> +		"elements":[
> +		{
> +			"elementIndex":0,
> +			"location":"002a",
> +			"models":[
> +			{
> +				"modelId":"0008",
> +				"bind":[
> +				"0000"]
> +			}]
> +		}],
> +		"IVindex":0,
> +		"IVupdate":0,
> +		"unicastAddress":"0010",
> 
		"token":"bba7c60afaa85fc1",

No token
> +		"deviceKey":"56325fd145f3d5eee1b82136dc3e1454",
> +		"netKeys":[
> +		{
> +			"index":"0000",
> +			"key":"2ddfef86d67144c394428ea3078f86f9",
> +			"keyRefresh":0
> +		}],
> +		"appKeys":[
> +		{
> +			"index":"0000",
> +			"boundNetKey":"0000",
> +			"key":"43886b02ca4343beaae26dc4b6773ba4"
> +		}],
> +		"sequenceNumber":15

no sequence number
> +	}


Actually, I don't like the full configuration exmple. It's not realy
"full". Better to provide a schema. We'll get to the schema in time.


[-- Attachment #2: smime.p7s --]
[-- Type: application/x-pkcs7-signature, Size: 3265 bytes --]