From e47e5c61ebcc56cd7728225d01ec4768a42ca3ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Du=C5=A1an=20Borov=C4=8Danin?= Date: Thu, 20 Jun 2019 18:28:25 +0200 Subject: [PATCH] Update docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Dušan Borovčanin --- bootstrap/swagger.yml | 2 +- docs/bootstrap.md | 20 ++++++++++++-------- things/swagger.yaml | 11 ++++++++++- 3 files changed, 23 insertions(+), 10 deletions(-) diff --git a/bootstrap/swagger.yml b/bootstrap/swagger.yml index d6eb0d5a63..6541835332 100644 --- a/bootstrap/swagger.yml +++ b/bootstrap/swagger.yml @@ -288,7 +288,7 @@ parameters: required: true ConfigId: name: configId - description: Unique Config identifier. + description: Unique Config identifier. It's the ID of the corresponding Thing. in: path type: string required: true diff --git a/docs/bootstrap.md b/docs/bootstrap.md index d7bd47a3ba..2f16661ead 100644 --- a/docs/bootstrap.md +++ b/docs/bootstrap.md @@ -12,7 +12,7 @@ Bootstrapping procedure is the following: ![Configure device](img/bootstrap/1.png) *1) Configure device with Bootstrap service URL, an external key and external ID* - + > ![Provision Mainflux channels](img/bootstrap/2.png) *Optionally create Mainflux channels if they don't exist* @@ -30,15 +30,16 @@ Bootstrapping procedure is the following: ### Configuration -The configuration of Mainflux thing consists of two major parts: +The configuration of Mainflux thing consists of three major parts: - The list of Mainflux channels the thing is connected to - Custom configuration related to the specific thing +- Thing key and certificate data related to that thing Also, the configuration contains an external ID and external key, which will be explained later. In order to enable the thing to start bootstrapping process, the user needs to upload a valid configuration for that specific thing. This can be done using the following HTTP request: -``` +```bash curl -s -S -i -X POST -H "Authorization: " -H "Content-Type: application/json" http://localhost:8200/things/configs -d '{ "external_id":"09:6:0:sb:sa", "thing_id": "1b9b8fae-9035-4969-a240-7fe5bdc0ed28", @@ -50,11 +51,14 @@ curl -s -S -i -X POST -H "Authorization: " -H "Content-Type: applica "ff13ca9c-7322-4c28-a25c-4fe5c7b753fc", "c3642289-501d-4974-82f2-ecccc71b2d82" ], - "content": "config..." + "content": "config...", + "client_cert": "PEM cert", + "client_key": "PEM client cert key", + "ca_cert": "PEM CA cert" }' ``` -In this example, `channels` field represents the list of Mainflux channel IDs the thing is connected to. These channels need to be provisioned before the configuration is uploaded. Field `content` represents custom configuration. This custom configuration contains parameters that can be used to set up the thing. It can also be empty if no additional set up is needed. Field `name` is human readable name and `thing_id` is an ID of the Mainflux thing. This field is not required. If `thing_id` is empty, corresponding Mainflux thing will be created implicitly and its ID will be sent as a part of `Location` header of the response. +In this example, `channels` field represents the list of Mainflux channel IDs the thing is connected to. These channels need to be provisioned before the configuration is uploaded. Field `content` represents custom configuration. This custom configuration contains parameters that can be used to set up the thing. It can also be empty if no additional set up is needed. Field `name` is human readable name and `thing_id` is an ID of the Mainflux thing. This field is not required. If `thing_id` is empty, corresponding Mainflux thing will be created implicitly and its ID will be sent as a part of `Location` header of the response. Fields `client_cert`, `client_key`, and `ca_cert` represent PEM or base64-encoded DER client certificate, client certificate key, and trusted CA, respectively. There are two more fields: `external_id` and `external_key`. External ID represents an ID of the device that corresponds to the given thing. For example, this can be a MAC address or the serial number of the device. The external key represents the device key. This is the secret key that's safely stored on the device and it is used to authorize the thing during the bootstrapping process. Please note that external ID and external key and Mainflux ID and Mainflux key are _completely different concepts_. External id and key are only used to authenticate a device that corresponds to the specific Mainflux thing during the bootstrapping procedure. @@ -62,13 +66,13 @@ There are two more fields: `external_id` and `external_key`. External ID represe Currently, the bootstrapping procedure is executed over the HTTP protocol. Bootstrapping is nothing else but fetching and applying the configuration that corresponds to the given Mainflux thing. In order to fetch the configuration, _the thing_ needs to send a bootstrapping request: -``` +```bash curl -s -S -i -H "Authorization: " http://localhost:8200/things/bootstrap/ ``` The response body should look something like: -``` +```json { "mainflux_id":"7c9df5eb-d06b-4402-8c1a-df476e4394c8", "mainflux_key":"86a4f870-eba4-46a0-bef9-d94db2b64392", @@ -99,7 +103,7 @@ The response consists of an ID and key of the Mainflux thing, the list of channe Uploading configuration does not automatically connect thing to the given list of channels. In order to connect the thing to the channels, user needs to send the following HTTP request: -``` +```bash curl -s -S -i -X PUT -H "Authorization: " -H "Content-Type: application/json" http://localhost:8200/things/state/ -d '{"state": 1}' ``` diff --git a/things/swagger.yaml b/things/swagger.yaml index 403ac6a92e..98b70a853a 100644 --- a/things/swagger.yaml +++ b/things/swagger.yaml @@ -52,6 +52,7 @@ paths: - $ref: "#/parameters/Authorization" - $ref: "#/parameters/Limit" - $ref: "#/parameters/Offset" + - $ref: "#/parameters/Name" responses: 200: description: Data retrieved. @@ -229,6 +230,7 @@ paths: - $ref: "#/parameters/Authorization" - $ref: "#/parameters/Limit" - $ref: "#/parameters/Offset" + - $ref: "#/parameters/Name" responses: 200: description: Data retrieved. @@ -383,7 +385,7 @@ parameters: name: chanId description: Unique channel identifier. in: path - type: integera + type: integer minimum: 1 required: true ThingId: @@ -410,6 +412,13 @@ parameters: default: 0 minimum: 0 required: false + Name: + name: name + description: Name filter. Filtering is performed as a case-insensitive partial match. + in: query + type: string + minimum: 0 + required: false responses: ServiceError: