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:   =?UTF-8?q?Micha=C5=82=20Lowas-Rzechonek?= 
        <michal.lowas-rzechonek@silvair.com>
To:     linux-bluetooth@vger.kernel.org
Cc:     Jakub Witowski <jakub.witowski@silvair.com>
Subject: [PATCH BlueZ v5 1/4] mesh: Add ImportLocalNode API documentation
Date:   Wed, 17 Jul 2019 10:36:47 +0200
Message-Id: <20190717083650.26346-2-michal.lowas-rzechonek@silvair.com>
In-Reply-To: <20190717083650.26346-1-michal.lowas-rzechonek@silvair.com>
References: <20190717083650.26346-1-michal.lowas-rzechonek@silvair.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Sender: linux-bluetooth-owner@vger.kernel.org
Precedence: bulk

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)
 
 		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 */
+}
-- 
2.19.1