Re: [PATCH BlueZ v5 1/4] mesh: Add ImportLocalNode API documentation

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

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

Hi Mical, Jakub, Brian...


On Wed, 2019-07-17 at 10:36 +0200, Michał Lowas-Rzechonek wrote:
> From: Jakub Witowski <jakub.witowski@silvair.com>
> 
> This updates the mesh-api.txt with new ImportLocalNode() API.
> ---
>  doc/mesh-api.txt | 52 ++++++++++++++++++++++++++++++++++++++------
> ----
>  1 file changed, 41 insertions(+), 11 deletions(-)
> 
> diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt
> index 0ac2fdfd1..7c2a1fafa 100644
> --- a/doc/mesh-api.txt
> +++ b/doc/mesh-api.txt
> @@ -151,16 +151,31 @@ 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)


I apologize for the backtracking, but I would like to revisit this API.

I feel like having "object app_root" is unnecessary and also, creates
some gnarly pathways within the code.

What exactly is the problem for requiring the composition data to be
part of the import_data? It's just weird to say "oh, it may be there or
it may be not".

Getting rid of the app_root and mandating the composition to be part of
the import_data allows:

1) Avoid checking whether this is a "full" configuration or the
"minimal" one

2) Efficiently re-use the existing code:
Adding an API call like this one may be sufficient

mesh_config_import(const char *cfg_dir,
                   const uint8_t uuid[16],
                   const uint8 *import_data, <import__len>?,
                   mesh_config_node_func_t cb,
                   void *user_data)

We can just re-factor the code that parses and populates a single node
from the stored configuration. user_data may contain whatever we need
to preserve in order to respond to d-bus call.

>  
>  		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.
> +
> +		The import_data parameter contains a representation of
> a
> +		provisioned node. Format of this representation depends
> on
> +		value of data_type parameter.
> +
> +		Allowed data_type values are: "json".
> +
> +		When data_type is "json", bluetooth-meshd daemon treats
> +		import_data is a JSON document following <TBD> schema.
> See the
> +		examples at the end of this document.
> +
> +		The import_data parameter can contain either minimal,
> or
> +		complete representation of a provisioned node.
> +
> +		When a complete representation is provided, it is
> validated
> +		against composition data provided by the application.
>  
>  		The returned token must be preserved by the application
> in
>  		order to authenticate itself to the mesh daemon and
> attach to
> @@ -173,8 +188,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
> @@ -1064,6 +1079,21 @@ Properties:
>  		Uniform Resource Identifier points to out-of-band (OOB)
>  		information (e.g., a public key)
>  
> -Mesh Node Configuration Schema
> -==============================
> -<TBD>
> +Mesh Node Configuration Examples
> +================================
> +Minimal JSON representation for ImportLocalNode():
> +
> +{
> +	"IVindex":0,
> +	"IVupdate":0,
> +	"unicastAddress":"0012",
> +	"deviceKey":"7daa45cd1e9e11a4b86eeef7d01efa11",
> +	"netKeys":[
> +		{
> +			"index":"0000",
> +			"key":"2ddfef86d67144c394428ea3078f86f9",
> +			"keyRefresh":0
> +		}
> +	],
> +	"sequenceNumber":15  /* optional */
> +}

Regards, Inga

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