diff --git a/docs/src/contribute/BUILDING.md b/docs/src/contribute/build.md similarity index 85% rename from docs/src/contribute/BUILDING.md rename to docs/src/contribute/build.md index e7d7d52181f..923bbf00e6a 100644 --- a/docs/src/contribute/BUILDING.md +++ b/docs/src/contribute/build.md @@ -1,10 +1,10 @@ --- -title: Build thin-edge +title: Build tags: [Contribute, Build] -sidebar_position: 1 +description: Build %%te%% from the source code --- -# Building thin-edge.io +This page details how to build %%te%% from the source code. ## Requirements @@ -26,7 +26,7 @@ A list of our test platforms can be found [here](../references/supported-platfor ## Get the code -thin-edge.io code is in git repository on github to acquire the code use following command: +%%te%% code is in git repository on github to acquire the code use following command: * via SSH: @@ -71,13 +71,13 @@ For other shells, you'll want to find the appropriate place to set a configurati eg. zsh uses `~/.zshrc`. Check your shell's documentation to find what file it uses. ::: -thin-edge.io operates the `MSRV` (Minimum Supported Rust Version) and uses stable toolchain. +%%te%% operates the `MSRV` (Minimum Supported Rust Version) and uses stable toolchain. Current MSRV is `1.65`. ### Cross compilation toolchain (optional) -thin-edge.io can be compiled for target architecture on non-target device, this is called cross compilation. +%%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). To install [cargo cross](https://github.com/rust-embedded/cross): @@ -105,7 +105,7 @@ just release-linux-virtual ## Compiling -To build thin-edge.io we are using `cargo`. +To build %%te%% we are using `cargo`. As we are using `cargo workspace` for all our crates. All compiled files are put in `./target/` directory with target's name eg: `./target/debug` or `./target/release` for native builds and for cross compiled targets `./target//debug` or `./target//release` dependent on the target of the build. @@ -158,7 +158,7 @@ Binaries can be run eg: `./target/release/tedge`. ## Building deb package -Currently thin-edge.io contains 2 binaries, `tedge` (cli) and `tedge-mapper` which are packaged as separate debian packages. To create following commands are to be issued: +Currently %%te%% contains 2 binaries, `tedge` (cli) and `tedge-mapper` which are packaged as separate debian packages. To create following commands are to be issued: ```sh cargo deb -p tedge @@ -204,7 +204,7 @@ cross build --target armv7-unknown-linux-gnueabihf --release ## Running tests -When contributing to thin-edge.io we ask you to write tests for the code you have written. The tests will be run by build pipeline when you create pull request, but you can easily run all the tests when you are developing with following command: +When contributing to %%te%% we ask you to write tests for the code you have written. The tests will be run by build pipeline when you create pull request, but you can easily run all the tests when you are developing with following command: ```sh cargo test diff --git a/docs/src/contribute/design/index.md b/docs/src/contribute/design/index.md index c666dc356bf..4932aa53f25 100644 --- a/docs/src/contribute/design/index.md +++ b/docs/src/contribute/design/index.md @@ -1,11 +1,10 @@ --- title: Design tags: [Documentation, next] -sidebar_position: 1 --- import DocCardList from '@theme/DocCardList'; -The following pages describe important design elements of thin-edge. +The following pages describe important design elements of %%te%%. diff --git a/docs/src/contribute/design/mqtt-topic-design.md b/docs/src/contribute/design/mqtt-topic-design.md index bac1016dbd8..9b3ca4a8b1a 100644 --- a/docs/src/contribute/design/mqtt-topic-design.md +++ b/docs/src/contribute/design/mqtt-topic-design.md @@ -63,7 +63,7 @@ The above topic schema uses fixed positions to indicate the entity type, e.g. to A service represents an entity that has dependence on a device. For example a service is running on device, and therefore can not exist on its own. The lifecycle of the service is linked to the device it is running on, so when the device is removed, then the service is also removed. ::: -The `` can be either set to `main`, which represents the thin-edge device, or to a id/name used to represent a child device. Telemetry data targeted to the main or child devices, require the `service` and `` segments to be set to an empty string. +The `` can be either set to `main`, which represents the %%te%% device, or to a id/name used to represent a child device. Telemetry data targeted to the main or child devices, require the `service` and `` segments to be set to an empty string. The following table shows some examples showing the relationship between the topic and the entity/component. diff --git a/docs/src/contribute/index.md b/docs/src/contribute/index.md index d4a8aed1dbf..10600e5f166 100644 --- a/docs/src/contribute/index.md +++ b/docs/src/contribute/index.md @@ -1,12 +1,12 @@ --- -title: Contribute to thin-edge +title: Contribute to thin-edge.io tags: [Contribute] sidebar_position: 5 --- import DocCardList from '@theme/DocCardList'; -This section is for who wants to contribute to thin-edge, +This section is for who wants to contribute to %%te%%, submitting issues, writing documentation, implementing features. \ No newline at end of file diff --git a/docs/src/contribute/DEBIAN_PACKAGE_HOSTING.md b/docs/src/contribute/package-hosting.md similarity index 87% rename from docs/src/contribute/DEBIAN_PACKAGE_HOSTING.md rename to docs/src/contribute/package-hosting.md index 4f538aef52e..dea43af32e4 100644 --- a/docs/src/contribute/DEBIAN_PACKAGE_HOSTING.md +++ b/docs/src/contribute/package-hosting.md @@ -1,16 +1,14 @@ --- -title: Debian Package Hosting +title: Package Hosting tags: [Contribute, Packaging] -sidebar_position: 3 +description: Package hosting of %%te%% components --- -# Debian Package Hosting - -In additional to the thin-edge.io install script, the packages are also publicly hosted APT repository. +In additional to the %%te%% install script, the packages are also publicly hosted APT repository. ## Official releases -The following APT repositories contain the official releases of thin-edge.io. The packages will have a nice `x.y.z` version number, and all of the packages go through our full suite of automated and manual testing. +The following APT repositories contain the official releases of %%te%%. The packages will have a nice `x.y.z` version number, and all of the packages go through our full suite of automated and manual testing. The packages are the same ones which are uploaded to the [GitHub Releases](https://github.com/thin-edge/thin-edge.io/releases) page. @@ -45,7 +43,7 @@ curl -1sLf \ ## Pre releases -The latest built packages from the `main` branch of the project. The packages go through the same automated testing process as the official releases, however they are not tagged in git, so the version numbers will look like `0.8.1-171-ga72e5432` (see the [Version syntax](./DEBIAN_PACKAGE_HOSTING.md#version-syntax) for description about the version). +The latest built packages from the `main` branch of the project. The packages go through the same automated testing process as the official releases, however they are not tagged in git, so the version numbers will look like `0.8.1-171-ga72e5432` (see the [Version syntax](#version-syntax) for description about the version). These repositories allow you to test new features as they get merged to `main`, rather than waiting for the official release. However it is still advised to only use these repositories for development and testing purposes as the official versions go through additional testing. @@ -101,7 +99,7 @@ curl -1sLf \ ## Removing the APT repositories -All of the `thin-edge.io` apt repositories can be removed by the following command. +All of the %%te%% apt repositories can be removed by the following command. ```sh sudo rm -f /etc/apt/sources.list.d/thinedge-tedge-*.list @@ -110,7 +108,7 @@ sudo rm -rf /var/lib/apt/lists/* sudo apt-get update ``` -## Version syntax +## Version syntax {#version-syntax} The version is automatically generated from the source code management tool, git. The version is based on the commit used to build the packages and its distance from the last tag (e.g. the last official released version). diff --git a/docs/src/contribute/INSTALLING_DOCKER.md b/docs/src/contribute/setting-up-docker.md similarity index 91% rename from docs/src/contribute/INSTALLING_DOCKER.md rename to docs/src/contribute/setting-up-docker.md index 6aba51cd183..b4abee5a7fe 100644 --- a/docs/src/contribute/INSTALLING_DOCKER.md +++ b/docs/src/contribute/setting-up-docker.md @@ -1,12 +1,9 @@ --- title: Setting up Docker tags: [Contribute] -sidebar_position: 10 --- -# Setting up Docker (OSS - Variant) - -This guide is to assist with the installation of docker and some of the docker cli tools. It is not meant to replace other online articles but more of a cheat sheet to getting your setup up and running as fast as possible. If you encounter issues with the setup, please search online for a fix. +This guide is to assist with the installation of docker (OSS Variant) and some of the docker cli tools. It is not meant to replace other online articles but more of a cheat sheet to getting your setup up and running as fast as possible. If you encounter issues with the setup, please search online for a fix. ## Installation diff --git a/docs/src/contribute/DEV_CONTAINER.md b/docs/src/contribute/vscode-dev-containers.md similarity index 94% rename from docs/src/contribute/DEV_CONTAINER.md rename to docs/src/contribute/vscode-dev-containers.md index eada3391b2a..7b57428b422 100644 --- a/docs/src/contribute/DEV_CONTAINER.md +++ b/docs/src/contribute/vscode-dev-containers.md @@ -1,11 +1,8 @@ --- title: VSCode Dev Containers tags: [Contribute] -sidebar_position: 2 --- -# VSCode Dev Containers - VSCode Dev Containers are great for developing as they contain all of the project's dependencies and in the end you have a ready-to-use dockerFile which can also be used in your CI/CD pipeline. It provides a normalized experience to all VSCode users across MacOS, Windows and Linux. All you need to get going is a the open source docker engine (not Docker Desktop!) and docker-compose. @@ -18,7 +15,7 @@ Before VSCode Dev container can be used, you need to install a few things. 1. Install `docker` and `docker-compose` if you do not already have these - Checkout the [INSTALLING_DOCKER](./INSTALLING_DOCKER.md) instructions to help guide you + Checkout the [INSTALLING_DOCKER](./setting-up-docker.md) instructions to help guide you 1. Install VSCode and make sure it is up to date @@ -60,7 +57,7 @@ But in both methods it is recommended to fork the project first, then clone from 1. Open a terminal -2. Clone the forked thin-edge.io project +2. Clone the forked %%te%% project **Example** @@ -94,7 +91,7 @@ But in both methods it is recommended to fork the project first, then clone from 2. Click on the `Remote Explorer` Icon on the left hand navigation menu (the icon looks like a computer monitor) -3. From the `Dev Containers` section, right-click on the thin-edge.io dev container, and select `Open Folder in Container` +3. From the `Dev Containers` section, right-click on the %%te%% dev container, and select `Open Folder in Container` ## Rebuilding the dev container diff --git a/docs/src/contribute/writing-documentation/index.md b/docs/src/contribute/writing-documentation/index.md index 177dea84b74..ca54a5b7002 100644 --- a/docs/src/contribute/writing-documentation/index.md +++ b/docs/src/contribute/writing-documentation/index.md @@ -1,5 +1,5 @@ --- -title: Writing documentation +title: Writing Documentation tags: [Documentation] --- diff --git a/docs/src/contribute/writing-documentation/markdown-components.md b/docs/src/contribute/writing-documentation/markdown-components.md index 2363f063df0..8cd91eba2aa 100644 --- a/docs/src/contribute/writing-documentation/markdown-components.md +++ b/docs/src/contribute/writing-documentation/markdown-components.md @@ -1,5 +1,5 @@ --- -title: Markdown components +title: Markdown Components tags: [Documentation] sidebar_position: 1 --- @@ -197,7 +197,7 @@ tedge disconnect aws ## MQTT Code block -One of the main interfaces for thin-edge.io is MQTT, therefore a special plugin has been created to display how to publish/subscribe to messages on an MQTT broker. +One of the main interfaces for %%te%% is MQTT, therefore a special plugin has been created to display how to publish/subscribe to messages on an MQTT broker. The code block only expects the writer to provide the `tedge mqtt ...` command, and the plugin will take care of the translation to the various formats. The decision was made to use the `tedge mqtt` command as the base format so that the code blocks would also still be useful when viewing the raw markdown documents. diff --git a/docs/src/contribute/writing-documentation/markdown-guidelines.md b/docs/src/contribute/writing-documentation/markdown-guidelines.md index 2c7d0b775d6..84a33f232f5 100644 --- a/docs/src/contribute/writing-documentation/markdown-guidelines.md +++ b/docs/src/contribute/writing-documentation/markdown-guidelines.md @@ -1,5 +1,5 @@ --- -title: Markdown guidelines +title: Markdown Guidelines tags: [Documentation] sidebar_position: 2 --- diff --git a/docs/src/extend/firmware-management/building-image/index.md b/docs/src/extend/firmware-management/building-image/index.md index f4ce17fd04d..3904a7c4c05 100644 --- a/docs/src/extend/firmware-management/building-image/index.md +++ b/docs/src/extend/firmware-management/building-image/index.md @@ -6,6 +6,6 @@ sidebar_position: 1 import DocCardList from '@theme/DocCardList'; -Instructions on how to build different Operation System images with thin-edge.io setup to perform Over-the-Air (OTA) updates of the operating system. +Instructions on how to build different Operation System images with %%te%% setup to perform Over-the-Air (OTA) updates of the operating system. \ No newline at end of file diff --git a/docs/src/extend/firmware-management/building-image/rugpi/index.md b/docs/src/extend/firmware-management/building-image/rugpi/index.md index b7077516a7f..2221fcc4761 100644 --- a/docs/src/extend/firmware-management/building-image/rugpi/index.md +++ b/docs/src/extend/firmware-management/building-image/rugpi/index.md @@ -6,7 +6,7 @@ sidebar_position: 1 import DocCardList from '@theme/DocCardList'; -Guides to building custom thin-edge.io based images using [Rugpi](https://github.com/silitics/rugpi). The images produced support Over-the-Air (OTA) Operating System updates. +Guides to building custom %%te%% based images using [Rugpi](https://github.com/silitics/rugpi). The images produced support Over-the-Air (OTA) Operating System updates. Currently Rugpi only supports Raspberry Pi devices, however this maybe expanded upon in the future. diff --git a/docs/src/extend/firmware-management/building-image/yocto/index.md b/docs/src/extend/firmware-management/building-image/yocto/index.md index 604d3aff2bf..3d8000f8f6c 100644 --- a/docs/src/extend/firmware-management/building-image/yocto/index.md +++ b/docs/src/extend/firmware-management/building-image/yocto/index.md @@ -6,6 +6,6 @@ sidebar_position: 1 import DocCardList from '@theme/DocCardList'; -Guides to building custom thin-edge.io based images using [The Yocto Project](https://www.yoctoproject.org/). The images produced support Over-the-Air (OTA) Operating System updates using proven technologies such as mender. +Guides to building custom %%te%% based images using [The Yocto Project](https://www.yoctoproject.org/). The images produced support Over-the-Air (OTA) Operating System updates using proven technologies such as mender. diff --git a/docs/src/extend/firmware-management/building-image/yocto/tutorial.md b/docs/src/extend/firmware-management/building-image/yocto/tutorial.md index 95b0c3b3ace..af683b4baad 100644 --- a/docs/src/extend/firmware-management/building-image/yocto/tutorial.md +++ b/docs/src/extend/firmware-management/building-image/yocto/tutorial.md @@ -48,8 +48,8 @@ The project uses different Yocto layers to build an image which contains: |Item|Description| |--|--| |Yocto Linux Distribution|Base operating system| -|thin-edge.io|thin-edge.io and all of its components| -|thin-edge.io mender workflow|A workflow definition to perform Operation System A/B updates, e.g. mender commit or rollback| +|thin-edge.io|%%te%% and all of its components| +|%%te%% mender workflow|A workflow definition to perform Operation System A/B updates, e.g. mender commit or rollback| |mender|mender binary configured in standalone mode| ### Cloning the project diff --git a/docs/src/extend/firmware-management/device-onboarding.md b/docs/src/extend/firmware-management/device-onboarding.md index 9541602f9a5..5c8fdb2d018 100644 --- a/docs/src/extend/firmware-management/device-onboarding.md +++ b/docs/src/extend/firmware-management/device-onboarding.md @@ -2,9 +2,10 @@ title: Onboarding a Device tags: [Extend, Build] sidebar_position: 5 +description: Connecting devices to the cloud for the first time --- -Onboarding a new devices involves configuring thin-edge.io to connect to a cloud for the first time. This generally involves the following steps: +Onboarding a new devices involves configuring %%te%% to connect to a cloud for the first time. This generally involves the following steps: 1. Configure the cloud url to connect to 2. Generate the device certificate (if it does not already exist) diff --git a/docs/src/extend/firmware-management/index.md b/docs/src/extend/firmware-management/index.md index 797c757d182..14ddc5ff0ef 100644 --- a/docs/src/extend/firmware-management/index.md +++ b/docs/src/extend/firmware-management/index.md @@ -6,6 +6,6 @@ sidebar_position: 1 import DocCardList from '@theme/DocCardList'; -Instructions on how to build different Operation System images with thin-edge.io setup to perform Over-the-Air (OTA) updates of the operating system. +Instructions on how to build different Operation System images with %%te%% setup to perform Over-the-Air (OTA) updates of the operating system. \ No newline at end of file diff --git a/docs/src/extend/index.md b/docs/src/extend/index.md index c7a4636473f..8404c9c7b15 100644 --- a/docs/src/extend/index.md +++ b/docs/src/extend/index.md @@ -1,12 +1,12 @@ --- -title: Extend thin-edge +title: Extend thin-edge.io tags: [Extend] sidebar_position: 4 --- import DocCardList from '@theme/DocCardList'; -This section is for the agent developers who want to adapt and extend thin-edge +This section is for the agent developers who want to adapt and extend %%te%% to meet the requirements of their domain application, target devices and cloud. \ No newline at end of file diff --git a/docs/src/extend/write-my-software-management-plugin.md b/docs/src/extend/software-management.md similarity index 97% rename from docs/src/extend/write-my-software-management-plugin.md rename to docs/src/extend/software-management.md index d1fb7f87c0b..cbc560c947c 100644 --- a/docs/src/extend/write-my-software-management-plugin.md +++ b/docs/src/extend/software-management.md @@ -1,15 +1,14 @@ --- -title: Software Management Plugin +title: Software Management tags: [Extend, Software Management] sidebar_position: 1 +description: How to create a custom software management plugin --- -# Write my software management plugin - -**thin-edge.io** Software Management natively supports APT (Debian) packages. +%%te%% Software Management natively supports APT (Debian) packages. However, there are many package management systems in the world, and you may want to have a plugin that is suitable for your device. -For such a demand, we provide the [**Package Manager Plugin API**](./../references/plugin-api.md) +For such a demand, we provide the [**Package Manager Plugin API**](./../references/software-management-plugin-api.md) to write a custom Software Management plugin in your preferred programming language. In this tutorial, we will look into the **Package Manager Plugin API**, @@ -418,5 +417,5 @@ That example exists immediately if one of the commands fails. Additional information and examples can be found from the following references: -- [Package Manager Plugin API Specification](https://github.com/thin-edge/thin-edge.io/blob/main/docs/src/references/plugin-api.md). +- [Package Manager Plugin API Specification](https://github.com/thin-edge/thin-edge.io/blob/main/docs/src/references/software-management-plugin-api.md). - [tedge-apt-plugin (Debian APT Plugin)](https://github.com/thin-edge/thin-edge.io/tree/main/plugins/tedge_apt_plugin) written in Rust. diff --git a/docs/src/install/index.md b/docs/src/install/index.md index 6257c679cff..9c875832807 100644 --- a/docs/src/install/index.md +++ b/docs/src/install/index.md @@ -5,14 +5,14 @@ sidebar_position: 1 --- :::tip Announcement -thin-edge.io ❤️ Linux so we now support installing thin-edge on any Linux distribution! +%%te%% ❤️ Linux so we now support installing %%te%% on any Linux distribution! -Systemd is still the default init system (aka. service manager), however if you don't have Systemd, then it won't be used. You are then free to configure your own service manager to run thin-edge how you want, or use one of the [community supported packages](#optional-linux-distributions-without-systemd). +Systemd is still the default init system (aka. service manager), however if you don't have Systemd, then it won't be used. You are then free to configure your own service manager to run %%te%% how you want, or use one of the [community supported packages](#optional-linux-distributions-without-systemd). ::: ## Install/update -The easiest way to get started with thin-edge.io is to use the installation script which will auto detect the installation method appropriate for your Linux distribution. The script will configure the package manager and install thin-edge.io and its dependencies (e.g. mosquitto). If your distribution does not have one of the supported package managers, then the tarball will be used to install thin-edge.io. +The easiest way to get started with %%te%% is to use the installation script which will auto detect the installation method appropriate for your Linux distribution. The script will configure the package manager and install %%te%% and its dependencies (e.g. mosquitto). If your distribution does not have one of the supported package managers, then the tarball will be used to install %%te%%. To install or update to the latest version, run the following command: @@ -26,7 +26,7 @@ wget -O - https://thin-edge.io/install.sh | sh -s ### Update using a package manager -thin-edge.io and its components can be updated by running the install.sh script again, or using the Linux package manager on your distribution. +%%te%% and its components can be updated by running the install.sh script again, or using the Linux package manager on your distribution. ```sh tab={"label":"Debian/Ubuntu"} sudo apt-get update @@ -48,7 +48,7 @@ If you have any trouble updating via the package manager, then run the install.s ### Optional: Linux distributions without Systemd -thin-edge.io uses Systemd by default to run all of its components as background services. If your Linux distribution does not have Systemd installed, then you will also have to run one more additional step. +%%te%% uses Systemd by default to run all of its components as background services. If your Linux distribution does not have Systemd installed, then you will also have to run one more additional step. Run the script below to automatically detect and install the relevant service definitions for the init system provided by your Linux distribution. @@ -60,26 +60,26 @@ curl -fsSL https://thin-edge.io/install-services.sh | sh -s wget -O - https://thin-edge.io/install-services.sh | sh -s ``` -Check out the [init systems](../operate/installation/init_systems.md) for more information on the service definitions. +Check out the [init systems](../operate/installation/init-systems.md) for more information on the service definitions. :::info -If the script detects that Systemd is installed, then it will not install anything as thin-edge.io comes with Systemd service definitions. +If the script detects that Systemd is installed, then it will not install anything as %%te%% comes with Systemd service definitions. ::: ## Supported Linux Package Managers -The following Linux Package Managers are supported out-of-the-box. For all other Linux distributions, the tarball (.tar.gz binary) can be used to add the thin-edge.io executables/binaries. +The following Linux Package Managers are supported out-of-the-box. For all other Linux distributions, the tarball (.tar.gz binary) can be used to add the %%te%% executables/binaries.
@@ -119,15 +119,15 @@ The instructions require you to have the following tools installed. You will need to have `sudo` also installed if you want to run these instructions. ```sh tab={"label":"Debian/Ubuntu"} -curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-main/setup.deb.sh' | sudo bash +curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-release/setup.deb.sh' | sudo bash ``` ```sh tab={"label":"RHEL/Fedora/RockyLinux"} -curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-main/setup.rpm.sh' | sudo bash +curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-release/setup.rpm.sh' | sudo bash ``` ```sh tab={"label":"Alpine"} -curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-main/setup.alpine.sh' | sudo bash +curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-release/setup.alpine.sh' | sudo bash ``` **Running as root** @@ -135,21 +135,21 @@ curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-main/setup.alpine.sh' These commands must be run as the root user. ```sh tab={"label":"Debian/Ubuntu"} -curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-main/setup.deb.sh' | bash +curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-release/setup.deb.sh' | bash ``` ```sh tab={"label":"RHEL/Fedora/RockyLinux"} -curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-main/setup.rpm.sh' | bash +curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-release/setup.rpm.sh' | bash ``` ```sh tab={"label":"Alpine"} -curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-main/setup.alpine.sh' | bash +curl -1sLf 'https://dl.cloudsmith.io/public/thinedge/tedge-release/setup.alpine.sh' | bash ``` #### Installing and updating using a package manager -Once you have the repository setup, you can install the **tedge-full** virtual package which will automatically pull in all of the thin-edge.io packages. This makes it easier to install and update in the future, as you only have to type in one package name, `tedge-full`. +Once you have the repository setup, you can install the **tedge-full** virtual package which will automatically pull in all of the %%te%% packages. This makes it easier to install and update in the future, as you only have to type in one package name, `tedge-full`. ```sh tab={"label":"Debian/Ubuntu"} sudo apt-get update @@ -169,7 +169,7 @@ sudo apk add --no-cache tedge-full You can force the install.sh script to install via the tarball instead of via a package manager. The install script will also take care of the required post installation steps. -To install the thin-edge.io via the tarball run the following command: +To install the %%te%% via the tarball run the following command: ```sh tab={"label":"curl"} @@ -182,7 +182,7 @@ wget -O - https://thin-edge.io/install.sh | sh -s -- --package-manager tarball ## Package repository hosting -[![Hosted By: Cloudsmith](https://img.shields.io/badge/OSS%20hosting%20by-cloudsmith-blue?logo=cloudsmith&style=for-the-badge)](https://cloudsmith.com) +[_![Hosted By: Cloudsmith](https://img.shields.io/badge/OSS%20hosting%20by-cloudsmith-blue?logo=cloudsmith&style=for-the-badge)_](https://cloudsmith.com) Package repository hosting is graciously provided by [Cloudsmith](https://cloudsmith.com). Cloudsmith is the only fully hosted, cloud-native, universal package management solution, that @@ -198,26 +198,26 @@ The packages can be viewed directly from the [Cloudsmith.io](https://cloudsmith. - Debian logo + Debian logo - Latest version of 'tedge-full' @ Cloudsmith + Latest version of 'tedge-full' @ Cloudsmith - RedHat logo + RedHat logo - Latest version of 'tedge-full' @ Cloudsmith + Latest version of 'tedge-full' @ Cloudsmith - Alpine logo + Alpine logo - Latest version of 'tedge-full' @ Cloudsmith + Latest version of 'tedge-full' @ Cloudsmith diff --git a/docs/src/legacy/child_device_config_management_agent.md b/docs/src/legacy/child-device-configuration-management.md similarity index 77% rename from docs/src/legacy/child_device_config_management_agent.md rename to docs/src/legacy/child-device-configuration-management.md index 3c76aab5eb4..2b8f7559bc0 100644 --- a/docs/src/legacy/child_device_config_management_agent.md +++ b/docs/src/legacy/child-device-configuration-management.md @@ -2,59 +2,60 @@ title: Child Device Configuration Management tags: [Cumulocity, Configuration, Legacy] sidebar_position: 6 +description: Legacy configuration management for child devices using Cumulocity IoT --- # Enable configuration management on child devices Configuration management can be enabled for child devices using the same `c8y-configuration-plugin`, -used for configuration management on thin-edge devices. +used for configuration management on %%te%% devices. But, an additional piece of software must be developed by the child device owner, -to coordinate configuration management operations on it with the `c8y-configuration-plugin` running on thin-edge. +to coordinate configuration management operations on it with the `c8y-configuration-plugin` running on %%te%%. This software is referred to as "child device agent" in the rest of this document. The child device agent needs to handle the following responsibilities: -* Declare the supported configuration list to thin-edge -* Handle configuration snapshot requests from thin-edge -* Handle configuration update requests from thin-edge +* Declare the supported configuration list to %%te%% +* Handle configuration snapshot requests from %%te%% +* Handle configuration update requests from %%te%% The *supported configuration list* is the list of configuration files on the child device that needs to be managed from the cloud. -Configuration management by thin-edge is enabled *only* for the files provided in this list. -These declared configuration files can be fetched from thin-edge with config snapshot requests +Configuration management by %%te%% is enabled *only* for the files provided in this list. +These declared configuration files can be fetched from %%te%% with config snapshot requests and can be updated with config update requests. -Handling the above mentioned responsibilities involve multiple interactions with thin-edge +Handling the above mentioned responsibilities involve multiple interactions with %%te%% over MQTT to receive and respond to configuration management requests, and HTTP to upload/download files while handling those requests. For example, during the bootstrapping/startup of the child device, -the agent needs to upload the supported configuration list of the child device to thin-edge -by uploading a file using the HTTP `file-transfer` API of thin-edge, -followed by an MQTT message informing thin-edge that the upload completed. +the agent needs to upload the supported configuration list of the child device to %%te%% +by uploading a file using the HTTP `file-transfer` API of %%te%%, +followed by an MQTT message informing %%te%% that the upload completed. Similarly, handling of a configuration snapshot or update request involves sending -MQTT messages before and after the configuration file is uploaded/downloaded via HTTP to/from thin-edge. +MQTT messages before and after the configuration file is uploaded/downloaded via HTTP to/from %%te%%. -Since child device agents typically run on an external device and not on the thin-edge device itself, -the MQTT and HTTP APIs of thin-edge need to be accessed over the network using its IP address, +Since child device agents typically run on an external device and not on the %%te%% device itself, +the MQTT and HTTP APIs of %%te%% need to be accessed over the network using its IP address, which is configured using the tedge configuration settings `mqtt.external.bind.address` or `mqtt.bind.address`. The MQTT APIs are exposed via port 1883 and the HTTP APIs are exposed via port 8000. -In rare cases, where the child device agent is installed alongside thin-edge on the same device, +In rare cases, where the child device agent is installed alongside %%te%% on the same device, these APIs can be accessed via a local IP or even `127.0.0.1`. The following sections explain the child device agent responsibilities in detail. ## Declare supported configuration list to thin-edge -The supported configuration list should be sent to thin-edge during the startup/bootstrap phase of the child device agent. +The supported configuration list should be sent to %%te%% during the startup/bootstrap phase of the child device agent. This bootstrapping is a 3 step process: 1. Prepare a `c8y-configuration-plugin.toml` file with the supported configuration list -1. Upload this file to thin-edge via HTTP -1. Notify thin-edge about the upload via MQTT +1. Upload this file to %%te%% via HTTP +1. Notify %%te%% about the upload via MQTT The child device agent needs to capture the list of configuration files that needs be managed from the cloud -in a `c8y-configuration-plugin.toml` file in the same format as specified in the [configuration management documentation](../operate/c8y/config_management_plugin.md) as follows: +in a `c8y-configuration-plugin.toml` file in the same format as specified in the [configuration management documentation](../operate/c8y/configuration-management.md) as follows: ```toml title="file: c8y-configuration-plugin.toml" files = [ @@ -66,13 +67,13 @@ files = [ * `path` is the full path to the configuration file on the child device file system. * `type` is a unique alias for each file entry which will be used to represent that file in Cumulocity UI -The child device agent needs to upload this file to thin-edge [File Transfer Service](../references/tedge-file-transfer-service.md) with an HTTP PUT request +The child device agent needs to upload this file to %%te%% [File Transfer Service](../references/file-transfer-service.md) with an HTTP PUT request to the URL: `http://{fts-address}:8000/tedge/file-transfer/{child-id}/c8y-configuration-plugin` -* `{fts-address}` is the address of the thin-edge.io device on which the [File Transfer Service](../references/tedge-file-transfer-service.md) is running +* `{fts-address}` is the address of the %%te%% device on which the [File Transfer Service](../references/file-transfer-service.md) is running * `{child-id}` is the child-device-id -Once the upload is complete, the agent should notify thin-edge about the upload by sending the following MQTT message: +Once the upload is complete, the agent should notify %%te%% about the upload by sending the following MQTT message: ```sh te2mqtt formats=v1 tedge mqtt pub 'tedge/{child-d}/commands/res/config_snapshot' '{"type": "c8y-configuration-plugin", "path": "/child/local/fs/path"}' @@ -80,7 +81,7 @@ tedge mqtt pub 'tedge/{child-d}/commands/res/config_snapshot' '{"type": "c8y-con ## Handle config snapshot requests from thin-edge -Handling config snapshot requests from thin-edge is a 4-step process: +Handling config snapshot requests from %%te%% is a 4-step process: 1. Subscribe to, and receive config snapshot requests via MQTT 1. Send an "executing" operation status update to acknowledge the receipt of the request via MQTT @@ -90,7 +91,7 @@ Handling config snapshot requests from thin-edge is a 4-step process: These steps are explained in detail below: The child device agent must subscribe to the `tedge/{child-d}/commands/req/config_snapshot` MQTT topic -to receive the config snapshot requests from thin-edge. +to receive the config snapshot requests from %%te%%. These requests arrive in the following JSON format: ```json @@ -101,7 +102,7 @@ These requests arrive in the following JSON format: } ``` -The `type` and `path` fields are the same values that the child device sent to thin-edge in its `c8y-configuration-plugin.toml` file. +The `type` and `path` fields are the same values that the child device sent to %%te%% in its `c8y-configuration-plugin.toml` file. The `url` value is what the child device agent must use to upload the requested config file. On receipt of the request, the agent must send an "executing" MQTT status message as follows: @@ -148,7 +149,7 @@ a "failed" status update must be sent instead, to the same topic as follows: ## Handle config update requests from thin-edge -Handling config update requests from thin-edge is a 5-step process: +Handling config update requests from %%te%% is a 5-step process: 1. Subscribe to, and receive config update requests via MQTT 1. Send an "executing" operation status update to acknowledge the receipt of the request via MQTT @@ -157,7 +158,7 @@ Handling config update requests from thin-edge is a 5-step process: 1. Send a "successful" operation status update via MQTT The child device agent must subscribe to the `tedge/{child-d}/commands/req/config_update` MQTT topic -to receive the config update requests from thin-edge. +to receive the config update requests from %%te%%. These requests arrive in the following JSON format: ```json @@ -168,7 +169,7 @@ These requests arrive in the following JSON format: } ``` -The child device agent must download the config file update for the given `type` from thin-edge using the `url`. +The child device agent must download the config file update for the given `type` from %%te%% using the `url`. On receipt of the request, the agent must send an "executing" MQTT status message as follows: diff --git a/docs/src/legacy/child_device_firmware_management.md b/docs/src/legacy/child-device-firmware-management.md similarity index 81% rename from docs/src/legacy/child_device_firmware_management.md rename to docs/src/legacy/child-device-firmware-management.md index b8d76ab3ae4..2cb24515431 100644 --- a/docs/src/legacy/child_device_firmware_management.md +++ b/docs/src/legacy/child-device-firmware-management.md @@ -2,6 +2,7 @@ title: Child Device Firmware Management tags: [Cumulocity, Firmware, Legacy] sidebar_position: 7 +description: Legacy firmware management for child devices using Cumulocity IoT --- # Enable firmware management on child devices with Cumulocity @@ -11,42 +12,42 @@ sidebar_position: 7 ::: Firmware management can be enabled for child devices using the `c8y-firmware-plugin`. -This thin-edge plugin coordinates the firmware update operation handling with Cumulocity, +This %%te%% plugin coordinates the firmware update operation handling with Cumulocity, by establishing secure communication with the cloud, managing firmware file downloads, which are typically large files, even over flaky networks, caching the downloaded files for re-use across multiple child devices etc. -For more details on the inner workings of this plugin, refer to the [reference guide](c8y-firmware-management.md). +For more details on the inner workings of this plugin, refer to the [reference guide](firmware-management.md). In order to install the firmware itself on the child device, an additional piece of software must be developed by the child device owner as well, -to coordinate firmware installation on the device with the `c8y-firmware-plugin` running on thin-edge. +to coordinate firmware installation on the device with the `c8y-firmware-plugin` running on %%te%%. This software is referred to as `child-device-connector` in the rest of this document. The responsibilities of the child device connector are: -* Receive firmware update requests from thin-edge -* Download and apply the updated firmware from thin-edge -* Send status updates on the progress of the firmware update operation to thin-edge +* Receive firmware update requests from %%te%% +* Download and apply the updated firmware from %%te%% +* Send status updates on the progress of the firmware update operation to %%te%% Handling the above-mentioned responsibilities involves -multiple interactions with thin-edge over its MQTT and HTTP APIs. -In cases where the child device connector is installed alongside thin-edge on the same device, +multiple interactions with %%te%% over its MQTT and HTTP APIs. +In cases where the child device connector is installed alongside %%te%% on the same device, these APIs can be accessed via a local IP or even `127.0.0.1`. The MQTT APIs are exposed via port 1883 and the HTTP APIs are exposed via port 8000, by default. When the child device connector is running directly on the external child device, -the MQTT and HTTP APIs of thin-edge need to be accessed over the network using its IP address and ports, +the MQTT and HTTP APIs of %%te%% need to be accessed over the network using its IP address and ports, which are configured using the tedge config settings `mqtt.client.host` or `mqtt.client.port` for MQTT and `http.address` and `http.port` for HTTP. -The `c8y-firmware-plugin` running on thin-edge, along with the `child-device-connector` -running either on the thin-edge device itself or directly on the child device, +The `c8y-firmware-plugin` running on %%te%%, along with the `child-device-connector` +running either on the %%te%% device itself or directly on the child device, provides firmware management support for that device. ## Declare firmware management support of child device At first, the child device needs to declare that it supports firmware management from Cumulocity -using the [supported operations API](../operate/c8y/supported_operations.md) of thin-edge -by simply creating an empty operations file on the thin-edge device as follows: +using the [supported operations API](../operate/c8y/supported-operations.md) of %%te%% +by simply creating an empty operations file on the %%te%% device as follows: ```sh sudo touch /etc/tedge/operations/c8y//c8y_Firmware @@ -55,7 +56,7 @@ sudo touch /etc/tedge/operations/c8y//c8y_Firmware This action will add `c8y_Firmware` as a new supported operation for the child device in Cumulocity. :::note -This initial bootstrapping step needs to be performed on the thin-edge device directly +This initial bootstrapping step needs to be performed on the %%te%% device directly and can not be done from the child device over the network. An over-the-network API for the same could be provided in future releases. ::: @@ -63,9 +64,9 @@ An over-the-network API for the same could be provided in future releases. # Handle firmware update requests from thin-edge Once the firmware management operation is enabled for a child device, -it is ready to serve firmware update requests received from Cumulocity via thin-edge. +it is ready to serve firmware update requests received from Cumulocity via %%te%%. -Handling firmware update requests from thin-edge is a 5-step process: +Handling firmware update requests from %%te%% is a 5-step process: 1. Subscribe to, and receive firmware update requests via MQTT 1. Send an "executing" operation status update to acknowledge the receipt of the request via MQTT @@ -78,7 +79,7 @@ The following sections cover these steps in detail. ### Subscribe to firmware update requests via MQTT The child device connector must subscribe to the `tedge/{CHILD_ID}/commands/req/firmware_update` MQTT topic -to receive the firmware update requests from thin-edge. +to receive the firmware update requests from %%te%%. **Example** @@ -119,7 +120,7 @@ The fields in the request are describe below. |Property|Description| |--------|-----------| |id| A unique id for the request. All responses must be sent back with the same id.| -|attempt| This `attempt` count can be used to differentiate between fresh requests and re-sent requests, as this `attempt` count will be higher than `1` if the same request is resent from thin-edge on rare occasions (e.g: thin-edge gets restarted while the child device is processing a firmware request).| +|attempt| This `attempt` count can be used to differentiate between fresh requests and re-sent requests, as this `attempt` count will be higher than `1` if the same request is resent from %%te%% on rare occasions (e.g: %%te%% gets restarted while the child device is processing a firmware request).| |name| Name of the firmware package| |version| Version of the firmware package| |sha256| The SHA-256 checksum of the firmware binary served in the `url` which can be used to verify the integrity of the downloaded package post-download.| @@ -210,10 +211,10 @@ mosquitto_pub -h {TEDGE_DEVICE_IP} -t "tedge/{CHILD_ID}/commands/res/firmware_up ## Cleanup -To save bandwidth, thin-edge downloads a single firmware file only once and keeps it cached for reuse across multiple child devices, +To save bandwidth, %%te%% downloads a single firmware file only once and keeps it cached for reuse across multiple child devices, as firmware updates could be applied to a fleet of devices together. The cached files are stored under the tedge data directory `/var/tedge/cache`, by default. -Since thin-edge does not know how many devices it will be reused for and for how long, it can not clean them up on its own. +Since %%te%% does not know how many devices it will be reused for and for how long, it can not clean them up on its own. So, the user must manually delete the cached firmware files once the update is complete on all child devices. ## References diff --git a/docs/src/legacy/c8y-firmware-management.md b/docs/src/legacy/firmware-management.md similarity index 93% rename from docs/src/legacy/c8y-firmware-management.md rename to docs/src/legacy/firmware-management.md index 4f58c733f06..e3fd34440cc 100644 --- a/docs/src/legacy/c8y-firmware-management.md +++ b/docs/src/legacy/firmware-management.md @@ -2,11 +2,12 @@ title: Firmware Management tags: [Firmware, Legacy] sidebar_position: 9 +description: Legacy child device firmware management using Cumulocity IoT --- # Child-Device Firmware Management using Cumulocity (legacy API) -Thin-edge provides a legacy operation plugin to +%%te%% provides a legacy operation plugin to [manage device firmware using Cumulocity](https://cumulocity.com/guides/users-guide/device-management/#firmware-repo) on child devices. @@ -16,14 +17,14 @@ on child devices. ::: - The firmware update operations are defined and triggered from Cumulocity -- Thin-edge acts as the proxy between Cumulocity and the child device +- %%te%% acts as the proxy between Cumulocity and the child device facilitating the routing of firmware update requests as well as the transfer of firmware binary files from cloud to the device. - Updating the firmware of a device is done by some device specific firmware management software. - Since thin-edge can not directly interact with that piece of software over whatever third-party protocol it supports, + Since %%te%% can not directly interact with that piece of software over whatever third-party protocol it supports, an additional piece of software, referred to as `child-device-connector` in the rest of this doc, - must be developed by the child device admin to perform the actual installation itself, in coordination with thin-edge. -- The `child-device-connector` may be installed directly on the child device or alongside thin-edge as well, - as long as it can access the HTTP and MQTT APIs of thin-edge interact with the child device directly. + must be developed by the child device admin to perform the actual installation itself, in coordination with %%te%%. +- The `child-device-connector` may be installed directly on the child device or alongside %%te%% as well, + as long as it can access the HTTP and MQTT APIs of %%te%% interact with the child device directly. This document describes: - how to install, configure and use the `c8y-firmware-plugin` @@ -91,7 +92,7 @@ Notifying the Cumulocity tenant of their progress (messages `501`, `502` and `50 During a successful operation, `c8y-firmware-plugin` updates the installed firmware info in Cumulocity tenant with SmartREST message `115`. -The thin-edge `CONFIG_DIR` is used to find where: +The %%te%% `CONFIG_DIR` is used to find where: * to store temporary files on download: `tedge config get tmp.path`, * to log operation errors and progress: `tedge config get log.path`, * to connect the MQTT bus: `tedge config get mqtt.bind.port`, @@ -108,9 +109,9 @@ sudo systemctl start c8y-firmware-plugin ## Firmware update protocol between thin-edge and the child-devices -The plugin manages the download and delivery of firmware files for child-devices connected to the thin-edge device, +The plugin manages the download and delivery of firmware files for child-devices connected to the %%te%% device, acting as a proxy between the cloud and the child-devices. -The firmware updates are downloaded from the cloud on the thin-edge device then made available to the child-devices over HTTP. +The firmware updates are downloaded from the cloud on the %%te%% device then made available to the child-devices over HTTP. The child devices are notified of incoming firmware update requests via MQTT. The `child-device-connector` has to subscribe to these MQTT messages, download the firmware files via HTTP, and notify the firmware plugin of the firmware update progress via MQTT. @@ -133,14 +134,14 @@ and notify the firmware plugin of the firmware update progress via MQTT. ### Child device connector connecting to thin-edge device -The `child-device-connector` is responsible for handling the firmware update requests sent by the thin-edge +The `child-device-connector` is responsible for handling the firmware update requests sent by the %%te%% and translating it to the relevant 3rd-party device specific API to install the firmware on that device. -The `child-device-connector` interacts with thin-edge over its MQTT and HTTP APIs. -In cases where the child device connector is installed alongside thin-edge on the same device, +The `child-device-connector` interacts with %%te%% over its MQTT and HTTP APIs. +In cases where the child device connector is installed alongside %%te%% on the same device, these APIs can be accessed via a local IP or even `127.0.0.1`. The MQTT APIs are exposed via port 1883 and the HTTP APIs are exposed via port 8000, by default. When the child device connector is running directly on the external child device, -the MQTT and HTTP APIs of thin-edge need to be accessed over the network using its IP address and ports, +the MQTT and HTTP APIs of %%te%% need to be accessed over the network using its IP address and ports, which are configured using the tedge config settings `mqtt.client.host` or `mqtt.client.port` for MQTT and `http.address` and `http.port` for HTTP. @@ -263,7 +264,7 @@ The following keywords are used in the following section for brevity: 1. Validate the integrity of the downloaded binary by matching its SHA-256 hash value against the `sha256` checksum value received in the request. 1. Apply the downloaded firmware file update on the device using whatever device specific protocol. -1. After applying the update, send the final operation status update to thin-edge via MQTT: +1. After applying the update, send the final operation status update to %%te%% via MQTT: 1. Topic: `tedge/$CHILD_DEVICE_ID/commands/res/firmware_update` 1. The payload must be a JSON record with the following fields: * `id`: The `id` of the request received diff --git a/docs/src/legacy/index.md b/docs/src/legacy/index.md index 0a07f956a03..06e1c336789 100644 --- a/docs/src/legacy/index.md +++ b/docs/src/legacy/index.md @@ -6,7 +6,7 @@ sidebar_position: 9 import DocCardList from '@theme/DocCardList'; -Thin-edge 1.0 introduced a set of breaking changes that might affect plugins and extensions implemented on previous versions. +%%te%% 1.0 introduced a set of breaking changes that might affect plugins and extensions implemented on previous versions. In most cases, a compatibility layer has been introduced to smooth the transition. For instance, any measurement published by an extension on the former topic `tedge/measurement` @@ -14,6 +14,6 @@ is republished by the **tedge-agent** to the topic `te/device/main///m/` which is dedicated to untyped measurements for the main device. However, the compatibility layers don't address all the breaking changes and, in any case, they will be deprecated medium-term. -Here are the developer guides to port a legacy extension to the new thin-edge API. +Here are the developer guides to port a legacy extension to the new %%te%% API. \ No newline at end of file diff --git a/docs/src/legacy/mqtt-topics.md b/docs/src/legacy/mqtt-topics.md index 97c38f412aa..8b8a2868043 100644 --- a/docs/src/legacy/mqtt-topics.md +++ b/docs/src/legacy/mqtt-topics.md @@ -2,9 +2,10 @@ title: MQTT topics tags: [MQTT, Legacy] sidebar_position: 1 +description: Legacy %%te%% MQTT topics and how to map to the new topics --- -The most visible breaking change introduced by thin-edge 1.0 is the [new topic structure](../references/mqtt-api.md), +The most visible breaking change introduced by %%te%% 1.0 is the [new topic structure](../references/mqtt-api.md), which has been made more consistent and extensible with a better support for child devices and services. Porting an extension that publishes telemetry data on the legacy `tedge` topic, should not pose any difficulty: @@ -17,7 +18,7 @@ Porting an extension that publishes telemetry data on the legacy `tedge` topic, The **tedge-agent** running on the main device implements a compatibility layer and republishes on the new topics any message received on the legacy topics. -Thanks to this compatibility mechanism a legacy extension works out of the box with thin-edge 1.0. +Thanks to this compatibility mechanism a legacy extension works out of the box with %%te%% 1.0. However, this mechanism will be deprecated medium-term, and we encourage you to port any legacy extension to the new API. diff --git a/docs/src/operate/c8y/apama_software_management_plugin.md b/docs/src/operate/c8y/apama.md similarity index 75% rename from docs/src/operate/c8y/apama_software_management_plugin.md rename to docs/src/operate/c8y/apama.md index 7d26f165c01..389e97551b7 100644 --- a/docs/src/operate/c8y/apama_software_management_plugin.md +++ b/docs/src/operate/c8y/apama.md @@ -1,18 +1,16 @@ --- -title: Apama Plugin +title: Apama tags: [Operate, Cumulocity, Software Management] -sidebar_position: 10 +description: Using the Apama plugin with %%te%% --- -# Apama Software Management Plugin - -The Apama plugin, part of the Apama thin-edge support package, can be used to install Apama projects using the Cumulocity software management feature. +The Apama plugin, part of the Apama %%te%% support package, can be used to install Apama projects using the Cumulocity software management feature. ## Prerequisites -The Apama thin-edge support package must be installed before you can install Apama projects on thin-edge. +The Apama %%te%% support package must be installed before you can install Apama projects on %%te%%. The recommended way of installing Apama support on Debian based distributions is with the apt package manager. -Further details about this can be found in the thin-edge.io documentation at [Manage the software on your devices from Cumulocity cloud](../../start/software-management.md). +Further details about this can be found in the %%te%% documentation at [Manage the software on your devices from Cumulocity cloud](../../start/software-management.md). #### Set up the Debian repository from which the Apama packages will be installed @@ -23,15 +21,15 @@ Further details about this can be found in the thin-edge.io documentation at [Ma - **Description**: apama-repo (or something else if you choose) - **Device Filter Type**: (leave empty) - **Software Type**: apt - - **Version**: 2022::apt + - **Version**: 2022 - **SOFTWARE FILE**: check the *Provide a file path* option and enter the URL: https://downloads.apamacommunity.com/debian/apama-repo_2022_all.deb 4. Click the **Add Software** button. 5. Now select the **Devices** menu option and then select **All devices**. -6. In the list of devices, select the thin-edge device installed previously. +6. In the list of devices, select the %%te%% device installed previously. 7. In the sub-menu for the device, select the **Software** option. 8. Click the **Install software** button in the bottom left; the apama-repo should be listed. -9. Click the drop-down arrow on the right and check the `2022::apt` radio button, then click **Install**. +9. Click the drop-down arrow on the right and check the `2022` radio button, then click **Install**. 10. Finally, click the **Apply changes** button in the lower right of the panel. #### Add the Apama thin-edge support package to the tenant software repository and deploy it to thin-edge @@ -42,17 +40,17 @@ Further details about this can be found in the thin-edge.io documentation at [Ma - **Description**: apama-thin-edge-support (or something else if you choose) - **Device Filter Type**: (leave empty) - **Software Type**: apt - - **Version**: latest::apt + - **Version**: latest - **SOFTWARE FILE**: select the **Provide a file path** option and give an **empty space** (' '). 4. Click the **Add Software** button. 5. Now return to the **Devices** menu option and then select **All devices**. -6. In the list of devices, select the thin-edge device installed previously. +6. In the list of devices, select the %%te%% device installed previously. 7. In the sub-menu for the device, select the **Software** option. 8. Click the **Install software** button in the bottom left; the apama-thin-edge-support should be listed. -9. Click the drop-down arrow on the right and check the `latest::apt` radio button, then click **Install**. +9. Click the drop-down arrow on the right and check the `latest` radio button, then click **Install**. 10. Finally, click the **Apply changes** button in the lower right of the panel. -After installation of the support for Apama onto the thin-edge device, the correlator will attempt to start, but will fail initially because there is not yet an Apama project installed. Instructions are given below for installing an Apama project on the device. +After installation of the support for Apama onto the %%te%% device, the correlator will attempt to start, but will fail initially because there is not yet an Apama project installed. Instructions are given below for installing an Apama project on the device. ## Install Apama projects from Cumulocity @@ -62,8 +60,7 @@ There is a naming convention that you need to follow while creating software ent For Apama projects: -1. The version must be suffixed with `::apama` as in `1.0::apama` or just `::apama` if no version number is necessary. -2. The uploaded binary must be a `zip` file that contains the `project` directory. If a directory named `project` is not found by the plugin at the root level in the zip, it is considered invalid. +1. The uploaded binary must be a `zip` file that contains the `project` directory. If a directory named `project` is not found by the plugin at the root level in the zip, it is considered invalid.

