Skip to content

Commit

Permalink
Merge pull request #3000 from reubenmiller/docs-user-context
Browse files Browse the repository at this point in the history 
docs: improve mapper documentation via adding user-context
  • Loading branch information
@reubenmiller
reubenmiller authored Jul 17, 2024
2 parents 05ef169 + ef95336 commit 837073b
Show file tree
Hide file tree
Showing 5 changed files with 283 additions and 67 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
188 changes: 157 additions & 31 deletions docs/src/start/connect-aws.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,21 @@ sidebar_position: 4
description: Connect %%te%% to AWS 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,AWS_URL,AWS_REGION,AWS_ACCOUNT_ID" />

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

### Overview

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.
Expand All @@ -23,7 +38,7 @@ Before you try to connect your device to AWS IoT, you need:
You can now use [`tedge` command](../references/cli/index.md) to:

* [create a certificate for your device](#create-certificate),
* [register the device on AWS IoT Hub](#register),
* [register the device on AWS IoT Core](#register),
* [configure the device](#configure),
* [connect the device](#connect), and
* [send your first telemetry data](#send).
Expand All @@ -37,10 +52,15 @@ 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>

## Show certificate details

You can then check the content of that certificate.
Expand All @@ -49,83 +69,180 @@ 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.
To use a certificate signed by your Certificate Authority,
see the reference guide of [`tedge cert`](../references/cli/tedge-cert.md).

## Register the device on AWS IoT Hub {#register}
## Register the device on AWS IoT Core {#register}

For a device to be trusted by AWS, one needs a device certificate and the `tedge cert create` command is the simplest way to get one.
Also a policy needs to be attached to the device certificate in AWS IoT Core. AWS IoT Core policies determine what an
authenticated identity can do (here the authenticated identity is the device being connected). More info on AWS IoT Core
policies can be found [here](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html).

To create a new policy, head over to the AWS IoT Core and navigate to
### Create new policy

**Security &rarr; Policies &rarr; Create policy &rarr; Policy properties &rarr; Policy name &rarr; Enter the name of your policy (e.g.tedge)**
Before you can register any devices, you must create a policy which can be assigned to each new device during the registration process. The policy grants permissions to the devices to be able to write to specific MQTT topics.

On the Policy statements tab click on ***JSON*** and enter the policy in the ***Policy document*** (an example policy can be found [here](https://raw.githubusercontent.com/thin-edge/thin-edge.io/main/docs/src/start/aws-example-policy.json)) then click ***Create***.
1. Open your AWS IoT Core

In the AWS IoT Core, navigate to ***Manage &rarr; All devices &rarr; Things &rarr; Create things &rarr; Create Single thing &rarr; Next***. Enter the Thing name which can be obtained from the device with the output of the following command:
2. Navigate to the Policies section under **Security** &rarr; **Policies**

```sh
tedge config get device.id
```
3. Click **Create policy**, and enter a policy name (e.g. `thin-edge.io`)

4. Under the **Policy statements** tab click on ***JSON*** and add the following JSON:

:::tip
If you haven't provided the [User Context](#user-context) then it is strongly encouraged to do so, as the following snippet will be updated to reflect your AWS IoT Core settings.
:::

<UserContext>

```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:client/${iot:Connection.Thing.ThingName}"
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topicfilter/thinedge/${iot:Connection.Thing.ThingName}/cmd/#",
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/shadow/#",
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topicfilter/thinedge/devices/${iot:Connection.Thing.ThingName}/test-connection"
]
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": [
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/cmd",
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/cmd/*",
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow",
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*",
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/devices/${iot:Connection.Thing.ThingName}/test-connection"
]
},
{
"Effect": "Allow",
"Action": "iot:Publish",
"Resource": [
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/td",
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/td/*",
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow",
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*",
"arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/devices/${iot:Connection.Thing.ThingName}/test-connection"
]
}
]
}
```

</UserContext>

:::info
A static form of the example policy can be downloaded from the [repository](https://raw.githubusercontent.com/thin-edge/thin-edge.io/main/docs/src/start/aws-example-policy.json), though you will need to replace the `<region>` and `<account-id>` placeholders with your AWS IoT Core values.
:::

4. Click **Create**

In the Device Shadow section which allows connected devices to sync states with AWS choose ***Unnamed shadow (classic)*** and click ***Next*** and ***Configure device certificate - optional*** page opens.
### Registering a Device (thing)

At ***Device certificate*** choose ***Use my certificate &rarr; CA is not registered with AWS IoT*** then ***Choose file*** and select your tedge-certificate.pem file, click on ***Open &rarr; Next***.
1. Open the AWS IoT Core page

The last step needed is to attach previously created policy to your certificate, **Attach policies to certificate -optional** &rarr; Select your created policy **&rarr; Create thing**.
2. Navigate to **Manage** &rarr; **All devices** &rarr; **Things**

3. Click **Create things**, select the **Create single thing** option, then click **Next**

4. Enter the device name (e.g. Thing name)

<UserContext>

```
$DEVICE_ID
```
</UserContext>
:::tip
The thing name must match the device certificate's Common Name. If you are unsure what the value is, then you can check the common name of the device by using the following `tedge` command:
```sh
tedge config get device.id
```
:::
4. Select the ***Unnamed shadow (classic)*** option and click ***Next***
5. On the ***Device certificate*** page, choose ***Use my certificate &rarr; CA is not registered with AWS IoT***
6. ***Choose file*** and select your `tedge-certificate.pem` file, click on ***Open &rarr; Next***
If you haven't previously downloaded the public device certificate, you can print the contents (don't worry this is not sensitive information), and then you can save the certificate's contents to a file on your computer so it can be uploaded to AWS.
You can print the public certificate to the console using the following command:
```sh
cat /etc/tedge/device-certs/tedge-certificate.pem
```
7. On the **Policies** page, select the previously created policy, e.g. `thin-edge.io`, then click **Create thing**
## Configure the device {#configure}
To connect the device to the AWS IoT Hub, one needs to set the URL of the IoT Hub and the root certificate of the IoT
To connect the device to the AWS IoT Core, one needs to set the URL of the IoT Hub and the root certificate of the IoT
Hub as below.
Set the URL of your AWS IoT Hub.
Set the URL of your AWS IoT Core.
<UserContext>
```sh
sudo tedge config set aws.url "${AWS_URL}"
sudo tedge config set aws.url "$AWS_URL"
```

```sh title="Example"
sudo tedge config set aws.url "a2e8ahbpo21syc.iot.eu-central-1.amazonaws.com"
```
</UserContext>

The URL is unique to the AWS account and region that is used, and can be found in the AWS IoT Core by navigating to
"Settings". It will be listed under "Device data endpoint" (e.g. `a2e8ahbpo21syc.iot.eu-central-1.amazonaws.com`)
**Settings**. It will be listed under **Device data endpoint**.

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

```sh
sudo tedge config set aws.root_cert_path /etc/ssl/certs/AmazonRootCA1.pem
```
:::note
The Amazon's public root certificate for your region's AWS IoT Core needs to be present in your ca-certificate store for the communication to the cloud to be trusted.

This will set the root certificate path of the AWS IoT Hub. In most of the Linux flavors, the certificate will be
present in /etc/ssl/certs. If not found download it from
[here](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs).
In most of the Linux flavors, the certificate will be present in `/etc/ssl/certs` directory. If the certificate is not present, then you can download it manually from
[Amazon](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs) and add it to your system's ca-certificate store by following the
[Adding a root certificate](../operate/security/cloud-authentication.md#adding-a-root-certificate) documentation.
:::

## Connect the device {#connect}

Now, you are ready to get your device connected to AWS IoT Hub with `tedge connect aws`.
Now, you are ready to get your device connected to AWS IoT Core with `tedge connect aws`.
This command configures the MQTT broker:

* to establish a permanent and secure connection to the AWS cloud,
* to forward local messages to the cloud and vice versa.

Also, if you have installed `tedge-mapper`, this command starts and enables the tedge-mapper-aws systemd service.
At last, it sends packets to AWS IoT Hub to check the connection.
At last, it sends packets to AWS IoT Core to check the connection.

```sh
sudo tedge connect aws
Expand Down Expand Up @@ -198,6 +315,15 @@ tedge-mapper-aws service successfully started and enabled!
```

:::tip
If you having troubles with the connection, then check the following items:

* Check that the policy is attached to the device's certificate
* Check that the policy includes your AWS IoT Core's region and account id
* Check [Amazon diagnosing connectivity issues](https://docs.aws.amazon.com/iot/latest/developerguide/diagnosing-connectivity-issues.html) documentation for further debugging steps
* Check the mosquitto logs for errors, e.g. "verify" errors would indicate that you are missing Amazon's root certificate in the ca-certificate store
:::

## Sending your first telemetry data {#send}

Using the AWS mapper, you can publish measurement telemetry data to AWS by publishing on the `te/device/main///m/` topic:
Expand Down
Loading

0 comments on commit 837073b

Please sign in to comment.