DOCSEARCHbyAlgolia
Submit Docs

thin-edge.io Documentation

website·Indexed 29 days ago

https://thin-edge.github.io/thin-edge.io/

Specifications and guides for thin-edge.io, an open-source framework for connecting devices to cloud providers like Cumulocity. It covers telemetry data sourcing using the Thin-Edge-Json format, MQTT bus communication, software management via Package Manager Plugins, and operations management using the Tedge CLI.

Tokens
319.2K
Snippets
1.7K
Records
2.3K
Agent score
71%

What's inside thin-edge.io

  1. Overview of thin-edge.io

    thin-edge.io is an open-source development toolbox for creating IoT agents. It provides a set of ready-to-use software components for telemetry data processing, cloud connectivity, device monitoring, configuration, and updates. The system is designed to be extensible, allowing developers to add application-specific extensions that communicate with the core thin-edge.io components over MQTT and HTTP using a JSON API. It is particularly suited for smart equipment that requires real-time data collection, edge analytics, and secure cloud forwarding at scale.

  2. Overview of thin-edge.io configuration plugins

    thin-edge.io supports extensible configuration management via plugins. While the default behavior is limited to basic file-based configurations, custom plugins allow for:

    1. Reading configurations from diverse sources (databases, registries, etc.).
    2. Aggregating multiple configuration extensions into a single 'effective configuration'.
    3. Implementing pre-processing (validation, backups) and post-processing (service restarts, rollbacks) during updates.

  3. Overview of thin-edge.io security and authentication

    thin-edge.io utilizes X.509 certificates to authenticate peers across three primary communication paths:

    1. Gateway to Cloud: The MQTT connection is established over TLS. Certificates are used for mutual authentication (the cloud authenticates the device, and the device authenticates the cloud).
    2. Local MQTT Connections: Connections from child devices or local services to the local MQTT broker can be configured for TLS. In high-security settings, clients must authenticate themselves using certificates.
    3. Local HTTP Services: The File Transfer Service and Cumulocity Proxy can be configured to use HTTPS, with optional enforcement of certificate-based client authentication.

  4. Overview of thin-edge.io agent components

    The thin-edge.io agent implements device management operations (software, configuration, firmware management, restarts, remote console access, and log retrieval). In version 2.0.1, these features are split across multiple executables rather than a single binary.
    # Core agent and plugins
tedge-agent
c8y-firmware-plugin
c8y-remote-access-plugin

  5. Overview of thin-edge.io flow mapper architecture

    The thin-edge.io mapper allows users to extend built-in mapping rules (for Cumulocity, Azure, and AWS) using a pipeline of connectors, flows, and steps.

    • Connectors: Consume messages from sources (MQTT, files, background processes) and produce messages to sinks (MQTT, files).
    • Flows: Define a chain of transformation steps that process input messages into output messages.
    • Steps: Effect-free functions that transform one input message into zero, one, or more output messages. They focus on format conversion, filtering, and content extraction.
    • Context: A shared object passed to all steps to provide state and configuration. It is divided into three namespaces: context.mapper (shared by all flows), context.flow (private to a flow), and context.script (private to a script instance and persisted across reloads).

  6. Overview of tedge-agent configuration management

    The tedge-agent provides bi-directional configuration management for devices. It allows a device to act as a reference by uploading configuration snapshots to a tedge file transfer repository, or to receive configuration updates pushed from the repository to all devices of the same type.

    Key behaviors include:

    • Atomic Updates: Downloaded files are stored with a temporary name and renamed only after a successful download to prevent system corruption.
    • Permission Preservation: Unix user, group, and mode are preserved when copying downloaded files.
    • Notification: The agent publishes an operation status update to the local MQTT bus after a configuration update is downloaded. Device software should subscribe to these messages to trigger actions like restarting daemons.
    • Scope: The agent handles file transfer and atomic updates but is NOT responsible for validating file content or restarting processes.

  7. Overview of the thin-edge.io Agent

    The agent is a core component of thin-edge.io that enables edge device management (installing software, updating configurations, inspecting logs, and restarting devices) across diverse hardware and clouds. It abstracts the device location, operating system, file system, and hardware.

    Key architectural details:

    • Communication: Any service securely connected to the local MQTT bus can trigger or respond to commands.
    • Implementation: tedge-agent is the default implementation of the device management APIs and can run on both main and child devices. It can be replaced by custom components that implement the same APIs.
    • Protocols:
      • MQTT: Used to declare supported operations, trigger commands, and monitor progress.
      • HTTP: Used for transferring files between devices independently of their file systems.
    • Operation Workflows: The agent supports user-defined operation workflows to define the sequence of steps executed when an operation is triggered.

  8. Overview of tedge-mapper functionality

    The tedge-mapper translates messages from the cloud-agnostic thin-edge.io JSON format into cloud-specific formats. It subscribes to the reserved MQTT topic te/+/+/+/+/m/+ with QoS level 1. If a message is incorrectly formatted, the mapper publishes an error message to the te/errors topic with QoS level 1.

  9. Overview of thin-edge.io IoT development toolbox

    thin-edge.io is an open-source IoT development toolbox designed to simplify the creation of smart IoT agents. These agents act as gateways between IT cloud computing and OT industrial equipment, handling secure cloud connectivity, uniform asset monitoring/control, telemetry collection, local data processing, and remote device management.

  10. Overview of thin-edge.io software management plugins

    thin-edge.io uses plugins as facades for package managers to handle the installation, uninstallation, and querying of software modules. Plugins are executables that must follow a specific API. Multiple plugins can coexist on a device to handle different module types (e.g., one for apt and another for docker). The sm-agent invokes plugins based on the module type name specified in the cloud request.

  11. Overview of thin-edge Package Manager Plugins

    Thin-edge uses plugins as facades to delegate software management operations (installation, uninstallation, and queries) to specific package managers. Plugins are executables stored in /etc/tedge/sm-plugins. The filename of the plugin must match the software module type specified in the cloud request (e.g., a plugin named apt handles modules of type apt). Multiple plugins can coexist for the same package manager if they have different names to implement different policies.

  12. Overview of thin-edge.io Device Profiles

    A device profile is a collection of firmware, software, and configuration updates designed to bring a fleet of devices into a consistent, homogeneous state. Instead of managing multiple individual updates, a device profile groups them into a single operation, reducing monitoring overhead. The tedge-agent processes these operations sequentially. Note that no global rollback is performed on partial failures unless the specific subcommand for the failed module supports its own rollback.