Skip to content

Commit

Permalink
utilize user context component to improve user experience
Browse files Browse the repository at this point in the history 
Signed-off-by: Reuben Miller <[email protected]>
  • Loading branch information
@reubenmiller
reubenmiller committed Jul 17, 2024
1 parent 05ef169 commit 1d8aebe
Show file tree
Hide file tree
Showing 4 changed files with 126 additions and 36 deletions.
27 changes: 22 additions & 5 deletions docs/src/operate/c8y/connect.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,19 @@ tags: [Operate, Cloud]
description: Connecting %%te%% to Cumulocity IoT
---

import UserContext from '@site/src/components/UserContext';
import UserContextForm from '@site/src/components/UserContextForm';

:::tip
#### User Context {#user-context}

You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use %%te%%.

<UserContextForm settings="DEVICE_ID,C8Y_URL,C8Y_USER" />

The user context will be persisted in your web browser's local storage.
:::

To create northbound connection a local bridge shall be established and this can be achieved with `tedge` cli and following commands:

:::note
Expand All @@ -14,10 +27,14 @@ To create northbound connection a local bridge shall be established and this can

Configure required parameters for %%te%% with [`tedge config set`](../../references/cli/tedge-config.md):

<UserContext>

```sh
sudo tedge config set c8y.url example.cumulocity.com
sudo tedge config set c8y.url $C8Y_URL
```

</UserContext>

:::info
If you are unsure which parameters required by the command, simply run the command and it will tell you which parameters are missing.

Expand Down Expand Up @@ -54,13 +71,13 @@ and the command will prompt you for this user's password.
These credentials are used only for this upload and will in no case be stored on the device.
:::

<UserContext>

```sh
sudo tedge cert upload c8y --user "${C8Y_USER}"
sudo tedge cert upload c8y --user "$C8Y_USER"
```

```sh title="Example"
sudo tedge cert upload c8y --user "[email protected]"
```
</UserContext>

## Creating an MQTT bridge between the device and the cloud

Expand Down
33 changes: 29 additions & 4 deletions docs/src/start/connect-azure.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,19 @@ sidebar_position: 3
description: Connect %%te%% to Azure IoT and publish telemetry data
---

import UserContext from '@site/src/components/UserContext';
import UserContextForm from '@site/src/components/UserContextForm';

:::tip
#### User Context {#user-context}

You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use %%te%%.

<UserContextForm settings="DEVICE_ID,AZURE_URL" />

The user context will be persisted in your web browser's local storage.
:::

The very first step to enable %%te%% is to connect your device to the cloud.
* This is a 10 minutes operation to be done only once.
* It establishes a permanent connection from your device to the cloud end-point.
Expand Down Expand Up @@ -35,10 +48,14 @@ This identifier will be used to uniquely identify your devices among others in y
This identifier will be also used as the Common Name (CN) of the certificate.
Indeed, this certificate aims to authenticate that this device is the device with that identity.

<UserContext>

```sh
sudo tedge cert create --device-id my-device
sudo tedge cert create --device-id "$DEVICE_ID"
```

</UserContext>

