Provide How-to guide for the Kanto Local Digital Twins (#155)

---------

Signed-off-by: Antonia Avramova <[email protected]>

quickstart/hono_commands_ldt.py

@@ -0,0 +1,83 @@
+# Copyright (c) 2024 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Eclipse Public License 2.0 which is available at
+# https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+# which is available at https://www.apache.org/licenses/LICENSE-2.0.
+#
+# SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+
+import getopt
+import json
+import os
+import signal
+import sys
+import time
+import uuid
+from string import Template
+import paho.mqtt.client as mqtt
+
+retrieve_things_template = Template("""
+{
+    "topic": "_/_/things/twin/commands/retrieve",
+    "headers": {
+        "correlation-id": "$correlation_id",
+        "reply-to": "command/$tenant_id",
+        "response-required": true
+    },
+    "path": "/",
+    "value": {
+		"thingIds": [
+			"$namespace:$name",
+			"$namespace:$name:edge:containers"
+		]
+	}
+}
+""")
+
+class MQTTClient(mqtt.Client):
+
+    def on_connect(self, mqttc, obj, flags, rc):
+        print('[client connected]')
+        self.subscribe("command//+/req/#")
+
+    def on_message(self, mqttc, obj, msg):
+        print('[got response]')
+        payload = str(msg.payload.decode("utf-8"))
+        print(json.dumps(json.loads(payload), indent=2))
+
+    def run(self):
+        self.connect("localhost")
+        self.loop_start()
+        time.sleep(2)
+        namespaced_id = device_id.split(':', 1)
+        payload = retrieve_things_template.substitute(
+            namespace=namespaced_id[0], name=namespaced_id[1],
+            tenant_id=tenant_id, correlation_id=str(uuid.uuid4()))
+        pub_topic = 'event/{}/{}'.format(tenant_id, device_id)
+        self.publish(pub_topic, payload)
+        time.sleep(1)
+        self.loop_stop()
+
+# Parse command line args
+options, reminder = getopt.getopt(sys.argv[1:], 't:d:')
+opts_dict = dict(options)
+tenant_id = opts_dict.get('-t') or os.environ["TENANT"]
+device_id = opts_dict.get('-d') or os.environ["DEVICE_ID"]
+
+uri = 'localhost'
+print('[starting] demo local digital twins app for tenant [{}], device [{}] at [{}]'.format(tenant_id, device_id, uri))
+
+def handler(signum, frame):
+    print('[stopping] demo local digital twins app for tenant [{}], device [{}] at [{}]'.format(tenant_id, device_id, uri))
+    mqttc.loop_stop()
+    print('[stopped]')
+    exit(0)
+
+signal.signal(signal.SIGINT, handler)
+mqttc = MQTTClient()
+mqttc.run()
+print('[stopped] demo local digital twins app for tenant [{}], device [{}] at [{}]'.format(tenant_id, device_id, uri))

quickstart/requirements.txt

@@ -11,3 +11,4 @@
 # SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 
 python-qpid-proton==0.36.0
+paho-mqtt==1.6.1

web/site/content/docs/how-to-guides/offline-edge-device.md

@@ -0,0 +1,91 @@
+---
+title: "Offline explore edge device"
+type: docs
+description: >
+    Offline receive the structure of your edge device.
+weight: 6
+---
+
+By following the steps below, you will get the structure of the edge digital twins with all its features and properties using Eclipse Kanto.
+A simple Eclipse Hono northbound business application written in Python is provided to display the things' and their features' structure.
+
+### Before you begin
+
+To ensure that your edge device is capable to execute the steps in this guide, you need:
+
+* If you don't have an installed and running Eclipse Kanto on your edge device,
+  follow {{% relrefn "install" %}} Install Eclipse Kanto {{% /relrefn %}}
+
+* If you don't have a connected Eclipse Kanto to Eclipse Hono sandbox,
+  follow {{% relrefn "hono" %}} Explore via Eclipse Hono {{% /relrefn %}}
+
+* Stop `suite-connector.service`. The local digital twins service is a replacement for the suite connector service, that is why either one of the services must be running.
+
+  ```shell
+  sudo systemctl stop suite-connector.service
+  ```
+
+* The {{% refn "https://github.com/eclipse-kanto/kanto/blob/main/quickstart/hono_commands_ldt.py" %}} offline explore application {{% /refn %}}
+
+  Navigate to the `quickstart` folder where the resources from the {{% relrefn "hono" %}} Explore via Eclipse Hono  {{% /relrefn %}} guide are located and execute the following script:
+
+  ```shell
+  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_ldt.py
+  ```
+
+### Configure Local digital twins
+
+Open file `/etc/suite-connector/config.json`, copy `tenantId`, `deviceId`, `authId` and `password`.
+```json
+{
+    ...
+    "tenantId": "demo",
+    "deviceId": "demo:device",
+    "authId": "demo_device",
+    "password": "secret"
+    ...
+}
+```
+The local digital twins service uses the `/etc/local-digital-twins/config.json` to acquire all the remote communication, identification and
+authentication data to establish the remote connection. Update the configuration as shown below and
+replace `tenantId`, `deviceId`, `authId` and `password` with the settings that you copied in the previous step.
+
+```json
+  {
+    "logFile": "/var/log/local-digital-twins/local-digital-twins.log",
+    "caCert": "/etc/local-digital-twins/iothub.crt",
+    "thingsDb": "/var/lib/local-digital-twins/thing.db",
+    "tenantId": "demo",
+    "deviceId": "demo:device",
+    "authId": "demo_device",
+    "password": "secret"
+  }
+```
+
+Save the configuration and start the local digital twins service using the following command:
+
+```shell
+sudo systemctl start local-digital-twins.service
+```
+
+### Receive the structure of the edge device
+
+Now we are ready to request the structure of the edge digital twins via executing the offline explore application that requires the local digital twins tenant (`-t`) and the device identifier (`-d`):
+
+```shell
+python3 hono_commands_ldt.py -t demo -d demo:device
+```
+
+### Verify
+
+On the shell there will be output of the structure of the edge digital twins with all its features and properties. Things with the following identifiers will be presented:
+* demo:device
+* demo:device:edge:containers
+
+### Clean up
+
+Stop the local digital twins service and start suite connector service by executing:
+```shell
+sudo systemctl stop local-digital-twins.service && \
+sudo systemctl restart suite-connector.service
+```