- Cumulocity custom fragments -

- - -For information on which fragments Cumulocity supports please see the -[Cumulocity API docs](https://cumulocity.com/guides/10.6.6/reference/device-management/). diff --git a/docs/src/operate/c8y/config_management_plugin.md b/docs/src/operate/c8y/configuration-management.md similarity index 88% rename from docs/src/operate/c8y/config_management_plugin.md rename to docs/src/operate/c8y/configuration-management.md index eff7675129f..12b46cd81b5 100644 --- a/docs/src/operate/c8y/config_management_plugin.md +++ b/docs/src/operate/c8y/configuration-management.md @@ -1,17 +1,15 @@ --- title: Configuration Management tags: [Operate, Cumulocity, Configuration] -sidebar_position: 5 +description: Managing configuration on devices --- -# How to manage configuration files with Cumulocity - -With `thin-edge.io`, 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/guides/users-guide/device-management/#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. -The configuration management functionality is provided by the **tedge-agent** service which is installed by default. If it is not installed then please install the components again following the [install guide](../../install/index.md). +The configuration management functionality is provided by the **tedge-agent** service which is installed by default. ## Getting started diff --git a/docs/src/operate/connection/connect.md b/docs/src/operate/c8y/connect.md similarity index 95% rename from docs/src/operate/connection/connect.md rename to docs/src/operate/c8y/connect.md index 26c1ad2a467..14ddcad0725 100644 --- a/docs/src/operate/connection/connect.md +++ b/docs/src/operate/c8y/connect.md @@ -1,22 +1,18 @@ --- -title: Cloud Connection +title: Connect tags: [Operate, Cloud] -sidebar_position: 1 +description: Connecting %%te%% to Cumulocity IoT --- -# How to connect? - -## Connect to Cumulocity IoT - To create northbound connection a local bridge shall be established and this can be achieved with `tedge` cli and following commands: :::note -`tedge connect` requires `sudo` privilege. +`tedge connect` requires root privileges, so you need to run it using `sudo` or run the command as root. ::: ## Setting the cloud end-point -Configure required parameters for thin-edge.io with [`tedge config set`](../../references/cli/tedge-config.md): +Configure required parameters for %%te%% with [`tedge config set`](../../references/cli/tedge-config.md): ```sh sudo tedge config set c8y.url example.cumulocity.com @@ -318,4 +314,4 @@ Caused by: Service mosquitto not found. Install mosquitto to use this command. ``` -mosquitto server has not been installed on the system and it is required to run this command, refer to [How to install thin-edge.io?](../../install/index.md) to install mosquitto and try again. +mosquitto server has not been installed on the system and it is required to run this command, refer to the [install guide](../../install/index.md) to install mosquitto and try again. diff --git a/docs/src/operate/c8y/custom-fragments.md b/docs/src/operate/c8y/custom-fragments.md new file mode 100644 index 00000000000..dec0564ff84 --- /dev/null +++ b/docs/src/operate/c8y/custom-fragments.md @@ -0,0 +1,108 @@ +--- +title: Custom Fragments +tags: [Operate, Cumulocity] +description: Publishing custom fragments/properties to Cumulocity IoT +--- + +%%te%% supports update custom fragments (also known as properties) on the device's digital twin representation in Cumulocity IoT. + +## 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. + +```json +{ + "type": "thin-edge.io", + "c8y_Agent": { + "name": "thin-edge.io", + "url": "https://thin-edge.io", + "version": "1.0.0" + } +} +``` + +The default value for the `type` property can be changed using the `tedge config` command as follows: + +```sh +sudo tedge config set device.type VALUE +``` + +For example, you can set the `type` property to `edge_gateway` using: + +```sh +sudo tedge config set device.type edge_gateway +``` + +## Custom fragments + +Additional fragments can be added to the device by either publishing to a give MQTT topic, or via a file based method. Each section describes what data and when to use it. + +### MQTT Dynamic Fragments {#dynamic-fragments} + +%%te%% offers an MQTT topic which can be used to publish data to custom fragments for a device, child devices or services. + +* Values which change over time +* Update values without having to restart any services + +The following shows an example of publishing the name and version of the Operating System to the `os_Version` fragment for the main device. + +```sh te2mqtt +tedge mqtt pub te/device/main///twin/os_Version '{ + "name": "Poky (Yocto Project Reference Distro)", + "version": "4.0.15 (kirkstone)" +}' +``` + +The example above will result in the following fragment being added to the device's digital twin (e.g. *Managed Object*) in Cumulocity IoT. + +```json5 +{ + // ... other fragments are left out for simplicity + "os_Version": { + "name": "Poky (Yocto Project Reference Distro)", + "version": "4.0.15 (kirkstone)" + } +} +``` + +### File-based Static Fragments {#static-fragments} + +The file based approach is intended for static information, e.g. build date, or a custom image type assigned to the device. The values are only published on startup of the **tedge-mapper-c8y** service. + +If you wish to add more fragments to Cumulocity, you can do so by populating `/etc/tedge/device/inventory.json`. + +An example `inventory.json` looks something like this: + +```json title="file: /etc/tedge/device/inventory.json" +{ + "c8y_RequiredAvailability": { + "responseInterval": 5 + }, + "c8y_Hardware": { + "model": "BCM2708", + "revision": "000e", + "serialNumber": "00000000e2f5ad4d" + } +} +``` + +To see the changes you need to restart the tedge-mapper. +If you're using systemctl you can do: + +```sh +sudo systemctl restart tedge-mapper-c8y +``` + +In the Cumulocity UI this will looks something like this: + +

+ Cumulocity custom fragments +

+ + +For information on which fragments Cumulocity supports please see the +[Cumulocity API docs](https://cumulocity.com/guides/reference/device-management-library/). diff --git a/docs/src/operate/c8y/c8y_service_monitoring.md b/docs/src/operate/c8y/health-monitoring.md similarity index 82% rename from docs/src/operate/c8y/c8y_service_monitoring.md rename to docs/src/operate/c8y/health-monitoring.md index df5360c939b..44f9017cd35 100644 --- a/docs/src/operate/c8y/c8y_service_monitoring.md +++ b/docs/src/operate/c8y/health-monitoring.md @@ -1,18 +1,15 @@ --- title: Health Monitoring tags: [Operate, Cumulocity, Monitoring] -sidebar_position: 8 +description: Monitoring the health of services on devices --- -# How to monitor health of service from Cumulocity IoT - -The health of a `thin-edge.io` service or any other `service` that is running on the `thin-edge.io` device +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**. -## Send the health status of a service to health topic. +## Publish health status -A health status message can be published for any service on a `status/health` channel. The health message has to contain -at least the `status` of the service. +A health status message can be published for any service on a `status/health` channel. The health message should at least contain the `status` of the service. :::note The `status` here can be `up or down` or any other string. For example, `unknown`. @@ -26,7 +23,7 @@ tedge mqtt pub te/device/my-device/service/my-test-service/status/health '{"stat ``` :::note -The health status message has to be sent as a `retain` message. +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`. @@ -40,12 +37,12 @@ auto-registration, it will be auto-registered as described [in the Auto Registra section](https://thin-edge.github.io/thin-edge.io/next/references/mqtt-api/#auto-registration). For example, assuming a service `device/child1/service/service1`, running on a device `device/child1//`, which is a -child device of thin-edge.io device `device/main//` with an ID of `TE_DEVICE`, the resulting topic mapping looks like +child device of %%te%% device `device/main//` with an ID of `TE_DEVICE`, the resulting topic mapping looks like this:
-**Thin-edge.io health status message** +**%%te%% health status message** ```sh te2mqtt formats=v1 tedge mqtt pub te/device/child1/service/service1/status/health '{"status":"up"}' -q 2 -r diff --git a/docs/src/operate/c8y/index.md b/docs/src/operate/c8y/index.md index fd7e6631b78..241e7a06fe1 100644 --- a/docs/src/operate/c8y/index.md +++ b/docs/src/operate/c8y/index.md @@ -2,10 +2,11 @@ title: Device Management with Cumulocity tags: [Operate, Cloud] sidebar_position: 9 +description: Device management with %%te%% and Cumulocity IoT --- import DocCardList from '@theme/DocCardList'; -This section is for the cloud operators who manage a fleet of thin-edge devices connected to Cumulocity. +This section is for the cloud operators who manage a fleet of %%te%% devices connected to Cumulocity. diff --git a/docs/src/operate/c8y/tedge_log_management.md b/docs/src/operate/c8y/log-management.md similarity index 88% rename from docs/src/operate/c8y/tedge_log_management.md rename to docs/src/operate/c8y/log-management.md index ebbfdff4a17..2161fa1a300 100644 --- a/docs/src/operate/c8y/tedge_log_management.md +++ b/docs/src/operate/c8y/log-management.md @@ -1,11 +1,9 @@ --- -title: Log management +title: Log Management tags: [Operate, Cumulocity, Log Files] -sidebar_position: 3 +description: Managing log files on devices --- -# How to retrieve logs with the log plugin - The **tedge-agent** service provides out of the box support for requesting log files from a device directly from your Cumulocity UI. If you go to Cumulocity, you should see that you are able to see the logs tab. @@ -14,7 +12,7 @@ To add a new log type, you need to edit the `tedge-log-plugin.toml` in `/etc/ted In this toml file you specify the log type and log path of the logs wished to be retrieved from Cumulocity UI. -For example, if you wish to request thin-edge software logs and mosquitto logs +For example, if you wish to request %%te%% software logs and mosquitto logs an example toml file would be: ```toml title="file: /etc/tedge/plugins/tedge-log-plugin.toml" diff --git a/docs/src/operate/c8y/remote-access.md b/docs/src/operate/c8y/remote-access.md new file mode 100644 index 00000000000..3d71ebe6c25 --- /dev/null +++ b/docs/src/operate/c8y/remote-access.md @@ -0,0 +1,56 @@ +--- +title: Remote Access +tags: [Operate, Cumulocity, Remote Access] +description: Accessing devices remote using tcp based protocols (e.g. ssh, vnc etc.) +--- + +# Remote Access + +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/). + +## Requirements + +- Working %%te%% installation + +- The **Cloud Remote Access Feature** is assigned to your Tenant. If not ask your Administrator to get it assigned to your Tenant. Please note that the Version must be at least 1007.2.0+ + +- The *Cloud Remote Access Role* must be assigned to the user who wants to use that Feature: Administration → Role → <any Role> → check "Remote Access". Assign the role to the user used for the next steps. + +- A VNC or SSH server running on the device you wish to connect to. + + +## Usage + +Make sure %%te%% is connected to Cumulocity. + +You device within Cumulocity should look similar to this (the "Remote access" tab should be visible in the menu on the left): + +

+ Cumulocity remote access device management +

+ +You can configure now within the Remote access tab to which e.g. VNC or SSH server you want to jump to. Please keep in mind that the Host is from the %%te%% point of view. + +

+ Cumulocity remote access endpoint +

+ +If you click on connect after the proper configuration an websocket window opens and %%te%% triggers the c8y-remote-access-connect plugin to reach that websocket. + +

+ Cumulocity remote access websocket +

diff --git a/docs/src/operate/c8y/remote_access_with_cumulocity.md b/docs/src/operate/c8y/remote_access_with_cumulocity.md deleted file mode 100644 index 2047e9479c2..00000000000 --- a/docs/src/operate/c8y/remote_access_with_cumulocity.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Remote Access -tags: [Operate, Cumulocity, Remote Access] -sidebar_position: 8 ---- - -# Cumulocity Remote Access plugin - -To access a device remotely that runs thin-edge.io, 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. - -[View the Cumulocity documentation for the Remote Access feature](https://cumulocity.com/guides/cloud-remote-access/using-cloud-remote-access/) - -## Requirements - -- Working thin-edge.io installation - -- The Cloud Remote Access Feature is assigned to your Tenant. If not ask your Administrator to get it assigned to your Tenant. Please note that the Version must be at least 1007.2.0+ - -- The Cloud Remote Access Role must be assigned to the user who wants to use that Feature: Administration → Role → <any Role> → check "Remote Access". Assign the role to the user used for the next steps. - -- A VNC or SSH server running on the device you wish to connect to. - - -## Usage - -Make sure thin-edge.io is connected to Cumulocity. - -You device within Cumulocity should look similar to this (the "Remote access" tab should be visible in the menu on the left): - -

- Cumulocity remote access device management -

- -You can configure now within the Remote access tab to which e.g. VNC or SSH server you want to jump to. Please keep in mind that the Host is from the thin-edge.io point of view. - -

- Cumulocity remote access endpoint -

- -If you click on connect after the proper configuration an websocket window opens and thin-edge.io triggers the c8y-remote-access-connect plugin to reach that websocket. - -

- Cumulocity remote access websocket -

diff --git a/docs/src/operate/c8y/restart-device.md b/docs/src/operate/c8y/restart-device.md new file mode 100644 index 00000000000..37d934440a0 --- /dev/null +++ b/docs/src/operate/c8y/restart-device.md @@ -0,0 +1,21 @@ +--- +title: Restart Device +tags: [Operate, Operation, Cumulocity] +description: Restarting a device from the cloud +--- + +If your device is running %%te%%, you can restart it from the cloud. + +### Cumulocity IoT + +1. Go to the *Device Management* application in Cumulocity IoT + +2. Find your device and open up its homepage + +3. Open the *Control* menu item + + ![Control button](../../images/control-button-red-highlight.png) + +4. In the top right corner, you will find the *More* button, click it and select, *Restart device* + + ![Restart device button](../../images/restart-button-red-highlight.png) diff --git a/docs/src/operate/c8y/smartrest_templates.md b/docs/src/operate/c8y/smartrest-templates.md similarity index 85% rename from docs/src/operate/c8y/smartrest_templates.md rename to docs/src/operate/c8y/smartrest-templates.md index d88a6070af9..19baff8dc00 100644 --- a/docs/src/operate/c8y/smartrest_templates.md +++ b/docs/src/operate/c8y/smartrest-templates.md @@ -1,17 +1,15 @@ --- -title: SmartRest Template +title: SmartREST Templates tags: [Operate, Cumulocity] -sidebar_position: 4 +description: SmartREST 2.0 template registration and usage --- -# How to use Cumulocity Custom SmartREST 2.0 Templates +[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 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. - -`thin-edge.io` 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/guides/users-guide/device-management/#smartrest-templates). 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 `thin-edge.io`, subscriptions to all these relevant topics on Cumulocity cloud will be done by `thin-edge.io` internally. +When these templates are configured with %%te%%, subscriptions to all these relevant topics on Cumulocity cloud will be done by %%te%% internally. Local processes on the device can access these templates on the local MQTT broker by simply publishing to `c8y/s/uc/` and subscribing to `c8y/s/dc/` topics (note the `c8y/` prefix in topics). A template named `$TEMPLATE_NAME` requires the following subscriptions to be added when connecting to Cumulocity: @@ -31,13 +29,13 @@ tedge config get c8y.smartrest.templates ## Add new template to thin-edge configuration -To add new template to `thin-edge.io` the `tedge config` cli tool can be used as following: +To add new template to %%te%% the `tedge config` cli tool can be used as following: ```sh sudo tedge config set c8y.smartrest.templates template-1,template-2 ``` -After adding or removing a template, you will need to run the following command before thin-edge.io will use the new settings: +After adding or removing a template, you will need to run the following command before %%te%% will use the new settings: ```sh sudo tedge reconnect c8y @@ -98,7 +96,7 @@ tedge config get c8y.smartrest.templates ["template-1"] ``` -After adding or removing a template, you will need to run the following command before thin-edge.io will use the new settings: +After adding or removing a template, you will need to run the following command before %%te%% will use the new settings: ```sh sudo tedge reconnect c8y @@ -108,9 +106,9 @@ sudo tedge reconnect c8y The following example shows how to create a new SmartREST template with a single custom operation which will be activated when an operation is created with the `set_wifi` fragment. The operation includes 3 parameters where the wifi `name`, `ssid` and `type` are included in the message which is sent to the device via MQTT. -In this example, the operation handler on the thin-edge.io 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. +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 thin-edge.io 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 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 snippets below are used to illustrate the message translation of the Cumulocity IoT operation to the message received by the device. @@ -128,7 +126,7 @@ The snippets below are used to illustrate the message translation of the Cumuloc } ``` -**SmartREST (CSV) format received by thin-edge.io** +**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: @@ -227,7 +225,7 @@ Alternatively, you can import a SmartREST template from an existing file. This a On the device, perform the following steps: -1. Set the custom SmartREST template to be used by thin-edge.io +1. Set the custom SmartREST template to be used by %%te%% ```sh tedge config set c8y.smartrest.templates "custom_devmgmt" @@ -242,7 +240,7 @@ On the device, perform the following steps: ``` :::info - This step ensures that the new SmartREST template id is also added in the list of MQTT topics to subscribe to. Without this step, thin-edge.io will not be able to receive the custom operation. + This step ensures that the new SmartREST template id is also added in the list of MQTT topics to subscribe to. Without this step, %%te%% will not be able to receive the custom operation. ::: :::tip @@ -251,7 +249,7 @@ You don't need to re-run this step when you add a new message definition to an e ### Step 3: Creating the operation handler -On your thin-edge.io device, run the following steps: +On your %%te%% device, run the following steps: 1. Create the following custom operation handler file @@ -262,7 +260,7 @@ On your thin-edge.io device, run the following steps: on_message = "dm101" ``` - The operation definition tells thin-edge.io what to do when receiving a specific message (with the message id) on the given topic. Specifically, the definition will execute the `/usr/bin/set_wifi` script when a `dm101` message is received on the `c8y/s/dc/custom_devmgmt` topic. + The operation definition tells %%te%% what to do when receiving a specific message (with the message id) on the given topic. Specifically, the definition will execute the `/usr/bin/set_wifi` script when a `dm101` message is received on the `c8y/s/dc/custom_devmgmt` topic. 2. Create the script which is called when receiving the `dm101` message @@ -339,7 +337,7 @@ On your thin-edge.io device, run the following steps: ![smartrest-custom-operation-control.png](./images/smartrest-custom-operation-control.png) -3. On the thin-edge.io device, open a console, and check the log file which when processing the custom operation +3. On the %%te%% device, open a console, and check the log file which when processing the custom operation The following command uses a simple bash one-liner to print the contents of the most recent file created matching the `set_wifi*` pattern under the `/var/log/tedge/agent/` folder. @@ -368,7 +366,7 @@ If you encounter any problems whilst trying to create or use a custom operation ### Check the incoming MQTT message -You can observe the MQTT message which is received by the local MQTT broker by subscribing to the following topic on your thin-edge.io device: +You can observe the MQTT message which is received by the local MQTT broker by subscribing to the following topic on your %%te%% device: ```sh tedge mqtt sub 'c8y/#' @@ -382,7 +380,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 that the thin-edge.io config has been updated to subscribe to the related SmartREST topic. Maybe you forgot to run: +* Check that the %%te%% config has been updated to subscribe to the related SmartREST topic. Maybe you forgot to run: ``` sudo tedge reconnect c8y @@ -392,7 +390,7 @@ If you don't receive a message, then check the following: If you know the expected format of the SmartREST message, then you can debug any potential scripting problems by manually calling your script with a simulated message. -For instance, if the operation definition has `exec.command` set to call the `/usr/bin/set_wifi` script, then you can simulate how thin-edge.io would call the script by using the following command: +For instance, if the operation definition has `exec.command` set to call the `/usr/bin/set_wifi` script, then you can simulate how %%te%% would call the script by using the following command: ```sh sudo -u tedge /usr/bin/set_wifi "dm101,$(tedge config get device.id),Factory Wifi,factory-onboarding-wifi,WPA3-Personal" diff --git a/docs/src/operate/installation/install_and_enable_software_management.md b/docs/src/operate/c8y/software-management.md similarity index 76% rename from docs/src/operate/installation/install_and_enable_software_management.md rename to docs/src/operate/c8y/software-management.md index 7bc7175d770..b3fac00dd1b 100644 --- a/docs/src/operate/installation/install_and_enable_software_management.md +++ b/docs/src/operate/c8y/software-management.md @@ -1,23 +1,21 @@ --- -title: Enable Software Management Support +title: Software Management tags: [Operate, Installation, Software Management] -sidebar_position: 4 +description: Managing software on devices --- -# Install and enable the software management feature - :::note As of now, this feature is supported only on devices with **debian** based distributions, which use the **apt** package manager(Ex: RaspberryPi OS , Ubuntu, Debian), from Cumulocity cloud. ::: -Below steps show how to download, install and enable thin-edge software management feature. +Below steps show how to download, install and enable %%te%% software management feature. ## Download and install software management packages on the device As a prerequisite, install [tedge and tedge-mapper](../../install/index.md) if not installed already. -The thin-edge software management packages are in repository on GitHub: [thin-edge.io](https://github.com/thin-edge/thin-edge.io/releases). +The %%te%% software management packages are in repository on GitHub: [%%te%%](https://github.com/thin-edge/thin-edge.io/releases). To download the package from github repository use the following command (use desired version): @@ -26,7 +24,7 @@ curl -LJO https://github.com/thin-edge/thin-edge.io/releases/download/_ ``` Where: -- `version` -> thin-edge.io software management components version in x.x.x format +- `version` -> %%te%% software management components version in x.x.x format - `arch` -> architecture type (amd64, armhf) Download `tedge-apt-plugin` and `tedge-agent` @@ -38,7 +36,7 @@ curl -LJO https://github.com/thin-edge/thin-edge.io/releases/download/0.9.0/tedg Once the packages are downloaded, proceed to installation. -To install `tedge-apt-plugin` and `tedge-agent` on thin-edge device do: +To install `tedge-apt-plugin` and `tedge-agent` on a %%te%% device do: ```sh sudo dpkg -i tedge-apt-plugin__.deb @@ -58,9 +56,9 @@ sudo tedge connect c8y ### Using tedge connect c8y The `tedge connect c8y` will automatically start and enable the software management feature. -Find more about [how to connect thin-edge device to cloud](../connection/connect.md) +Find more about [how to connect %%te%% device to cloud](../c8y/connect.md) -Once the thin-edge device is successfully connected to Cumulocity cloud, the **Software** option will be enabled and +Once the %%te%% device is successfully connected to Cumulocity cloud, the **Software** option will be enabled and the list of software that are installed on the device will be visible as shown in the figure below.

@@ -72,7 +70,7 @@ the list of software that are installed on the device will be visible as shown i

:::note -Disconnecting thin-edge device from cloud with `tedge disconnect c8y` command will stop and disable the software management feature. +Disconnecting %%te%% device from cloud with `tedge disconnect c8y` command will stop and disable the software management feature. ::: ### Manually enabling and disabling software management feature diff --git a/docs/src/operate/c8y/supported_operations.md b/docs/src/operate/c8y/supported-operations.md similarity index 97% rename from docs/src/operate/c8y/supported_operations.md rename to docs/src/operate/c8y/supported-operations.md index 5eca5b70170..459225fb72a 100644 --- a/docs/src/operate/c8y/supported_operations.md +++ b/docs/src/operate/c8y/supported-operations.md @@ -1,11 +1,9 @@ --- title: Supported Operations tags: [Operate, Cumulocity, Operation] -sidebar_position: 1 +description: Declaring and using custom operations --- -# Supported Operations - ## Concepts ### Device operations @@ -124,7 +122,7 @@ but only when such a capability message is received from a child device. ### Removing supported operations -To remove a supported operation for a thin-edge device, the corresponding operation file must be removed from the `/etc/tedge/operations/c8y` directory. eg: +To remove a supported operation for a %%te%% device, the corresponding operation file must be removed from the `/etc/tedge/operations/c8y` directory. eg: ```sh sudo rm /etc/tedge/operations/c8y/c8y_Restart @@ -166,7 +164,7 @@ When such a message is received, the operation plugin located at `/etc/tedge/ope The operation is configured to `timeout` after 10 seconds, to avoid it from running for too long/forever. :::note -The operation file needs to be readable by `thin-edge.io` user - `tedge` - and should have permissions `644`. +The operation file needs to be readable by %%te%% user - `tedge` - and should have permissions `644`. The filename **MUST** only use alphanumeric and underscore characters, e.g. `A-Z`, `a-z`, `0-9` and `_`. You cannot use a dash "-", or any other characters in the filename, otherwise the custom operation definition will be ignored. ::: diff --git a/docs/src/operate/configuration/config.md b/docs/src/operate/configuration/configuration-tools.md similarity index 88% rename from docs/src/operate/configuration/config.md rename to docs/src/operate/configuration/configuration-tools.md index 9f5cfed74e9..414db7c3b0d 100644 --- a/docs/src/operate/configuration/config.md +++ b/docs/src/operate/configuration/configuration-tools.md @@ -1,17 +1,19 @@ --- title: Configuration Tools tags: [Operate, Configuration] -sidebar_position: 1 +description: Customizing %%te%% settings --- -# How-to configure thin-edge.io +## Overview -`thin-edge.io` can be configured in a few different ways: +%%te%% can be configured in a few different ways: 1. The `tedge config` command ([reference here](../../references/cli/tedge-config.md)) 2. The `tedge.toml` file 3. Environment variables +The following sections detail each of the configuration methods. + ## tedge config command To set a value in `tedge.toml` using the `tedge` CLI, you can run: @@ -48,7 +50,7 @@ bind_address = "127.0.0.1" ## Environment variables -To aid in configuring `thin-edge.io` in containerised environments, `thin-edge.io` supports passing in the configuration via environment variables. For instance, to configure the Cumulocity URL and MQTT bind address, you can run: +To aid in configuring %%te%% in containerised environments, %%te%% supports passing in the configuration via environment variables. For instance, to configure the Cumulocity URL and MQTT bind address, you can run: ```sh env TEDGE_C8Y_URL=mytenant.cumulocity.com TEDGE_MQTT_BIND_ADDRESS=127.0.0.1 tedge connect c8y diff --git a/docs/src/operate/configuration/index.md b/docs/src/operate/configuration/index.md index b40c4fbeca6..f69f53096a3 100644 --- a/docs/src/operate/configuration/index.md +++ b/docs/src/operate/configuration/index.md @@ -2,10 +2,11 @@ title: Configuration tags: [Operate, Configuration] sidebar_position: 2 +description: How to configure %%te%% --- import DocCardList from '@theme/DocCardList'; -How to configure thin-edge +How to configure %%te%% diff --git a/docs/src/operate/configuration/config-mapper-mqtt-topics.md b/docs/src/operate/configuration/mapper-configuration.md similarity index 97% rename from docs/src/operate/configuration/config-mapper-mqtt-topics.md rename to docs/src/operate/configuration/mapper-configuration.md index a24ca90b90b..ab88c5ac318 100644 --- a/docs/src/operate/configuration/config-mapper-mqtt-topics.md +++ b/docs/src/operate/configuration/mapper-configuration.md @@ -1,10 +1,9 @@ --- title: Mapper Configuration tags: [Operate, Configuration, Cloud, MQTT] +description: How to control which MQTT topics the mappers subscribe to --- -# How to control which MQTT topics the mappers subscribe to - The cloud-specific mappers subscribe to the reserved MQTT topics and convert incoming MQTT messages to cloud-specific messages. In an advanced use case, such as using more than one cloud mappers for the same device, you may want to customize the external tedge MQTT topics that each cloud mapper subscribes to. diff --git a/docs/src/operate/configuration/config_local_mqtt_bind_address_and_port.md b/docs/src/operate/configuration/mosquitto-configuration.md similarity index 83% rename from docs/src/operate/configuration/config_local_mqtt_bind_address_and_port.md rename to docs/src/operate/configuration/mosquitto-configuration.md index 05e07ca7c4c..295528ea593 100644 --- a/docs/src/operate/configuration/config_local_mqtt_bind_address_and_port.md +++ b/docs/src/operate/configuration/mosquitto-configuration.md @@ -1,26 +1,26 @@ --- title: Mosquitto Configuration tags: [Operate, Configuration, MQTT] -sidebar_position: 2 +description: Mosquitto specific configuration guide --- -# How to configure the local port and bind address in mosquitto? +## Configuring mosquitto bind address and port {#mosquitto-bind-address} -Configuring a mosquitto port and bind address in thin-edge.io is a three-step process. +Configuring a mosquitto port and bind address in %%te%% is a three-step process. :::note The mqtt.bind.port and the mqtt.bind.address can be set/unset independently. ::: -## Step 1: Disconnect thin-edge.io edge device +### Step 1: Disconnect thin-edge.io edge device -The thin edge device has to be disconnected from the cloud using the `tedge` command +The %%te%% device has to be disconnected from the cloud using the `tedge` command ```sh tedge disconnect c8y/az ``` -## Step 2: Set the new mqtt port and bind address +### Step 2: Set the new mqtt port and bind address Use the `tedge` command to set the mqtt.bind.port and mqtt.bind.address with a desired port and bind address as below. @@ -40,7 +40,7 @@ For example, this can be get as `ifconfig | grep inet` or set it to `0.0.0.0` This will make sure that all the mqtt clients use the newer port and the bind address that has been set once the device is connected to the cloud as in step 3. -## Step 3: Verify the port and the bind address configured/set +### Step 3: Verify the port and the bind address configured/set Use the `tedge` command to print the mqtt port and bind address that has been set as below. @@ -54,7 +54,7 @@ tedge config get mqtt.bind.address 0.0.0.0 ``` -## Step 4: Connect the thin edge device to cloud +### Step 4: Connect the thin edge device to cloud Use the `tedge` command to connect to the desired cloud as below. @@ -87,7 +87,7 @@ sudo tedge config unset mqtt.bind.address Once the port or the bind address is reverted to default, the [step 1](#Step-3:-Connect-the-thin-edge-device-to-cloud) and 3 has to be followed to use the default port or the default bind address. -## Error case +## Common Errors The below example shows that we cannot set a string value for the port number. diff --git a/docs/src/operate/configuration/update_config_paths.md b/docs/src/operate/configuration/path-configuration.md similarity index 83% rename from docs/src/operate/configuration/update_config_paths.md rename to docs/src/operate/configuration/path-configuration.md index 7c16681df94..4640eb0a460 100644 --- a/docs/src/operate/configuration/update_config_paths.md +++ b/docs/src/operate/configuration/path-configuration.md @@ -1,15 +1,13 @@ --- title: Path Configuration tags: [Operate, Configuration, Unix] -sidebar_position: 4 +description: Customize %%te%% file/folder paths --- -# How to change default paths - ## thin-edge.io directories -The `tedge config set` command can be used to change various file system paths used by tedge components. -The following table captures the paths that can be changed, with their default locations. +The `tedge config set` command can be used to change various file system paths used by the %%te%% components. +The following table captures the paths that can be changed along with their default locations. | Config Key | Description | Default Value | |------------|-------------|---------------| @@ -26,10 +24,10 @@ The following daemons also need to be re-started after `data.path` is updated: ## Example: Set a custom temporary directory path -The following shows how to change the temp directory used by thin-edge.io and its components. +The following shows how to change the temp directory used by %%te%% and its components. -1. Create a new directory which will be used by thin-edge.io +1. Create a new directory which will be used by %%te%% ```sh # create a directory (with/without sudo) diff --git a/docs/src/operate/connection/index.md b/docs/src/operate/connection/index.md deleted file mode 100644 index c169128705c..00000000000 --- a/docs/src/operate/connection/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Cloud Connection -tags: [Operate, Cloud] -sidebar_position: 4 ---- - -import DocCardList from '@theme/DocCardList'; - -How to connect your device to the cloud - - diff --git a/docs/src/operate/index.md b/docs/src/operate/index.md index cbe7ca98043..bc368038bdc 100644 --- a/docs/src/operate/index.md +++ b/docs/src/operate/index.md @@ -2,11 +2,12 @@ title: Operate Devices tags: [Operate] sidebar_position: 3 +description: Working with devices that are using %%te%% --- import DocCardList from '@theme/DocCardList'; -This section is for the device operators who operate a device running thin-edge -and the cloud operators who manage a fleet of thin-edge devices. +This section is for the device operators who operate a device running %%te%% +and the cloud operators who manage a fleet of %%te%% devices. diff --git a/docs/src/operate/installation/index.md b/docs/src/operate/installation/index.md index 1c6756eea0b..0fe864a8729 100644 --- a/docs/src/operate/installation/index.md +++ b/docs/src/operate/installation/index.md @@ -6,6 +6,6 @@ sidebar_position: 1 import DocCardList from '@theme/DocCardList'; -How to install thin-edge on a specific hardware and operating systems +How to install %%te%% on a specific hardware and operating systems diff --git a/docs/src/operate/installation/init_systems.md b/docs/src/operate/installation/init-systems.md similarity index 91% rename from docs/src/operate/installation/init_systems.md rename to docs/src/operate/installation/init-systems.md index 8a94c325364..f7fb98094d6 100644 --- a/docs/src/operate/installation/init_systems.md +++ b/docs/src/operate/installation/init-systems.md @@ -2,11 +2,12 @@ title: Init Systems tags: [Installation, Unix, Init, Services] sidebar_position: 1 +description: Extended support for other init systems --- # Init systems -thin-edge.io supports Systemd out of the box, however not all Linux distributions use Systemd. To use thin-edge.io on a Linux distribution without Systemd requires a few extra steps. +%%te%% supports Systemd out of the box, however not all Linux distributions use Systemd. To use %%te%% on a Linux distribution without Systemd requires a few extra steps. Support for different init systems (service managers) is provided by a community repository, [tedge-services](https://github.com/thin-edge/tedge-services). The following service definitions are currently supported (though check the community repository if you don't see your preferred init system in the list). @@ -16,7 +17,7 @@ Support for different init systems (service managers) is provided by a community * SysVinit * supervisord -You are also free to use any service manager to run thin-edge how you want. Check out the [init system reference](../../references/init-system-config.md) guide to see how to create a configuration to interact with your preferred init system. +You are also free to use any service manager to run %%te%% how you want. Check out the [init system reference](../../references/init-system-configuration.md) guide to see how to create a configuration to interact with your preferred init system. :::tip Contributions are welcome in the [tedge-services](https://github.com/thin-edge/tedge-services) repository to improve any of the services, or to add support for additional init systems. @@ -171,7 +172,7 @@ sudo dnf install tedge-supervisord sudo apk add tedge-supervisord ``` -After installing the supervisord definitions, you will have to make sure the supervisord configuration pulls in the services definitions. Below shows an example `supervisord.conf` file which imports all thin-edge.io services definitions which were installed. +After installing the supervisord definitions, you will have to make sure the supervisord configuration pulls in the services definitions. Below shows an example `supervisord.conf` file which imports all %%te%% services definitions which were installed. ```ini title="file: /etc/supervisord.conf" # ... other supervisord settings diff --git a/docs/src/operate/monitoring/enable_tedge_watchdog_using_systemd.md b/docs/src/operate/monitoring/systemd-watchdog.md similarity index 85% rename from docs/src/operate/monitoring/enable_tedge_watchdog_using_systemd.md rename to docs/src/operate/monitoring/systemd-watchdog.md index d4cd3f35f1a..3bc638a4b45 100644 --- a/docs/src/operate/monitoring/enable_tedge_watchdog_using_systemd.md +++ b/docs/src/operate/monitoring/systemd-watchdog.md @@ -3,10 +3,9 @@ title: Systemd Watchdog tags: [Operate, Monitoring] sidebar_position: 1 unlisted: true +description: Enabling systemd watchdog for %%te%% services --- -# Enabling systemd watchdog for thin-edge services - ## Introduction The systemd watchdog feature enables systemd to detect when a service is unhealthy or unresponsive and @@ -15,11 +14,11 @@ To detect if a service is healthy or not, systemd relies on periodic health noti If the service fails to send that notification within a time threshold, then systemd will assume that service to be unhealthy and restart it. -This document describes how the systemd watchdog mechanism can be enabled for thin-edge services. +This document describes how the systemd watchdog mechanism can be enabled for %%te%% services. ## Enabling the systemd watchdog feature for a tedge service -Enabling systemd watchdog for a `thin-edge.io` service (tedge-agent, tedge-mapper-c8y/az/collectd) is a two-step process. +Enabling systemd watchdog for a %%te%% service (tedge-agent, tedge-mapper-c8y/az/collectd) is a two-step process. ### Step 1: Enable the watchdog feature in the systemd service file @@ -74,8 +73,8 @@ Once the health status response is received from a particular service, the `tedg monitored service. :::note -If none of the `thin-edge` services are enabled with the watchdog feature, then the `tedge-watchdog` service will stop with an `inactive` state. -To monitor any of the `thin-edge` services, one has to update the corresponding `systemd` service file with `WatchdogSec` +If none of the %%te%% services are enabled with the watchdog feature, then the `tedge-watchdog` service will stop with an `inactive` state. +To monitor any of the %%te%% services, one has to update the corresponding `systemd` service file with `WatchdogSec` and then restart the `tedge-watchdog` service. ::: @@ -93,7 +92,7 @@ tedge mqtt sub 'te/+/+/+/+/status/health' tedge mqtt sub 'te/+/+/+/+/cmd/health/check' ``` -Check out the [Monitor tedge health](../troubleshooting/monitor_tedge_health.md) for more details about the health endpoint. +Check out the [Monitor tedge health](../troubleshooting/monitoring-service-health.md) for more details about the health endpoint. :::note If the watchdog service does not send the notification to the systemd within `WatchdogSec` interval for a service, diff --git a/docs/src/operate/operations/index.md b/docs/src/operate/operations/index.md deleted file mode 100644 index 6f1168fd716..00000000000 --- a/docs/src/operate/operations/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Operations -tags: [Operate, Operation] -sidebar_position: 6 ---- - -import DocCardList from '@theme/DocCardList'; - -Maintenance operations on a thin-edge device - - diff --git a/docs/src/operate/operations/restart_device_operation.md b/docs/src/operate/operations/restart_device_operation.md deleted file mode 100644 index 4e9a7c85f1b..00000000000 --- a/docs/src/operate/operations/restart_device_operation.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Device Restart -tags: [Operate, Operation] -sidebar_position: 1 ---- - -# How to restart your thin-edge.io device - -If your device is running thin-edge.io, you can restart it from the cloud. This guide shows how to trigger a restart operation from different cloud providers. - -### Cumulocity - -Go to your device's homepage on c8y, and find the "Control" button. - -![Control button](../../images/control-button-red-highlight.png) - - In the top right corner, you will find the "More" button, click it and select, "Restart device". - -![Restart device button](../../images/restart-button-red-highlight.png) diff --git a/docs/src/operate/plugins/index.md b/docs/src/operate/plugins/index.md index ed7002f9f22..39045260ad1 100644 --- a/docs/src/operate/plugins/index.md +++ b/docs/src/operate/plugins/index.md @@ -25,7 +25,7 @@ New plugins can be added by following these [instructions](https://github.com/th In addition, a list of [Github plugins](https://github.com/topics/thin-edge) are visible directly from Github. If your plugin is hosted on Github as a public repository, then you can make your plugin discoverable by adding the `thin-edge` tag to the repository, afterwards the plugin will appear in the list.
- ![Github thin-edge.io plugins](github_plugins_list.png) + ![Github %%te%% plugins](github_plugins_list.png)
Github plugins
diff --git a/docs/src/operate/security/cloud_authentication.md b/docs/src/operate/security/cloud-authentication.md similarity index 87% rename from docs/src/operate/security/cloud_authentication.md rename to docs/src/operate/security/cloud-authentication.md index f804f94fdf2..176918fd511 100644 --- a/docs/src/operate/security/cloud_authentication.md +++ b/docs/src/operate/security/cloud-authentication.md @@ -1,10 +1,10 @@ --- title: Cloud Authentication tags: [Operate, Security] -sidebar_position: 3 +description: Configuring certificates for your cloud connection --- -When thin-edge connects a cloud, the cloud endpoint is authenticated using X.509 certificates. +When %%te%% connects a cloud, the cloud endpoint is authenticated using X.509 certificates. For that to work, the signing certificate of the cloud certificate must be trusted by the device. Usually, these certificates are stored in `/etc/ssl/certs` and nothing specific has to done on the device. @@ -12,7 +12,7 @@ A specific configuration will be required only for cloud endpoints which CA is n ## Configuration -Several `tedge config` settings are used by thin-edge to locate the signing certificate of the cloud endpoint. +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) @@ -25,7 +25,7 @@ Per default, all these paths are set to the system default: `/etc/ssl/certs`. ## Adding a Root Certificate -If the server you are trying to connect `thin-edge.io` to is presenting a certificate with a root that is not currently trusted, +If the server you are trying to connect %%te%% to is presenting a certificate with a root that is not currently trusted, then you can add the server's root certificate to the list of trusted root certificates. For the most part the store will be filled with certificates from your TLS/SSL provider, but if this is not the case you may need to update your local certificate store. @@ -50,7 +50,7 @@ If you do not have the `ca-certificates` package installed on your system, insta sudo apt install ca-certificates ``` -To add a self-signed certificate to the trusted certificate repository on thin-edge.io system: +To add a self-signed certificate to the trusted certificate repository on %%te%% system: Create a `/usr/local/share/ca-certificates/` directory if it does not exist on your computer: diff --git a/docs/src/operate/security/cumulocity_token.md b/docs/src/operate/security/cumulocity-token.md similarity index 90% rename from docs/src/operate/security/cumulocity_token.md rename to docs/src/operate/security/cumulocity-token.md index 87696889043..fd3b4d4f0da 100644 --- a/docs/src/operate/security/cumulocity_token.md +++ b/docs/src/operate/security/cumulocity-token.md @@ -1,18 +1,18 @@ --- title: Cumulocity IoT Token tags: [Operate, Security, Cumulocity, JWT] -sidebar_position: 11 +description: Requesting a token for manual Cumulocity IoT API requests --- :::tip -thin-edge.io provides an alternative way to access the Cumulocity IoT REST API without having to request a token. The [Cumulocity IoT Proxy Service](../../references/tedge-cumulocity-proxy.md) can be used which handles the authorization as required. +%%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. -It is recommended to use the [Cumulocity IoT Proxy Service](../../references/tedge-cumulocity-proxy.md) where possible. +It is recommended to use the [Cumulocity IoT Proxy Service](../../references/cumulocity-proxy.md) where possible. ::: ## Overview -For instances where you cannot use the [Cumulocity IoT Proxy Service](../../references/tedge-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 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. ## Retrieving the token @@ -103,7 +103,7 @@ curl -s -H "Authorization: Bearer $C8Y_TOKEN" \ ``` :::tip -The same functionality (as above) can be achieved by using the [Cumulocity IoT Proxy Service](../../references/tedge-cumulocity-proxy.md): +The same functionality (as above) can be achieved by using the [Cumulocity IoT Proxy Service](../../references/cumulocity-proxy.md): ```sh curl -s -H "Accept: application/json" \ diff --git a/docs/src/operate/security/device-certificate.md b/docs/src/operate/security/device-certificate.md index a9db43ebcf6..5fdf5d85715 100644 --- a/docs/src/operate/security/device-certificate.md +++ b/docs/src/operate/security/device-certificate.md @@ -1,7 +1,7 @@ --- -title: Device Certificate Setting +title: Device Certificate Settings tags: [Operate, Security, Cloud] -sidebar_position: 2 +description: Controlling device certificate settings --- ## Obtaining a Device Certificate @@ -33,7 +33,7 @@ i.e. on the same box as the MQTT broker establishing the MQTT connection to the Note that *only* the MQTT broker should be able to read or write the private key, while the certificate itself is public. -Then thin-edge must be told where the certificate is stored. +Then %%te%% must be told where the certificate is stored. Note that the device certificate file must contain not only the device certificate itself but also the signing certificate (so the cloud endpoint can check the chain, starting from the device certificate up to the trusted root). @@ -43,7 +43,7 @@ but also the signing certificate cat demo-device-007.pem > demo-device-007.chain.pem cat signing-cert.pem >> demo-device-007.chain.pem -# Configure the cert chain file as the main cert to be used by thin-edge.io +# Configure the cert chain file as the main cert to be used by %%te%% tedge config set device.cert_path /etc/mosquitto/certs/demo-device-007.chain.pem tedge config set device.key_path /etc/mosquitto/certs/demo-device-007.key ``` diff --git a/docs/src/operate/security/https_configuration.md b/docs/src/operate/security/https-configuration.md similarity index 96% rename from docs/src/operate/security/https_configuration.md rename to docs/src/operate/security/https-configuration.md index 6a7a610b7f4..27848c74b83 100644 --- a/docs/src/operate/security/https_configuration.md +++ b/docs/src/operate/security/https-configuration.md @@ -1,12 +1,12 @@ --- title: HTTPS Configuration tags: [Operate, Security, HTTP] -sidebar_position: 6 +description: Setting up HTTPS for secure local communication --- -Thin-edge provides two services over HTTP: -- The [File Transfer Service](../../references/tedge-file-transfer-service.md) is used by the mappers and the child devices to transfer files locally. -- The [Cumulocity Proxy](../../references/tedge-cumulocity-proxy.md) acts as a local proxy to the Cumulocity IoT REST API. +%%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. Three levels of security are supported: @@ -144,7 +144,7 @@ Hence, the signing certificate will have to be added to the list of trusted root ### Generating Certificates -Thin-edge currently provides no specific tool to generate and deploy certificates over child devices. +%%te%% currently provides no specific tool to generate and deploy certificates over child devices. You can use the following script to generate all the required certificates. diff --git a/docs/src/operate/security/index.md b/docs/src/operate/security/index.md index 57866b950af..bd97712295e 100644 --- a/docs/src/operate/security/index.md +++ b/docs/src/operate/security/index.md @@ -2,25 +2,26 @@ title: Security and Access Control tags: [Operate, Security] sidebar_position: 1 +description: Configuring %%te%% for secure communication --- import DocCardList from '@theme/DocCardList'; -Thin-edge uses X.509 certificates as the key mechanism to authenticate peers. +%%te%% uses X.509 certificates as the key mechanism to authenticate peers. - The MQTT connection between the gateway device and the cloud is established over TLS and uses certificates to authenticate the device on the cloud, as well as to authenticate the cloud on the device. - The local MQTT connections, from the miscellaneous services and child devices to the local MQTT broker, can also be configured to be established over TLS. In the stronger setting, the clients have to authenticate themselves using certificates. -- The local HTTP services (namely the [File Transfer Service](../../references/tedge-file-transfer-service.md) and the [Cumulocity Proxy](../../references/tedge-cumulocity-proxy.md)) +- The local HTTP services (namely the [File Transfer Service](../../references/file-transfer-service.md) and the [Cumulocity Proxy](../../references/cumulocity-proxy.md)) can be configured to use HTTPS. As for MQTT, certificate-based authentication of the clients can also be enforced. A complete setting requires numerous private keys, certificates and trust chains. Nothing really complex, but this requires rigorous settings. It is therefore recommended to set things up step by step. - The only mandatory step is to configure the authentication between the gateway device and the cloud. - - This can be done using a [self-signed device certificate](self_signed_device_certificate.md) or a proper [CA-signed certificate](device-certificate.md). + - This can be done using a [self-signed device certificate](self-signed-device-certificate.md) or a proper [CA-signed certificate](device-certificate.md). - Most of the time the cloud certificate will be trusted out-of-the-box, - but a [self-signed cloud certificate](cloud_authentication.md) will need specific care. + but a [self-signed cloud certificate](cloud-authentication.md) will need specific care. - The second step is to enable TLS on the local MQTT and HTTP connections. - The final step is to enforce certificate-based client authentication on the local MQTT and HTTP connections. diff --git a/docs/src/operate/security/mqtt_tls_configuration.md b/docs/src/operate/security/mqtt-tls-configuration.md similarity index 97% rename from docs/src/operate/security/mqtt_tls_configuration.md rename to docs/src/operate/security/mqtt-tls-configuration.md index c09799e5acf..207c972fbbf 100644 --- a/docs/src/operate/security/mqtt_tls_configuration.md +++ b/docs/src/operate/security/mqtt-tls-configuration.md @@ -1,10 +1,10 @@ --- title: MQTT TLS Configuration tags: [Operate, Security, MQTT] -sidebar_position: 5 +description: Setting up TLS for secure local MQTT communication --- -thin-edge.io supports certificate-based authentication when communicating with +%%te%% supports certificate-based authentication when communicating with an MQTT broker. Three levels of security are supported: 1. No authentication (default) @@ -73,7 +73,7 @@ sudo tedge config set mqtt.external.ca_path /etc/ssl/certs ## Server authentication -Enabling server authentication causes thin-edge.io MQTT clients to require a +Enabling server authentication causes %%te%% MQTT clients to require a valid certificate from a broker when connecting. The broker certificate is valid when it is signed by a CA that the clients trust. @@ -167,7 +167,7 @@ set. As with the server private key, set `tedge:tedge` as the owner of the certificate and the private key, so that the private key can be read by -thin-edge components. +%%te%% components. ### Step 3: Restart services diff --git a/docs/src/operate/security/self_signed_device_certificate.md b/docs/src/operate/security/self-signed-device-certificate.md similarity index 92% rename from docs/src/operate/security/self_signed_device_certificate.md rename to docs/src/operate/security/self-signed-device-certificate.md index 9377bdbeb77..a1e8e9e9ae1 100644 --- a/docs/src/operate/security/self_signed_device_certificate.md +++ b/docs/src/operate/security/self-signed-device-certificate.md @@ -1,17 +1,17 @@ --- title: Self-signed Device Certificate tags: [Operate, Security, Cloud] -sidebar_position: 1 +description: Using self-signed device certificates with %%te%% --- -Using a self-signed device certificate is the simplest way to connect a thin-edge device to the cloud. +Using a self-signed device certificate is the simplest way to connect a %%te%% device to the cloud. This is a secure method even if more adapted for testing purposes. Indeed, the self-signed certificates must be trusted individually by the cloud tenant, raising managing issues when there are more than a few devices. ## Create self-signed certificate -To create a new certificate you can use [`tedge cert create`](../../references/cli/tedge-cert.md) thin-edge.io command: +To create a new certificate you can use [`tedge cert create`](../../references/cli/tedge-cert.md) %%te%% command: ```sh sudo tedge cert create --device-id alpha @@ -63,7 +63,7 @@ tedge cert upload c8y --user ## Renew self-signed certificate -To renew the expired certificate you can use [`tedge cert renew`](../../references/cli/tedge-cert.md) thin-edge.io command: +To renew the expired certificate you can use [`tedge cert renew`](../../references/cli/tedge-cert.md) %%te%% command: ```sh sudo tedge cert renew @@ -123,5 +123,5 @@ Afterwards, try executing [`tedge cert create`](../../references/cli/tedge-cert. ## Next steps -1. [How to connect?](../connection/connect.md) -2. [How to use mqtt pub/sub?](../telemetry/pub_sub.md) +1. [How to connect?](../c8y/connect.md) +2. [How to use mqtt pub/sub?](../telemetry/mqtt-tools.md) diff --git a/docs/src/operate/telemetry/data-model.md b/docs/src/operate/telemetry/data-model.md index 681e696b0c7..e8cba31c84f 100644 --- a/docs/src/operate/telemetry/data-model.md +++ b/docs/src/operate/telemetry/data-model.md @@ -1,27 +1,25 @@ --- title: Data Model tags: [Concept, MQTT] -sidebar_position: 9 +description: Overview of the %%te%% data model and how to interact with it --- -# thin-edge Data Model - -The **data model** identifies all data send or received from/to **thin-edge** and its components, to interact with those. +The **data model** identifies all data send or received from/to %%te%% and its components, to interact with those. For all data it defines format and explains behaviour. ## Use of MQTT -**thin-edge** expects the MQTT broker [mosquitto](https://mosquitto.org/) to be available on the device. -**thin-edge** uses **mosquitto** to consume and provide telemetry data. All telemetry data are reflected with specific MQTT topics and payload in JSON format. +%%te%% expects the MQTT broker [mosquitto](https://mosquitto.org/) to be available on the device. +%%te%% uses **mosquitto** to consume and provide telemetry data. All telemetry data are reflected with specific MQTT topics and payload in JSON format. -**thin-edge** assumes **mosquitto** is configured in a secure manner, to avoid any inappropriate access to **thin-edge** topics and payload. -Any malicious access to the broker can hazard **thin-edge** and all connected devices. Mosquitto provides a wide range of authentication and access control options. For more details see _Authentication_ and _ACL_ (Access Control List) in [mosquitto documentation](https://mosquitto.org/man/mosquitto-conf-5.html). +%%te%% assumes **mosquitto** is configured in a secure manner, to avoid any inappropriate access to %%te%% topics and payload. +Any malicious access to the broker can hazard %%te%% and all connected devices. Mosquitto provides a wide range of authentication and access control options. For more details see _Authentication_ and _ACL_ (Access Control List) in the [mosquitto documentation](https://mosquitto.org/man/mosquitto-conf-5.html). ### Telemetry Data on MQTT All telemetry data (**Measurements**, **Events**, **Alarms**) are reflected with MQTT topics, where each has its specific subtopic (e.g. `te/+/+/+/+/m/+`, `te/+/+/+/+/e/+`, `te/+/+/+/+/a/+` etc.). - * each provider of a **measurement**, **event** or **alarm** sends the occurring data to **thin-edge's** MQTT broker + * each provider of a **measurement**, **event** or **alarm** sends the occurring data to %%te%%'s MQTT broker * a provider can be the domain application, other SW components / 3rd parties * all processes (e.g. the domain application, other SW components / 3rd parties) on the main-device and all child-devices can consume those telemetry data from the MQTT broker * the cloud mapper on the **main-device** picks-up _all_ telemetry data from the MQTT broker and transfers those to the cloud @@ -32,7 +30,7 @@ The communication diagram below illustrates that behaviour. ### Telemetry Data for Child-Devices -All telemetry data provided to the MQTT bus are associated by **thin-edge** and all consumers with the thin-edge **main-device** or some **child-device**. +All telemetry data provided to the MQTT bus are associated by %%te%% and all consumers with the %%te%% **main-device** or some **child-device**. MQTT topics for the **main-device**: @@ -99,11 +97,11 @@ One MQTT message can contain a mixture of more than one single-value and multi-v | --------- | --------- | |`name` |a string that identifies the measurement uniquely in context of the device| |`value` |the value that was sampled; can be named (especially in context of a multi-value measurement) or unnamed; must be an integer or floating point number| -|`timestamp` |optional time that indicates when values were sampled; when not provided, thin-edge.io uses the current system time as the time of the sample; when provided must be conform to ISO 8601| +|`timestamp` |optional time that indicates when values were sampled; when not provided, %%te%% uses the current system time as the time of the sample; when provided must be conform to ISO 8601| #### Behaviour of measurements -- thin-edge does not store any historical sampled values for measurements -- there is no initialization value for measurements; i.e. a measurement is not visible on thin-edge before the 1st sample was sent to thin-edge +- %%te%% does not store any historical sampled values for measurements +- there is no initialization value for measurements; i.e. a measurement is not visible on %%te%% before the 1st sample was sent to %%te%% - a measurement should never be published as MQTT retain message; That is as a single retained measurement might be consumed and processed more than once by a consuming software component (e.g. when that software component restarts and subscribes again). @@ -138,11 +136,11 @@ te/device////e/ | ------------------ | --------- | |`event-type` |a string part of the MQTT topic, that identifies the event uniquely in context of the device| |`text` |carries a human readable event-text; must be UTF-8 encoded| -|`timestamp` |optional time that indicates when the event has occurred; when not provided, thin-edge.io uses the current system time as the time of the event; when provided must be conform to ISO 8601| +|`timestamp` |optional time that indicates when the event has occurred; when not provided, %%te%% uses the current system time as the time of the event; when provided must be conform to ISO 8601| |`custom fragments` |additional fields are handled as custom specific information; if the connected cloud supports custom fragments its mapper transfers those accordingly to the cloud| #### Behaviour of events -- thin-edge does not store any historical occurrences for events +- %%te%% does not store any historical occurrences for events - an event should never be published as MQTT retain message; That is as a single retained event might be consumed and processed more than once by a consuming software component (e.g. when that software component restarts and subscribes again). @@ -180,11 +178,11 @@ te/device////a/ |`alarm-type` |a string part of the MQTT topic, that identifies the alarm uniquely in context of the device| |`severity` |a string part of the MQTT payload, that indicates the severity of the alarm; recommended to be `critical`, `major`, `minor` or `warning`| |`text` |carries a human readable alarm-text; must be UTF-8 encoded| -|`timestamp` |optional time that indicates when the alarm has occurred; when not provided, thin-edge.io uses the current system time as the time of the alarm; when provided must be conform to ISO 8601| +|`timestamp` |optional time that indicates when the alarm has occurred; when not provided, %%te%% uses the current system time as the time of the alarm; when provided must be conform to ISO 8601| |`custom fragments` |additional fields are handled as custom specific information; if the connected cloud supports custom fragments its mapper transfers those accordingly to the cloud| #### Behaviour of alarms -- thin-edge does not store any historical occurrences for alarms +- %%te%% does not store any historical occurrences for alarms - **alarms** are stateful; i.e. once raised, an **alarm** is active until it was explicitly cleared by the device's software or the cloud - all alarms shall be published as MQTT retain message to reflect the alarm's stateful behaviour in the broker; The retain messages is kept in the MQTT broker as long as the alarm is raised. When a raised alarm is gone again, an empty retain message shall be published to clear diff --git a/docs/src/operate/telemetry/pub_sub.md b/docs/src/operate/telemetry/mqtt-tools.md similarity index 92% rename from docs/src/operate/telemetry/pub_sub.md rename to docs/src/operate/telemetry/mqtt-tools.md index 3691c400e04..ebfb0d54cdc 100644 --- a/docs/src/operate/telemetry/pub_sub.md +++ b/docs/src/operate/telemetry/mqtt-tools.md @@ -1,12 +1,10 @@ --- title: MQTT Tools tags: [Operate, MQTT] -sidebar_position: 1 +description: Publish and subscribe to MQTT messages on the command line --- -# Publish and subscribe to MQTT messages on the command line - -thin-edge.io cli provides a convenient way to debug and aid development process. +%%te%% cli provides a convenient way to debug and aid development process. ## Publish diff --git a/docs/src/operate/troubleshooting/trouble_shooting_monitoring.md b/docs/src/operate/troubleshooting/device-monitoring.md similarity index 68% rename from docs/src/operate/troubleshooting/trouble_shooting_monitoring.md rename to docs/src/operate/troubleshooting/device-monitoring.md index 7ad626f874a..d823c3bc63f 100644 --- a/docs/src/operate/troubleshooting/trouble_shooting_monitoring.md +++ b/docs/src/operate/troubleshooting/device-monitoring.md @@ -1,11 +1,10 @@ --- -title: Troubleshooting Device Monitoring +title: Device Monitoring tags: [Operate, Monitoring] sidebar_position: 1 +description: How to troubleshoot device monitoring --- -# How to trouble shoot device monitoring - To install and configure monitoring on your device, see the tutorial [Monitor your device with collectd](../../start/device-monitoring.md). @@ -30,7 +29,7 @@ tedge mqtt sub 'collectd/#' If no metrics are collected, please check the [MQTT configuration](../../start/device-monitoring.md#collectdconf) :::note -The `collectd.conf` file included with thin-edge.io is configured for conservative interval times, e.g. 10 mins to 1 hour depending on the metric. This is done so that the metrics don't consume unnecessary IoT resources both on the device and in the cloud. If you want to push the metrics more frequently then you will have to adjust the `Interval` settings either globally or on the individual plugins. Make sure you restart the collectd service after making any changes to the configuration. +The `collectd.conf` file included with %%te%% is configured for conservative interval times, e.g. 10 mins to 1 hour depending on the metric. This is done so that the metrics don't consume unnecessary IoT resources both on the device and in the cloud. If you want to push the metrics more frequently then you will have to adjust the `Interval` settings either globally or on the individual plugins. Make sure you restart the collectd service after making any changes to the configuration. ::: ## Is the tedge-mapper-collectd running? diff --git a/docs/src/operate/troubleshooting/index.md b/docs/src/operate/troubleshooting/index.md index df47660bdc3..ad4442136b1 100644 --- a/docs/src/operate/troubleshooting/index.md +++ b/docs/src/operate/troubleshooting/index.md @@ -2,10 +2,11 @@ title: Troubleshooting tags: [Operate] sidebar_position: 8 +description: Troubleshooting %%te%% on a device --- import DocCardList from '@theme/DocCardList'; -How to trouble shoot a thin-edge device +How to troubleshoot a %%te%% device diff --git a/docs/src/operate/troubleshooting/thin_edge_logs.md b/docs/src/operate/troubleshooting/log-files.md similarity index 59% rename from docs/src/operate/troubleshooting/thin_edge_logs.md rename to docs/src/operate/troubleshooting/log-files.md index 49716adc896..c19e6a0b26d 100644 --- a/docs/src/operate/troubleshooting/thin_edge_logs.md +++ b/docs/src/operate/troubleshooting/log-files.md @@ -2,20 +2,20 @@ title: Log Files tags: [Operate, Log Files] sidebar_position: 1 +description: How to get log files from %%te%% components --- -# The thin-edge logs -The logs that are useful for debugging thin-edge.io break down into logs that are created by thin-edge itself and by third party components. +The logs that are useful for debugging %%te%% break down into logs that are created by %%te%% itself and by third party components. -## Thin-edge logs -On a thin-edge device different components like mappers, agent, and plugins run. The log messages of these components can be accessed as below. +## %%te%% logs {#thin-edge-logs} +On a %%te%% device different components like mappers, agent, and plugins run. The log messages of these components can be accessed as below. The logs here capture INFO, WARNING, and ERROR messages. -### Cloud mapper logs -The thin-edge cloud mapper component that sends the measurement data to the cloud can be accessed as below. +### Cloud mapper logs {#mapper} +The %%te%% cloud mapper component that sends the measurement data to the cloud can be accessed as below. -#### Tedge Cumulocity mapper -The log messages of the Cumulocity mapper component that sends the measurement data from the thin-edge device to the Cumulocity +#### Cumulocity mapper {#c8y-mapper} +The log messages of the Cumulocity mapper component that sends the measurement data from the %%te%% device to the Cumulocity cloud can be accessed as below ```sh @@ -26,8 +26,8 @@ journalctl -u tedge-mapper-c8y Run `tedge-mapper --debug c8y` to log more debug messages ::: -#### Tedge Azure mapper -The log messages of the Azure mapper component that sends the measurement data from the thin-edge device to the Azure +#### Azure mapper {#az-mapper} +The log messages of the Azure mapper component that sends the measurement data from the %%te%% device to the Azure cloud can be accessed as below. ```sh @@ -38,8 +38,8 @@ journalctl -u tedge-mapper-az Run `tedge-mapper --debug az` to log more debug messages ::: -#### Tedge AWS mapper -The log messages of the AWS mapper component that sends the measurement data from the thin-edge device to the AWS +#### AWS mapper {#aws-mapper} +The log messages of the AWS mapper component that sends the measurement data from the %%te%% device to the AWS cloud can be accessed as below. ```sh @@ -50,10 +50,10 @@ journalctl -u tedge-mapper-aws Run `tedge_mapper --debug aws` to log more debug messages ::: -### Device monitoring logs -The thin-edge device monitoring component logs can be found as below +### Device monitoring logs {#device-logs} +The %%te%% device monitoring component logs can be found as below -#### Collectd mapper logs +#### Collectd mapper logs {#collectd-mapper} The log messages of the collectd mapper that sends the monitoring data to the cloud can be accessed as below ```sh @@ -64,15 +64,15 @@ journalctl -u tedge-mapper-collectd Run `tedge-mapper --debug collectd` to log more debug messages ::: -### Software Management logs +### Software Management logs {#software-management} This section describes how to access the software management component logs -#### Software update operation log +#### Software update operation log {#software-update} For every new software operation (list/update), a new log file will be created at `/var/log/tedge/agent`. For each `plugin command` like prepare, update-list (install, remove), finalize, and list, the log file captures `exit status, stdout, and stderr` messages. -#### Tedge Agent logs +#### tedge-agent logs {#tedge-agent-logs} The agent service logs can be accessed as below ```sh @@ -90,12 +90,12 @@ tedge-agent : TTY=unknown ; PWD=/tmp ; USER=root ; COMMAND=/etc/tedge/sm-plugins Run `tedge-agent --debug` to log more debug messages ::: -## Thirdparty component logs -Thin-edge uses the third-party components `Mosquitto` as the mqtt broker and `Collectd` for monitoring purpose. -The logs that are created by these components can be accessed on a thin-edge device as below. +## Thirdparty component logs {#thirdparty} +%%te%% uses the third-party components `Mosquitto` as the mqtt broker and `Collectd` for monitoring purpose. +The logs that are created by these components can be accessed on a %%te%% device as below. -### Mosquitto logs -Thin-edge uses `Mosquitto` as the `mqtt broker` for local communication as well as to communicate with the cloud. +### Mosquitto logs {#mosquitto} +%%te%% uses `Mosquitto` as the `mqtt broker` for local communication as well as to communicate with the cloud. The `Mosquitto` logs can be found in `/var/log/mosquitto/mosquitto.log`. `Mosquitto` captures error, warning, notice, information, subscribe, and unsubscribe messages. @@ -103,8 +103,8 @@ The `Mosquitto` logs can be found in `/var/log/mosquitto/mosquitto.log`. Set `log_type debug` or `log_type all` on `/etc/mosquitto/mosquitto.conf`, to capture more debug information. ::: -### Collectd logs -`Collectd` is used for monitoring the resource status of a thin-edge device. +### Collectd logs {#collectd} +`Collectd` is used for monitoring the resource status of a %%te%% device. Collectd logs all the messages at `/var/log/syslog`. So, the collectd specific logs can be accessed using the `journalctl` as below @@ -112,14 +112,14 @@ So, the collectd specific logs can be accessed using the `journalctl` as below journalctl -u collectd ``` -## Configuring log levels in thin-edge.io +## Configuring log levels in %%te%% {#configure-log-levels} -The log levels can be configured for `thin-edge.io` services using either by command line or setting the required log +The log levels can be configured for %%te%% services using either by command line or setting the required log level in `system.toml` -### Setting the log level through cli +### Setting the log level through cli {#configure-log-levels-cli} -The log level can be enabled for a `thin-edge.io` service as below +The log level can be enabled for a %%te%% service as below For example for tedge-mapper: @@ -128,11 +128,11 @@ sudo -u tedge -- tedge-mapper --debug c8y ``` :::note -In a similar way it can be set for all the `thin-edge.io` services. +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. ::: -### Setting log level through system.toml +### 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/docs/src/operate/troubleshooting/monitor_tedge_health.md b/docs/src/operate/troubleshooting/monitoring-service-health.md similarity index 92% rename from docs/src/operate/troubleshooting/monitor_tedge_health.md rename to docs/src/operate/troubleshooting/monitoring-service-health.md index 03ba0dbb5f8..e215018e3ae 100644 --- a/docs/src/operate/troubleshooting/monitor_tedge_health.md +++ b/docs/src/operate/troubleshooting/monitoring-service-health.md @@ -2,11 +2,10 @@ title: Monitoring Service Health tags: [Operate, Monitoring] sidebar_position: 1 +description: How to monitor health of tedge services --- -# How to monitor health of tedge services - -The health of tedge services like `tedge-mapper`, `tedge-agent` etc can be monitored via MQTT. +The health of %%te%% services like `tedge-mapper`, `tedge-agent` etc can be monitored via MQTT. These services expose MQTT health endpoints which you can query to check if the process is still active or not. To get the last known health status of a service you can subscribe to the following topic @@ -69,7 +68,7 @@ All future tedge services will also follow the same topic naming scheme conventi ## Mosquitto bridge health endpoints -The mosquitto bridge clients connecting thin-edge devices to the respective cloud platforms also report their health +The mosquitto bridge clients connecting %%te%% devices to the respective cloud platforms also report their health status as retained messages to `te/device/main/service//status/health` topics. The health check messages published by these clients are just numeric values `1` or `0`, indicating active and dead bridge clients respectively. diff --git a/docs/src/operate/troubleshooting/test_connection.md b/docs/src/operate/troubleshooting/testing-cloud-connection.md similarity index 77% rename from docs/src/operate/troubleshooting/test_connection.md rename to docs/src/operate/troubleshooting/testing-cloud-connection.md index 7b4c4a54383..d9e83f8d527 100644 --- a/docs/src/operate/troubleshooting/test_connection.md +++ b/docs/src/operate/troubleshooting/testing-cloud-connection.md @@ -1,12 +1,11 @@ --- -title: Testing the cloud connection +title: Testing Cloud Connection tags: [Operate, Cloud, Connection] sidebar_position: 1 +description: How to test the connection to the cloud --- -# How to test the connection to cloud? - -We provide a way to test the connection from your device to a cloud provider. +%%te%% provides a way to test the connection from your device to a cloud provider. You can call this connection check function by ```sh @@ -24,7 +23,7 @@ The subsequent sections explain the cloud-specific behaviour. ### For Cumulocity IoT -The test publishes [a SmartREST2.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/guides/device-sdk/mqtt/#a-nameinventory-templatesinventory-templates-1xxa) 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/docs/src/overview.md b/docs/src/overview.md index 54f518abec7..dc0f80158b6 100644 --- a/docs/src/overview.md +++ b/docs/src/overview.md @@ -36,7 +36,7 @@ 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), [Azure IoT](start/connect-azure.md) or [AWS IoT](start/connect-aws.md), -- [send telemetry data](start//send-thin-edge-data.md), [alarms](start//raise-alarm.md) and [events](start//send-events.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. @@ -55,7 +55,7 @@ Better understand how %%te%% works by reviewing the core [Concepts](understand/i One of the core feature of %%te%% is to be extensible. -- [Write a software-management plugin](extend/write-my-software-management-plugin.md) +- [Write a software-management plugin](extend/software-management.md) - [Build Operating System images with %%te%% setup to perform Over-the-Air (OTA) updates](extend/firmware-management/index.md) ## How to contribute {#contribute} diff --git a/docs/src/references/agent/device-management-api.md b/docs/src/references/agent/device-management-api.md index fc591c2cd53..6e5e88b878b 100644 --- a/docs/src/references/agent/device-management-api.md +++ b/docs/src/references/agent/device-management-api.md @@ -2,11 +2,12 @@ title: Device Management API tags: [Reference, Agent, API] sidebar_position: 2 +description: Details of the Device Management API --- # Device Management API -The agent and the operation plugins enable device management on thin-edge, +The agent and the operation plugins enable device management on %%te%%, giving the cloud operators a uniform interface to install software packages, update configuration files, inspect log files, restart devices ... @@ -32,14 +33,14 @@ It can be to restart the device or to install some new software. From an implementation perspective, an operation is an API identified by a well-known name such as `restart` or `software_update`. This API rules the coordination among the software components that need to interact to advance the operation. -Not all entities and components of a thin-edge device support all the operations, +Not all entities and components of a %%te%% device support all the operations, and, even if they do, the implementations might be specific. Installing a software package on top of service makes no sense. Restarting the device is not the same as restarting one of its services. Each entity or component has to declare its *capabilities* i.e. the operations made available on this target. Strictly speaking, capabilities are not implemented nor declared by the devices and the services themselves. -They are implemented by thin-edge services and plugins. +They are implemented by %%te%% services and plugins. These are the components which actually implement the operations interacting with the operating system and other software. For instance, device restart and software updates are implemented by the `tedge-agent`. @@ -70,7 +71,7 @@ and participate as per their role, when it is their turn. ## Topics -Following [thin-edge MQTT topic conventions](../mqtt-api.md#commands), +Following [%%te%% MQTT topic conventions](../mqtt-api.md#commands), each device is assigned a specific topic prefix, with a metadata sub-topic per command type and specific sub-topics for the requests. @@ -103,7 +104,7 @@ Where the groups are described as follows: | Group | Description | |--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| root | The [topic root prefix](../mqtt-api.md#group-root) for this installation of thin-edge. | +| root | The [topic root prefix](../mqtt-api.md#group-root) for this installation of %%te%%. | | target | The [topic identifier](../mqtt-api.md#group-identifier) of the target device, possibly a [custom identifier](/contribute/design/mqtt-topic-design.md#using-custom-identifier-schemas). | | `cmd` | The [command channel](../mqtt-api.md#group-channel) grouping all of the commands for this target. | | command_type | The type name of the operation. | @@ -233,7 +234,7 @@ An operation workflow defines the possible sequences of actions for an operation from its initialization up to its success or failure. It specifies the actions to perform as well as any prerequisite checks, outcome validations and possible rollbacks. However, a workflow doesn't define how to perform these actions. -These are delegated to thin-edge services, scripts, application-specific services or other devices. +These are delegated to %%te%% services, scripts, application-specific services or other devices. More precisely, an operation workflow defines: - the *observable states* of an ongoing operation instance from initialization up to a final success or failure diff --git a/docs/src/references/agent/index.md b/docs/src/references/agent/index.md index b5f20f8e845..58347d3b577 100644 --- a/docs/src/references/agent/index.md +++ b/docs/src/references/agent/index.md @@ -8,7 +8,7 @@ import DocCardList from '@theme/DocCardList'; # The Agent and Operations Plugins -The __agent__ and the __operation plugins__ are the main components used by thin-edge +The __agent__ and the __operation plugins__ are the main components used by %%te%% to enable edge device management from various clouds on diverse hardware, giving the cloud operators a uniform interface to install software packages, update configuration files, inspect log files, restart devices ... @@ -19,11 +19,11 @@ __Any service securely connected to the local MQTT bus can trigger commands as w - The agent and the operation plugins interact with the operating system, running the appropriate sequences of checks and actions in response to command requests initiated by [mappers](../mappers) on behalf of cloud operators. -- `tedge-agent` is the out-of-the-box implementation of the device management APIs provided by thin-edge.io. +- `tedge-agent` is the out-of-the-box implementation of the device management APIs provided by %%te%%. It can run on the main device as well as child devices. It can be replaced with any other user-developed components that implement these device management APIs addressing specific requirements or hardware. -- Thin-edge also provides the tools to define, extend and combine *user-defined operation workflows* +- %%te%% also provides the tools to define, extend and combine *user-defined operation workflows* that rule the sequence of steps applied when an *operation* is triggered by an operator or a software component. ```mermaid diff --git a/docs/src/references/agent/operation-workflow.md b/docs/src/references/agent/operation-workflow.md index 1d82a2dfeda..d85b127ff6e 100644 --- a/docs/src/references/agent/operation-workflow.md +++ b/docs/src/references/agent/operation-workflow.md @@ -12,7 +12,7 @@ import ProposalBanner from '@site/src/components/ProposalBanner' An agent developer can define application specific [operation workflows](./device-management-api.md#mqtt-driven-workflows) to control how an operation is performed on a device. -Thin-edge **tedge-agent** provides the tools to: +%%te%% **tedge-agent** provides the tools to: - override existing workflows - define new states and actions such as pre-requisite or post-execution checks @@ -100,7 +100,7 @@ This API should be based on the principles of MQTT-driven workflow and defines: - the well-known name such as **download** or **downloaded** - the schema of the state payload and the required parameters to process a command at this stage - developer documentation on the role of each parameter and the expected checks and actions -- the schema for the capability message sent when the operation is enabled on some thin-edge entity or component +- the schema for the capability message sent when the operation is enabled on some %%te%% entity or component - developer documentation on the role of each field of the capability message A workflow implementation is free to define the states a command can go through @@ -137,14 +137,14 @@ However, there are some rules and best practices. - This is important as we want to *extend* the workflow of an operation. A software component added by the user might need these *extra* fields the plugin is not aware of. - A workflow implementation must not react on *no-op* states nor terminal states. - - The transition from a *no-op* state must be handled either by thin-edge as direct transition + - The transition from a *no-op* state must be handled either by %%te%% as direct transition or overridden by the user with domain-specific checks and actions. - The terminal states, a.k.a **successful** and **failed**, are owned by the process which created the **init** state (in practice, the mapper). Only this process should clear the retained message state for an operation instance by sending an empty payload on command's topic. ## User-defined Operation Workflow -Thin-edge provides a mechanism to define, extend and combine workflows. +%%te%% provides a mechanism to define, extend and combine workflows. This mechanism is provided by the **tedge-agent** which gathers a set of user-defined workflows and combined them with the builtin workflows implemented by the agent itself. @@ -199,7 +199,7 @@ on_error = "failed" action = "cleanup" ``` -Thin-edge combines all these workflows to determine what has to be done +%%te%% combines all these workflows to determine what has to be done when a state message is published for a command on a topic matching the global topic filter for commands, i.e. `te/+/+/+/+/cmd/+/+`. - Each running instance of the __tedge_agent__ reacts only on commands targeting its own device. diff --git a/docs/src/references/agent/restart-operation.md b/docs/src/references/agent/restart-operation.md index 1bfb61fa5ab..43f8a5ca636 100644 --- a/docs/src/references/agent/restart-operation.md +++ b/docs/src/references/agent/restart-operation.md @@ -2,11 +2,12 @@ title: Restart Operation tags: [Reference, Agent, Restart] sidebar_position: 4 +description: Restarting the device via an operation --- # Restart Operation -Thin-edge defines a `restart` operation to restart a device, being the main device or a child device. +%%te%% defines a `restart` operation to restart a device, being the main device or a child device. - A restart is typically triggered by a [mapper](../mappers/index.md) on behalf of a cloud operator. - A restart can also be triggered from another operation (as a software update) @@ -16,7 +17,7 @@ Thin-edge defines a `restart` operation to restart a device, being the main devi ## MQTT API -The `restart` operation API follows the [generic thin-edge rules for operations](./device-management-api.md): +The `restart` operation API follows the [generic %%te%% rules for operations](./device-management-api.md): - The `te//cmd/restart` topic is used to tell the device `` can be restarted. - Each `restart` request is given a `` and a dedicated topic `te//cmd/restart/`, diff --git a/docs/src/references/agent/running-tedge-agent.md b/docs/src/references/agent/running-tedge-agent.md index 61a03181fe8..eeddef76d05 100644 --- a/docs/src/references/agent/running-tedge-agent.md +++ b/docs/src/references/agent/running-tedge-agent.md @@ -1,12 +1,11 @@ --- -title: Running the agent +title: Running the Agent tags: [Reference, Agent] sidebar_position: 1 +description: Running the agent for device management on main and child devices --- -# Running the agent - -In order to enable thin-edge device management features on a device, +In order to enable %%te%% device management features on a device, being the main device or a child device, one has to install and run the `tedge-agent` service on this device. diff --git a/docs/src/references/agent/software-management.md b/docs/src/references/agent/software-management.md index fdae07d6041..b6fc6a34e7b 100644 --- a/docs/src/references/agent/software-management.md +++ b/docs/src/references/agent/software-management.md @@ -1,10 +1,11 @@ --- -title: Software management +title: Software Management tags: [Reference, Agent, Software Management] sidebar_position: 3 +description: Details of the API to manage software on a device --- -Thin-edge software management is implemented by two operations +%%te%% software management is implemented by two operations which give the ability to manage software packages of different types on the same device. - `software_list` is used to fetch a pertinent subset of the software packages installed on a device. @@ -12,7 +13,7 @@ which give the ability to manage software packages of different types on the sam ## software_list MQTT API -The `software_list` operation API follows the [generic thin-edge rules for operations](device-management-api.md): +The `software_list` operation API follows the [generic %%te%% rules for operations](device-management-api.md): - The `te//cmd/software_list` topic is used to publish the type of software packages that can be managed on the device with the given topic identifier. - Each `te//cmd/software_list/+` topic is dedicated to a software list command instance, @@ -125,7 +126,7 @@ tedge mqtt pub --retain 'te/device/child001///cmd/software_list/c8y-2023-09-25T1 ## software_update MQTT API -The `software_update` operation API follows the [generic thin-edge rules for operations](device-management-api.md): +The `software_update` operation API follows the [generic %%te%% rules for operations](device-management-api.md): - The `te//cmd/software_update` topic is used to publish the type of software packages that can be managed on the device with the given topic identifier. - Each `te//cmd/software_update/+` topic is dedicated to a software update command instance, @@ -357,7 +358,7 @@ The `tedge-agent` service uses software management plugins to interact with the For each type of software package supported on the device must be provided a specific software management plugin: -- A plugin is an executable file implementing the [software plugin API](../plugin-api.md), +- A plugin is an executable file implementing the [software plugin API](../software-management-plugin-api.md), to `list`, `install` and `remove` software packages of a specific type. - These plugins are looked up by `tedge-agent` in the plugin directory (`/etc/tedge/sm-plugins` if not specified otherwise). - `tedge-agent` uses the file name of a plugin executables as the software package type name. @@ -371,8 +372,8 @@ For each type of software package supported on the device must be provided a spe ## Custom implementation -Thin-edge users can implement their own support for software management to address the specificities of their devices. -- This can be done leveraging the `tedge-agent` and implementing a custom [software plugin](../plugin-api.md). +%%te%% users can implement their own support for software management to address the specificities of their devices. +- This can be done leveraging the `tedge-agent` and implementing a custom [software plugin](../software-management-plugin-api.md). - If for some reasons the `tedge-agent` cannot run on the target hardware, then a service must be implemented to support the `software_list` and `software_update` operation, as described below. In this case, the service is free to choose its own mechanisms to manage software packages diff --git a/docs/src/references/agent/tedge-configuration-management.md b/docs/src/references/agent/tedge-configuration-management.md index d2f125079c9..757a45440ce 100644 --- a/docs/src/references/agent/tedge-configuration-management.md +++ b/docs/src/references/agent/tedge-configuration-management.md @@ -2,17 +2,18 @@ title: Configuration Management tags: [Reference, Configuration] sidebar_position: 6 +description: Details of the API to manage configuration on a device --- # Configuration Management -Thin-edge implements an operation to manage device configuration files. +%%te%% implements an operation to manage device configuration files. * The __tedge-agent__ enables configuration management on its running device and, combined with a cloud mapper, extends this capability to enable configuration management from the cloud. * This management is bi-directional: * A device can act as a reference, - with all the managed files being uploaded to the [tedge file transfer repository](../tedge-file-transfer-service.md) + with all the managed files being uploaded to the [tedge file transfer repository](../file-transfer-service.md) and stored there as a configuration snapshot. * A configuration update can be pushed from the tedge file transfer repository to any devices of the same type, i.e. supporting the same kind of configuration files. @@ -28,7 +29,7 @@ Thin-edge implements an operation to manage device configuration files. They are atomically renamed, only after a fully successful download to avoid breaking the system with half-downloaded files. * When a downloaded file is copied to its target, the Unix user, group and mode are preserved. * Once an update has been downloaded from the tedge file transfer repository to the target device, - __the agent publishes an operation status update message on the local thin-edge MQTT bus__. + __the agent publishes an operation status update message on the local %%te%% MQTT bus__. The device software must subscribe to these messages if any action is required, such as checking the content of the file, to pre-processing it, or restarting a daemon. @@ -47,7 +48,7 @@ By contrast, the agent is not responsible for: A user-specific component installed on the device can implement more sophisticated configuration use-cases by: - * listening for configuration updates on the local thin-edge MQTT bus, + * listening for configuration updates on the local %%te%% MQTT bus, * restarting the appropriate processes when needed, * declaring intermediate files as the managed files, to have the opportunity to check or update their content @@ -85,7 +86,7 @@ the supported config types declaration message with a retained flag to the `config_snapshot` and `config_update` command topics with the set of `type`s listed in that configuration file (implicitly adding the `tedge-configuration-plugin` type also to that set). -The message can be observed over the MQTT bus of the thin-edge device. +The message can be observed over the MQTT bus of the %%te%% device. Given that `mqtt.topic_root` and `mqtt.device_topic_id` are set to `te` and `device/main//` for the main device, the message to declare the supported configuration types is as follows. @@ -111,7 +112,7 @@ tedge mqtt pub -r 'te/device/main///cmd/config_update' '{ then only `tedge-configuration-plugin.toml` is declared as a supported configuration type. ::: -The behavior of the agent is also controlled by the configuration of thin-edge: +The behavior of the agent is also controlled by the configuration of %%te%%: * `tedge config get mqtt.bind.address`: the address of the local MQTT bus. * `tedge config get mqtt.bind.port`: the TCP port of the local MQTT bus. diff --git a/docs/src/references/agent/tedge-log-management.md b/docs/src/references/agent/tedge-log-management.md index 3f4aeaf8d7c..878d3d3232a 100644 --- a/docs/src/references/agent/tedge-log-management.md +++ b/docs/src/references/agent/tedge-log-management.md @@ -2,11 +2,10 @@ title: Log File Management tags: [Reference, Log Files] sidebar_position: 5 +description: Details of the API to manage log files on a device --- -# Log file management - -Thin-edge implements an operation to upload log files from the device to the cloud. +%%te%% implements an operation to upload log files from the device to the cloud. * The log file management feature on the main or a child device is provided by the __tedge-agent__ running on that device. * The device owner can define the list of log files using the `tedge-log-plugin.toml` configuration file of the target device. diff --git a/docs/src/references/thin-edge-config-files.md b/docs/src/references/configuration-files.md similarity index 96% rename from docs/src/references/thin-edge-config-files.md rename to docs/src/references/configuration-files.md index af4c4bcb018..565da70ce6c 100644 --- a/docs/src/references/thin-edge-config-files.md +++ b/docs/src/references/configuration-files.md @@ -1,12 +1,11 @@ --- -title: Configuration files +title: Configuration Files tags: [Reference, Configuration] sidebar_position: 5 +description: Using a custom configuration path --- -# Thin-edge config files - -Thin-edge.io requires config files for its operation. The `tedge init` command is used to create +%%te%% requires config files for its operation. The `tedge init` command is used to create the base directory and other directories inside the base directory with appropriate user and permissions. The `tedge-mapper` and `tedge-agent` will create the config directories/files inside the base directory that are required for their operation on startup. diff --git a/docs/src/references/tedge-cumulocity-proxy.md b/docs/src/references/cumulocity-proxy.md similarity index 92% rename from docs/src/references/tedge-cumulocity-proxy.md rename to docs/src/references/cumulocity-proxy.md index ebeb4ec3f85..2039248b914 100644 --- a/docs/src/references/tedge-cumulocity-proxy.md +++ b/docs/src/references/cumulocity-proxy.md @@ -1,19 +1,18 @@ --- -title: Thin Edge Cumulocity HTTP Proxy +title: Cumulocity Proxy tags: [ Reference, HTTP, Cumulocity ] sidebar_position: 12 +description: Using the Cumulocity IoT Proxy for full access to Cumulocity API --- -# Thin Edge Cumulocity Proxy - The `tedge-mapper` (when running in `c8y` mode) hosts a proxy server to access the Cumulocity HTTP API from the -thin-edge device. +%%te%% device. It automatically handles authenticating with a JWT, avoiding the need for clients to support MQTT to retrieve this information. The Cumulocity HTTP API can be accessed at `http://{host}:{port}/c8y/{c8y-endpoint}`. Configuration settings `c8y.proxy.client.host` and `c8y.proxy.client.port` are used to configure `{host}` and `{port}` parts of the base URL -which will be used by thin-edge components to make requests to the C8y Proxy. `c8y.proxy.bind.address` and +which will be used by %%te%% components to make requests to the C8y Proxy. `c8y.proxy.bind.address` and `c8y.proxy.bind.port` are read by `tedge-mapper-c8y` and used as bind address and port for the Cumulocity HTTP proxy. In both `client` and `bind`, `127.0.0.1` and `8001` are used as defaults for the address and port, respectively. diff --git a/docs/src/references/tedge-file-transfer-service.md b/docs/src/references/file-transfer-service.md similarity index 93% rename from docs/src/references/tedge-file-transfer-service.md rename to docs/src/references/file-transfer-service.md index f64c594b2c4..46ef0088db7 100644 --- a/docs/src/references/tedge-file-transfer-service.md +++ b/docs/src/references/file-transfer-service.md @@ -2,13 +2,12 @@ title: File Transfer Service tags: [Reference, HTTP] sidebar_position: 6 +descrioption: Interacting with the %%te%% file transfer service --- -# Thin Edge File Transfer Service - The `tedge-agent` hosts a binary repository for child devices and other plugins/extensions to exchange binary files between them. This repository is meant to be used as a temporary storage for exchanging files, and not for storing items permanently, -as the storage on thin-edge devices are typically very limited. +as the storage on %%te%% devices are typically very limited. Files can be uploaded, downloaded and deleted from this repository via the following HTTP endpoints: @@ -30,7 +29,7 @@ An existing file at a given path is replaced on subsequent uploads using the sam Unique paths must be used in the URL path to avoid such overwrites. All uploaded files are preserved until they are explicitly deleted with the DELETE API. -To avoid exhaustion of storage space on the thin-edge device, +To avoid exhaustion of storage space on the %%te%% device, users must be diligent to delete any stored files as soon as their purpose is served. ## HTTPS and authenticated access diff --git a/docs/src/references/index.md b/docs/src/references/index.md index 0ab363476ce..9919fbad694 100644 --- a/docs/src/references/index.md +++ b/docs/src/references/index.md @@ -1,13 +1,11 @@ --- -title: Reference +title: References tags: [Reference] sidebar_position: 6 --- import DocCardList from '@theme/DocCardList'; -# Thin-edge Reference Guides - The reference guides include technical documentation about the following areas: - Command Line Interface diff --git a/docs/src/references/init-system-config.md b/docs/src/references/init-system-configuration.md similarity index 92% rename from docs/src/references/init-system-config.md rename to docs/src/references/init-system-configuration.md index 503cfc69712..8b6388a02d7 100644 --- a/docs/src/references/init-system-config.md +++ b/docs/src/references/init-system-configuration.md @@ -2,10 +2,9 @@ title: Init System Configuration tags: [Reference, Unix, Init, Services] sidebar_position: 6 +description: Configuring %%te%% to work with Linux init systems --- -# Init System Configuration File - To support multiple init systems and service managers, `tedge` requires the `/etc/tedge/system.toml` file. The file contains configurations about the init system and the supported actions. @@ -61,4 +60,4 @@ will be interpreted as ## Default settings -If the `system.toml` file does not exist, then thin-edge will assume that you are using Systemd, and use `/bin/systemctl` to control the services. +If the `system.toml` file does not exist, then %%te%% will assume that you are using Systemd, and use `/bin/systemctl` to control the services. diff --git a/docs/src/references/mappers/c8y-mapper.md b/docs/src/references/mappers/c8y-mapper.md index 99b77ff6a11..60b1ff62372 100644 --- a/docs/src/references/mappers/c8y-mapper.md +++ b/docs/src/references/mappers/c8y-mapper.md @@ -5,13 +5,13 @@ sidebar_position: 1 --- The Cumulocity mapper, referred to as `c8y-mapper` in the rest of this document, -maps data in [Thin Edge 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/guides/reference/smartrest-two/#smartrest-two). ## Registration Cumulocity keeps the record of all the registered devices and their associated metadata in its inventory. -The `c8y-mapper` creates and maintains inventory entries for all the devices and services registered with thin-edge. +The `c8y-mapper` creates and maintains inventory entries for all the devices and services registered with %%te%%. The mapper subscribes to the following topics to get a list of all registered devices and services: ```sh @@ -24,7 +24,7 @@ The registration messages received for child devices and services are mapped as
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/child01 @@ -61,7 +61,7 @@ with devices using the same name in other tedge deployments connected to the sam
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/child01 @@ -98,7 +98,7 @@ Where the provided `@id` is directly used as the external id.
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/nested_child01 @@ -134,7 +134,7 @@ c8y/s/us/:device:child01
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/main/service/nodered @@ -169,7 +169,7 @@ c8y/s/us
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/child01/service/nodered @@ -256,7 +256,7 @@ Telemetry data types like measurements, events and alarms are mapped to their re
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/main///m/environment @@ -297,7 +297,7 @@ c8y/measurement/measurements/create
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/main///m/ @@ -338,7 +338,7 @@ c8y/measurement/measurements/create
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/child01///m/ @@ -395,7 +395,7 @@ Then subsequent messages will be mapped with the registered unit value as follow
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/main///m/environment @@ -436,7 +436,7 @@ c8y/measurement/measurements/create
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/main///e/login_event @@ -469,7 +469,7 @@ c8y/s/us
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/main///e/login_event @@ -520,7 +520,7 @@ c8y/event/events/create
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/main///a/temperature_high @@ -554,7 +554,7 @@ c8y/s/us
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/main///a/pressure_alarm @@ -607,7 +607,7 @@ c8y/alarm/alarms/create
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic" te/device/main/service/my-service/status/health @@ -649,7 +649,7 @@ The type part of the topic is used to group the data so it is easier for compone
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic (retain=true)" te/device/main///twin/device_OS @@ -688,7 +688,7 @@ c8y/inventory/managedObjects/update/
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic (retain=true)" te/device/child01///twin/device_OS @@ -726,7 +726,7 @@ c8y/inventory/managedObjects/update/:device:child01
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic (retain=true)" te/device/main/service/tedge-agent/twin/runtime_stats @@ -765,7 +765,7 @@ c8y/inventory/managedObjects/update/:device:main:service:tedge-a
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic (retain=true)" te/device/child01/service/tedge-agent/twin/runtime_stats @@ -808,7 +808,7 @@ JSON objects must be published to their typed topics directly.
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic (retain=true)" te/device/main///twin/subtype @@ -850,7 +850,7 @@ as they are included in the entity registration message and can only be updated
-**Thin Edge (input)** +**%%te%% (input)** ```text title="Topic (retain=true)" te/device/child01/service/tedge-agent/twin/runtime_stats @@ -881,7 +881,7 @@ c8y/inventory/managedObjects/update/:device:child01:service:tedg ### Base inventory model The contents of `{tedge_config_dir}/device/inventory.json` are used to populate the initial inventory fragments -of the the main thin-edge device in Cumulocity. +of the the main %%te%% device in Cumulocity. For example, if the `inventory.json` contains the following fragments: ```json title="inventory.json" @@ -925,7 +925,7 @@ c8y/inventory/managedObjects/update } ``` -Where the `c8y_Agent` fragment is auto-generated by thin-edge and appended to the contents of the file before it is published. +Where the `c8y_Agent` fragment is auto-generated by %%te%% and appended to the contents of the file before it is published. The fragments in this file are also published to the `te/device/main///twin/` topics so that the local twin metadata on the broker is also up-to-date and other components can also consume it. @@ -995,7 +995,7 @@ c8y/inventory/managedObjects/update ## Operations/Commands -Operations from Cumulocity are mapped to their equivalent commands in Thin Edge format. +Operations from Cumulocity are mapped to their equivalent commands in %%te%% format. ### Supported Operations/Capabilities @@ -1051,7 +1051,7 @@ c8y/s/ds
-**Thin Edge (output)** +**%%te%% (output)** ```text title="Topic" te/device/main///cmd/restart/ @@ -1072,8 +1072,8 @@ the mapper recognizes and maps only the following `status` values as follows: - - + + @@ -1182,7 +1182,7 @@ c8y/s/ds
-**Thin Edge (output)** +**%%te%% (output)** ```text title="Topic" te/device/child01///cmd/restart @@ -1212,7 +1212,7 @@ c8y/s/ds
-**Thin Edge (output)** +**%%te%% (output)** ```text title="Topic" te/device/main///cmd/software_update/ @@ -1270,7 +1270,7 @@ c8y/s/ds
-**Thin Edge (output)** +**%%te%% (output)** ```text title="Topic" te/device/main///cmd/config_snapshot/ @@ -1306,7 +1306,7 @@ c8y/s/ds
-**Thin Edge (output)** +**%%te%% (output)** ```text title="Topic" te/device/main///cmd/config_update/ @@ -1343,7 +1343,7 @@ c8y/s/ds
-**Thin Edge (output)** +**%%te%% (output)** ```text title="Topic" te/device/main///cmd/log_upload/ diff --git a/docs/src/references/mappers/mqtt-topics.md b/docs/src/references/mappers/mqtt-topics.md index 3036b563c1b..9007589d077 100644 --- a/docs/src/references/mappers/mqtt-topics.md +++ b/docs/src/references/mappers/mqtt-topics.md @@ -56,12 +56,12 @@ You can find more information about Cumulocity topics ## Azure MQTT Topics -MQTT clients on Thin Edge device must use the below topics to communicate with the Azure cloud. +MQTT clients on %%te%% device must use the below topics to communicate with the Azure cloud. The Azure topics are prefixed by `az/`. * `az/messages/events/` - Use this topic to send the messages from device to cloud. The messages are forwarded to the Azure topic named - `devices/{device_id}/messages/events/` where device_id is the Thin Edge device + `devices/{device_id}/messages/events/` where device_id is the %%te%% device id. * `az/messages/devicebound/#` - Use this topic to subscribe for the messages that were sent from cloud to device. @@ -70,11 +70,11 @@ The Azure topics are prefixed by `az/`. ## AWS MQTT Topics -MQTT clients on Thin Edge device must use the below topics to communicate with the AWS cloud. +MQTT clients on %%te%% device must use the below topics to communicate with the AWS cloud. The AWS topics are prefixed by `aws/`. * `aws/td/#` - Use this topic to send the messages from device to cloud. The messages are forwarded to the AWS topic - named `thinedge/{device_id}/td` where `{device_id}` is the Thin Edge device id. + named `thinedge/{device_id}/td` where `{device_id}` is the %%te%% device id. * `aws/cmd/#` - Use this topic to subscribe for the messages that were sent from cloud to device. Any message published by AWS on one the subtopics of `thinedge/{device_id}/cmd/#` is republished here. @@ -97,4 +97,4 @@ The `collectd-mapper` daemon process ingests these measurements and emits transl to the measurement topic. * This process groups the atomic measurements that have been received during the same time-window (currently 200 ms) -* and produces a single thin-edge-json for the whole group of measurements. +* and produces a single %%te%% JSON for the whole group of measurements. diff --git a/docs/src/references/mqtt-api.md b/docs/src/references/mqtt-api.md index 2737dc39555..718a093a374 100644 --- a/docs/src/references/mqtt-api.md +++ b/docs/src/references/mqtt-api.md @@ -2,12 +2,13 @@ title: MQTT API tags: [Reference, MQTT] sidebar_position: 1 +description: MQTT API reference guide --- ## Topic Scheme -The thin-edge MQTT topic structure adopts a flexible and descriptive semantics, whilst keeping it consistent and predictable -to enable other clients/mappers to interact with the thin-edge components. +The %%te%% MQTT topic structure adopts a flexible and descriptive semantics, whilst keeping it consistent and predictable +to enable other clients/mappers to interact with the %%te%% components. Whilst the topic structure is flexible, the document will focus on the typical use case. Advanced use-cases can be viewed in the [advanced section](../contribute/design/mqtt-topic-design.md#using-custom-identifier-schemas), @@ -52,7 +53,7 @@ The specifics of each group are detailed in the following sections. ### Root {#group-root} -The root/base topic prefix is used to group all data related to one thin-edge instance. +The root/base topic prefix is used to group all data related to one %%te%% instance. The root topic is used to avoid conflicts with other clients communicating on the same MQTT broker. The convention is to use a fixed value of `te` (short for "thin-edge"). @@ -101,8 +102,8 @@ For instance publishing telemetry data of a device involves setting both the "se To help better understand how the **identifier** is used in the topics, let's image the following setup. You have two devices; the main device and a single child device called "child01". -Both the main device (where thin-edge is running), and the child device have a single service called "node_red". -Thin-edge will build digital twins for the devices (main and child device), +Both the main device (where %%te%% is running), and the child device have a single service called "node_red". +%%te%% will build digital twins for the devices (main and child device), and the "node_red" services associated with each of the devices. The following diagram details the device hierarchy of the fictional setup. @@ -113,7 +114,7 @@ The following diagram details the device hierarchy of the fictional setup. graph TD main --> child01 - subgraph main["main device (running thin-edge)"] + subgraph main["main device (running thin-edge.io)"] nodedred01["node_red service"] end @@ -125,7 +126,7 @@ graph TD