```text title="Output"
Certificate was successfully created
```
Expand All @@ -51,15 +68,19 @@ You can then check the content of that certificate.
sudo tedge cert show
```

<UserContext>

```text title="Output"
Device certificate: /etc/tedge/device-certs/tedge-certificate.pem
Subject: CN=my-device, O=Thin Edge, OU=Test Device
Issuer: CN=my-device, O=Thin Edge, OU=Test Device
Subject: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device
Issuer: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device
Valid from: Tue, 09 Mar 2021 14:10:30 +0000
Valid up to: Thu, 10 Mar 2022 14:10:30 +0000
Thumbprint: 860218AD0A996004449521E2713C28F67B5EA580
```

</UserContext>

You may notice that the issuer of this certificate is the device itself.
This is a self-signed certificate.
The Thumbprint is the Sha1sum of the certificate. This is required for registering the
Expand Down Expand Up @@ -90,10 +111,14 @@ To connect the device to the Azure IoT Hub, one needs to set the URL/Hostname of

Set the URL/Hostname of your Azure IoT Hub.

<UserContext>

```sh
sudo tedge config set az.url your-iot-hub-name.azure-devices.net
sudo tedge config set az.url $AZURE_URL
```

</UserContext>

The URL/Hostname can be found in the Azure web portal, clicking on the overview section of your IoT Hub.

Set the path to the root certificate if necessary. The default is `/etc/ssl/certs`.
Expand Down
61 changes: 49 additions & 12 deletions docs/src/start/connect-c8y.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,19 @@ sidebar_position: 2
description: Connect %%te%% to Cumulocity IoT and publish telemetry data
---

import UserContext from '@site/src/components/UserContext';
import UserContextForm from '@site/src/components/UserContextForm';

:::tip
#### User Context {#user-context}

You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use %%te%%.

<UserContextForm settings="DEVICE_ID,C8Y_URL,C8Y_USER" />

The user context will be persisted in your web browser's local storage.
:::

The very first step to enable %%te%% is to connect your device to the cloud.
* This is a 10 minutes operation to be done only once.
* It establishes a permanent connection from your device to the cloud end-point.
Expand Down Expand Up @@ -36,10 +49,14 @@ To connect the device to the Cumulocity IoT, one needs to set the URL of your Cu

Set the URL of your Cumulocity IoT tenant.

<UserContext>

```sh
sudo tedge config set c8y.url your-tenant.cumulocity.com
sudo tedge config set c8y.url $C8Y_URL
```

</UserContext>

Set the path to the root certificate if necessary. The default is `/etc/ssl/certs`.

```sh
Expand All @@ -56,17 +73,25 @@ If you are using the Cumulocity Iot [custom domain feature](https://cumulocity.c

For example, below shows setting the HTTP and MQTT endpoints:

<UserContext>

```sh
tedge config set c8y.http "custom.example.com"
tedge config set c8y.http "$C8Y_URL"
tedge config set c8y.mqtt "t12345.cumulocity.com:8883"
```

</UserContext>

:::tip
If you have `curl` and `jq` installed, then you can check if you are using a custom domain by executing the following command. If the response includes a different domain than the url used in the curl command, then you are using a custom domain, and you should use the output to set the `c8y.mqtt` thin-edge.io setting instead.

<UserContext>

```sh
curl custom.example.com/tenant/loginOptions | jq -r '.loginOptions[] | select(.loginRedirectDomain) | .loginRedirectDomain'
curl -sfL https://$C8Y_URL/tenant/loginOptions | jq -r '.loginOptions[] | select(.loginRedirectDomain) | .loginRedirectDomain'
```
</UserContext>

:::


Expand All @@ -84,13 +109,17 @@ This is the certificate chain of the server and not the device's certificate kep
:::

If the Cumulocity server's certificate chain file isn't available locally, it can be downloaded using a web browser or using some other
third-party tools like openssl command as follows (to be adjusted based on your env):
third-party tools like openssl command as follows:

<UserContext>

```sh
openssl s_client -connect <hostname>:<port> < /dev/null 2>/dev/null \
openssl s_client -connect $C8Y_URL:443 < /dev/null 2>/dev/null \
| sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'
```

</UserContext>

## Create the certificate

The `tedge cert create` command creates a self-signed certificate which can be used for testing purpose.
Expand All @@ -100,10 +129,14 @@ This identifier will be used to uniquely identify your devices among others in y
This identifier will be also used as the Common Name (CN) of the certificate.
Indeed, this certificate aims to authenticate that this device is actually the device with that identity.

<UserContext>

```sh
sudo tedge cert create --device-id my-device
sudo tedge cert create --device-id "$DEVICE_ID"
```

</UserContext>

```text title="Output"
Certificate was successfully created
```
Expand All @@ -114,15 +147,19 @@ You can then check the content of that certificate.
sudo tedge cert show
```

<UserContext>

```text title="Output"
Device certificate: /etc/tedge/device-certs/tedge-certificate.pem
Subject: CN=my-device, O=Thin Edge, OU=Test Device
Issuer: CN=my-device, O=Thin Edge, OU=Test Device
Subject: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device
Issuer: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device
Valid from: Tue, 09 Feb 2021 17:16:52 +0000
Valid up to: Tue, 11 May 2021 17:16:52 +0000
Thumbprint: CDBF4EC17AA02829CAC4E4C86ABB82B0FE423D3E
```

</UserContext>

You may notice that the issuer of this certificate is the device itself.
This is a self-signed certificate.
To use a certificate signed by your Certificate Authority,
Expand All @@ -141,13 +178,13 @@ This can be done:
to your tenant "Device Management/Management/Trusted certificates".
* or using the `tedge cert upload c8y` command.

<UserContext>

```sh
sudo tedge cert upload c8y --user "${C8Y_USER}"
sudo tedge cert upload c8y --user "$C8Y_USER"
```

```sh title="Example"
sudo tedge cert upload c8y --user "[email protected]"
```
</UserContext>

### Common errors

Expand Down
41 changes: 26 additions & 15 deletions docs/src/start/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,19 @@ tags: [Getting Started, Cumulocity]
sidebar_position: 1
---

import UserContext from '@site/src/components/UserContext';
import UserContextForm from '@site/src/components/UserContextForm';

:::tip
#### User Context {#user-context}

You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use %%te%%.

<UserContextForm settings="DEVICE_ID,C8Y_URL,C8Y_USER" />

The user context will be persisted in your web browser's local storage.
:::

After following this tutorial you will have an overview of the installation and configuration of %%te%%. As an example, a Raspberry Pi is used. This tutorial explains in small steps to reach the goal of sending data to Cumulocity IoT and performing some additional device management tasks.


Expand Down Expand Up @@ -107,40 +120,39 @@ To connect the device to the Cumulocity IoT it needs to be configured.

This URL is needed to allow the upload of the certificate to the specific tenant and the registration of the device. It can be configured via:

<UserContext>

```sh
sudo tedge config set c8y.url "${YOUR_C8Y_URL}"
sudo tedge config set c8y.url "$C8Y_URL"
```

```sh title="Example"
sudo tedge config set c8y.url "mycompany.cumulocity.com"
```
</UserContext>

### Certificate

%%te%% connects via MQTT protocol using a X.509 certificate for authentication. To do so, a certificate must be trusted by Cumulocity IoT. A certificate is trusted when it is added to the trusted certificates and is in an activated state.

First, we need to create the device certificate locally (If the device certificate is already uploaded, directly via the UI to Cumulocity IoT this step can be skipped).

<UserContext>

```sh
sudo tedge cert create --device-id "${DEVICE_ID}"
sudo tedge cert create --device-id "$DEVICE_ID"
```

```sh title="Example"
export DEVICE_ID="gateway_4932C0CE7D12"
sudo tedge cert create --device-id "${DEVICE_ID}"
```
</UserContext>

The device id is a unique identifier e.g. the MAC address that identifies the physical device.

The certificate is uploaded to the Cumulocity IoT Tenant via:

<UserContext>

```sh
sudo tedge cert upload c8y --user "${C8Y_USER}"
sudo tedge cert upload c8y --user "$C8Y_USER"
```

```sh title="Example"
sudo tedge cert upload c8y --user "[email protected]"
```
</UserContext>

If the password prompt appears, enter your password.

Expand Down Expand Up @@ -320,8 +332,7 @@ The APT plugin (provided by the `tedge-apt-plugin` package) is installed by defa
<!-- TODO: Verify if reconnecting the mapper is really necessary! -->

```sh
sudo tedge disconnect c8y
sudo tedge connect c8y
sudo tedge reconnect c8y
```

### Adding new software into the software repository in Cumulocity IoT
Expand Down

0 comments on commit 1d8aebe

Please sign in to comment.