Apertis maintains an instance of Eclipse cloud2edge that can be used to test the IoT images using Eclipse Kanto. The following sections describe how to set up the IoT image’s suite-connector configuration to be able to connect to this instance.

The following sections describe how to set the IoT image’s suite-connector configuration.

Required Information

Various stub values will be seen throughout the commands in this document that will need to be replaced. Any command that needs some values inside to be replaced will have those listed in the paragraph preceding the command.

The following variables need to be set to the credentials used to connect to the Apertis cloud2edge instance (these credentials are not publicly available, contact the Apertis team to request access):

  • $HONO_REGISTRY_USERNAME, $HONO_REGISTRY_PASSWORD: The username and password for Hono’s device registry.
  • $DITTO_USERNAME, $DITTO_PASSWORD: The username and password for Ditto.

The following variables need to be set to unique values for each individual device registration:

  • $DEVICE_ID: The identifier for the device, in the format NAMESPACE:NAME, where NAMESPACE is some unique identifying namespace for the device. In order to avoid conflicts, you are advised to use a non-trivial, hard-unique device identifier.
  • $AUTH_ID: The device’s authentication identifier (essentially a username) used to connect to Hono. This value is specific to a device and need not be globally unique, but for simplicity, feel free to reuse the device ID (note that : is not valid here and should be replaced with another character, such as _).
  • $PASSWORD: The device’s password used to connect to Hono. This should be a reasonably long, secure password, preferably generated via a secure password generation tool.

Device Registration

Registration is typically done outside of the IoT device.

You can register a new device $DEVICE_ID via the following command (set $HONO_REGISTRY_USERNAME, $HONO_REGISTRY_PASSWORD, and $DEVICE_ID):

1

$ curl -X POST -u "$HONO_REGISTRY_USERNAME:$HONO_REGISTRY_PASSWORD" "https://hono-registry.apertis.dev/v1/devices/dev.apertis/$DEVICE_ID"

After this, login credentials can be assigned to the device (set $HONO_REGISTRY_USERNAME, $HONO_REGISTRY_PASSWORD, $DEVICE_ID, $AUTH_ID, and $PASSWORD):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

$ curl -X PUT -u "$HONO_REGISTRY_USERNAME:$HONO_REGISTRY_PASSWORD" -H 'Content-Type: application/json' -d@- "https://hono-registry.apertis.dev/v1/credentials/dev.apertis/$DEVICE_ID" <<EOF
[
    {
        "type": "hashed-password",
        "auth-id": "$AUTH_ID",
        "secrets": [
            {
                "pwd-plain": "$PASSWORD"
            }
        ]
    }
]
EOF

Next, an Eclipse Ditto thing digital twin should be created for the device (set $DITTO_USERNAME, $DITTO_PASSWORD, and $DEVICE_ID):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

$ curl -X PUT -u "$DITTO_USERNAME:$DITTO_PASSWORD" -H 'Content-Type: application/json' -d@- "https://ditto.apertis.dev/api/2/things/$DEVICE_ID" <<EOF
{
    "_policy": {
        "entries": {
            "DEFAULT": {
                "subjects": {
                    "nginx:ditto": {
                        "type": "Ditto user authenticated via nginx"
                    }
                },
                "resources": {
                    "thing:/": {
                        "grant": ["READ", "WRITE"],
                        "revoke": []
                    },
                    "policy:/": {
                        "grant": ["READ", "WRITE"],
                        "revoke": []
                    },
                    "message:/": {
                        "grant": ["READ", "WRITE"],
                        "revoke": []
                    }
                }
            },
            "HONO": {
                "subjects": {
                    "pre-authenticated:hono-connection": {
                        "type": "Connection to Eclipse Hono"
                    }
                },
                "resources": {
                    "thing:/": {
                        "grant": ["READ", "WRITE"],
                        "revoke": []
                    },
                    "message:/": {
                        "grant": ["READ", "WRITE"],
                        "revoke": []
                    }
                }
            }
        }
    },
    "attributes": {
        "location": "Germany"
    },
    "features": {
        "temperature": {
            "properties": {
                "value": null
            }
        },
        "humidity": {
            "properties": {
                "value": null
            }
        }
    }
}
EOF

In this example, digital twin is registered with the attributes location: Germany and the temperature and humidity features. (Note that the _policy section should remain untouched!)

Once your device is registered, you are ready to configure the IoT image on the device.

Configure the IoT Image

The configuration to connect to the server needs to be written in the /etc/suite-connector/config.json file and can be created via the following command (set $DEVICE_ID, $AUTH_ID, and $PASSWORD):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

$ sudo tee /etc/suite-connector/config.json >/dev/null <<EOF
{
    "cacert": "/etc/suite-connector/apertis.crt",
    "logFile": "/var/log/suite-connector/suite-connector.log",
    "address": "mqtts://hono.apertis.dev:8883",
    "tenantId": "dev.apertis",
    "deviceId": "$DEVICE_ID",
    "authId": "$AUTH_ID",
    "password": "$PASSWORD"
}
EOF

This setup assumes the SSL certificate for Apertis’s cloud2edge is located at /etc/suite-connector/apertis.crt. In order to obtain it, run:

1
2
3

$ openssl s_client -connect hono.apertis.dev:443 -showcerts </dev/null \
    | openssl x509 -outform PEM \
    | sudo tee /etc/suite-connector/apertis.crt >/dev/null

Starting the Service

The suite-connector service can now be enabled and started with:

1

$ sudo systemctl enable --now suite-connector.service

Device Deletion

After you’re done with a device, you can delete it and its digital twin via the following commands:

1
2

$ curl -X DELETE -u "$DITTO_USERNAME:$DITTO_PASSWORD" "https://ditto.apertis.dev/api/2/things/$DEVICE_ID"
$ curl -X DELETE -u "$HONO_REGISTRY_USERNAME:$HONO_REGISTRY_PASSWORD" "https://hono-registry.apertis.dev/v1/devices/dev.apertis/$DEVICE_ID"