From 2ed2c1d4bc9574d200828259d058a9a90ca97f01 Mon Sep 17 00:00:00 2001 From: Trifonova Antonia Date: Tue, 12 Jul 2022 14:31:00 +0300 Subject: [PATCH 1/3] Provide Reference guide for the Kanto Suite Connector - provide information relevant to available configurations per a Suite Connector instance - add an example how to use this configuration - add this reference guide in Eclipse Kanto documentation Signed-off-by: Trifonova Antonia --- .../docs/references/suite-connector-config.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 web/site/content/docs/references/suite-connector-config.md diff --git a/web/site/content/docs/references/suite-connector-config.md b/web/site/content/docs/references/suite-connector-config.md new file mode 100644 index 00000000..5591f92c --- /dev/null +++ b/web/site/content/docs/references/suite-connector-config.md @@ -0,0 +1,98 @@ +--- +title: "Suite connector configuration" +type: docs +description: > + Customize the remote connectivity. +weight: 1 +--- + +### Properties + +To control all aspects of the suite connector behavior. + +| Property | Type | Default | Description | +| - | - | - | - | +| provisioningFile | string ​| provisioning.json | Path to the provisioning file, if {{% relrefn "docs/getting-started/dmp" %}}Bosch IoT Device Management{{% /relrefn %}} is in use | +| **Remote connectivity** | | | | +| address | string | mqtts://mqtt.bosch-iot-hub.com:8883 | Address of the MQTT endpoint that the suite connector will connect for the remote communication, the format is: `scheme://host:port` | +| deviceId | string | | Device unique identifier | +| authId | string | | Authentication unique identifier that is a part of the credentials | +| tenantId | string | | Tenant unique identifier that the device belongs to | +| password | string | | Password that is a part of the credentials | +| clientId | string | | MQTT client unique identifier | +| policyId | string | | Policy unique identifier of the digital twin | +| **Remote connectivity - TLS** | | | | +| cacert | string | iothub.crt | PEM encoded CA certificates file | +| cert | string | | PEM encoded certificate file to authenticate to the MQTT endpoint | +| key | string | | PEM encoded unencrypted private key file to authenticate to the MQTT endpoint | +| deviceIdPattern | string | | Pattern to generate the device identifier, `{{subject-dn}}` and `{{subject-cn}}` placeholders can be part of it | +| **Remote connectivity - TLS over TPM** | | | | +| tpmDevice | string | | Path to the device file or the unix socket to access the TPM 2.0 | +| tpmHandle | int | | TPM 2.0 storage root key handle, the type is unsigned 64-bit integer | +| tpmKeyPub | string | | File path to the public part of the TPM 2.0 key | +| tpmKey | string | | File path to the private part of the TPM 2.0 key | +| **Local connectivity** | | | | +| localAddress | string | tcp://localhost:1883 | Address of the MQTT server/broker that the suite connector will connect for the local communication, the format is: `scheme://host:port` | +| localUsername | string | | Username that is a part of the credentials | +| localPassword | string | | Password that is a part of the credentials | +| **Logging** | | | | +| logFile | string | log/suite-connector.log | Path to the file where log messages are written | +| logLevel | string | INFO | All log messages at this or higher level will be logged, the log levels in descending order are: ERROR, WARN, INFO, DEBUG and TRACE | +| logFileCount | int | 5 | Log file maximum rotations count | +| logFileMaxAge | int | 28 | Log file rotations maximum age in days, use 0 to not remove old log files | +| logFileSize | int | 2 | Log file size in MB before it gets rotated | + +### Example + +The minimal required configuration to connect the publicly available +{{% refn "https://www.eclipse.org/hono/sandbox/" %}}Eclipse Hono sandbox{{% /refn %}}. + +```json +{ + "address":"hono.eclipseprojects.io:1883", + "cacert": "/etc/suite-connector/iothub.crt", + "tenantId": "org.eclipse.kanto", + "deviceId": "org.eclipse.kanto:exampleDevice", + "authId": "org.eclipse.kanto_example", + "password": "secret", + "logFile": "/var/log/suite-connector/suite-connector.log" +} +``` + +### Template + +The configuration can be further adjusted according to the use case. +The following template illustrates all possible properties with their default values. + +{{% warn %}} +Be aware that some combinations may be incompatible +{{% /warn %}} + +```json +{ + "provisioningFile": "provisioning.json", + "address": "mqtts://mqtt.bosch-iot-hub.com:8883", + "deviceId": "", + "authId": "", + "tenantId": "", + "password": "", + "clientId": "", + "policyId": "", + "cacert": "iothub.crt", + "cert": "", + "key": "", + "deviceIdPattern": "", + "tpmDevice": "", + "tpmHandle": 0, + "tpmKeyPub": "", + "tpmKey": "", + "localAddress": "tcp://localhost:1883", + "localUsername": "", + "localPassword": "", + "logFile": "log/suite-connector.log", + "logLevel": "INFO", + "logFileCount": 5, + "logFileMaxAge": 28, + "logFileSize": 2 +} +``` From ac658b9d81a741469101f62eafcde1764e877bda Mon Sep 17 00:00:00 2001 From: Trifonova Antonia Date: Wed, 13 Jul 2022 13:47:31 +0300 Subject: [PATCH 2/3] Provide Reference guide for the Kanto Suite Connector - update the shortcode relrefn to return the relative path by provided page name - update the Suite Connector reference to use the shortcode only with page name Signed-off-by: Trifonova Antonia --- web/site/content/docs/references/suite-connector-config.md | 2 +- web/site/layouts/shortcodes/relrefn.html | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/web/site/content/docs/references/suite-connector-config.md b/web/site/content/docs/references/suite-connector-config.md index 5591f92c..e81c5d96 100644 --- a/web/site/content/docs/references/suite-connector-config.md +++ b/web/site/content/docs/references/suite-connector-config.md @@ -12,7 +12,7 @@ To control all aspects of the suite connector behavior. | Property | Type | Default | Description | | - | - | - | - | -| provisioningFile | string ​| provisioning.json | Path to the provisioning file, if {{% relrefn "docs/getting-started/dmp" %}}Bosch IoT Device Management{{% /relrefn %}} is in use | +| provisioningFile | string ​| provisioning.json | Path to the provisioning file, if {{% relrefn "dmp" %}}Bosch IoT Device Management{{% /relrefn %}} is in use | | **Remote connectivity** | | | | | address | string | mqtts://mqtt.bosch-iot-hub.com:8883 | Address of the MQTT endpoint that the suite connector will connect for the remote communication, the format is: `scheme://host:port` | | deviceId | string | | Device unique identifier | diff --git a/web/site/layouts/shortcodes/relrefn.html b/web/site/layouts/shortcodes/relrefn.html index fd7383c8..949b7e0e 100644 --- a/web/site/layouts/shortcodes/relrefn.html +++ b/web/site/layouts/shortcodes/relrefn.html @@ -1,4 +1,3 @@ {{ $_hugo_config := `{ "version": 1 }` }} -{{ $ref := index .Params 0 }} -{{ $page := .Page.GetPage $ref }} -{{- "" -}}{{if eq .Page.File.Ext "md"}}{{.Inner|markdownify}}{{else}}{{.Inner|htmlUnescape|safeHTML}}{{end}}{{- "" -}} +{{ $relreflink := relref . (index .Params 0) }} +{{- "" -}}{{if eq .Page.File.Ext "md"}}{{.Inner|markdownify}}{{else}}{{.Inner|htmlUnescape|safeHTML}}{{end}}{{- "" -}} \ No newline at end of file From 489969ee5d7386fa335128a7fde9fbeb0b382ec2 Mon Sep 17 00:00:00 2001 From: Trifonova Antonia Date: Wed, 13 Jul 2022 17:19:11 +0300 Subject: [PATCH 3/3] Provide Reference guide for the Kanto Suite Connector Simplify the shortcode. The usage of the variable is not necessary. Signed-off-by: Trifonova Antonia --- web/site/layouts/shortcodes/relrefn.html | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/web/site/layouts/shortcodes/relrefn.html b/web/site/layouts/shortcodes/relrefn.html index 949b7e0e..78281ab4 100644 --- a/web/site/layouts/shortcodes/relrefn.html +++ b/web/site/layouts/shortcodes/relrefn.html @@ -1,3 +1,2 @@ {{ $_hugo_config := `{ "version": 1 }` }} -{{ $relreflink := relref . (index .Params 0) }} -{{- "" -}}{{if eq .Page.File.Ext "md"}}{{.Inner|markdownify}}{{else}}{{.Inner|htmlUnescape|safeHTML}}{{end}}{{- "" -}} \ No newline at end of file +{{- "" -}}{{if eq .Page.File.Ext "md"}}{{.Inner|markdownify}}{{else}}{{.Inner|htmlUnescape|safeHTML}}{{end}}{{- "" -}} \ No newline at end of file