-The diagram shows that there are two devices; the "main" device (the digital twin representation of thin-edge), and a child device called "child01". +The diagram shows that there are two devices; the "main" device (the digital twin representation of %%te%%), and a child device called "child01". The following table shows how the identifier is used to represent the different combination of devices and services, e.g. main device, node_red service running on the main device, child device and the node_red service running on the child device. @@ -250,13 +251,13 @@ The following is an overview of the channel categories which are available. ## Entity registration -Since thin-edge doesn't enforce what each entity identification level means, +Since %%te%% doesn't enforce what each entity identification level means, an explicit registration is required to register every entity that is going to send data or receive commands. For example, before a measurement can be sent from a service named `tedge-agent` from the device `rpi1001`, the entity named `rpi1001` must be registered as a `device`, and `tedge-agent` must be registered as a `service` linked to that device. -An entity can be registered with thin-edge by publishing a retained message to the entity identification topic prefix +An entity can be registered with %%te%% by publishing a retained message to the entity identification topic prefix with the entity type and other metadata that defines that entity. To model the example mentioned above, if an entity identification topic scheme like the following is used: @@ -403,7 +404,7 @@ Users are highly encouraged to register the devices manually as it allows device ### Entity store -All the entity registration messages retained with the MQTT broker helps thin-edge components to +All the entity registration messages retained with the MQTT broker helps %%te%% components to maintain an entity store with all the registered devices and services along with their metadata. Components like mappers use such an entity store while processing data from various sources. @@ -422,7 +423,7 @@ The MQTT broker is used as the persistence layer to store the registered entitie Telemetry and commands use the data type topic levels after the entity/component subtopics. Even for the data type levels, a user is free to define those as they wish. -But thin-edge has some pre-defined `` subtopics for well-known types like +But %%te%% has some pre-defined `` subtopics for well-known types like *measurements*, *alarms*, *events* and *commands*, on which it enforces some constraints, so that it can process them. @@ -568,7 +569,7 @@ Where the command segments are describe as follows: ### Command examples -The following table details some example command types which are supported by thin-edge. +The following table details some example command types which are supported by %%te%%. | Command Type | Example Topic | |-----------------|------------------------------------------------| diff --git a/docs/src/references/plugin-api.md b/docs/src/references/software-management-plugin-api.md similarity index 96% rename from docs/src/references/plugin-api.md rename to docs/src/references/software-management-plugin-api.md index bac46868d9e..58be30745c7 100644 --- a/docs/src/references/plugin-api.md +++ b/docs/src/references/software-management-plugin-api.md @@ -2,16 +2,15 @@ title: Software Management Plugin API tags: [Reference, Software Management, API] sidebar_position: 10 +description: Software Management Plugin API reference --- -# Software Management Plugin API - -Thin-edge uses plugins to delegate software management operations to the appropriate package manager/installer. The plugins are responsible for: installation of packages, uninstalls and queries. +%%te%% uses plugins to delegate software management operations to the appropriate package manager/installer. The plugins are responsible for: installation of packages, uninstalls and queries. * A package manager plugin acts as a facade for a specific package manager. * A plugin is an executable that follows the [plugin API](#plugin-api). * On a device, several plugins can be installed to deal with different kinds of software modules. -* The filename of a plugin is used by thin-edge to determine the appropriate plugin for a software module. +* The filename of a plugin is used by %%te%% to determine the appropriate plugin for a software module. * All the actions on a software module are directed to the plugin bearing the name that matches the module type name. * The plugins are loaded and invoked by the sm-agent in a systematic order (in practice the alphanumerical order of their names in the file system). * The software modules to be installed/removed are also passed to the plugins in a consistent order. @@ -23,7 +22,7 @@ Thin-edge uses plugins to delegate software management operations to the appropr ## Plugin repository -* To be used by thin-edge, a plugin has to be stored in the directory `/etc/tedge/sm-plugins`. +* To be used by %%te%%, a plugin has to be stored in the directory `/etc/tedge/sm-plugins`. * A plugin must be named after the software module type as specified in the cloud request. That is, a plugin named `apt` handles software modules that are defined with type `apt` in the cloud request. Consequently a plugin to handle software module defined for `docker` must be named `docker`. @@ -42,7 +41,7 @@ On start-up, the sm-agent registers the plugins as follows: ## Plugin API -* A plugin must implement all the commands used by the sm-agent of thin-edge, +* A plugin must implement all the commands used by the sm-agent of %%te%%, and support all the options for these commands. * A plugin should not support extra commands or options. * A plugin might have a configuration file. diff --git a/docs/src/references/supported-platforms.md b/docs/src/references/supported-platforms.md index 29efa1dbd97..e3087de0b1a 100644 --- a/docs/src/references/supported-platforms.md +++ b/docs/src/references/supported-platforms.md @@ -1,12 +1,11 @@ --- -title: Supported Platform +title: Supported Platforms tags: [Reference, Installation] sidebar_position: 15 +description: List of supported platforms, CPU architectures and resource usage --- -# thin-edge.io platform support - -thin-edge.io can be run on any Linux based Operating System, such as; Debian/Ubuntu, Alpine, RHEL, Fedora, Pokey (Yocto) etc. +%%te%% can be run on any Linux based Operating System, such as; Debian/Ubuntu, Alpine, RHEL, Fedora, Pokey (Yocto) etc. In addition to a Linux based Operation system, the following requirements must also be fulfilled: @@ -23,7 +22,7 @@ mosquitto will be installed via the installation script, however it needs to be ## Recommended mosquitto version -Whilst thin-edge.io will work with any mosquitto version, it is recommended to use mosquitto version >=2.0.18 as it includes some important fixes regarding the MQTT bridge functionality. +Whilst %%te%% will work with any mosquitto version, it is recommended to use mosquitto version >=2.0.18 as it includes some important fixes regarding the MQTT bridge functionality. If you can't use the recommended version, then be aware of the following issues which affect various mosquitto versions in some corner cases: @@ -34,7 +33,7 @@ If you can't use the recommended version, then be aware of the following issues ## Supported CPU Architectures -thin-edge.io is developed in Rust which is a compiled language and each executable is specific for different CPU Architectures (e.g. x86_64/amd64, aarch64/arm64, armv7, armv6 etc.). +%%te%% is developed in Rust which is a compiled language and each executable is specific for different CPU Architectures (e.g. x86_64/amd64, aarch64/arm64, armv7, armv6 etc.). The following sections give detailed information about which CPU Architectures which are currently supported. @@ -54,13 +53,13 @@ Generally the newer ARM processors should be supported, as they are mostly based ## Memory Usage -The exact memory usage of thin-edge.io and the MQTT broker depends on a many factors; such factors are listed below: +The exact memory usage of %%te%% and the MQTT broker depends on a many factors; such factors are listed below: -* Which thin-edge.io components are running? +* Which components are running? * How many messages are being sent to the MQTT broker? * How long should mosquitto buffer messages during connectivity outages? -Despite the above factors which influence the memory usage, a guideline of the typical memory usage for each thin-edge.io components is shown below, where the memory usage refers to the typical [Resident Set Size (RSS)](https://en.wikipedia.org/wiki/Resident_set_size). +Despite the above factors which influence the memory usage, a guideline of the typical memory usage for each %%te%% components is shown below, where the memory usage refers to the typical [Resident Set Size (RSS)](https://en.wikipedia.org/wiki/Resident_set_size). |Name|Typical Memory Usage (MiB)| |--|--| @@ -74,9 +73,9 @@ To provide a better insight into the actual memory usage, the following sections #### Scenario: Gateway device -A typical gateway device setup is a device where the MQTT broker and thin-edge.io are running on the single device to provide management of the gateway itself and provide cloud connectivity to other devices in the local network. +A typical gateway device setup is a device where the MQTT broker and %%te%% are running on the single device to provide management of the gateway itself and provide cloud connectivity to other devices in the local network. -In this scenario, all of the thin-edge.io components are running on the gateway device. The breakdown of the typical memory usage is shown in the table below: +In this scenario, all of the %%te%% components are running on the gateway device. The breakdown of the typical memory usage is shown in the table below: |Name|Typical Memory Usage (MiB)| |--|--| @@ -88,7 +87,7 @@ In this scenario, all of the thin-edge.io components are running on the gateway #### Scenario: Child device (connected to a local gateway) -The thin-edge.io component, **tedge-agent**, can also be run on a child device where it connects to an MQTT broker running on a gateway device within the same local network. In this scenario the memory requirements are considerable less as only the **tedge-agent** needs to run on the device, as the cloud connection is managed on the gateway device. +The %%te%% component, **tedge-agent**, can also be run on a child device where it connects to an MQTT broker running on a gateway device within the same local network. In this scenario the memory requirements are considerable less as only the **tedge-agent** needs to run on the device, as the cloud connection is managed on the gateway device. Below shows the typical memory usage breakdown in this scenario: diff --git a/docs/src/start/connect-aws.md b/docs/src/start/connect-aws.md index 3d106ddc2d4..5d9866006bf 100644 --- a/docs/src/start/connect-aws.md +++ b/docs/src/start/connect-aws.md @@ -2,11 +2,10 @@ title: Connecting to AWS IoT tags: [Getting Started, AWS, Connection] sidebar_position: 4 +description: Connect %%te%% to AWS IoT and publish telemetry data --- -# Connect your device to AWS IoT - -The very first step to enable **thin-edge.io** is to connect your device to the cloud. +The very first step to enable %%te%% is to connect your device to the cloud. * This is a 10 minutes operation to be done only once. * It establishes a permanent connection from your device to the cloud end-point. @@ -19,7 +18,7 @@ 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: -* [Install `thin-edge.io` on your device](../install/index.md). +* [Install %%te%% on your device](../install/index.md). You can now use [`tedge` command](../references/cli/index.md) to: @@ -185,7 +184,7 @@ To view the messages that were sent from the device to the cloud, follow this You can now: -* learn how to [send various kind of telemetry data](send-thin-edge-data.md) - using the cloud-agnostic [Thin-Edge-Json data format](../understand/thin-edge-json.md), +* learn how to [send various kind of telemetry data](send-measurements.md) + using the cloud-agnostic [%%te%% JSON data format](../understand/thin-edge-json.md), * or have a detailed view of the [topics mapped to and from AWS](../references/mappers/mqtt-topics.md#aws-mqtt-topics) if you prefer to use directly AWS specific formats and protocols. diff --git a/docs/src/start/connect-azure.md b/docs/src/start/connect-azure.md index e5a69ebba17..6178b703c72 100644 --- a/docs/src/start/connect-azure.md +++ b/docs/src/start/connect-azure.md @@ -2,11 +2,10 @@ title: Connecting to Azure IoT tags: [Getting Started, Azure, Connection] sidebar_position: 3 +description: Connect %%te%% to Azure IoT and publish telemetry data --- -# Connect your device to Azure IoT - -The very first step to enable **thin-edge.io** is to connect your device to the cloud. +The very first step to enable %%te%% is to connect your device to the cloud. * This is a 10 minutes operation to be done only once. * It establishes a permanent connection from your device to the cloud end-point. * This connection is secure (encrypted over TLS), and the two peers are identified by x509 certificates. @@ -18,7 +17,7 @@ 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). -* [Install `thin-edge.io` on your device](../install/index.md). +* [Install %%te%% on your device](../install/index.md). You can now use [`tedge` command](../references/cli/index.md) to: * [create a certificate for your device](#create-certificate), @@ -173,7 +172,7 @@ More info about sending telemetry to Azure can be found [here](https://docs.micr ## Next Steps You can now: -* learn how to [send various kind of telemetry data](send-thin-edge-data.md) - using the cloud-agnostic [Thin-Edge-Json data format](../understand/thin-edge-json.md), +* learn how to [send various kind of telemetry data](send-measurements.md) + using the cloud-agnostic [%%te%% JSON data format](../understand/thin-edge-json.md), * or have a detailed view of the [topics mapped to and from Azure](../references/mappers/mqtt-topics.md#azure-mqtt-topics) if you prefer to use directly Azure specific formats and protocols. diff --git a/docs/src/start/connect-c8y.md b/docs/src/start/connect-c8y.md index 7e34bdfe7c0..fe7e6538458 100644 --- a/docs/src/start/connect-c8y.md +++ b/docs/src/start/connect-c8y.md @@ -2,11 +2,10 @@ title: Connecting to Cumulocity IoT tags: [Getting Started, Cumulocity, Connection] sidebar_position: 2 +description: Connect %%te%% to Cumulocity IoT and publish telemetry data --- -# Connect your device to Cumulocity IoT - -The very first step to enable `thin-edge.io` is to connect your device to the cloud. +The very first step to enable %%te%% is to connect your device to the cloud. * This is a 10 minutes operation to be done only once. * It establishes a permanent connection from your device to the cloud end-point. * This connection is secure (encrypted over TLS), and the two peers are identified by x509 certificates. @@ -23,7 +22,7 @@ Before you try to connect your device to Cumulocity IoT, you need: * None of these credentials will be stored on the device. * These are only required once, to register the device. -If not done yet, [install `thin-edge.io` on your device](../install/index.md). +If not done yet, [install %%te%% on your device](../install/index.md). You can now use the [`tedge` command](../references/cli/index.md) to: * [create a certificate for you device](connect-c8y.md#create-the-certificate), @@ -149,7 +148,7 @@ Check the following items to help you diagnose the root cause of the problem: #### 403 - Forbidden -The 403 (Forbidden) error means that your user/password is correct however you do not have sufficient permissions to add the thin-edge.io'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 IoT's [Trusted certificates](https://cumulocity.com/guides/device-integration/mqtt/#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. @@ -270,8 +269,8 @@ You should observe a "temperature measurement" graph with the new data point. ## Next Steps You can now: -* learn how to [send various kind of telemetry data](send-thin-edge-data.md) - using the cloud-agnostic [Thin-Edge-Json data format](../understand/thin-edge-json.md), +* learn how to [send various kind of telemetry data](send-measurements.md) + using the cloud-agnostic [%%te%% JSON data format](../understand/thin-edge-json.md), * or have a detailed view of the [topics mapped to and from Cumulocity](../references/mappers/mqtt-topics.md#cumulocity-mqtt-topics) if you prefer to use directly Cumulocity specific formats and protocols. -* learn how to [add custom fragments to cumulocity](../operate/c8y/c8y_fragments.md). +* learn how to [add custom fragments to cumulocity](../operate/c8y/custom-fragments.md). diff --git a/docs/src/start/device-monitoring.md b/docs/src/start/device-monitoring.md index 2f3def6fb2e..7aab247d0f8 100644 --- a/docs/src/start/device-monitoring.md +++ b/docs/src/start/device-monitoring.md @@ -2,29 +2,28 @@ title: Monitoring tags: [Getting Started, Monitoring, Collectd] sidebar_position: 8 +description: Monitoring your device with collectd --- -# Monitor your device with collectd - -With thin-edge.io device monitoring, you can collect metrics from your device +With %%te%% device monitoring, you can collect metrics from your device and forward these device metrics to IoT platforms in the cloud. 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. -Thin-edge.io uses the open source component [`collectd`](https://collectd.org/) to collect the metrics from the device. -Thin-edge.io translates the collected metrics from their native format to the [thin-edge.io JSON](../understand/thin-edge-json.md) format +%%te%% uses the open source component [`collectd`](https://collectd.org/) to collect the metrics from the device. +%%te%% translates the collected 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). Enabling monitoring on your device is a 3-steps process: 1. [Install `collectd`](#install-collectd), 2. [Configure `collectd`](#configure-collectd), -3. [Enable thin-edge.io monitoring](#enable-thin-edge-monitoring). +3. [Enable %%te%% monitoring](#enable-thin-edge-monitoring). ## Install collectd -Device monitoring is not enabled by default when you install thin edge. +Device monitoring is not enabled by default when you install %%te%%. You will have to install and configure [`collectd`](https://collectd.org/) first. To install collectd, follow the [collectd installation process](https://collectd.org/download.shtml) @@ -39,14 +38,14 @@ sudo apt-get install --no-install-recommends collectd-core libmosquitto1 ``` :::note -Either `mosquitto-clients` or `libmosquitto1` package is required as thin-edge.io makes use of the MQTT plugin of `collectd` which enables collectd to publish its metrics via the local MQTT broker where thin-edge.io is able to process the messages. +Either `mosquitto-clients` or `libmosquitto1` package is required as %%te%% makes use of the MQTT plugin of `collectd` which enables collectd to publish its metrics via the local MQTT broker where %%te%% is able to process the messages. ::: ## Configure collectd ### TLDR; Just want it running -Thin-edge.io provides a [basic `collectd` configuration](https://github.com/thin-edge/thin-edge.io/blob/main/configuration/contrib/collectd/collectd.conf) +%%te%% provides a [basic `collectd` configuration](https://github.com/thin-edge/thin-edge.io/blob/main/configuration/contrib/collectd/collectd.conf) that can be used to collect cpu, memory and disk metrics. Simply copy that file to the main collectd configuration file and restart the daemon @@ -59,19 +58,19 @@ sudo systemctl restart collectd ``` :::note -The `collectd.conf` file included with thin-edge.io is configured for conservative interval times, e.g. 10 mins to 1 hour depending on the metric. This is done so that the metrics don't consume unnecessary IoT resources both on the device and in the cloud. If you want to push the metrics more frequently then you will have to adjust the `Interval` settings either globally or on the individual plugins. Make sure you restart the collectd service after making any changes to the configuration. +The `collectd.conf` file included with %%te%% is configured for conservative interval times, e.g. 10 mins to 1 hour depending on the metric. This is done so that the metrics don't consume unnecessary IoT resources both on the device and in the cloud. If you want to push the metrics more frequently then you will have to adjust the `Interval` settings either globally or on the individual plugins. Make sure you restart the collectd service after making any changes to the configuration. ::: ### Collectd.conf -Unless you opted for the [minimal test configuration provided with thin-edge](#tldr-just-want-it-running), +Unless you opted for the [minimal test configuration provided with %%te%%](#tldr-just-want-it-running), you will have to update the [`collectd.conf` configuration file](https://collectd.org/documentation/manpages/collectd.conf.5.shtml) (usually located at `/etc/collectd/collectd.conf`) __Important notes__ You can enable or disable the collectd plugins of your choice, but with some notable exceptions: 1. __MQTT must be enabled__. - * Thin-edge.io expects the collectd metrics to be published on the local MQTT bus. + * %%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.5.shtml#plugin_mqtt). * 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. @@ -91,7 +90,7 @@ __Important notes__ You can enable or disable the collectd plugins of your choic ``` 2. __RRDTool and CSV might be disabled__ * The risk with these plugins is to run out of disk space on a small device. - * With thin-edge.io the metrics collected by `collectd` are forwarded to the cloud, + * With %%te%% the metrics collected by `collectd` are forwarded to the cloud, hence it makes sense to [disable Local storage](https://github.com/collectd/collectd/issues/2668). * For that, simply comment out these two plugins: @@ -124,7 +123,7 @@ __Important notes__ You can enable or disable the collectd plugins of your choic ``` -## Enable thin-edge monitoring +## Enable %%te%% monitoring {#enable} To enable monitoring on your device, you have to launch the `tedge-mapper-collectd` daemon process. @@ -134,7 +133,7 @@ sudo systemctl start tedge-mapper-collectd ``` This process subscribes to the `collectd/#` topics to read the monitoring metrics published by collectd -and emits the translated measurements in thin-edge.io JSON format to the **measurements** topic. +and emits the translated measurements in %%te%% JSON format to the **measurements** topic. You can inspect the collected and translated metrics, by subscribing to these topics: The metrics collected by `collectd` are emitted to subtopics named after the collectd plugin and the metric name: @@ -151,7 +150,7 @@ tedge mqtt sub 'collectd/#' [collectd/raspberrypi/memory/percent-used] 1623076680.159:1.10760866126707 ``` -The `tedge-mapper-collectd` translates these collectd measurements into the [thin-edge.io JSON](../understand/thin-edge-json.md) format, +The `tedge-mapper-collectd` translates these collectd measurements into the [%%te%% JSON](../understand/thin-edge-json.md) format, [grouping the measurements](../references/mappers/mqtt-topics.md#collectd-topics) emitted by each plugin: ```sh te2mqtt formats=v1 @@ -182,4 +181,4 @@ If your device is not connected yet one of the following guides: ## Troubleshooting -See here for [how to trouble shoot device monitoring?](../operate/troubleshooting/trouble_shooting_monitoring.md) +See here for [how to troubleshoot device monitoring?](../operate/troubleshooting/device-monitoring.md) diff --git a/docs/src/start/getting-started.md b/docs/src/start/getting-started.md index 0c340af0763..5463ae83288 100644 --- a/docs/src/start/getting-started.md +++ b/docs/src/start/getting-started.md @@ -1,17 +1,15 @@ --- -title: A tour of thin-edge +title: A tour of thin-edge.io tags: [Getting Started, Cumulocity] sidebar_position: 1 --- -# Getting started with thin-edge.io on a Raspberry Pi - -After following this tutorial you will have an overview of the installation and configuration of thin-edge.io. 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 IoT and performing some additional device management tasks. ## Introduction -thin-edge.io is an open-source project to provide a cloud-agnostic edge framework. It is much more generic than the device management agent, so it can connect to multiple IoT cloud platforms, and it allows flexible logic executed on the device. It is optimized for a very small footprint and high performance. +%%te%% is an open-source project to provide a cloud-agnostic edge framework. It is much more generic than the device management agent, so it can connect to multiple IoT cloud platforms, and it allows flexible logic executed on the device. It is optimized for a very small footprint and high performance. The Raspberry PI is a relatively simple and cheap device but powerful. Therefore it is ideal for testing and try-outs and some production use cases. @@ -21,17 +19,18 @@ The Raspberry PI is a relatively simple and cheap device but powerful. Therefore To follow this guide, you only need the following: - A [Cumulocity IoT](https://www.softwareag.cloud/site/product/cumulocity-iot.html) Trial tenant. -- A Raspberry Pi (3 or 4) with Raspbian installed, for other boards and OS'es have a look [here](../references/supported-platforms.md) -- Updated device: -` -sudo apt-get update && sudo apt-get upgrade -` +- 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 + + ``` + sudo apt-get update && sudo apt-get upgrade + ``` ## 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 thin-edge.io. +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%%. -- [Step 1 Install thin-edge.io](#step-1-install-thin-edgeio) +- [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 3 Sending Device Data](#step-3-sending-device-data) - [Step 4 Monitor the device](#step-4-monitor-the-device) @@ -40,7 +39,7 @@ This tutorial is divided into small steps. The first three steps are needed to i - [Step 7 Manage Log Files](#step-7-manage-log-files) -## Step 1 Install thin-edge.io +## Step 1 Install %%te%% {#step-1-install-thin-edgeio} The easiest way is to use the installation script with this command: @@ -52,7 +51,7 @@ curl -fsSL https://thin-edge.io/install.sh | sh -s wget -O - https://thin-edge.io/install.sh | sh -s ``` -After a successful installation, it is possible to use thin-edge.io via the CLI and use the tedge commands. +After a successful installation, it is possible to use %%te%% via the CLI and use the tedge commands. :::info For more information about the installation, please have a look [here](../install/index.md) for more information. @@ -100,7 +99,7 @@ SUBCOMMANDS: Here is an [overview of the commands for the CLI tool](../references/cli/index.md). -The CLI will be used to configure the thin-edge.io installation on the device in the next steps. +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 @@ -118,7 +117,7 @@ sudo tedge config set c8y.url "mycompany.cumulocity.com" ### Certificate -thin-edge.io 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 IoT. A certificate is trusted when it is added to the trusted certificates and is in an activated state. First, we need to create the device certificate locally (If the device certificate is already uploaded, directly via the UI to Cumulocity IoT this step can be skipped). @@ -177,13 +176,13 @@ Below shows some examples on how to publish an MQTT message via the command line tedge mqtt pub '{{TOPIC}}' '{{PAYLOAD}}' ``` -thin-edge.io comes with a tedge-mapper daemon. This process collects the data from the `te/#` topics and translates them to the tedge payloads on the `c8y/#` topics which are mapped directly to Cumulocity IoT. The mapper translates simple JSON to the desired target payload for Cumulocity IoT. +%%te%% comes with a tedge-mapper daemon. This process collects the data from the `te/#` topics and translates them to the tedge payloads on the `c8y/#` topics which are mapped directly to Cumulocity IoT. The mapper translates simple JSON to the desired target payload for Cumulocity IoT. ### Sending measurements Measurements within Cumulocity IoT represent regularly acquired readings and statistics from sensors. -A simple single-valued measurement like a temperature measurement can be represented in Thin Edge JSON as follows: +A simple single-valued measurement like a temperature measurement can be represented in %%te%% JSON as follows: ```json {"temperature": 25} @@ -205,7 +204,7 @@ tedge mqtt pub te/device/main///m/ '{"temperature": 25}' Events are used to pass real-time information, which is not just plain sensor values, through Cumulocity IoT. -A simple event can be represented in Thin Edge JSON as follows: +A simple event can be represented in %%te%% JSON as follows: ```json { @@ -232,19 +231,19 @@ When you go to events (`Device management` → `your device` → `events`) ## Step 4 Monitor the device -With thin-edge.io device monitoring, you can collect metrics from the device and forward these device metrics to Cumulocity IoT. +With %%te%% device monitoring, you can collect metrics from the device and forward these device metrics to Cumulocity IoT. -thin-edge.io uses the open source component `collectd` to collect the metrics from the device. thin-edge.io translates the `collected` metrics from their native format to the thin-edge.io JSON format and then into the cloud-vendor-specific format. +%%te%% uses the open source component `collectd` to collect the metrics from the device. %%te%% translates the `collected` metrics from their native format to the %%te%% JSON format and then into the cloud-vendor-specific format. Enabling monitoring on your device is a 3-steps process: - Install collectd - Configure collectd -- Enable thin-edge.io monitoring +- Enable %%te%% monitoring ### Install collectd -Because thin-edge.io uses the MQTT plugin of collectd, installation of the Mosquitto client library (either mosquitto-clients or libmosquitto1) is required. +Because %%te%% uses the MQTT plugin of collectd, installation of the Mosquitto client library (either mosquitto-clients or libmosquitto1) is required. ```sh title="Option 1: (Recommended)" sudo apt-get install --no-install-recommends collectd-core mosquitto-clients @@ -256,7 +255,7 @@ sudo apt-get install --no-install-recommends collectd-core libmosquitto1 ### Configure collectd -thin-edge.io provides a basic collectd configuration that can be used to collect CPU, memory and disk metrics. +%%te%% provides a basic collectd configuration that can be used to collect CPU, memory and disk metrics. Simply copy the file to the main collectd configuration file and restart the daemon. @@ -319,7 +318,7 @@ To change the monitored data, it is needed to change the collectd.conf. This can ## Step 5 Add software management -Software management takes care of allowing installation and management of any type of software from Cumulocity IoT. Since the type is generic, any type of software can be managed. In thin-edge.io this can be extended with plugins. For every software type, a particular plugin is needed. +Software management takes care of allowing installation and management of any type of software from Cumulocity IoT. Since the type is generic, any type of software can be managed. In %%te%% this can be extended with plugins. For every software type, a particular plugin is needed. The following plugins do exist: @@ -351,7 +350,7 @@ sudo tedge connect c8y 3. In the dialog box, enter a name for the software and confirm it by clicking `Add new`, a description and its version. -4. thin-edge.io contains a default plugin supporting `debian` packages from both `apt` repositories as well as remote locations. +4. %%te%% contains a default plugin supporting `debian` packages from both `apt` repositories as well as remote locations. If you prefer to use packages from an `apt` repository, select the `Provide a file path` option and give an empty space (' '). ![Add new software](./images/AddSoftware.png) @@ -378,11 +377,11 @@ When a different version of the already installed software needs to be installed Find more information about [how to manage the software](https://cumulocity.com/guides/users-guide/device-management/#managing-software-on-a-device) on a device. -How to [develop your own plugins](../extend/write-my-software-management-plugin.md) is described here. +How to [develop your own plugins](../extend/software-management.md) is described here. ## Step 6 Manage configuration files -With thin-edge.io it is possible to manage config files on a device by using the Cumulocity IoT configuration management feature as a part of Device Management. +With %%te%% it is possible to manage config files on a device by using the Cumulocity IoT configuration management feature as a part of Device Management. This functionality is directly installed with the initial script. However, it is needed to configure its configuration file to add the entries for the configuration files which need to be managed. @@ -418,17 +417,12 @@ In this tutorial the last option is explained, there are some steps to be taken: 1. Save the configuration file to the repository (`Device management` → `configuration`. In the list of configuration files pick a file to change and click on `Save to repository`). - 2. Go to `Management` → `configuration` snapshots repository. 3. Download the configuration file which needs to be changed (the one you saved to the repository in step 1). 4. Edit this file as needed. 5. Click on `Add configuration snapshot` (top right). -6. Fill the fields, make sure the device type is `thin-edge.io`, select the right Configuration type and add the (just edited) configuration file and click on `Add configuration`. +6. Fill the fields, make sure the device type is %%te%%, select the right Configuration type and add the (just edited) configuration file and click on `Add configuration`. 7. Go back to the device and then to the configuration. In the Available supported configuration you will see the configuration file which was just created. When you click on it, you will see the content. - -8. Then click on ``` send configuration to device ``` the configuration file is uploaded to the device. -9. If you then click on ``` get snapshot from device ``` (select the right configuration file in device supported configurations), you will see the change of the configuration file. - 8. Then click on `send configuration to device` the configuration file is uploaded to the device. 9. If you then click on `get snapshot from device` (select the right configuration file in device-supported configurations), you will see the change of the configuration file. @@ -454,16 +448,16 @@ To change the collectd metrics of the device, which are displayed in Cumulocity 3. Go to `Management` → `configuration` snapshots repository 4. Download the configuration file which needs to be changed 5. Edit this file as needed -6. Click on ``` Add configuration snapshot ``` (top right) -7. Fill in the fields, make sure the device type is ``` thin-edge.io ``` and select the right Configuration type and add the (just edited) configuration file.) and click on ```Add configuration ``` +6. Click on `Add configuration snapshot` (top right) +7. Fill in the fields, make sure the device type is %%te%% and select the right Configuration type and add the (just edited) configuration file then click on `Add configuration` 8. Go back to the device and then to the configuration. In the Available supported configuration you will see the configuration file which was just created. When you click on it, you will see the content -9. Then click on ``` send configuration to the device ``` the configuration file is uploaded to the device. +9. Then click on `send configuration to the device` the configuration file is uploaded to the device. 10. If you then click on get snapshot from device (select the right configuration file in device supported configurations), you will see the change of the configuration file. ## Step 7 Manage Log Files -With thin-edge.io it is possible to request log files from a device by using the Cumulocity IoT log request feature as a part of Device Management. +With %%te%% it is possible to request log files from a device by using the Cumulocity IoT log request feature as a part of Device Management. This functionality is also installed by default but some configuration is needed to indicate which log files the plugin should manage. @@ -502,6 +496,6 @@ However, keep in mind that the daemon has to be restarted every time the `/etc/t ### Final remarks and summary -With this getting started tutorial you gained some insights on how to install and configure thin-edge.io on a Raspberry Pi. +With this getting started tutorial you gained some insights on how to install and configure %%te%% on a Raspberry Pi. -If you didn't try the optional steps in this tutorial, it might be a nice idea to work on these as you then get a better insight into the device management capabilities of thin-edge.io. Other things you can work on are capabilities like working with child devices, building your own plugin etc. Tutorials for that can be found [here](../operate/index.md). +If you didn't try the optional steps in this tutorial, it might be a nice idea to work on these as you then get a better insight into the device management capabilities of %%te%%. Other things you can work on are capabilities like working with child devices, building your own plugin etc. Tutorials for that can be found [here](../operate/index.md). diff --git a/docs/src/start/raise-alarm.md b/docs/src/start/raise-alarm.md index c61488c1b87..87c6ad67a42 100644 --- a/docs/src/start/raise-alarm.md +++ b/docs/src/start/raise-alarm.md @@ -2,11 +2,12 @@ title: Raising Alarms tags: [Getting Started, Telemetry] sidebar_position: 7 +description: How to raise alarms with %%te%% --- # Raising Alarms -Alarms on thin-edge.io can be used to create alerts, represent state changes etc. +Alarms on %%te%% can be used to create alerts, represent state changes etc. For example, an alarm can be raised when a certain measurement value breaches some threshold (like high temperature) or when an unexpected event occurs in the system (like a sensor failure). A typical alarm cycle starts by the raising of an alarm by some monitoring process which alerts a system/human of an event needing some action. @@ -15,12 +16,12 @@ Once some action is taken, the alarm is cleared explicitly by that system/human. Every alarm is uniquely identified by its type and severity. That is, for a given alarm type, alarms of varying severities are treated as independent alarms and hence, must be acted upon separately. For an alarm of a given type and severity, only the last known state is considered relevant. -Thin-edge.io doesn't keep a history of all its state changes but only reacts to the last one it receives. +%%te%% doesn't keep a history of all its state changes but only reacts to the last one it receives. ## Raising an alarm -An alarm can be raised on thin-edge.io by sending an MQTT message in Thin Edge JSON format to certain MQTT topics. +An alarm can be raised on %%te%% by sending an MQTT message in %%te%% JSON format to certain MQTT topics. The scheme of the topic to publish the alarm data is as follows: @@ -39,9 +40,9 @@ The payload format must be as follows: ``` :::note -These messages must be sent with MQTT retained flag enabled and with QOS > 1 to ensure guaranteed processing by thin-edge.io. +These messages must be sent with MQTT retained flag enabled and with QOS > 1 to ensure guaranteed processing by %%te%%. Enabling the retained flag ensures that the alarm stays persisted with the MQTT broker until its state changes again. -These retained messages will make sure that the thin-edge.io processes or any other third-party processes subscribed to these alarms will get those, +These retained messages will make sure that the %%te%% processes or any other third-party processes subscribed to these alarms will get those, even if they were down at the moment the alarm was raised. If multiple messages are sent to the same alarm topic, the last alarm is considered to have overwritten the previous one. ::: @@ -60,7 +61,7 @@ tedge mqtt pub te/device/main///a/temperature_high ' :::note Both the `text` field and the `time` field are optional. When a `text` is not provided, it is assumed to be empty. -When `time` is not provided, thin-edge.io will use the current system time as the `time` of the alarm. +When `time` is not provided, %%te%% will use the current system time as the `time` of the alarm. When you want to skip both fields, use an empty json fragment `{}` as the payload to indicate the same. An empty message can't be used for the same, as empty messages are used to clear alarms, which is discussed in the next section. ::: @@ -74,7 +75,7 @@ The `` value in the MQTT payload is recommended to be one of the follo There are no such restrictions on the `` value. -Thin-edge.io doesn't keep any history of all alarms raised on an alarm topic. +%%te%% doesn't keep any history of all alarms raised on an alarm topic. ## Clearing alarms @@ -100,7 +101,7 @@ The alarm payload structure is the same, as described in the previous section. ### Raising an alarm with custom fragment -Thin-edge supports the creation of alarms using custom (user-defined) fragments. +%%te%% supports the creation of alarms using custom (user-defined) fragments. Custom fragments are supported for both the main and child devices. The custom fragments can be a simple json value or a complex json value. @@ -148,9 +149,9 @@ The default value for the `text` fragment will be derived from the `alarm-type` ## Cloud data mapping -If the device is connected to some supported IoT cloud platform, any alarms raised locally on thin-edge.io will be forwarded to the connected cloud platform as well. -The mapping of thin-edge alarms data to its respective cloud-native representation will be done by the corresponding cloud mapper process. -For example, if the device is connected to Cumulocity IoT cloud platform, the Cumulocity cloud mapper process will translate the thin-edge alarm JSON data to its equivalent Cumulocity SmartREST representation. +If the device is connected to some supported IoT cloud platform, any alarms raised locally on %%te%% will be forwarded to the connected cloud platform as well. +The mapping of %%te%% alarms data to its respective cloud-native representation will be done by the corresponding cloud mapper process. +For example, if the device is connected to Cumulocity IoT cloud platform, the Cumulocity cloud mapper process will translate the %%te%% alarm JSON data to its equivalent Cumulocity SmartREST representation. :::info As of now, alarm data mapping is supported only on Cumulocity IoT cloud platform. @@ -158,7 +159,7 @@ As of now, alarm data mapping is supported only on Cumulocity IoT cloud platform ### Cumulocity cloud data mapping -The Cumulocity mapper will convert Thin Edge JSON alarm into Cumulocity SmartREST messages and send it to Cumulocity via MQTT. +The Cumulocity mapper will convert %%te%% JSON alarm into Cumulocity SmartREST messages and send it to Cumulocity via MQTT. For example the `temperature_high` alarm with `critical` severity described in the earlier sections will be converted to the following Cumulocity SmartREST message: @@ -173,7 +174,7 @@ If the alarm is raised from a child device, the payload is published to `c8y/s/u If an alarm contains a `custom fragment` then, the alarm message will be converted to `cumulocity json` format and then will be published on to `c8y/alarm/alarms/create` topic. -An example of the translated custom message for `thin-edge` device will be as below +An example of the translated custom message for a %%te%% device will be as below ```json { diff --git a/docs/src/start/send-events.md b/docs/src/start/send-events.md index 3af1193fe4a..8d4ab2ae9ab 100644 --- a/docs/src/start/send-events.md +++ b/docs/src/start/send-events.md @@ -2,22 +2,23 @@ title: Sending Events tags: [Getting Started, Telemetry] sidebar_position: 6 +description: How to send events with %%te%% --- # Sending Events -Events on thin-edge.io can be used to trigger signals when some event happens in the system. +Events on %%te%% can be used to trigger signals when some event happens in the system. For example, a person entering a room or someone logging into a machine/website can all be represented as events. Events are stateless and hence are processed as and when they occur. They don't represent state but can be used to represent state changes. An event can't be updated/cleared once its triggered, unlike alarms that are cleared explicitly after processing. Every event is uniquely identified by its type. -If multiple events are raised for a given type, thin-edge.io will process them all separately in the order in which they were raised. +If multiple events are raised for a given type, %%te%% will process them all separately in the order in which they were raised. ## Sending an event -An event can be triggered on thin-edge.io by sending an MQTT message in Thin Edge JSON format to certain MQTT topics. +An event can be triggered on %%te%% by sending an MQTT message in %%te%% JSON format to certain MQTT topics. The scheme of the topic to publish the event data is as follows: @@ -49,7 +50,7 @@ Both the `text` field and the `time` field are optional. ::: When the `text` field is not provided, the `event-type` from the MQTT topic will be used as the message as well if the connected cloud mandates one. -When the `time` field is not provided, thin-edge.io will use the current system time as the `time` of the event. +When the `time` field is not provided, %%te%% will use the current system time as the `time` of the event. When you want to skip both fields, use an empty payload to indicate the same. There are no such restrictions on the `` value. @@ -61,9 +62,9 @@ The event payload structure is the same, as described in the previous section. ## Cloud data mapping -If the device is connected to some supported IoT cloud platform, an event that is triggered locally on thin-edge.io will be forwarded to the connected cloud platform as well. -The mapping of thin-edge events data to its respective cloud-native representation will be done by the corresponding cloud mapper process. -For example, if the device is connected to Cumulocity IoT cloud platform, the Cumulocity cloud mapper process will translate the thin-edge event JSON data to its equivalent Cumulocity SmartREST representation. +If the device is connected to some supported IoT cloud platform, an event that is triggered locally on %%te%% will be forwarded to the connected cloud platform as well. +The mapping of %%te%% events data to its respective cloud-native representation will be done by the corresponding cloud mapper process. +For example, if the device is connected to Cumulocity IoT cloud platform, the Cumulocity cloud mapper process will translate the %%te%% event JSON data to its equivalent Cumulocity SmartREST representation. :::caution As of now, event data mapping is supported only on Cumulocity IoT cloud platform. @@ -71,7 +72,7 @@ As of now, event data mapping is supported only on Cumulocity IoT cloud platform ### Cumulocity cloud data mapping -The Cumulocity mapper will convert Thin Edge JSON events into its Cumulocity SmartREST equivalent if the payload only contains either a `text` field or `time` field. +The Cumulocity mapper will convert %%te%% JSON events into its Cumulocity SmartREST equivalent if the payload only contains either a `text` field or `time` field. For example the `login_event` described in the earlier sections will be converted to the following Cumulocity SmartREST message: @@ -98,14 +99,14 @@ The Cumulocity JSON mapping of the same event would be as follows: ``` :::note -Mapped events will be sent to Cumulocity via MQTT if the incoming Thin Edge JSON event payload size is less than 16K bytes. If higher, HTTP will be used. +Mapped events will be sent to Cumulocity via MQTT if the incoming %%te%% JSON event payload size is less than 16K bytes. If higher, HTTP will be used. ::: Find more information about events data model in Cumulocity [here](https://cumulocity.com/guides/concepts/domain-model/#events). ## Sending an event for a child/external device to the cloud -An event for a child/external device can be triggered on thin-edge.io by sending an MQTT message in Thin Edge JSON format to certain MQTT topics. +An event for a child/external device can be triggered on %%te%% by sending an MQTT message in %%te%% JSON format to certain MQTT topics. The scheme of the topic to publish the event data is as follows: @@ -135,12 +136,12 @@ tedge mqtt pub te/device/external_sensor///e/login_event '{ ### Mapping of events to cloud-specific data format -If the child/external device is connected to some supported IoT cloud platform, an event that is triggered locally on thin-edge.io will be forwarded to the connected cloud platform as well. -The mapping of thin-edge events data to its respective cloud-native representation will be done by the corresponding cloud mapper process. +If the child/external device is connected to some supported IoT cloud platform, an event that is triggered locally on %%te%% will be forwarded to the connected cloud platform as well. +The mapping of %%te%% events data to its respective cloud-native representation will be done by the corresponding cloud mapper process. #### Cumulocity cloud data mapping -The Cumulocity mapper will convert Thin Edge JSON events into its Cumulocity JSON equivalent and sends them to the Cumulocity cloud. +The Cumulocity mapper will convert %%te%% JSON events into its Cumulocity JSON equivalent and sends them to the Cumulocity cloud. The translated payload will be in the below format. diff --git a/docs/src/start/send-thin-edge-data.md b/docs/src/start/send-measurements.md similarity index 67% rename from docs/src/start/send-thin-edge-data.md rename to docs/src/start/send-measurements.md index 6eb8a5e00af..67db865399e 100644 --- a/docs/src/start/send-thin-edge-data.md +++ b/docs/src/start/send-measurements.md @@ -2,21 +2,22 @@ title: Sending Measurements tags: [Getting Started, Telemetry] sidebar_position: 5 +description: How to send measurements with %%te%% --- # Sending Measurements -Once your Thin Edge device is configured and connected to an IoT cloud provider, you can start sending measurements. +Once your %%te%% device is configured and connected to an IoT cloud provider, you can start sending measurements. Refer to [Connecting to Cumulocity](./connect-c8y.md) or tutorials for other cloud providers -to learn how to connect your Thin Edge device to an IoT cloud provider. +to learn how to connect your %%te%% device to an IoT cloud provider. -In this tutorial, we'll see how different kinds of measurements are represented in Thin Edge JSON format and +In this tutorial, we'll see how different kinds of measurements are represented in %%te%% JSON format and how they can be sent to the connected cloud provider. -For a more detailed specification of this data format, refer to [Thin Edge JSON Specification](../understand/thin-edge-json.md). +For a more detailed specification of this data format, refer to [%%te%% JSON Specification](../understand/thin-edge-json.md). ## Sending measurements -A simple single-valued measurement like a temperature measurement, can be represented in Thin Edge JSON as follows: +A simple single-valued measurement like a temperature measurement, can be represented in %%te%% JSON as follows: ```json {"temperature": 25} @@ -24,8 +25,8 @@ A simple single-valued measurement like a temperature measurement, can be repres with the key-value pair representing the measurement type and the numeric value of the measurement. -This measurement can be sent from the Thin Edge device to the cloud by publishing this message to the `te/+/+/+/+/m/+` MQTT topic. -Processes running on the Thin Edge device can publish messages to the local MQTT broker using any MQTT client or library. +This measurement can be sent from the %%te%% device to the cloud by publishing this message to the `te/+/+/+/+/m/+` MQTT topic. +Processes running on the %%te%% device can publish messages to the local MQTT broker using any MQTT client or library. In this tutorial, we'll be using the `tedge mqtt pub` command line utility for demonstration purposes. The temperature measurement described above can be sent using the `tedge mqtt pub` command as follows: @@ -35,11 +36,11 @@ tedge mqtt pub te/device/main///m/environment '{"temperature": 25}' ``` The first argument to the `tedge mqtt pub` command is the topic to which the measurements must be published to. -The second argument is the Thin Edge JSON representation of the measurement itself. +The second argument is the %%te%% JSON representation of the measurement itself. When connected to a cloud provider, a message mapper component for that cloud provider would be running as a daemon, listening to any measurements published to `te/+/+/+/+/m/+`. -The mapper, on receipt of these Thin Edge JSON measurements, will map those measurements to their equivalent +The mapper, on receipt of these %%te%% JSON measurements, will map those measurements to their equivalent cloud provider native representation and send it to that cloud. For example, when the device is connected to Cumulocity, the Cumulocity mapper component will be performing these actions. @@ -51,7 +52,7 @@ You can see if your temperature measurement is appearing in the dashboard. ## Complex measurements -You can represent measurements that are far more complex than the single-valued ones described above using the Thin Edge JSON format. +You can represent measurements that are far more complex than the single-valued ones described above using the %%te%% JSON format. A multi-valued measurement like `three_phase_current` that consists of `L1`, `L2` and `L3` values, representing the current on each phase can be represented as follows: @@ -83,15 +84,15 @@ along with a multi-valued `coordinate` measurement, all sharing a single timesta ``` The `time` field is not a regular measurement like `temperature` or `pressure` but a special reserved field. -Refer to [Thin Edge JSON Specification](../understand/thin-edge-json.md) for more details on the kinds of telemetry -data that can be represented in Thin Edge JSON format and the reserved fields like `time` used in the above example. +Refer to [%%te%% JSON Specification](../understand/thin-edge-json.md) for more details on the kinds of telemetry +data that can be represented in %%te%% JSON format and the reserved fields like `time` used in the above example. ## Sending measurements to child devices -If valid Thin Edge JSON measurements are published to the `te/device////m/` topic, -the measurements are recorded under a child device of your thin-edge.io device. +If valid %%te%% JSON measurements are published to the `te/device////m/` topic, +the measurements are recorded under a child device of your %%te%% device. -Given your desired child device ID is `child1`, publish a Thin Edge JSON message to the following topic where the measurement type is set to `environment`: +Given your desired child device ID is `child1`, publish a %%te%% JSON message to the following topic where the measurement type is set to `environment`: ```sh te2mqtt formats=v1 tedge mqtt pub te/device/child1///m/environment '{"temperature": 25}' @@ -102,7 +103,7 @@ and the measurement is recorded in `Measurements` of the `child1` device. ## Error detection -If the data published to the measurements topic are not valid Thin Edge JSON measurements, those won't be +If the data published to the measurements topic are not valid %%te%% JSON measurements, those won't be sent to the cloud but instead you'll get a feedback on the `te/errors` topic, if you subscribe to it. The error messages published to this topic will be highly verbose and may change in the future. So, use it only for debugging purposes during the development phase and it should **NOT** be used for any automation. diff --git a/docs/src/start/software-management.md b/docs/src/start/software-management.md index 9858f1b7f5f..b4260131b9e 100644 --- a/docs/src/start/software-management.md +++ b/docs/src/start/software-management.md @@ -2,17 +2,16 @@ title: Updating Software tags: [Getting Started, Software Management] sidebar_position: 9 +description: Manage the software on your devices from Cumulocity cloud --- -# Manage the software on your devices from Cumulocity cloud - -This document describes how to manage the software modules that are installed on a thin-edge device from the -cloud using the **software management** feature of thin-edge.io. +This document describes how to manage the software modules that are installed on a %%te%% device from the +cloud using the **software management** feature of %%te%%. :::note This tutorial shows the Debian based distributions **apt** package manager use-case powered by our official **apt** plugin. Other package managers can be supported by adding a plugin. -Refer to [this](../extend/write-my-software-management-plugin.md) document on how to write a plugin to support software management for any other software type. +Refer to [this](../extend/software-management.md) document on how to write a plugin to support software management for any other software type. ::: :::info @@ -22,12 +21,12 @@ As of now, software management feature is supported only from Cumulocity cloud, Three components are required on your devices to enable software management: 1. Software management mapper for Cumulocity cloud acts as a proxy between the cloud and the device. - This translates the cloud specific message type into device specific type and vice-versa.(Example: Cumulocity smart-rest to/from thin-edge json) + This translates the cloud specific message type into device specific type and vice-versa.(Example: Cumulocity smart-rest to/from %%te%% json) The messages from cloud will be translated and forwarded to the `tedge-agent` and messages from `tedge-agent` will be translated and sent to cumulocity cloud. You can find this process with the name `tedge-mapper c8y` in `ps` once it starts. 2. Software management agent - The thin-edge software management agent is the one that calls the plugins. + The %%te%% software management agent is the one that calls the plugins. You can find this process with the name `tedge-agent` in `ps` once it starts. 3. Software management plugin @@ -35,10 +34,6 @@ Three components are required on your devices to enable software management: You can find them in /etc/tedge/sm-plugins. As of now there is only one (apt) plugin is supported. -## Enable software management feature - -Find more information about [how to install and enable software management.](../operate/installation/install_and_enable_software_management.md) - ## Managing the device software **repository** on Cumulocity cloud Managing the software packages installed on the devices from your Cumulocity tenant is a two steps operation. @@ -70,7 +65,7 @@ Find more information about [managing the device software](https://cumulocity.co 3. Optionally, you can define the device type filter when adding a new software. -4. thin-edge.io ships a default plugin supporting `debian` packages from both `apt` repositories as well as remote locations. +4. %%te%% ships a default plugin supporting `debian` packages from both `apt` repositories as well as remote locations. If you prefer to use packages from an `apt` repository, select the **Provide a file path** option and give an **empty space** (' '). diff --git a/docs/src/understand/mqtt-bus.md b/docs/src/understand/mqtt-bus.md index c3ed6725203..517b3602fa4 100644 --- a/docs/src/understand/mqtt-bus.md +++ b/docs/src/understand/mqtt-bus.md @@ -2,14 +2,13 @@ title: MQTT Bus tags: [Concept, MQTT] sidebar_position: 3 +description: Overview of the MQTT Bus --- -# Thin Edge MQTT bus - -Thin-edge uses a combination of MQTT and HTTP to coordinate the interactions +%%te%% uses a combination of MQTT and HTTP to coordinate the interactions between the miscellaneous hardware and software components that make up a piece of equipment. -- A local MQTT broker is deployed along each thin-edge enabled piece of equipment. +- A local MQTT broker is deployed along each %%te%% enabled piece of equipment. - Each device and service is given dedicated MQTT topics to publish their measurements, events and alarms as well as to receive targeted operation requests. - Similarly, a local HTTP server is used to transfer files to and from child devices, @@ -42,7 +41,7 @@ as well as to trigger operations on devices and services. However, it's more pertinent to use HTTP to transfer files from one device to another. And this is not only because of payload size constraints, but also for *pull* versus *push* constraints. -By combining MQTT with HTTP, a thin-edge service can *notify* a child-device that a file is *available* for local transfer +By combining MQTT with HTTP, a %%te%% service can *notify* a child-device that a file is *available* for local transfer and then let the child-device *download* the file when *ready*. A notable use is to install a new version of firmware, software package or configuration file on a child-device. diff --git a/docs/src/understand/overview.md b/docs/src/understand/overview.md index cecd2baad00..d7631708efa 100644 --- a/docs/src/understand/overview.md +++ b/docs/src/understand/overview.md @@ -2,11 +2,10 @@ title: Overview tags: [Concept] sidebar_position: 1 +description: Overview of the how/what/why/who of %%te%% --- -# Thin-edge Overview - -Thin-edge is an open-source IoT development toolbox +%%te%% is an open-source IoT development toolbox designed to ease the development of smart IoT agents with a versatile set of ready-to-use software components that can be easily combined with application-specific extensions. @@ -24,19 +23,19 @@ The main functions and challenges are to: ## How -To implement these functions, thin-edge proposes to design an IoT agent using a combination of software components, +To implement these functions, %%te%% proposes to design an IoT agent using a combination of software components, which are deployed on the main gateway device as well as the set of interconnected embedded devices that form the equipment. -A typical thin-edge setup consists of the following components: +A typical %%te%% setup consists of the following components: - a local MQTT broker that is used as a message bus between all the components of the equipment - an MQTT bridge connection between the local message bus and the remote cloud end-point -- thin-edge (out-of-the-box) device management services which provide features such as monitoring, configuration and software management +- %%te%% (out-of-the-box) device management services which provide features such as monitoring, configuration and software management - equipment-specific services that interact with the hardware that make the equipment, publishing the collected data and forwarding operation requests on the MQTT bus as well as abstracting various device specific protocols - a cloud-specific service that maps the messages exchanged on the local bus with messages sent to or received from the cloud The first point to note is that all these software components can be provided by independent vendors: -by the thin-edge open-source project, by the equipment maker, by the IoT application developer +by the %%te%% open-source project, by the equipment maker, by the IoT application developer or even by cloud providers, hardware manufacturers and protocol implementors. Their interoperability is based on: - ubiquitous protocols: JSON over MQTT and HTTP, @@ -45,9 +44,9 @@ Their interoperability is based on: for measurements, events, alarms, configurations, software updates, firmware updates, - various extension points: for child devices, services, operations and clouds. -The second key point is that thin-edge not only defines a set of APIs +The second key point is that %%te%% not only defines a set of APIs but also provides a set of ready-to-use software components implementing the associated features. -Out-of-the-box thin-edge supports telemetry and device management features on the main devices and child devices. +Out-of-the-box %%te%% supports telemetry and device management features on the main devices and child devices. These features are implemented by composable software components that: - can be freely adapted, combined, removed or replaced - provide the foundation to start the development of an agent with sensible defaults @@ -55,34 +54,34 @@ These features are implemented by composable software components that: ## Why -The aim of thin-edge is to reduce the development effort to build smart IoT agents +The aim of %%te%% is to reduce the development effort to build smart IoT agents without compromising on quality and feature completeness. -thin-edge's goal is to deliver: +%%te%%'s goal is to deliver: - ready-to-use components provide sound foundations - interchangeable software components make it possible to adapt the generic agent to specific contexts - simple, yet flexible, extension points enable custom functionality to be added in a modular fashion ## Who -The flexibility of thin-edge means that it can be used at different levels. -- As a beginner, the simplest option is to use thin-edge as a pre-assembled agent, +The flexibility of %%te%% means that it can be used at different levels. +- As a beginner, the simplest option is to use %%te%% as a pre-assembled agent, ready to be installed on a device and configured for a cloud account. - The [getting started guide](../start/index.md) gives a taste of what can be done with thin-edge out-of-the-box + The [getting started guide](../start/index.md) gives a taste of what can be done with %%te%% out-of-the-box - As a cloud operator, no direct access to a device is required, except for occasional troubleshooting, as most of the operations can be done remotely. However, being able to operate directly on a device gives the required understanding - to administrate a fleet of thin-edge devices with confidence -- As a __device operator__, be prepared to operate a device that is not running the pre-assembled thin-edge agent, + to administrate a fleet of %%te%% devices with confidence +- As a __device operator__, be prepared to operate a device that is not running the pre-assembled %%te%% agent, but an agent specifically designed for your equipment and application. Among all the [available features](../operate/index.md), some might have been configured differently, disabled, extended, replaced or even added -- As an __agent developer__, the nature of thin-edge lets you +- As an __agent developer__, the nature of %%te%% lets you start the design of an agent with the pre-assembled agent and to incrementally [configure, adapt and extend](../extend/index.md) the agent to meet the requirements of the equipment and application. Part of this work can be to implement software components - that interact with thin-edge through its JSON API over MQTT and HTTP + that interact with %%te%% through its JSON API over MQTT and HTTP and are to be deployed on the main devices and the attached child devices -- As a contributor, you can [extend thin-edge using its Rust API](../contribute/index.md), +- As a contributor, you can [extend %%te%% using its Rust API](../contribute/index.md), when loosely coupling components over MQTT and HTTP is not appropriate (e.g. for performance reasons) \ No newline at end of file diff --git a/docs/src/understand/software-management.md b/docs/src/understand/software-management.md index edc1bf2b1ed..b1e9941f21b 100644 --- a/docs/src/understand/software-management.md +++ b/docs/src/understand/software-management.md @@ -2,11 +2,10 @@ title: Software Management tags: [Concept, Software Management] sidebar_position: 7 +description: Software Management with %%te%% --- -# Software Management with thin-edge.io - -With thin-edge.io you can ease the burden of managing packages on your device. +With %%te%% you can ease the burden of managing packages on your device. Software Management operates end to end from a cloud down to the OS of your device and reports statuses accordingly. ## Software management components @@ -33,8 +32,7 @@ The key points are that the **Tedge Agent** is always generic in cloud platforms The **Software Management Plugin** is dedicated to defining the behaviour of software actions (list, update, remove) per software type (apt, docker, etc.) ## Related documents -1. [How to install and enable software management?](../operate/installation/install_and_enable_software_management.md) -2. [Manage my device software](../start/software-management.md) -3. [Write my software management plugin](../extend/write-my-software-management-plugin.md) -4. [The Software Management Plugin API](../references/plugin-api.md) -5. [Software Management Specification](https://github.com/thin-edge/thin-edge.io-specs/tree/main/src/software-management) +1. [Manage my device software](../start/software-management.md) +2. [Write my software management plugin](../extend/software-management.md) +3. [The Software Management Plugin API](../references/software-management-plugin-api.md) +4. [Software Management Specification](https://github.com/thin-edge/thin-edge.io-specs/tree/main/src/software-management) diff --git a/docs/src/understand/tedge-agent.md b/docs/src/understand/tedge-agent.md index d4fe6dd4dc6..a1df000de24 100644 --- a/docs/src/understand/tedge-agent.md +++ b/docs/src/understand/tedge-agent.md @@ -2,11 +2,10 @@ title: The Agent tags: [Concept, MQTT] sidebar_position: 5 +description: Overview of the fundamental components that make up the %%te%% agent --- -# Thin-edge Agent - -Thin-edge agent is a set of services that implement the device management operations on a device. +%%te%% agent is a set of services that implement the device management operations on a device. Examples of such device management functionality include: - software management, checking installed packages and updating these packages - configuration management, checking and updating configuration files @@ -16,7 +15,7 @@ Examples of such device management functionality include: - log file management, retrieving excerpts from log files :::note -In the current version of thin-edge, the agent features are not implemented by a single executable, +In the current version of %%te%%, the agent features are not implemented by a single executable, but by a set of executables: - `tedge-agent` @@ -27,7 +26,7 @@ The short-term plan is to re-organize these plugins to move the Cumulocity aspec and to group the management operations into a single executable. ::: -Thin-edge agent acts as a device connector: +%%te%% agent acts as a device connector: - listening to operation requests published on the MQTT bus - delegating the actual operations to the operating system or other components - reporting progress of the requests @@ -68,7 +67,7 @@ Where the command segments are describe as follows: ### Command examples -The following table details some example command types which are supported by thin-edge. +The following table details some example command types which are supported by %%te%%. | Command Type | Description | Example Topic | |-----------------|-------------|------------------------------------------------| diff --git a/docs/src/understand/tedge-mapper.md b/docs/src/understand/tedge-mapper.md index f4c2f827f23..10d6ff20d40 100644 --- a/docs/src/understand/tedge-mapper.md +++ b/docs/src/understand/tedge-mapper.md @@ -2,13 +2,12 @@ title: The Mapper tags: [Concept, Cloud, MQTT] sidebar_position: 6 +description: Overview of the core component which interfaces with the cloud --- -# Thin-edge Mapper - The tedge-mapper is a key concept to support multiple cloud providers. The purpose is to translate -messages written using the cloud-agnostic [Thin Edge JSON format](thin-edge-json.md), +messages written using the cloud-agnostic [%%te%% JSON format](thin-edge-json.md), into cloud-specific messages. The tedge-mapper is composed of multiple cloud-specific mappers, such as Cumulocity mapper and Azure mapper. @@ -18,7 +17,7 @@ For instance, `tedge connect c8y` establishes a bridge to Cumulocity and launche that translates the messages in the background. A mapper subscribes to the reserved MQTT topic `te/+/+/+/+/m/+` with the QoS level 1 (at least once). -The messages that arrive in the mapper should be formed in the [Thin Edge JSON](thin-edge-json.md) format. +The messages that arrive in the mapper should be formed in the [%%te%% JSON](thin-edge-json.md) format. The mapper verifies whether the arrived messages are correctly formatted, in case the verification fails, the mapper publishes a corresponded error message on the topic `te/errors` with the QoS level 1 (at least once). @@ -28,11 +27,11 @@ the message will be translated into a cloud-specific format. ## Cumulocity mapper -The Cumulocity mapper translates [Thin Edge JSON](thin-edge-json.md) into Cumulocity's [JSON via MQTT](https://cumulocity.com/guides/device-sdk/mqtt/#json). +The Cumulocity mapper translates [%%te%% JSON](thin-edge-json.md) into Cumulocity's [JSON via MQTT](https://cumulocity.com/guides/device-sdk/mqtt/#json). The translated messages are published on the topic `c8y/measurement/measurements/create` from where they are forwarded to Cumulocity. This mapper is launched by the `tedge connect c8y` command, and stopped by the `tedge disconnect c8y` command. -Example in Thin Edge JSON: +Example in %%te%% JSON: ```json { @@ -64,8 +63,8 @@ String `temperature` is used as fragment and series. (1) The `type` is a mandatory field in the Cumulocity's JSON via MQTT manner, therefore, the Cumulocity mapper uses the user provided type from the topic, and if it is empty then it uses a default value of `ThinEdgeMeasurement`. -(2) `time` will be added by the mapper **only when it is not specified in a received Thin Edge JSON message**. -In this case, the mapper uses the device's local timezone. If you want another timezone, specify the time filed in Thin Edge JSON. +(2) `time` will be added by the mapper **only when it is not specified in a received %%te%% JSON message**. +In this case, the mapper uses the device's local timezone. If you want another timezone, specify the time filed in %%te%% JSON. (3) The mapper uses a measurement name ("temperature" in this example) as both a fragment type and a fragment series in [Cumulocity's measurements](https://cumulocity.com/guides/reference/measurements/#examples). @@ -76,18 +75,18 @@ the message will be transferred to the topic `measurement/measurements/create` b ### For child devices The Cumulocity mapper collects measurements not only from the main device but also from child devices. -These measurements are collected under the `te/device////m/+` topics and forwarded to Cumulocity to corresponding child devices created under the `thin-edge.io` parent device. +These measurements are collected under the `te/device////m/+` topics and forwarded to Cumulocity to corresponding child devices created under the %%te%% parent device. (`` is your desired child device ID.) The mapper works in the following steps. -1. When the mapper receives a Thin Edge JSON message on the `te/device////m/+` topic, - the mapper sends a request to create a child device under the `thin-edge.io` parent device. +1. When the mapper receives a %%te%% JSON message on the `te/device////m/+` topic, + the mapper sends a request to create a child device under the %%te%% parent device. The child device is named after the `` topic name, and the type is `thin-edge.io-child`. 2. Publish corresponded Cumulocity JSON measurements messages over MQTT. 3. The child device is created on receipt of the very first measurement for that child device. -If the incoming Thin Edge JSON message (published on `te/device/child1///m/`) is as follows, +If the incoming %%te%% JSON message (published on `te/device/child1///m/`) is as follows, ```json { @@ -115,14 +114,14 @@ it gets translated into JSON via MQTT by the Cumulocity mapper. ## Azure IoT Hub mapper -The Azure IoT Hub mapper takes messages formatted in the [Thin Edge JSON](thin-edge-json.md) as input. -It validates if the incoming message is correctly formatted Thin Edge JSON, then outputs the message. +The Azure IoT Hub mapper takes messages formatted in the [%%te%% JSON](thin-edge-json.md) as input. +It validates if the incoming message is correctly formatted %%te%% JSON, then outputs the message. The validated messages are published on the topic `az/messages/events/` from where they are forwarded to Azure IoT Hub. This mapper is launched by the `tedge connect az` command, and stopped by the `tedge disconnect az` command. The Azure IoT Hub Mapper processes a message in the following ways. -1. Validates if it is a correct Thin Edge JSON message or not. +1. Validates if it is a correct %%te%% JSON message or not. 2. Validates the incoming message size is below 255 KB. [The size of all device-to-cloud messages must be up to 256 KB](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-d2c-guidance). The mapper keeps 1 KB as a buffer for the strings added by Azure. @@ -168,8 +167,8 @@ to the specified format. ## AWS mapper -The AWS mapper takes messages formatted in the [Thin Edge JSON](thin-edge-json.md) as input. -It validates if the incoming message is correctly formatted Thin Edge JSON, then outputs the message. +The AWS mapper takes messages formatted in the [%%te%% JSON](thin-edge-json.md) as input. +It validates if the incoming message is correctly formatted %%te%% JSON, then outputs the message. The validated messages are published on the topic `aws/td/#` from where they are forwarded to AWS. This mapper is launched by the `tedge connect aws` command, and stopped by the `tedge disconnect aws` command. @@ -178,7 +177,7 @@ This mapper is launched by the `tedge connect aws` command, and stopped by the ` When some error occurs in a mapper process, the mapper publishes a corresponded error message on the topic `te/errors` with the QoS level 1 (at least once). -Here is an example if you publish invalid Thin Edge JSON messages on `te/+/+/+/+/m/+`: +Here is an example if you publish invalid %%te%% JSON messages on `te/+/+/+/+/m/+`: ```sh tedge mqtt pub te/device/main///m/ '{"temperature": 23,"pressure": 220' diff --git a/docs/src/understand/thin-edge-json.md b/docs/src/understand/thin-edge-json.md index bc538eecdc3..bc79f03c0df 100644 --- a/docs/src/understand/thin-edge-json.md +++ b/docs/src/understand/thin-edge-json.md @@ -2,51 +2,50 @@ title: Thin Edge JSON tags: [Concept, MQTT] sidebar_position: 4 +description: Overview of the %%te%% JSON basics --- -# Thin Edge JSON format - -Thin Edge JSON is a lightweight format used in `thin-edge.io` to represent telemetry data: +%%te%% JSON is a lightweight format used in %%te%% to represent telemetry data: measurements, events and alarms as well as operations: software update, configuration update etc. These data are exchanged over the [MQTT bus](mqtt-bus.md) by the devices and services. ## Sending Telemetry Data -The `thin-edge.io` framework exposes some MQTT endpoints that can be used by local processes +The %%te%% framework exposes some MQTT endpoints that can be used by local processes and other devices connected over the network to exchange data between themselves as well as to get some data forwarded to the cloud. -### Sending Telemetry Data to thin-edge.io +### Sending Telemetry Data to %%te%% {#publish-to-te} -All topics with the prefix `te/` are reserved by `thin-edge.io` for this purpose. -To send measurements to `thin-edge.io`, the measurements represented in Thin Edge JSON format can be published +All topics with the prefix `te/` are reserved by %%te%% for this purpose. +To send measurements to %%te%%, the measurements represented in %%te%% JSON format can be published to the `te/+/+/+/+/m/+` topic. -Other processes running on the thin-edge device can subscribe to this topic to process these measurements. +Other processes running on the %%te%% device can subscribe to this topic to process these measurements. -If the messages published to any of the telemetry topics are not well-formed Thin Edge JSON, -then these messages won’t be processed by `thin-edge.io`, not even partially, +If the messages published to any of the telemetry topics are not well-formed %%te%% JSON, +then these messages won’t be processed by %%te%%, not even partially, and an appropriate error message on why the validation failed will be published to a dedicated `te/errors` topic. The messages published to this topic will be highly verbose error messages and can be used for any debugging during development. You should not rely on the structure of these error messages to automate any actions as they are purely textual data and bound to change from time-to-time. -Here is the complete list of topics reserved by `thin-edge.io` for its internal working: +Here is the complete list of topics reserved by %%te%% for its internal working: | Topic | Description | |---------------------------------------------|------------------------------------------------------------------------| -| `te/` | Reserved root topic of `thin-edge.io` | +| `te/` | Reserved root topic of %%te%% | | `te//m/` | Measurements | | `te//e/` | Events | | `te//a/` | Alarms | -| `te/errors` | Error messages emitted by `thin-edge.io` while processing measurements | +| `te/errors` | Error messages emitted by %%te%% while processing measurements | ### Sending Telemetry Data to the cloud -The `thin-edge.io` framework allows users forward telemetry data generated and published to one of the -`te/#` MQTT topics from the thin-edge device to any IoT cloud provider that it is connected to, +The %%te%% framework allows users forward telemetry data generated and published to one of the +`te/#` MQTT topics from the %%te%% device to any IoT cloud provider that it is connected to, with the help of a *mapper* component designed for that cloud. The responsibility of a mapper is to subscribe to the `te/#` topic to receive all incoming data -represented in the cloud vendor neutral Thin Edge JSON format, to a format that the connected cloud understands. +represented in the cloud vendor neutral %%te%% JSON format, to a format that the connected cloud understands. Refer to [Cloud Message Mapper Architecture](./tedge-mapper.md) for more details on the mapper component. ## Measurements @@ -57,7 +56,7 @@ For instance: - state of the manufacturing control process - free disk space on the device -Thin Edge JSON can be used to represent single-valued measurements, multi-valued measurements +%%te%% JSON can be used to represent single-valued measurements, multi-valued measurements or a combination of both along with some auxiliary data like the timestamp at which the measurement(s) was generated. ### Single-valued measurements @@ -115,7 +114,7 @@ tedge mqtt pub te/device/main///m/example '{ ### Grouping measurements -Multiple single-valued and multi-valued measurements can be grouped into a single Thin Edge JSON message as follows: +Multiple single-valued and multi-valued measurements can be grouped into a single %%te%% JSON message as follows: ```sh te2mqtt formats=v1 tedge mqtt pub te/device/main///m/example '{ @@ -133,8 +132,8 @@ The grouping of measurements is usually done to represent measurements collected ### Auxiliary measurement data -When `thin-edge.io` receives a measurement, it will add a timestamp to it before any further processing. -If the user doesn't want to rely on `thin-edge.io` generated timestamps, +When %%te%% receives a measurement, it will add a timestamp to it before any further processing. +If the user doesn't want to rely on %%te%% generated timestamps, an explicit timestamp can be provided in the measurement message itself by adding the time value as a string in ISO 8601 format using `time` as the key name, as follows: @@ -156,7 +155,7 @@ The `time` field must be defined at the root level of the measurement JSON and n like inside the object value of a multi-valued measurement. Non-numeric values like the ISO 8601 timestamp string are allowed only for such reserved keys and not for regular measurements. -Here is the complete list of reserved keys that has special meanings inside the `thin-edge.io` framework +Here is the complete list of reserved keys that has special meanings inside the %%te%% framework and hence must not be used as measurement keys: | Key | Description | @@ -187,7 +186,7 @@ tedge mqtt pub te/device/main///e/login '{ |--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `event_type` | Uniquely identifies the event in the context of the device; part of the MQTT topic | | `text` | Text description of the event; must be UTF-8 encoded | -| `timestamp` | Optional time that indicates when the event occurred, in ISO 8601 string format; when not provided, thin-edge.io uses the current system time | +| `time` | Optional timestamp that indicates when the event occurred, in ISO 8601 string format; when not provided, %%te%% uses the current system time | | `*` | Additional fields are handled as custom specific information; if the connected cloud supports custom fragments its mapper transfers those accordingly to the cloud | ## Alarms @@ -216,6 +215,6 @@ tedge mqtt pub te/device/main///a/temperature_high '{ | `alarm_type` | Uniquely identifies the alarm in the context of the device; part of the MQTT topic | | `severity` | Severity of the alarm; recommended to be `critical`, `major`, `minor` or `warning` | | `text` | Text description of the alarm; must be UTF-8 encoded | -| `timestamp` | Optional time that indicates when the alarm has occurred, in ISO 8601 string format; when not provided, thin-edge.io uses the current system time | +| `timestamp` | Optional time that indicates when the alarm has occurred, in ISO 8601 string format; when not provided, %%te%% uses the current system time | | `*` | Additional fields are handled as custom specific information; if the connected cloud supports custom fragments its mapper transfers those accordingly to the cloud | diff --git a/docs/src/understand/typical-iot-agent.md b/docs/src/understand/typical-iot-agent.md index d0bd80bcd83..fadcc8bc8f7 100644 --- a/docs/src/understand/typical-iot-agent.md +++ b/docs/src/understand/typical-iot-agent.md @@ -2,10 +2,9 @@ title: Typical IoT Agent tags: [Concept] sidebar_position: 1 +description: A typical IoT agent running %%te%% --- -# A typical IoT agent running thin-edge - ## IoT agent A typical IoT agent acts as a gateway between the cloud and devices deployed over machines and plants. @@ -36,7 +35,7 @@ which are virtual representations of the actual devices giving remote capabiliti ## Running thin-edge -__The purpose of thin-edge is to support the development of such smart IoT agents__, +__The purpose of %%te%% is to support the development of such smart IoT agents__, by providing the building blocks to: - provide a uniform way to monitor and control miscellaneous hardware and software @@ -46,24 +45,24 @@ by providing the building blocks to: for firmware, software and configuration management on these devices - collect monitoring and telemetry data, forwarding these data to the cloud when appropriate -![Typical thin-edge deployment](images/typical-iot-agent.svg) +![Typical %%te%% deployment](images/typical-iot-agent.svg) -Thin-edge offers a combination of ready-to-use software components supporting the core features, +%%te%% offers a combination of ready-to-use software components supporting the core features, and extension points which allow users to develop small modular components to meet specific requirements for the piece of equipment, hardware or application. - An [__MQTT bus__](mqtt-bus.md) is used for all the interactions between these components. - Thin-edge defines a [__JSON over MQTT API__](thin-edge-json.md) for the major features: + %%te%% defines a [__JSON over MQTT API__](thin-edge-json.md) for the major features: telemetry data collection, service monitoring, remote operations as well as firmware, software and configuration management. To be precise, this API combines MQTT and HTTP, the latter being used for local file transfers and the former for asynchronous event processing. -- Thin-edge components, the [__agent__](tedge-agent.md) and a set of __operation specific plugins__, supervise all the operations, +- %%te%% components, the [__agent__](tedge-agent.md) and a set of __operation specific plugins__, supervise all the operations, coordinating remote requests with the local thin-edge-compatible software components. - Device-specific software components, the __child device connectors__, that interact with the hardware that make the piece of equipment. Note that the use of MQTT and HTTP APIs give the freedom to deploy these connectors directly on the associated hardware as well as on the main device acting as proxy, when, for some reasons, - the child device software cannot be updated to directly support the thin-edge protocol. + the child device software cannot be updated to directly support the %%te%% protocol. - A cloud specific [__mapper__](tedge-mapper.md) handles the communication with the cloud, translating and forwarding requests and responses to and from the local components. This bidirectional communication establishes the twin live representation of the asset
Thin Edge (input)Cumulocity (output)%%te%% (input)Cumulocity IoT (output)