Received-SPF: pass (google.com: best guess record for domain of linux-bluetooth-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
From:   Jakub Witowski <jakub.witowski@silvair.com>
To:     linux-bluetooth@vger.kernel.org
Cc:     Inga Stotland <inga.stotland@intel.com>
Subject: [PATCH BlueZ v3 1/3] mesh: Add ImportLocalNode api documentation
Date:   Fri,  5 Jul 2019 17:22:14 +0200
Message-Id: <20190705152216.27766-1-jakub.witowski@silvair.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Sender: linux-bluetooth-owner@vger.kernel.org
Precedence: bulk

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 data_type parameter defines the import_data type. Supported
+		data_type parameters:
+			- “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 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>
+Mesh Node Configuration Examples
+================================
+Example of Json format for ImportLocalNode():
+
+	Import simplified node operation:
+	{
+		"IVindex":0,
+		"IVupdate":0,
+		"unicastAddress":"0012",
+		"deviceKey":"7daa45cd1e9e11a4b86eeef7d01efa11",
+		"sequenceNumber":15
+		"netKeys":[
+		{
+			"index":"0000",
+			"key":"2ddfef86d67144c394428ea3078f86f9",
+			"keyRefresh":0
+		}],
+	}
+
+	Import full node operation:
+	{
+		"cid":"fee5",
+		"pid":"0042",
+		"vid":"0001",
+		"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",
+		"deviceKey":"56325fd145f3d5eee1b82136dc3e1454",
+		"netKeys":[
+		{
+			"index":"0000",
+			"key":"2ddfef86d67144c394428ea3078f86f9",
+			"keyRefresh":0
+		}],
+		"appKeys":[
+		{
+			"index":"0000",
+			"boundNetKey":"0000",
+			"key":"43886b02ca4343beaae26dc4b6773ba4"
+		}],
+		"sequenceNumber":15
+	}
-- 
2.20.1