From 1b508e8d38e9b26f5988431554f3932127c4fae2 Mon Sep 17 00:00:00 2001 From: reubenmiller Date: Wed, 29 Jan 2025 18:01:45 +0100 Subject: [PATCH] docs: backporting cumulocity documentation links to 1.4.2 --- versioned_docs/version-1.4.2/.version | 2 +- .../version-1.4.2/contribute/build.md | 6 +- .../building-image/rugpi/tutorial.md | 4 +- .../building-image/yocto/tutorial.md | 4 +- .../child-device-configuration-management.md | 2 +- .../child-device-firmware-management.md | 4 +- .../version-1.4.2/operate/c8y/apama.md | 4 +- .../operate/c8y/configuration-management.md | 6 +- .../version-1.4.2/operate/c8y/connect.md | 4 +- .../operate/c8y/custom-fragments.md | 10 +-- .../operate/c8y/device-availability.md | 12 ++-- .../operate/c8y/device-profiles.md | 4 +- .../operate/c8y/health-monitoring.md | 8 +-- .../version-1.4.2/operate/c8y/index.md | 2 +- .../operate/c8y/remote-access.md | 2 +- .../operate/c8y/restart-device.md | 4 +- .../operate/c8y/smartrest-templates.md | 38 +++++------ .../operate/c8y/software-management.md | 18 ++--- .../operate/c8y/supported-operations.md | 4 +- .../operate/configuration/index.md | 2 +- .../configuration/mapper-configuration.md | 6 +- .../operate/monitoring/systemd-watchdog.md | 2 +- .../operate/registration/deregister.md | 2 +- .../operate/security/cloud-authentication.md | 6 +- .../operate/security/cumulocity-token.md | 32 ++++----- .../operate/security/device-certificate.md | 2 +- .../operate/security/https-configuration.md | 10 +-- .../troubleshooting/device-monitoring.md | 4 +- .../operate/troubleshooting/log-files.md | 15 ++-- .../testing-cloud-connection.md | 4 +- versioned_docs/version-1.4.2/overview.md | 4 +- .../references/agent/software-management.md | 2 +- .../references/configuration-files.md | 4 +- .../references/cumulocity-proxy.md | 2 +- .../references/mappers/c8y-mapper.md | 56 +++++++-------- .../references/mappers/mqtt-topics.md | 2 +- .../references/supported-platforms.md | 2 +- .../version-1.4.2/start/connect-aws.md | 2 +- .../version-1.4.2/start/connect-azure.md | 10 +-- .../version-1.4.2/start/connect-c8y.md | 38 +++++------ .../version-1.4.2/start/device-monitoring.md | 8 +-- .../version-1.4.2/start/getting-started.md | 68 +++++++++---------- .../version-1.4.2/start/raise-alarm.md | 8 +-- .../version-1.4.2/start/send-events.md | 6 +- .../version-1.4.2/start/send-measurements.md | 2 +- .../start/software-management.md | 12 ++-- .../version-1.4.2/understand/faq.md | 2 +- .../version-1.4.2/understand/tedge-mapper.md | 6 +- 48 files changed, 230 insertions(+), 227 deletions(-) diff --git a/versioned_docs/version-1.4.2/.version b/versioned_docs/version-1.4.2/.version index c9929e3..6d98379 100644 --- a/versioned_docs/version-1.4.2/.version +++ b/versioned_docs/version-1.4.2/.version @@ -1 +1 @@ -1.4.2 \ No newline at end of file +1.4.2-82-gce649ba125 main \ No newline at end of file diff --git a/versioned_docs/version-1.4.2/contribute/build.md b/versioned_docs/version-1.4.2/contribute/build.md index 923bbf0..61bb478 100644 --- a/versioned_docs/version-1.4.2/contribute/build.md +++ b/versioned_docs/version-1.4.2/contribute/build.md @@ -78,9 +78,9 @@ Current MSRV is `1.65`. ### Cross compilation toolchain (optional) %%te%% can be compiled for target architecture on non-target device, this is called cross compilation. -Currently we support `Raspberry Pi 3B` for `armv7` architecture with Rust's cross compilation toolchain called [cargo cross](https://github.com/rust-embedded/cross). +Currently we support `Raspberry Pi 3B` for `armv7` architecture with Rust's cross compilation toolchain called [cargo cross](https://github.com/cross-rs/cross). -To install [cargo cross](https://github.com/rust-embedded/cross): +To install [cargo cross](https://github.com/cross-rs/cross): ```sh cargo install cross @@ -179,7 +179,7 @@ total 2948 ## Cross compiling -To create binaries which can run on different platform than one you are currently on you can use [cargo cross](https://github.com/rust-embedded/cross): +To create binaries which can run on different platform than one you are currently on you can use [cargo cross](https://github.com/cross-rs/cross): ```sh cross build --target armv7-unknown-linux-gnueabihf diff --git a/versioned_docs/version-1.4.2/extend/firmware-management/building-image/rugpi/tutorial.md b/versioned_docs/version-1.4.2/extend/firmware-management/building-image/rugpi/tutorial.md index d967ebc..46c8de1 100644 --- a/versioned_docs/version-1.4.2/extend/firmware-management/building-image/rugpi/tutorial.md +++ b/versioned_docs/version-1.4.2/extend/firmware-management/building-image/rugpi/tutorial.md @@ -43,7 +43,7 @@ Feel free to clone the project if you want to make your own customizations, howe ### Pre-requisites -To run the project tasks, you will need to install a command line tool called [just](https://just.systems/man/en/chapter_5.html). +To run the project tasks, you will need to install a command line tool called [just](https://just.systems/man/en/packages.html). You can install just using on of the following commands: @@ -59,7 +59,7 @@ cargo install just curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | sudo bash -s -- --to /usr/bin ``` -For other installation possibilities check out the [just documentation](https://just.systems/man/en/chapter_4.html). +For other installation possibilities check out the [just documentation](https://just.systems/man/en/packages.html). ### Cloning the project {#clone-project} diff --git a/versioned_docs/version-1.4.2/extend/firmware-management/building-image/yocto/tutorial.md b/versioned_docs/version-1.4.2/extend/firmware-management/building-image/yocto/tutorial.md index 945ff51..e35928e 100644 --- a/versioned_docs/version-1.4.2/extend/firmware-management/building-image/yocto/tutorial.md +++ b/versioned_docs/version-1.4.2/extend/firmware-management/building-image/yocto/tutorial.md @@ -67,13 +67,13 @@ The project uses different Yocto layers to build an image which contains: cd meta-tedge/kas ``` -2. Install [just](https://just.systems/man/en/chapter_5.html) which is used to run different tasks provided by the project +2. Install [just](https://just.systems/man/en/packages.html) which is used to run different tasks provided by the project ```sh curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | sudo bash -s -- --to /usr/bin ``` - Check out the [justfile website](https://just.systems/man/en/chapter_5.html) for more installation options. + Check out the [justfile website](https://just.systems/man/en/packages.html) for more installation options. 3. Install [kas](https://kas.readthedocs.io/en/latest/) which is used to managed bitbake projects diff --git a/versioned_docs/version-1.4.2/legacy/child-device-configuration-management.md b/versioned_docs/version-1.4.2/legacy/child-device-configuration-management.md index 2b8f755..9e7cc84 100644 --- a/versioned_docs/version-1.4.2/legacy/child-device-configuration-management.md +++ b/versioned_docs/version-1.4.2/legacy/child-device-configuration-management.md @@ -2,7 +2,7 @@ title: Child Device Configuration Management tags: [Cumulocity, Configuration, Legacy] sidebar_position: 6 -description: Legacy configuration management for child devices using Cumulocity IoT +description: Legacy configuration management for child devices using Cumulocity --- # Enable configuration management on child devices diff --git a/versioned_docs/version-1.4.2/legacy/child-device-firmware-management.md b/versioned_docs/version-1.4.2/legacy/child-device-firmware-management.md index 20c74b7..37f30bb 100644 --- a/versioned_docs/version-1.4.2/legacy/child-device-firmware-management.md +++ b/versioned_docs/version-1.4.2/legacy/child-device-firmware-management.md @@ -2,13 +2,13 @@ title: Child Device Firmware Management tags: [Cumulocity, Firmware, Legacy] sidebar_position: 9 -description: Legacy child device firmware management using Cumulocity IoT +description: Legacy child device firmware management using Cumulocity --- # Child-Device Firmware Management using Cumulocity (legacy API) %%te%% provides a legacy operation plugin to -[manage device firmware using Cumulocity](https://cumulocity.com/guides/users-guide/device-management/#firmware-repo) +[manage device firmware using Cumulocity](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-firmware) on child devices. :::caution diff --git a/versioned_docs/version-1.4.2/operate/c8y/apama.md b/versioned_docs/version-1.4.2/operate/c8y/apama.md index ee0f483..2d70667 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/apama.md +++ b/versioned_docs/version-1.4.2/operate/c8y/apama.md @@ -14,7 +14,7 @@ Further details about this can be found in the %%te%% documentation at [Manage t #### Set up the Debian repository from which the Apama packages will be installed -1. In the Cumulocity IoT tenant, open the **Device Management** app, go to the **Management** menu option and select the **Software repository**. +1. In the Cumulocity tenant, open the **Device Management** app, go to the **Management** menu option and select the **Software repository**. 2. Click **Add software** at the right of the top menu bar. 3. In the **ADD SOFTWARE** dialog enter the following details: - **Software**: apama-repo @@ -82,7 +82,7 @@ Follow the instructions [here](https://github.com/thin-edge/thin-edge.io_example You can test if the project was successfully installed by running the following Apama command: ```sh -/opt/softwareag/Apama/bin/apama_env engine_inspect -m +/opt/cumulocity/Apama/bin/apama_env engine_inspect -m ``` ```text title="Example Output" diff --git a/versioned_docs/version-1.4.2/operate/c8y/configuration-management.md b/versioned_docs/version-1.4.2/operate/c8y/configuration-management.md index 73e196b..1a59d38 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/configuration-management.md +++ b/versioned_docs/version-1.4.2/operate/c8y/configuration-management.md @@ -4,10 +4,10 @@ tags: [Operate, Cumulocity, Configuration] description: Managing configuration on devices --- -With %%te%%, you can manage config files on a device by using the [Cumulocity configuration management feature](https://cumulocity.com/guides/users-guide/device-management/#managing-configurations) as a part of Device Management. +With %%te%%, you can manage config files on a device by using the [Cumulocity configuration management feature](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-configurations) as a part of Device Management. If you are new to the Cumulocity **Configuration Management** feature, -we recommend you to read [the Cumulocity user guide](https://cumulocity.com/guides/users-guide/device-management/#managing-configurations) along with this how-to guide. +we recommend you to read [the Cumulocity user guide](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-configurations) along with this how-to guide. The configuration management functionality is provided by the **tedge-agent** service which is installed by default. @@ -52,7 +52,7 @@ This is the configuration file of `tedge-configuration-plugin`, where you can ad ## Update tedge-configuration-plugin configuration from Cumulocity -To update any configuration file, create a local copy of that config file and then upload that file to the [Cumulocity configuration repository](https://cumulocity.com/guides/users-guide/device-management/#to-add-a-configuration-snapshot) with the appropriate configuration type. +To update any configuration file, create a local copy of that config file and then upload that file to the [Cumulocity configuration repository](https://cumulocity.com/docs/device-management-application/managing-device-data/#to-add-a-configuration-snapshot) with the appropriate configuration type. The `tedge-configuration-plugin.toml` file can also be updated from the cloud in a similar manner to add/remove further configuration file entries. The updated TOML file has to be uploaded with the configuration type: **tedge-configuration-plugin**. diff --git a/versioned_docs/version-1.4.2/operate/c8y/connect.md b/versioned_docs/version-1.4.2/operate/c8y/connect.md index 9745c08..1f16f4c 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/connect.md +++ b/versioned_docs/version-1.4.2/operate/c8y/connect.md @@ -1,7 +1,7 @@ --- title: Connect tags: [Operate, Cloud] -description: Connecting %%te%% to Cumulocity IoT +description: Connecting %%te%% to Cumulocity --- import UserContext from '@site/src/components/UserContext'; @@ -59,7 +59,7 @@ in this case we are told to run `tedge config set c8y.url `. ## Making the cloud trust the device The next step is to have the device certificate trusted by Cumulocity. This is done by uploading the certificate of the signee. -You can upload the root certificate using the [Cumulocity UI](https://cumulocity.com/guides/users-guide/device-management/#trusted-certificates) +You can upload the root certificate using the [Cumulocity UI](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-trusted-certificates) or with [`tedge cert upload`](../../references/cli/tedge-cert.md) command as described below. :::note diff --git a/versioned_docs/version-1.4.2/operate/c8y/custom-fragments.md b/versioned_docs/version-1.4.2/operate/c8y/custom-fragments.md index dec0564..ef052f0 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/custom-fragments.md +++ b/versioned_docs/version-1.4.2/operate/c8y/custom-fragments.md @@ -1,14 +1,14 @@ --- title: Custom Fragments tags: [Operate, Cumulocity] -description: Publishing custom fragments/properties to Cumulocity IoT +description: Publishing custom fragments/properties to Cumulocity --- -%%te%% supports update custom fragments (also known as properties) on the device's digital twin representation in Cumulocity IoT. +%%te%% supports update custom fragments (also known as properties) on the device's digital twin representation in Cumulocity. ## Default fragments -By default, the device will send the following information to Cumulocity IoT. The information makes it easy to identify devices which are using %%te%% in your fleet. +By default, the device will send the following information to Cumulocity. The information makes it easy to identify devices which are using %%te%% in your fleet. ```json { @@ -53,7 +53,7 @@ tedge mqtt pub te/device/main///twin/os_Version '{ }' ``` -The example above will result in the following fragment being added to the device's digital twin (e.g. *Managed Object*) in Cumulocity IoT. +The example above will result in the following fragment being added to the device's digital twin (e.g. *Managed Object*) in Cumulocity. ```json5 { @@ -105,4 +105,4 @@ In the Cumulocity UI this will looks something like this: For information on which fragments Cumulocity supports please see the -[Cumulocity API docs](https://cumulocity.com/guides/reference/device-management-library/). +[Cumulocity API docs](https://cumulocity.com/docs/device-integration/fragment-library/). diff --git a/versioned_docs/version-1.4.2/operate/c8y/device-availability.md b/versioned_docs/version-1.4.2/operate/c8y/device-availability.md index 551bfeb..0f68f1f 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/device-availability.md +++ b/versioned_docs/version-1.4.2/operate/c8y/device-availability.md @@ -6,16 +6,16 @@ description: Monitoring the availability of devices # Availability Monitoring -%%te%% fully supports the [Cumulocity IoT's device availability monitoring feature](https://cumulocity.com/docs/device-management-application/monitoring-and-controlling-devices/#availability) +%%te%% fully supports the [Cumulocity's device availability monitoring feature](https://cumulocity.com/docs/device-management-application/monitoring-and-controlling-devices/#availability) allowing you to set the desired required interval for the devices -and also sending heartbeats to **Cumulocity IoT** periodically when a device is deemed available. +and also sending heartbeats to **Cumulocity** periodically when a device is deemed available. %%te%% considers a device as available when the `tedge-agent` service on it is up and running, monitored using its service health endpoint. The health endpoint can be changed from the `tedge-agent` to any other entity's health endpoint as well. ## Set the required availability interval -As described in the [Cumulocity IoT's user documentation](https://cumulocity.com/docs/device-integration/fragment-library/#device-availability), +As described in the [Cumulocity's user documentation](https://cumulocity.com/docs/device-integration/fragment-library/#device-availability), %%te%% main and child devices set their required interval during their first connection. Availability monitoring is enabled by default with a default required interval of 1 hour. The value to be updated using the `tedge config set` command as follows: @@ -29,7 +29,7 @@ availability monitoring is disabled and the device is considered to be in mainte ## Change the health endpoint for heartbeat messages -Once the device connection to **Cumulocity IoT** is established, +Once the device connection to **Cumulocity** is established, **tedge-mapper-c8y** will keep sending heartbeat messages (empty inventory update messages) on behalf of the main and child devices to keep their availability active. By default, the status of the **tedge-agent** service is used to determine whether the device is available or not. @@ -48,7 +48,7 @@ tedge mqtt pub te/device/my-device// '{"@health":"device/my-device/service/foo", ``` If the status of the new endpoint is reported as `up`, the device is considered "available", -and a heartbeat signal is sent to Cumulocity IoT. +and a heartbeat signal is sent to Cumulocity. If the status has any other value, the device is considered "unavailable", and no heartbeat message are sent to Cumulocity until the status changes to `up` again. @@ -61,4 +61,4 @@ To disable the feature, use the `tedge config set` command as follows and restar sudo tedge config set c8y.availability.enable false ``` -When disabled, the required availability interval and periodic heartbeat messages aren't sent to Cumulocity IoT. +When disabled, the required availability interval and periodic heartbeat messages aren't sent to Cumulocity. diff --git a/versioned_docs/version-1.4.2/operate/c8y/device-profiles.md b/versioned_docs/version-1.4.2/operate/c8y/device-profiles.md index f80348f..9de0cb1 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/device-profiles.md +++ b/versioned_docs/version-1.4.2/operate/c8y/device-profiles.md @@ -6,10 +6,10 @@ description: Managing device profiles on devices ## Management -%%te%% enables you to manage the firmware, software and configuration for a device in a single operation which makes it suitable for managing a large fleet of devices. The following sections detail how to create and assign a device profile to a device. Using Cumulocity IoT, you can either assign a device profile using a single operation (described on this page), or by using a [bulk operation](https://cumulocity.com/docs/device-management-application/monitoring-and-controlling-devices/#to-add-a-bulk-operation) to assign it to a fleet of devices. +%%te%% enables you to manage the firmware, software and configuration for a device in a single operation which makes it suitable for managing a large fleet of devices. The following sections detail how to create and assign a device profile to a device. Using Cumulocity, you can either assign a device profile using a single operation (described on this page), or by using a [bulk operation](https://cumulocity.com/docs/device-management-application/monitoring-and-controlling-devices/#to-add-a-bulk-operation) to assign it to a fleet of devices. :::info -For more detailed information on the Cumulocity IoT **Device Management** features, please check out the [official documentation](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-device-profiles). +For more detailed information on the Cumulocity **Device Management** features, please check out the [official documentation](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-device-profiles). ::: ### To add a new device profile {#add-to-repo} diff --git a/versioned_docs/version-1.4.2/operate/c8y/health-monitoring.md b/versioned_docs/version-1.4.2/operate/c8y/health-monitoring.md index 347816b..e4461e5 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/health-monitoring.md +++ b/versioned_docs/version-1.4.2/operate/c8y/health-monitoring.md @@ -5,7 +5,7 @@ description: Monitoring the health of services on devices --- The health of a %%te%% service or any other `service` that is running on the %%te%% device -or on the `child` device can be monitored from the **Cumulocity IoT** by sending the `health-status` message to **Cumulocity IoT**. +or on the `child` device can be monitored from the **Cumulocity** by sending the `health-status` message to **Cumulocity**. ## Publish health status @@ -28,7 +28,7 @@ The health status message has to be sent as a *retain* message. When an empty health status message is sent, e.g. `{}` or `''`, the `status` will be replaced with `unknown`. -## Conversion of the health status message to Cumulocity IoT service monitor message +## Conversion of the health status message to Cumulocity service monitor message The `tedge-mapper-c8y` will translate any health status message that is received on `te/+/+/+/+/status/health` topic to Cumulocity [Service creation](https://cumulocity.com/docs/smartrest/mqtt-static-templates/#102) SmartREST message and @@ -52,7 +52,7 @@ tedge mqtt pub te/device/child1/service/service1/status/health '{"status":"up"}'
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/s/us/:device:child1 @@ -90,4 +90,4 @@ sudo tedge config unset service.type More info about the service monitoring can be found in the link below. -[Service monitoring Cumulocity IoT](https://cumulocity.com/docs/device-management-application/viewing-device-details/#services) +[Service monitoring Cumulocity](https://cumulocity.com/docs/device-management-application/viewing-device-details/#services) diff --git a/versioned_docs/version-1.4.2/operate/c8y/index.md b/versioned_docs/version-1.4.2/operate/c8y/index.md index 241e7a0..023079e 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/index.md +++ b/versioned_docs/version-1.4.2/operate/c8y/index.md @@ -2,7 +2,7 @@ title: Device Management with Cumulocity tags: [Operate, Cloud] sidebar_position: 9 -description: Device management with %%te%% and Cumulocity IoT +description: Device management with %%te%% and Cumulocity --- import DocCardList from '@theme/DocCardList'; diff --git a/versioned_docs/version-1.4.2/operate/c8y/remote-access.md b/versioned_docs/version-1.4.2/operate/c8y/remote-access.md index 3d71ebe..9718223 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/remote-access.md +++ b/versioned_docs/version-1.4.2/operate/c8y/remote-access.md @@ -8,7 +8,7 @@ description: Accessing devices remote using tcp based protocols (e.g. ssh, vnc e To access a device remotely that runs %%te%%, a plugin of the operation plugin concept is used. The tedge-mapper is checking for cloud remote access operation and is triggering the particular plugin. You can use the remote access tab in device management to access the device via SSH or VNC. -Background information on the remote access feature provided by Cumulocity IoT can be found in their [official documentation](https://cumulocity.com/guides/cloud-remote-access/using-cloud-remote-access/). +Background information on the remote access feature provided by Cumulocity can be found in their [official documentation](https://cumulocity.com/docs/cloud-remote-access/using-cloud-remote-access/). ## Requirements diff --git a/versioned_docs/version-1.4.2/operate/c8y/restart-device.md b/versioned_docs/version-1.4.2/operate/c8y/restart-device.md index 37d9344..cf1073e 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/restart-device.md +++ b/versioned_docs/version-1.4.2/operate/c8y/restart-device.md @@ -6,9 +6,9 @@ description: Restarting a device from the cloud If your device is running %%te%%, you can restart it from the cloud. -### Cumulocity IoT +### Cumulocity -1. Go to the *Device Management* application in Cumulocity IoT +1. Go to the *Device Management* application in Cumulocity 2. Find your device and open up its homepage diff --git a/versioned_docs/version-1.4.2/operate/c8y/smartrest-templates.md b/versioned_docs/version-1.4.2/operate/c8y/smartrest-templates.md index 2e52e4a..6a29ab3 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/smartrest-templates.md +++ b/versioned_docs/version-1.4.2/operate/c8y/smartrest-templates.md @@ -4,9 +4,9 @@ tags: [Operate, Cumulocity] description: SmartREST 2.0 template registration and usage --- -[Custom SmartREST 2.0 Templates](https://cumulocity.com/guides/reference/smartrest-two) can be used to extend the functionality of a device to support more operations than what the [static SmartREST templates](https://cumulocity.com/guides/reference/smartrest-two/#mqtt-static-templates) offer. +[Custom SmartREST 2.0 Templates](https://cumulocity.com/docs/smartrest/smartrest-introduction/) can be used to extend the functionality of a device to support more operations than what the [static SmartREST templates](https://cumulocity.com/docs/smartrest/mqtt-static-templates/) offer. -%%te%% supports subscription to custom templates as documented [here](https://cumulocity.com/guides/users-guide/device-management/#smartrest-templates). +%%te%% supports subscription to custom templates as documented [here](https://cumulocity.com/docs/smartrest/smartrest-two/#template-collections). For every template that the device uses, it must publish all data to `s/uc/` topic and subscribe to `s/dc/` to receive data from the cloud, based on that template. When these templates are configured with %%te%%, subscriptions to all these relevant topics on Cumulocity cloud will be done by %%te%% internally. @@ -122,11 +122,11 @@ The following example shows how to create a new SmartREST template with a single In this example, the operation handler on the %%te%% side only prints out the received message on the console, but it can be extended to execute any command that is required for your task. -The operation response defined in the SmartREST template will convert the Cumulocity IoT Operation from json to an MQTT message in a Comma Separated Variables (CSV) format. The MQTT message is then received by %%te%% and a script is called passing the message as the message to it. The script is used to perform the desired actions using the parameters provided in the message. +The operation response defined in the SmartREST template will convert the Cumulocity Operation from json to an MQTT message in a Comma Separated Variables (CSV) format. The MQTT message is then received by %%te%% and a script is called passing the message as the message to it. The script is used to perform the desired actions using the parameters provided in the message. -The snippets below are used to illustrate the message translation of the Cumulocity IoT operation to the message received by the device. +The snippets below are used to illustrate the message translation of the Cumulocity operation to the message received by the device. -**Cumulocity IoT Operation** +**Cumulocity Operation** ```json { @@ -142,7 +142,7 @@ The snippets below are used to illustrate the message translation of the Cumuloc **SmartREST (CSV) format received by %%te%%** -The above Cumulocity IoT operation is transformed into CSV (using the formatting/rules defined in the SmartREST template) and sent to the device via MQTT. The example below shows the format of the message as received by the device: +The above Cumulocity operation is transformed into CSV (using the formatting/rules defined in the SmartREST template) and sent to the device via MQTT. The example below shows the format of the message as received by the device: ```csv title="topic: c8y/s/dc/custom_devmgmt" dm101,,,, @@ -152,7 +152,7 @@ The following procedure details the step-by-step instructions on how to implemen ### Step 1: Creating a SmartREST template -1. Open the Cumulocity IoT *Device Management* Application in your web browser +1. Open the Cumulocity *Device Management* Application in your web browser 2. Navigate to *Device Types → SmartREST Templates* @@ -212,7 +212,7 @@ Alternatively, you can import a SmartREST template from an existing file. This a } ``` -2. Open the Cumulocity IoT *Device Management* Application +2. Open the Cumulocity *Device Management* Application 3. Navigate to *Device Types → SmartREST templates* @@ -247,7 +247,7 @@ On the device, perform the following steps: The `custom_devmgmt` is the id of the SmartREST template that was created in the previous step. -2. Reconnect to Cumulocity IoT (assuming you have already connected to Cumulocity IoT once) +2. Reconnect to Cumulocity (assuming you have already connected to Cumulocity once) ```sh tedge reconnect c8y @@ -287,9 +287,9 @@ On your %%te%% device, run the following steps: # Input arguments MESSAGE="$1" - NAME=$(echo "$COMMAND" | cut -d, -f 3) - SSID=$(echo "$COMMAND" | cut -d, -f 4) - TYPE=$(echo "$COMMAND" | cut -d, -f 5) + NAME=$(echo "$MESSAGE" | cut -d, -f 3) + SSID=$(echo "$MESSAGE" | cut -d, -f 4) + TYPE=$(echo "$MESSAGE" | cut -d, -f 5) echo "Processing message: $MESSAGE" echo "NAME: $NAME" @@ -310,9 +310,9 @@ On your %%te%% device, run the following steps: ### Step 4: Sending a custom operation -1. On your local machine, create a custom operation instance in Cumulocity IoT +1. On your local machine, create a custom operation instance in Cumulocity - Below shows an example of creating the operation using the [go-c8y-cli)](https://goc8ycli.netlify.app/) cli tool. It assumes you have already activated your go-c8y-cli session which points to your intended Cumulocity IoT tenant. + Below shows an example of creating the operation using the [go-c8y-cli)](https://goc8ycli.netlify.app/) cli tool. It assumes you have already activated your go-c8y-cli session which points to your intended Cumulocity tenant. ```sh c8y operations create \ @@ -321,13 +321,13 @@ On your %%te%% device, run the following steps: --description "Configure wifi" ``` - Where `12345` should be replaced with the Cumulocity IoT device id of your device. + Where `12345` should be replaced with the Cumulocity device id of your device. If you're not familiar with go-c8y-cli, then you can send the Cumulocity REST API request using other tools such as Postman, curl etc., though you will have use the appropriate Authorization Header as defined by the official [Cumulocity API Guide](https://cumulocity.com/api/core/). - **Cumulocity IoT REST Request** + **Cumulocity REST Request** - The custom operation can be created via the Cumulocity IoT REST API using the following details: + The custom operation can be created via the Cumulocity REST API using the following details: ``` POST /devicecontrol/operations @@ -347,7 +347,7 @@ On your %%te%% device, run the following steps: } ``` -2. In the Cumulocity IoT *Device Management* application, check the *Control* page where you should see the "Configure Wifi" operation. +2. In the Cumulocity *Device Management* application, check the *Control* page where you should see the "Configure Wifi" operation. ![smartrest-custom-operation-control.png](./images/smartrest-custom-operation-control.png) @@ -393,7 +393,7 @@ When a new operation is received, the above mqtt sub command should print the fo ``` If you don't receive a message, then check the following: -* Check your SmartREST definition in Cumulocity IoT. The definition must be defined per Cumulocity IoT Tenant! +* Check your SmartREST definition in Cumulocity. The definition must be defined per Cumulocity Tenant! * Check that the %%te%% config has been updated to subscribe to the related SmartREST topic. Maybe you forgot to run: ``` diff --git a/versioned_docs/version-1.4.2/operate/c8y/software-management.md b/versioned_docs/version-1.4.2/operate/c8y/software-management.md index 604a37e..a4bdf29 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/software-management.md +++ b/versioned_docs/version-1.4.2/operate/c8y/software-management.md @@ -9,7 +9,7 @@ description: Managing software on devices %%te%% enables you to manage the software installed on your device. The following sections details how to install and remove software packages. :::info -For more detailed information on the Cumulocity IoT **Device Management** features, please check out the [official documentation](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-software). +For more detailed information on the Cumulocity **Device Management** features, please check out the [official documentation](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-software). ::: ### To add a new software or software version {#add-to-repo} @@ -77,7 +77,7 @@ For more detailed information on the Cumulocity IoT **Device Management** featur ### Updating to the latest %%te%% version {#self-update} -Updating %%te%% from Cumulocity IoT is the same process as installing any other software. You can update all of the %%te%% packages by installing a single package called `tedge-full`. +Updating %%te%% from Cumulocity is the same process as installing any other software. You can update all of the %%te%% packages by installing a single package called `tedge-full`. Below shows instructions on how to update %%te%% to the latest version: @@ -114,7 +114,7 @@ If you are upgrading %%te%% from any version prior to `1.0.0` (including `1.0.0- ### Switching to Advanced Software Management -%%te%% supports both [Legacy Software Management](https://cumulocity.com/docs/device-integration/fragment-library/#legacy-software-management) and [Advanced Software Management](https://cumulocity.com/docs/device-integration/fragment-library/#advanced-software-management) features of Cumulocity IoT. +%%te%% supports both [Legacy Software Management](https://cumulocity.com/docs/device-integration/fragment-library/#legacy-software-management) and [Advanced Software Management](https://cumulocity.com/docs/device-integration/fragment-library/#advanced-software-management) features of Cumulocity. By default, Legacy Software Management is selected. To switch to Advanced Software Management, use the `tedge` command to change the following configurations: @@ -169,18 +169,18 @@ sudo tedge config set apt.maintainer '.*(thin-edge.io|other).*' The following contains frequently asked questions regarding the software management feature. -### Hosting linux packages in Cumulocity IoT +### Hosting linux packages in Cumulocity The recommended way to install linux packages such as deb, apk and rpm is to install packages directly from a configure package repository such as public repositories for your Operating System, or using a package service such as Cloudsmith, JFrog, Gemfury, Packagecloud etc. Using a package repository supports the full dependency resolution that users are familiar with when install packages manually, e.g. using `apt-get install mypackage`, and the correct architecture will be automatically selected for your device (e.g arm64/aarch or amd64/x86_64 etc.). -If you choose to host the software packages in Cumulocity IoT or via some other blob store, then the automatic dependency installation and architecture will not function so you have to manage all of this yourself. It might be manageable if you have simple packages with no dependencies and have an architecture agnostic package (e.g. the architecture is set to `all` or `noarch`). +If you choose to host the software packages in Cumulocity or via some other blob store, then the automatic dependency installation and architecture will not function so you have to manage all of this yourself. It might be manageable if you have simple packages with no dependencies and have an architecture agnostic package (e.g. the architecture is set to `all` or `noarch`). -When hosting the linux packages within Cumulocity IoT then ensure that: +When hosting the linux packages within Cumulocity then ensure that: * the package does not have any dependencies -* the name and version used in the Cumulocity IoT *Software repository* matches the exact information contained in the package's meta data +* the name and version used in the Cumulocity *Software repository* matches the exact information contained in the package's meta data - For example, below shows the `apt-cache show jq` information for the `jq` package where the **Package** and **Version** fields should match the **name** and **version** properties in Cumulocity IoT. + For example, below shows the `apt-cache show jq` information for the `jq` package where the **Package** and **Version** fields should match the **name** and **version** properties in Cumulocity. ``` Package: jq @@ -189,7 +189,7 @@ When hosting the linux packages within Cumulocity IoT then ensure that: ``` If the package name and version does not match, then the package might fail to be installed due to a validation error. -* the *Device type filter* property is set in the Cumulocity IoT Software repository if the packages is only valid for a specific CPU architecture. The *Device type filter* is used to filter which packages are available for different devices types to ensure you can only install compatible packages on a given device. +* the *Device type filter* property is set in the Cumulocity Software repository if the packages is only valid for a specific CPU architecture. The *Device type filter* is used to filter which packages are available for different devices types to ensure you can only install compatible packages on a given device.

Hosted binary diff --git a/versioned_docs/version-1.4.2/operate/c8y/supported-operations.md b/versioned_docs/version-1.4.2/operate/c8y/supported-operations.md index da66070..ebe65ae 100644 --- a/versioned_docs/version-1.4.2/operate/c8y/supported-operations.md +++ b/versioned_docs/version-1.4.2/operate/c8y/supported-operations.md @@ -14,7 +14,7 @@ IoT devices often do more than just send data to the cloud. They also do things * reboot on demand * install or remove software -These operations are supported by [Cumulocity IoT](https://cumulocity.com/guides/reference/device-management-library) and other cloud providers. +These operations are supported by [Cumulocity](https://cumulocity.com/docs/device-integration/fragment-library/) and other cloud providers. When such an operation is triggered from the cloud, the cloud mapper (e.g: `tedge-mapper-c8y`) processes that request. The Cumulocity mapper treats the following operations as inbuilt operations and converts those into their equivalent tedge commands: @@ -44,7 +44,7 @@ an operation with that name is supported by the tedge device on Cumulocity. For e.g, an empty file named `c8y_Restart` in this directory represents that the tedge device supports Cumulocity device restart operation. -The aggregated list of all the operation files in this directory represents the [Cumulocity supported operations list](https://cumulocity.com/guides/reference/device-management-library/#announcing-capabilities) of that device. +The aggregated list of all the operation files in this directory represents the [Cumulocity supported operations list](https://cumulocity.com/docs/device-integration/fragment-library/#announcing-capabilities) of that device. Whenever a new operation file is added to Similarly, an operation file at `/etc/tedge/operations/c8y/` indicates that diff --git a/versioned_docs/version-1.4.2/operate/configuration/index.md b/versioned_docs/version-1.4.2/operate/configuration/index.md index 6325239..f3342b3 100644 --- a/versioned_docs/version-1.4.2/operate/configuration/index.md +++ b/versioned_docs/version-1.4.2/operate/configuration/index.md @@ -7,7 +7,7 @@ description: How to configure %%te%% The settings of all the %%te%% components are grouped in the `/etc/tedge/tedge.toml` file, using [TOML](https://toml.io/). These configuration settings are organized in a hierarchy that reflects the component hierarchy. -For instance, all the settings related to Cumulocity IoT share a `c8y` prefix, such as `c8y.url` for the Cumulocity URL. +For instance, all the settings related to Cumulocity share a `c8y` prefix, such as `c8y.url` for the Cumulocity URL. This file can be edited directly and can even be extended to include plugin-specific settings. However, it's recommended to use the [`tedge config`](../../references/cli/tedge-config.md) command diff --git a/versioned_docs/version-1.4.2/operate/configuration/mapper-configuration.md b/versioned_docs/version-1.4.2/operate/configuration/mapper-configuration.md index 5e7b856..4fa30e8 100644 --- a/versioned_docs/version-1.4.2/operate/configuration/mapper-configuration.md +++ b/versioned_docs/version-1.4.2/operate/configuration/mapper-configuration.md @@ -12,7 +12,7 @@ The `tedge config` command and the keys `c8y.topics`, `az.topics`, and `aws.topi | Cloud | tedge config key | Environmental variable | systemctl service | |----------------|------------------|------------------------|-------------------| -| Cumulocity IoT | c8y.topics | TEDGE_C8Y_TOPICS | tedge-mapper-c8y | +| Cumulocity | c8y.topics | TEDGE_C8Y_TOPICS | tedge-mapper-c8y | | Azure IoT | az.topics | TEDGE_AZ_TOPICS | tedge-mapper-az | | AWS IoT | aws.topics | TEDGE_AWS_TOPICS | tedge-mapper-aws | @@ -36,7 +36,7 @@ tedge config get c8y.topics ## Set the desired new MQTT topics If you want to change the subscribed MQTT topics, use `tedge config set`. -For example, if you want the Cumulocity IoT mapper to subscribe only to `te/+/+/+/+/m/+` and `te/+/+/+/+/a/+` topic, +For example, if you want the Cumulocity mapper to subscribe only to `te/+/+/+/+/m/+` and `te/+/+/+/+/a/+` topic, the command to run should be as below. ```sh @@ -55,7 +55,7 @@ If an invalid MQTT topic is given, the mapper will ignore it. ::: The service must be restarted for the setting to take effect. -The following command shows how to restart the Cumulocity IoT mapper on a device using systemd as the init system. +The following command shows how to restart the Cumulocity mapper on a device using systemd as the init system. ```sh sudo systemctl restart tedge-mapper-c8y diff --git a/versioned_docs/version-1.4.2/operate/monitoring/systemd-watchdog.md b/versioned_docs/version-1.4.2/operate/monitoring/systemd-watchdog.md index 3bc638a..00d1587 100644 --- a/versioned_docs/version-1.4.2/operate/monitoring/systemd-watchdog.md +++ b/versioned_docs/version-1.4.2/operate/monitoring/systemd-watchdog.md @@ -69,7 +69,7 @@ The health check request for service is published to `te/device/main/service//status/health` topic. Once the health status response is received from a particular service, the `tedge-watchdog` service will send the -[systemd notification](https://www.freedesktop.org/software/systemd/man/sd_notify.html#) to systemd on behalf of that +[systemd notification](https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html) to systemd on behalf of that monitored service. :::note diff --git a/versioned_docs/version-1.4.2/operate/registration/deregister.md b/versioned_docs/version-1.4.2/operate/registration/deregister.md index b84e16f..1513432 100644 --- a/versioned_docs/version-1.4.2/operate/registration/deregister.md +++ b/versioned_docs/version-1.4.2/operate/registration/deregister.md @@ -1,7 +1,7 @@ --- title: Deregister entities tags: [Child-Device, Registration] -sidebar_position: 1 +sidebar_position: 2 description: Deregister child devices and services from %%te%% --- diff --git a/versioned_docs/version-1.4.2/operate/security/cloud-authentication.md b/versioned_docs/version-1.4.2/operate/security/cloud-authentication.md index e329456..a893333 100644 --- a/versioned_docs/version-1.4.2/operate/security/cloud-authentication.md +++ b/versioned_docs/version-1.4.2/operate/security/cloud-authentication.md @@ -14,8 +14,8 @@ A specific configuration will be required only for cloud endpoints which CA is n Several `tedge config` settings are used by %%te%% to locate the signing certificate of the cloud endpoint. -- `c8y.root_cert_path` The path where Cumulocity IoT root certificate(s) are stored (MQTT) -- `c8y.proxy.ca_path` The path where Cumulocity IoT root certificate(s) are stored (HTTP) +- `c8y.root_cert_path` The path where Cumulocity root certificate(s) are stored (MQTT) +- `c8y.proxy.ca_path` The path where Cumulocity root certificate(s) are stored (HTTP) - `aws.root_cert_path` The path where AWS IoT root certificate(s) are stored (MQTT). - `az.root_cert_path` The path where Azure IoT root certificate(s) are stored (MQTT). @@ -31,7 +31,7 @@ For the most part the store will be filled with certificates from your TLS/SSL p but if this is not the case you may need to update your local certificate store. :::note -Updating the local certificate store is notably required to connect Cumulocity IoT Edge, +Updating the local certificate store is notably required to connect Cumulocity Edge, as this distribution of Cumulocity uses self-signed certificates to authenticate itself. ::: diff --git a/versioned_docs/version-1.4.2/operate/security/cumulocity-token.md b/versioned_docs/version-1.4.2/operate/security/cumulocity-token.md index fd3b4d4..9a89e2d 100644 --- a/versioned_docs/version-1.4.2/operate/security/cumulocity-token.md +++ b/versioned_docs/version-1.4.2/operate/security/cumulocity-token.md @@ -1,22 +1,22 @@ --- -title: Cumulocity IoT Token +title: Cumulocity Token tags: [Operate, Security, Cumulocity, JWT] -description: Requesting a token for manual Cumulocity IoT API requests +description: Requesting a token for manual Cumulocity API requests --- :::tip -%%te%% provides an alternative way to access the Cumulocity IoT REST API without having to request a token. The [Cumulocity IoT Proxy Service](../../references/cumulocity-proxy.md) can be used which handles the authorization as required. +%%te%% provides an alternative way to access the Cumulocity REST API without having to request a token. The [Cumulocity Proxy Service](../../references/cumulocity-proxy.md) can be used which handles the authorization as required. -It is recommended to use the [Cumulocity IoT Proxy Service](../../references/cumulocity-proxy.md) where possible. +It is recommended to use the [Cumulocity Proxy Service](../../references/cumulocity-proxy.md) where possible. ::: ## Overview -For instances where you cannot use the [Cumulocity IoT Proxy Service](../../references/cumulocity-proxy.md), the following instructions detail how to manually request a token, and then how to use the token to make manual REST API calls to the Cumulocity IoT tenant. +For instances where you cannot use the [Cumulocity Proxy Service](../../references/cumulocity-proxy.md), the following instructions detail how to manually request a token, and then how to use the token to make manual REST API calls to the Cumulocity tenant. ## Retrieving the token -Follow the below steps in order to retrieve the token from Cumulocity IoT using MQTT. +Follow the below steps in order to retrieve the token from Cumulocity using MQTT. 1. Subscribe to the token topic @@ -36,12 +36,12 @@ Follow the below steps in order to retrieve the token from Cumulocity IoT using 71,${Base64 encoded JWT} ``` - Store the token as required (e.g. assign to a variable), and use in REST API request to the Cumulocity IoT tenant. + Store the token as required (e.g. assign to a variable), and use in REST API request to the Cumulocity tenant. :::note - Typically tokens are only valid for 1 hour (depending on your Cumulocity IoT settings), so you will need to request a new token before it expires otherwise your API Requests will return an Unauthorized (401) error. + Typically tokens are only valid for 1 hour (depending on your Cumulocity settings), so you will need to request a new token before it expires otherwise your API Requests will return an Unauthorized (401) error. - The expiration timestamp, issuer (Cumulocity IoT URL), and tenant are encoded in the token and can be decoded using the standard [JSON Web Token Standard](https://datatracker.ietf.org/doc/html/rfc7519) which there should be a library in most popular programming languages. + The expiration timestamp, issuer (Cumulocity URL), and tenant are encoded in the token and can be decoded using the standard [JSON Web Token Standard](https://datatracker.ietf.org/doc/html/rfc7519) which there should be a library in most popular programming languages. ::: ### Alternative: Retrieving the token using mosquitto_rr @@ -77,33 +77,33 @@ Where: * `-e` represents the response topic which will print the message on the console -## Using token in REST API calls to Cumulocity IoT +## Using token in REST API calls to Cumulocity -The retrieved token can be used to make HTTP calls to the [Cumulocity IoT REST API](https://cumulocity.com/api/core/). +The retrieved token can be used to make HTTP calls to the [Cumulocity REST API](https://cumulocity.com/api/core/). -For simplicity, this example will retrieve the Cumulocity IoT URL via the tedge cli command. If you are using a higher level programming language like python3, then you get the Cumulocity IoT URL by decoding the token, e.g. using [PyJWT](https://pyjwt.readthedocs.io/en/latest/). +For simplicity, this example will retrieve the Cumulocity URL via the tedge cli command. If you are using a higher level programming language like python3, then you get the Cumulocity URL by decoding the token, e.g. using [PyJWT](https://pyjwt.readthedocs.io/en/latest/). The following code snippet does the following steps: -1. Get the Cumulocity IoT URL (using `tedge`) +1. Get the Cumulocity URL (using `tedge`) 2. Get the token (using `mosquitto_rr`) 3. Send a request (using `curl`) ```sh -# Get the Cumulocity IoT URL +# Get the Cumulocity URL export C8Y_URL="https://$(tedge config get c8y.url)" # Get the token (using mosquitto_rr cli command) export C8Y_TOKEN=$(mosquitto_rr -t c8y/s/uat -e c8y/s/dat -m '' | cut -d, -f2-) -# Send a REST API call to Cumulocity IoT +# Send a REST API call to Cumulocity curl -s -H "Authorization: Bearer $C8Y_TOKEN" \ -H "Accept: application/json" \ "$C8Y_URL/user/currentUser" ``` :::tip -The same functionality (as above) can be achieved by using the [Cumulocity IoT Proxy Service](../../references/cumulocity-proxy.md): +The same functionality (as above) can be achieved by using the [Cumulocity Proxy Service](../../references/cumulocity-proxy.md): ```sh curl -s -H "Accept: application/json" \ diff --git a/versioned_docs/version-1.4.2/operate/security/device-certificate.md b/versioned_docs/version-1.4.2/operate/security/device-certificate.md index aac7f67..0baad1e 100644 --- a/versioned_docs/version-1.4.2/operate/security/device-certificate.md +++ b/versioned_docs/version-1.4.2/operate/security/device-certificate.md @@ -67,7 +67,7 @@ must be added to the list of trusted signing certificate. This process is cloud dependent. See the respective documentation of the cloud you're trying to connect to for details on how to add a new signing certificate: -- [Cumulocity IoT: Managing trusted certificates](https://cumulocity.com/guides/users-guide/device-management/#managing-trusted-certificates) +- [Cumulocity: Managing trusted certificates](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-trusted-certificates) - [Understand how Azure IoT Edge uses certificates](https://learn.microsoft.com/en-us/azure/iot-edge/iot-edge-certs) - [AWS IoT: X.509 client certificates](https://docs.aws.amazon.com/iot/latest/developerguide/x509-client-certs.html) diff --git a/versioned_docs/version-1.4.2/operate/security/https-configuration.md b/versioned_docs/version-1.4.2/operate/security/https-configuration.md index 27848c7..71f72a0 100644 --- a/versioned_docs/version-1.4.2/operate/security/https-configuration.md +++ b/versioned_docs/version-1.4.2/operate/security/https-configuration.md @@ -6,7 +6,7 @@ description: Setting up HTTPS for secure local communication %%te%% provides two services over HTTP: - The [File Transfer Service](../../references/file-transfer-service.md) is used by the mappers and the child devices to transfer files locally. -- The [Cumulocity Proxy](../../references/cumulocity-proxy.md) acts as a local proxy to the Cumulocity IoT REST API. +- The [Cumulocity Proxy](../../references/cumulocity-proxy.md) acts as a local proxy to the Cumulocity REST API. Three levels of security are supported: @@ -31,8 +31,8 @@ curl http://localhost:8000/tedge/file-transfer/foo.txt ### Cumulocity Proxy -When a device is successfully connected to Cumulocity IoT, -**tedge-mapper** acts as a proxy to the Cumulocity IoT REST API. +When a device is successfully connected to Cumulocity, +**tedge-mapper** acts as a proxy to the Cumulocity REST API. For instance, the following lists the managed objects related to the device: ```sh @@ -40,12 +40,12 @@ curl http://localhost:8001/c8y/inventory/managedObjects ``` :::note -The connection from the Cumulocity Proxy to Cumulocity IoT is always established over HTTPS, +The connection from the Cumulocity Proxy to Cumulocity is always established over HTTPS, whatever the settings for local connections. The identity of the Cumulocity end-point is authenticated using the root certificates configured with `tedge config get c8y.proxy.ca_path` and the device itself -is authenticated using JWT tokens retrieved from Cumulocity IoT via MQTT. +is authenticated using JWT tokens retrieved from Cumulocity via MQTT. ::: ## Open HTTP services on the local network diff --git a/versioned_docs/version-1.4.2/operate/troubleshooting/device-monitoring.md b/versioned_docs/version-1.4.2/operate/troubleshooting/device-monitoring.md index db2a345..9d6f3ad 100644 --- a/versioned_docs/version-1.4.2/operate/troubleshooting/device-monitoring.md +++ b/versioned_docs/version-1.4.2/operate/troubleshooting/device-monitoring.md @@ -50,13 +50,13 @@ sudo systemctl start tedge-mapper-collectd tedge mqtt sub 'te/device/main///m/+' ``` -## Are the collectd metrics published to Cumulocity IoT? +## Are the collectd metrics published to Cumulocity? ```sh te2mqtt formats=v1 tedge mqtt sub 'c8y/#' ``` -If not see how to [connect a device to Cumulocity IoT](../../start/connect-c8y.md). +If not see how to [connect a device to Cumulocity](../../start/connect-c8y.md). ## Are the collectd metrics published to Azure IoT? diff --git a/versioned_docs/version-1.4.2/operate/troubleshooting/log-files.md b/versioned_docs/version-1.4.2/operate/troubleshooting/log-files.md index c19e6a0..9503f09 100644 --- a/versioned_docs/version-1.4.2/operate/troubleshooting/log-files.md +++ b/versioned_docs/version-1.4.2/operate/troubleshooting/log-files.md @@ -119,19 +119,22 @@ level in `system.toml` ### Setting the log level through cli {#configure-log-levels-cli} -The log level can be enabled for a %%te%% service as below - -For example for tedge-mapper: +The log-level can be configured for a %%te%% service using the `--log-level` +argument. For example for tedge-mapper: ```sh -sudo -u tedge -- tedge-mapper --debug c8y +sudo -u tedge -- tedge-mapper c8y --log-level debug ``` +The possible values for `--log-level` are `trace`, `debug`, `info` (the +default), `warn` and `error`. + :::note -In a similar way it can be set for all the %%te%% services. -Only `debug` level can be set through cli. Also, it enables `trace` level. +In a similar way it can be set for all the %%te%% services and the `tedge` CLI. ::: +There is also a `--debug` argument, which is shorthand for `--log-level debug`. + ### Setting log level through system.toml {#configure-log-levels-file} The log levels can also be configured through the `system.toml` file. The supported log levels are `info, warn, error, trace, debug`. diff --git a/versioned_docs/version-1.4.2/operate/troubleshooting/testing-cloud-connection.md b/versioned_docs/version-1.4.2/operate/troubleshooting/testing-cloud-connection.md index e7a78be..c7cb651 100644 --- a/versioned_docs/version-1.4.2/operate/troubleshooting/testing-cloud-connection.md +++ b/versioned_docs/version-1.4.2/operate/troubleshooting/testing-cloud-connection.md @@ -21,9 +21,9 @@ This test is already performed as part of the `tedge connect ` command. The connection test sends a message to the cloud and waits for a response. The subsequent sections explain the cloud-specific behaviour. -### For Cumulocity IoT +### For Cumulocity -The test publishes [a SmartREST 2.0 static template message for device creation `100`](https://cumulocity.com/guides/device-sdk/mqtt/#a-nameinventory-templatesinventory-templates-1xxa) to the topic `c8y/s/us`. +The test publishes [a SmartREST 2.0 static template message for device creation `100`](https://cumulocity.com/docs/smartrest/mqtt-static-templates/#100) to the topic `c8y/s/us`. If the device-twin is already created in your Cumulocity, the device is supposed to receive `41,100,Device already existing` on the error topic `c8y/s/e`. diff --git a/versioned_docs/version-1.4.2/overview.md b/versioned_docs/version-1.4.2/overview.md index dc0f801..c96c246 100644 --- a/versioned_docs/version-1.4.2/overview.md +++ b/versioned_docs/version-1.4.2/overview.md @@ -27,14 +27,14 @@ and need to be secured, configured and updated at scale. The easiest way to get started is either to install the docker based [demo container](https://github.com/thin-edge/tedge-demo-container) that showcases %%te%% and all its features or with the [beginner-friendly tutorial](start/getting-started.md) that introduces %%te%% and guides you on how to install it on a Raspberry Pi. -After the installation you can directly connect your device to [Cumulocity IoT](https://www.cumulocity.com/guides/concepts/introduction/), +After the installation you can directly connect your device to [Cumulocity](https://cumulocity.com/docs/concepts/introduction/), and then monitor it from the cloud. You can also explore the main use-cases using these [tutorials](start/index.md). You will learn to: - [install %%te%% on your specific hardware](install/index.md), -- connect your device to your cloud, whether [Cumulocity IoT](start/connect-c8y.md), +- connect your device to your cloud, whether [Cumulocity](start/connect-c8y.md), [Azure IoT](start/connect-azure.md) or [AWS IoT](start/connect-aws.md), - [send telemetry data](start//send-measurements.md), [alarms](start//raise-alarm.md) and [events](start//send-events.md), - operate, configure, update, monitor your device. diff --git a/versioned_docs/version-1.4.2/references/agent/software-management.md b/versioned_docs/version-1.4.2/references/agent/software-management.md index 6bc14b3..5b6a526 100644 --- a/versioned_docs/version-1.4.2/references/agent/software-management.md +++ b/versioned_docs/version-1.4.2/references/agent/software-management.md @@ -150,7 +150,7 @@ tedge mqtt pub --retain 'te/device/child001///cmd/software_update' '{ ``` :::info -The software types are currently not sent to the cloud (e.g. Cumulocity IoT), however this is planned in a future release. +The software types are currently not sent to the cloud (e.g. Cumulocity), however this is planned in a future release. ::: ### init state diff --git a/versioned_docs/version-1.4.2/references/configuration-files.md b/versioned_docs/version-1.4.2/references/configuration-files.md index 565da70..e686fce 100644 --- a/versioned_docs/version-1.4.2/references/configuration-files.md +++ b/versioned_docs/version-1.4.2/references/configuration-files.md @@ -164,7 +164,7 @@ This is a two step process. ### Step 1: Update the mosquitto.conf -Since the bridge configuration files for Cumulocity IoT, Azure IoT Hub or AWS IoT will be created in a directory given through `--config-dir`, +Since the bridge configuration files for Cumulocity, Azure IoT Hub or AWS IoT will be created in a directory given through `--config-dir`, the path to the bridge configuration files (tedge-mosquitto.conf, c8y/az/aws-bridge.conf) must be found by `mosquitto`. So, the below line has to be added to your `mosquitto.conf` file manually. @@ -174,7 +174,7 @@ include_dir /global/path/to/config/dir/tedge/mosquitto-conf ### Step 2: tedge connect using a custom config directory -Use the below command to connect to `Cumulocity IoT, Azure IoT Hub or AWS IoT` cloud using `--config-dir` +Use the below command to connect to `Cumulocity, Azure IoT Hub or AWS IoT` cloud using `--config-dir` ```sh sudo tedge --config-dir /global/path/to/config/dir connect c8y/az/aws diff --git a/versioned_docs/version-1.4.2/references/cumulocity-proxy.md b/versioned_docs/version-1.4.2/references/cumulocity-proxy.md index 2039248..1dc2502 100644 --- a/versioned_docs/version-1.4.2/references/cumulocity-proxy.md +++ b/versioned_docs/version-1.4.2/references/cumulocity-proxy.md @@ -2,7 +2,7 @@ title: Cumulocity Proxy tags: [ Reference, HTTP, Cumulocity ] sidebar_position: 12 -description: Using the Cumulocity IoT Proxy for full access to Cumulocity API +description: Using the Cumulocity Proxy for full access to Cumulocity API --- The `tedge-mapper` (when running in `c8y` mode) hosts a proxy server to access the Cumulocity HTTP API from the diff --git a/versioned_docs/version-1.4.2/references/mappers/c8y-mapper.md b/versioned_docs/version-1.4.2/references/mappers/c8y-mapper.md index 235ef69..9cff893 100644 --- a/versioned_docs/version-1.4.2/references/mappers/c8y-mapper.md +++ b/versioned_docs/version-1.4.2/references/mappers/c8y-mapper.md @@ -5,7 +5,7 @@ sidebar_position: 1 --- The Cumulocity mapper, referred to as `c8y-mapper` in the rest of this document, -maps data in [%%te%% format](../mqtt-api.md) into their equivalent [Cumulocity format](https://cumulocity.com/guides/reference/smartrest-two/#smartrest-two). +maps data in [%%te%% format](../mqtt-api.md) into their equivalent [Cumulocity format](https://cumulocity.com/docs/smartrest/smartrest-two/). ## Registration @@ -42,7 +42,7 @@ te/device/child01//

-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/s/us @@ -80,7 +80,7 @@ te/device/child01//
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/s/us @@ -118,7 +118,7 @@ te/device/nested_child01//
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/s/us/:device:child01 @@ -153,7 +153,7 @@ te/device/main/service/nodered
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/s/us @@ -188,7 +188,7 @@ te/device/child01/service/nodered
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/s/us/:device:child01 @@ -272,7 +272,7 @@ te/device/main///m/environment
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/measurement/measurements/create @@ -313,7 +313,7 @@ te/device/main///m/
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/measurement/measurements/create @@ -354,7 +354,7 @@ te/device/child01///m/
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/measurement/measurements/create @@ -399,7 +399,7 @@ te/device/main///e/login_event
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/s/us @@ -437,7 +437,7 @@ te/device/main///e/login_event
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/event/events/create @@ -484,7 +484,7 @@ te/device/main///a/temperature_high
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/s/us @@ -523,7 +523,7 @@ te/device/main///a/pressure_alarm
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/alarm/alarms/create @@ -570,7 +570,7 @@ te/device/main/service/my-service/status/health
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/s/us/ @@ -585,7 +585,7 @@ c8y/s/us/ ## Twin -The `twin` metadata is mapped to [inventory data](https://cumulocity.com/guides/concepts/domain-model/#inventory) in Cumulocity. +The `twin` metadata is mapped to [inventory data](https://cumulocity.com/docs/concepts/domain-model/#inventory) in Cumulocity. #### Twin - Main device @@ -612,7 +612,7 @@ te/device/main///twin/device_OS
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/inventory/managedObjects/update/ @@ -651,7 +651,7 @@ te/device/child01///twin/device_OS
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/inventory/managedObjects/update/:device:child01 @@ -689,7 +689,7 @@ te/device/main/service/tedge-agent/twin/runtime_stats
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/inventory/managedObjects/update/:device:main:service:tedge-agent @@ -728,7 +728,7 @@ te/device/child01/service/tedge-agent/twin/runtime_stats
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/inventory/managedObjects/update/:device:child01:service:tedge-agent @@ -768,7 +768,7 @@ te/device/main///twin/subtype
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/inventory/managedObjects/update/ @@ -810,7 +810,7 @@ te/device/child01/service/tedge-agent/twin/runtime_stats
-**Cumulocity IoT (output)** +**Cumulocity (output)** ```text title="Topic" c8y/inventory/managedObjects/update/:device:child01:service:tedge-agent @@ -983,7 +983,7 @@ are also mapped to their corresponding _supported logs_ and _supported configs_
-**Cumulocity IoT (input)** +**Cumulocity (input)** ```text title="Topic" c8y/s/ds @@ -1019,7 +1019,7 @@ the mapper recognizes and maps only the following `status` values as follows: - + @@ -1114,7 +1114,7 @@ All other `status` values are just ignored.
-**Cumulocity IoT (input)** +**Cumulocity (input)** ```text title="Topic" c8y/s/ds @@ -1144,7 +1144,7 @@ te/device/child01///cmd/restart
-**Cumulocity IoT (input)** +**Cumulocity (input)** ```text title="Topic" c8y/s/ds @@ -1202,7 +1202,7 @@ and the local `` of that binary is included in the mapped request.
-**Cumulocity IoT (input)** +**Cumulocity (input)** ```text title="Topic" c8y/s/ds @@ -1238,7 +1238,7 @@ Where the `url` is the target URL in the tedge file transfer repository to which
-**Cumulocity IoT (input)** +**Cumulocity (input)** ```text title="Topic" c8y/s/ds @@ -1275,7 +1275,7 @@ and the local `` of that binary is included in the mapped request.
-**Cumulocity IoT (input)** +**Cumulocity (input)** ```text title="Topic" c8y/s/ds diff --git a/versioned_docs/version-1.4.2/references/mappers/mqtt-topics.md b/versioned_docs/version-1.4.2/references/mappers/mqtt-topics.md index 9007589..3df7c7b 100644 --- a/versioned_docs/version-1.4.2/references/mappers/mqtt-topics.md +++ b/versioned_docs/version-1.4.2/references/mappers/mqtt-topics.md @@ -52,7 +52,7 @@ The topics follow the below format c8y/error You can find more information about Cumulocity topics -[Here](https://tech.forums.softwareag.com/t/cumulocity-iot-tips-and-tricks-mqtt-cheat-sheet/237187) +[Here](https://cumulocity.com/docs/smartrest/mqtt-static-templates/) ## Azure MQTT Topics diff --git a/versioned_docs/version-1.4.2/references/supported-platforms.md b/versioned_docs/version-1.4.2/references/supported-platforms.md index fa2542e..701d936 100644 --- a/versioned_docs/version-1.4.2/references/supported-platforms.md +++ b/versioned_docs/version-1.4.2/references/supported-platforms.md @@ -10,7 +10,7 @@ description: List of supported platforms, CPU architectures and resource usage In addition to a Linux based Operation system, the following requirements must also be fulfilled: * At least ~40MB of RAM on the gateway device, ~8MB on a child device (see [notes](#memory-usage)) -* [mosquitto](https://github.com/eclipse/mosquitto) MQTT Broker (see [notes](#recommended-mosquitto-version)) +* [mosquitto](https://github.com/eclipse-mosquitto/mosquitto) MQTT Broker (see [notes](#recommended-mosquitto-version)) :::tip If you are looking for new hardware it is highly recommended to choose a CPU which has at least 2 cores, as it provides a much more responsive experience and should provide enough processing headroom for future requirements. diff --git a/versioned_docs/version-1.4.2/start/connect-aws.md b/versioned_docs/version-1.4.2/start/connect-aws.md index e973cd8..67eb5dc 100644 --- a/versioned_docs/version-1.4.2/start/connect-aws.md +++ b/versioned_docs/version-1.4.2/start/connect-aws.md @@ -28,7 +28,7 @@ The very first step to enable %%te%% is to connect your device to the cloud. * Sending data to the cloud will then be as simple as sending data locally. The focus is here on connecting the device to AWS IoT. -See this [tutorial](connect-c8y.md), if you want to connect Cumulocity IoT instead. +See this [tutorial](connect-c8y.md), if you want to connect Cumulocity instead. See this [tutorial](connect-azure.md), if you want to connect Azure IoT instead. Before you try to connect your device to AWS IoT, you need: diff --git a/versioned_docs/version-1.4.2/start/connect-azure.md b/versioned_docs/version-1.4.2/start/connect-azure.md index 9d3c222..6889671 100644 --- a/versioned_docs/version-1.4.2/start/connect-azure.md +++ b/versioned_docs/version-1.4.2/start/connect-azure.md @@ -25,11 +25,11 @@ The very first step to enable %%te%% is to connect your device to the cloud. * Sending data to the cloud will then be as simple as sending data locally. The focus is here on connecting the device to Azure IoT. -See this [tutorial](connect-c8y.md), if you want to connect Cumulocity IoT instead. +See this [tutorial](connect-c8y.md), if you want to connect Cumulocity instead. See this [tutorial](connect-aws.md), if you want to connect AWS IoT instead. Before you try to connect your device to Azure IoT, you need: -* Create a Azure **IoT Hub** in Azure portal as described [here](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-create-through-portal). +* Create a Azure **IoT Hub** in Azure portal as described [here](https://learn.microsoft.com/en-us/azure/iot-hub/create-hub). * [Install %%te%% on your device](../install/index.md). You can now use [`tedge` command](../references/cli/index.md) to: @@ -103,7 +103,7 @@ Here provide the configuration parameters that are required to create the device Upon successfully saved the configuration a new device has been created on the IoT Hub. The new device can be seen on the IoT Hub portal by navigating to **Explores** → **IoT Devices**. -More info about registering a device can be found [here](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-authenticate-downstream-device?view=iotedge-2018-06) +More info about registering a device can be found [here](https://learn.microsoft.com/en-us/azure/iot-edge/how-to-authenticate-downstream-device?view=iotedge-2018-06) ## Configure the device {#configure} @@ -224,9 +224,9 @@ Alternatively, post your own custom messages on `az/messages/events/#` topic: tedge mqtt pub az/messages/events/ '{"text": "My message"}' ``` -To view the messages that were sent from the device to the cloud, follow this [document](https://docs.microsoft.com/en-us/azure/iot-hub/quickstart-send-telemetry-cli#create-and-monitor-a-device). +To view the messages that were sent from the device to the cloud, follow this [document](https://learn.microsoft.com/en-us/azure/iot-hub/quickstart-send-telemetry-cli#create-and-monitor-a-device). -More info about sending telemetry to Azure can be found [here](https://docs.microsoft.com/en-us/azure/iot-hub/quickstart-send-telemetry-dotnet) +More info about sending telemetry to Azure can be found [here](https://learn.microsoft.com/en-us/azure/iot/tutorial-send-telemetry-iot-hub) ## Next Steps diff --git a/versioned_docs/version-1.4.2/start/connect-c8y.md b/versioned_docs/version-1.4.2/start/connect-c8y.md index d8903b8..2a362dc 100644 --- a/versioned_docs/version-1.4.2/start/connect-c8y.md +++ b/versioned_docs/version-1.4.2/start/connect-c8y.md @@ -1,8 +1,8 @@ --- -title: Connecting to Cumulocity IoT +title: Connecting to Cumulocity tags: [Getting Started, Cumulocity, Connection] sidebar_position: 2 -description: Connect %%te%% to Cumulocity IoT and publish telemetry data +description: Connect %%te%% to Cumulocity and publish telemetry data --- import UserContext from '@site/src/components/UserContext'; @@ -24,11 +24,11 @@ The very first step to enable %%te%% is to connect your device to the cloud. * This connection is secure (encrypted over TLS), and the two peers are identified by x509 certificates. * Sending data to the cloud will then be as simple as sending data locally. -The focus is here on connecting to [Cumulocity IoT](https://www.cumulocity.com/guides/concepts/introduction/). +The focus is here on connecting to [Cumulocity](https://cumulocity.com/docs/sector/getting_started/). See this [tutorial](connect-azure.md), if you want to connect Azure IoT instead. See this [tutorial](connect-aws.md), if you want to connect AWS IoT instead. -Before you try to connect your device to Cumulocity IoT, you need: +Before you try to connect your device to Cumulocity, you need: * The url of the endpoint to connect (e.g. `eu-latest.cumulocity.com`). * Your credentials to connect Cumulocity: * Your tenant identifier (e.g. `t00000007`), a user name and password. @@ -45,9 +45,9 @@ You can now use the [`tedge` command](../references/cli/index.md) to: ## Configure the device -To connect the device to the Cumulocity IoT, one needs to set the URL of your Cumulocity IoT tenant and the root certificate as below. +To connect the device to the Cumulocity, one needs to set the URL of your Cumulocity tenant and the root certificate as below. -Set the URL of your Cumulocity IoT tenant. +Set the URL of your Cumulocity tenant. @@ -63,13 +63,13 @@ Set the path to the root certificate if necessary. The default is `/etc/ssl/cert sudo tedge config set c8y.root_cert_path /etc/ssl/certs ``` -This will set the root certificate path of the Cumulocity IoT. +This will set the root certificate path of the Cumulocity. In most of the Linux flavors, the certificate will be present in `/etc/ssl/certs`. If not found download it from [here](https://www.identrust.com/dst-root-ca-x3). ### Custom domain -If you are using the Cumulocity Iot [custom domain feature](https://cumulocity.com/docs/enterprise-tenant/customization/#domain-name), then you need to set two urls instead of one, as the HTTP and MQTT endpoints on custom domains are different because the custom domain only applies to the HTTP endpoint. The MQTT endpoint must point to the underlying Cumulocity IoT instance. +If you are using the Cumulocity [custom domain feature](https://cumulocity.com/docs/enterprise-tenant/customization/#domain-name), then you need to set two urls instead of one, as the HTTP and MQTT endpoints on custom domains are different because the custom domain only applies to the HTTP endpoint. The MQTT endpoint must point to the underlying Cumulocity instance. For example, below shows setting the HTTP and MQTT endpoints: @@ -97,7 +97,7 @@ curl -sfL https://$C8Y_URL/tenant/loginOptions | jq -r '.loginOptions[] | select ## Connecting to Cumulocity server signed with self-signed certificate -If the Cumulocity IoT instance that you're connecting to, is signed with a self-signed certificate(eg: Cumulocity IoT Edge instance), +If the Cumulocity instance that you're connecting to, is signed with a self-signed certificate(eg: Cumulocity Edge instance), then the path to that server certificate must be set as the c8y.root_cert_path as follows: ```sh @@ -204,32 +204,32 @@ Caused by: #### 401 - Unauthorized -The 401 (Unauthorized) error means either the user and/or password is invalid for the configured Cumulocity IoT url that was set in the `tedge config set c8y.url ` command. +The 401 (Unauthorized) error means either the user and/or password is invalid for the configured Cumulocity url that was set in the `tedge config set c8y.url ` command. Check the following items to help you diagnose the root cause of the problem: -* Check the configured `c8y.url`. Copy/paste the url into a Web Browser to validate that it does open the intended Cumulocity IoT tenant -* Check your username. The user/email is case-sensitive, so make sure the user matches your configured Cumulocity IoT user +* Check the configured `c8y.url`. Copy/paste the url into a Web Browser to validate that it does open the intended Cumulocity tenant +* Check your username. The user/email is case-sensitive, so make sure the user matches your configured Cumulocity user * Check your password. Use copy/paste to enter your password as this eliminates typos -* Check that you are not using a SSO user. SSO users are not permitted to use the REST API calls which the `tedge cert upload c8y` command is using. Please create a new Cumulocity IoT user via the [Administration Page](https://cumulocity.com/guides/users-guide/administration/#to-add-a-user) +* Check that you are not using a SSO user. SSO users are not permitted to use the REST API calls which the `tedge cert upload c8y` command is using. Please create a new Cumulocity user via the [Administration Page](https://cumulocity.com/docs/standard-tenant/managing-users/#to-add-a-user) #### 403 - Forbidden -The 403 (Forbidden) error means that your user/password is correct however you do not have sufficient permissions to add the %%te%%'s device certificate to the Cumulocity IoT's [Trusted certificates](https://cumulocity.com/guides/device-integration/mqtt/#device-certificates). +The 403 (Forbidden) error means that your user/password is correct however you do not have sufficient permissions to add the %%te%%'s device certificate to the Cumulocity's [Trusted certificates](https://cumulocity.com/docs/device-integration/device-certificates/). -Your Cumulocity IoT user **MUST** be assigned the **Tenant Manager** Global Role in order to add new trusted certificates to Cumulocity IoT. Global roles can be assigned to users via the Cumulocity IoT **Administration** application under Accounts → Users → `` → Global Roles section. Below shows a screenshot of the **Tenant Manager** role that your user needs to be assigned to. +Your Cumulocity user **MUST** be assigned the **Tenant Manager** Global Role in order to add new trusted certificates to Cumulocity. Global roles can be assigned to users via the Cumulocity **Administration** application under Accounts → Users → `` → Global Roles section. Below shows a screenshot of the **Tenant Manager** role that your user needs to be assigned to. ![User Global Roles](./c8y-user-globl-roles.png) -Alternatively, you can explicitly add one of the following permissions to your Cumulocity IoT user: `ROLE_TENANT_MANAGEMENT_ADMIN` OR `ROLE_TENANT_ADMIN`, however this method requires you to be familiar with the [Cumulocity IoT OpenAPI](https://cumulocity.com/api/core/#operation/postTrustedCertificateCollectionResource). +Alternatively, you can explicitly add one of the following permissions to your Cumulocity user: `ROLE_TENANT_MANAGEMENT_ADMIN` OR `ROLE_TENANT_ADMIN`, however this method requires you to be familiar with the [Cumulocity OpenAPI](https://cumulocity.com/api/core/#operation/postTrustedCertificateCollectionResource). -If you are still having trouble, please check out the official [Cumulocity IoT documentation](https://cumulocity.com/guides/device-integration/mqtt/#upload-your-ca-certificate). +If you are still having trouble, please check out the official [Cumulocity documentation](https://cumulocity.com/docs/device-integration/device-certificates/#upload-your-ca-certificate). #### Address is unreachable -If you are unable to reach Cumulocity IoT, then it is likely that your device's network is not properly configured. This could be for many different reasons, however the following checks might help you spot where the mistake is: +If you are unable to reach Cumulocity, then it is likely that your device's network is not properly configured. This could be for many different reasons, however the following checks might help you spot where the mistake is: * Can you ping a well known DNS server? @@ -362,7 +362,7 @@ Persisting tedge-agent on reboot. tedge-agent service successfully started and enabled! ``` -If the device certificate is trusted by Cumulocity IoT, the %%te%% instance will automatically connect to the cloud once connectivity is restored. +If the device certificate is trusted by Cumulocity, the %%te%% instance will automatically connect to the cloud once connectivity is restored. ## Sending your first telemetry data diff --git a/versioned_docs/version-1.4.2/start/device-monitoring.md b/versioned_docs/version-1.4.2/start/device-monitoring.md index 3de2aa6..f5c4d50 100644 --- a/versioned_docs/version-1.4.2/start/device-monitoring.md +++ b/versioned_docs/version-1.4.2/start/device-monitoring.md @@ -12,7 +12,7 @@ Using these metrics, you can monitor the health of devices and can proactively initiate actions in case the device seems to malfunction. Additionally, the metrics can be used to help the customer troubleshoot when problems with the device are reported. -%%te%% uses the open source component [collectd](https://collectd.org/) to collect the metrics from the device. +%%te%% uses the open source component [collectd](https://www.collectd.org/) to collect the metrics from the device. %%te%% translates the `collectd` metrics from their native format to the [%%te%% JSON](../understand/thin-edge-json.md) format and then into the [cloud-vendor specific format](../understand/tedge-mapper.md). @@ -20,7 +20,7 @@ and then into the [cloud-vendor specific format](../understand/tedge-mapper.md). ## Install -Device monitoring is not enabled by default, however it can be enabled using a community package, [tedge-collectd-setup](https://cloudsmith.io/~thinedge/repos/community/packages/?q=name%3A%27%5Etedge-collectd-setup%24%27), which will install [collectd](https://collectd.org/) and configure some sensible defaults including monitoring of cpu, memory and disk metrics. +Device monitoring is not enabled by default, however it can be enabled using a community package, [tedge-collectd-setup](https://cloudsmith.io/~thinedge/repos/community/packages/?q=name%3A%27%5Etedge-collectd-setup%24%27), which will install [collectd](https://www.collectd.org/) and configure some sensible defaults including monitoring of cpu, memory and disk metrics. ```sh tab={"label":"Debian/Ubuntu"} sudo apt-get install tedge-collectd-setup @@ -50,13 +50,13 @@ You can further customize the default collectd configuration by editing the foll /etc/collectd/collectd.conf ``` -Details about collectd plugins and their configuration can be viewed directly from the [collectd documentation](https://collectd.org/documentation/manpages/collectd.conf.html). +Details about collectd plugins and their configuration can be viewed directly from the [collectd documentation](https://www.collectd.org/documentation/manpages/collectd.conf.html). However keep in mind the following points when editing the file: 1. __MQTT must be enabled__. * %%te%% expects the `collectd` metrics to be published on the local MQTT bus. - Hence, you must enable the [MQTT write plugin of collectd](https://collectd.org/documentation/manpages/collectd.conf.html#plugin-mqtt). + Hence, you must enable the [MQTT write plugin of collectd](https://www.collectd.org/documentation/manpages/collectd.conf.html). * The MQTT plugin is available on most distribution of `collectd`, but this is not the case on MacOS using homebrew. If you are missing the MQTT plugin, please recompile `collectd` to include the MQTT plugin. See [https://github.com/collectd/collectd](https://github.com/collectd/collectd) for details. diff --git a/versioned_docs/version-1.4.2/start/getting-started.md b/versioned_docs/version-1.4.2/start/getting-started.md index bd79d3b..5dc95f9 100644 --- a/versioned_docs/version-1.4.2/start/getting-started.md +++ b/versioned_docs/version-1.4.2/start/getting-started.md @@ -17,7 +17,7 @@ You can customize the documentation and commands shown on this page by providing 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. +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 and performing some additional device management tasks. ## Introduction @@ -30,7 +30,7 @@ The Raspberry PI is a relatively simple and cheap device but powerful. Therefore ## Prerequisite To follow this guide, you only need the following: -- A [Cumulocity IoT](https://cumulocity.com/pages/free-trial/) Trial tenant. +- A [Cumulocity](https://www.cumulocity.com/start-your-journey/free-trial/) Trial tenant. - A Raspberry Pi (any model is fine) with RaspberryPi OS installed, for other boards and OS'es have a look [here](../references/supported-platforms.md) - Updated device @@ -43,10 +43,10 @@ To follow this guide, you only need the following: ## Steps -This tutorial is divided into small steps. The first three steps are needed to install and connect to Cumulocity IoT. The last three are optional but needed to get a good overview of the capabilities of %%te%%. +This tutorial is divided into small steps. The first three steps are needed to install and connect to Cumulocity. The last three are optional but needed to get a good overview of the capabilities of %%te%%. - [Step 1 Install %%te%%](#step-1-install-thin-edgeio) -- [Step 2 Configure and Connect to Cumulocity IoT](#step-2-configure-and-connect-to-cumulocity-iot) +- [Step 2 Configure and Connect to Cumulocity](#step-2-configure-and-connect-to-cumulocity) - [Step 3 Sending Device Data](#step-3-sending-device-data) - [Step 4 Monitor the device](#step-4-monitor-the-device) - [Step 5 Add software management](#step-5-add-software-management) @@ -116,9 +116,9 @@ Here is an [overview of the commands for the CLI tool](../references/cli/index.m The CLI will be used to configure the %%te%% installation on the device in the next steps. -## Step 2 Configure and Connect to Cumulocity IoT +## Step 2 Configure and Connect to Cumulocity -To connect the device to the Cumulocity IoT it needs to be configured. +To connect the device to the Cumulocity 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: @@ -132,9 +132,9 @@ sudo tedge config set c8y.url "$C8Y_URL" ### 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. +%%te%% connects via MQTT protocol using a X.509 certificate for authentication. To do so, a certificate must be trusted by Cumulocity. 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). +First, we need to create the device certificate locally (If the device certificate is already uploaded, directly via the UI to Cumulocity this step can be skipped). @@ -146,7 +146,7 @@ sudo tedge cert create --device-id "$DEVICE_ID" 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: +The certificate is uploaded to the Cumulocity Tenant via: @@ -159,18 +159,18 @@ sudo tedge cert upload c8y --user "$C8Y_USER" If the password prompt appears, enter your password. :::info -In a production environment, it is not recommended to use the above self-signed certificate, which is for demo purposes. If you plan to use this tutorial as a basis for production, please have a look here: [Registering devices using certificates](https://cumulocity.com/guides/10.7.0/device-sdk/mqtt/#device-certificates). +In a production environment, it is not recommended to use the above self-signed certificate, which is for demo purposes. If you plan to use this tutorial as a basis for production, please have a look here: [Registering devices using certificates](https://cumulocity.com/docs/device-integration/device-certificates/#registering-devices-using-certificates). ::: ### Connect -We now are ready to connect the device to Cumulocity IoT. This can be achieved via: +We now are ready to connect the device to Cumulocity. This can be achieved via: ```sh sudo tedge connect c8y ``` -When the connection is established, the device will be created in Cumulocity IoT. When you go to Device Management → Devices → All devices, the device is visible in the list. +When the connection is established, the device will be created in Cumulocity. When you go to Device Management → Devices → All devices, the device is visible in the list.

%%te%% (input)Cumulocity IoT (output)Cumulocity (output)