From 502045346fc9f23116057c05b62b9bdce3065630 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Wed, 2 Mar 2022 14:01:06 +0000 Subject: [PATCH 1/8] Vision statement Signed-off-by: Didier Wenzek --- design/thin-edge-core.md | 50 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 design/thin-edge-core.md diff --git a/design/thin-edge-core.md b/design/thin-edge-core.md new file mode 100644 index 00000000000..72dff73048f --- /dev/null +++ b/design/thin-edge-core.md @@ -0,0 +1,50 @@ +# Thin-edge Core Vision + +A typical IoT application has to address: + +* __sophisticated business-cases__, with applications involving several vendors, actors and users; +* __very diverse integration needs__ over operating systems, protocols, data sources, processing tools, actuators, cloud end-points; +* __constraint environments__ with low-resources devices, large-scale deployments, high exposure to security risks, + prohibitive manual operations, long-term supports; +* __safety related requirements__ with devices operating machines in hazardous contexts. + +The forces behind these requirements are pushing in opposite directions. + +* On one side, from the use-case and integration perspective, one needs a dynamic and open setting with a large set of features that can be easily extended and combined. + [NodeRed](https://nodered.org/) is the archetype of such tools facilitating connections of components. +* On the other side, to meet resource and security constraints, one needs a minimal system specifically built for a task with cherry-picked components. + On the extreme side this leads to the idea of [unikernel](https://en.wikipedia.org/wiki/Unikernel) with sealed, single-purpose software images. + +Can these two poles be reconciled? + +The approach of thin-edge is to ease the development of IoT applications on edge devices with a smooth transition between: +* prototyping use-cases - when the aim is to easily onboard devices for IIoT, +* production use-cases - when the need is to deploy a hardened specific software on a large fleet of devices, +* as well as intermediate use-cases - when the application is build by several vendors with components written using different programming languages; + or when a manufacturer assembles his tools on the devices while letting open to his customers the option to add their own modules. + +To achieve this goal, the foundations of thin-edge address the hardened case first. +* The core of thin-edge and its components are written using the *Rust* programming languages. +* The set of components used by an application is defined at *build time*. +* These components cooperate using a streaming, asynchronous message passing, *internal* API. +* Connections to the outside are delegated to specific bridge components + that abstract the actual protocol (MQTT, HTTP, Modbus, OPC UA) + while making these external channels accessible to the other components. +* The *internal* messages exchanged by the components are *predefined* and cover the domain of telemetry and IoT + (measurements, events, alarms, operation requests, operation outcomes ...). + Messages sent to the outside are freely defined by the respective bridge components. +* The core of thin-edge provides the tools to configure the components as well as the internal message routes. +* An executable for an IoT application is statically defined by an assemblage of components and their configuration. + +To open this static core, thin-edge provides bridge components opening channels to external end-points and message buses. +* Notably, thin-edge provides an MQTT component to connect external processes + that are not necessarily part of the core, can be written using any programming languages + and can run on other devices. +* This MQTT bus works as an extension of the channels used internally by the core components. + For that purpose, the internal thin-edge messages are serialized over MQTT using the thin-edge JSON schema. +* On top of this MQTT bus, thin-edge provides plugins to connect specific application, + *e.g.* `collectd` or Apama. +* Most of the extensions of thin-edge will be provided by such bridge components: + * to handle specific south-bound protocols as Modbus or OPC UA, + * to trigger operations on the devices through a command line interface, + * and, last but not least, to connect to specific cloud end-point with mapper components. \ No newline at end of file From e3f58cf63a5618c8e95aa0795f2e4d39d180afdf Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Wed, 16 Mar 2022 17:30:00 +0000 Subject: [PATCH 2/8] Describe the two levels of plugins Signed-off-by: Didier Wenzek --- design/thin-edge-core.md | 149 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 148 insertions(+), 1 deletion(-) diff --git a/design/thin-edge-core.md b/design/thin-edge-core.md index 72dff73048f..0951c1a492a 100644 --- a/design/thin-edge-core.md +++ b/design/thin-edge-core.md @@ -47,4 +47,151 @@ To open this static core, thin-edge provides bridge components opening channels * Most of the extensions of thin-edge will be provided by such bridge components: * to handle specific south-bound protocols as Modbus or OPC UA, * to trigger operations on the devices through a command line interface, - * and, last but not least, to connect to specific cloud end-point with mapper components. \ No newline at end of file + * and, last but not least, to connect to specific cloud end-point with mapper components. + + +## Building an application with thin-edge + +A thin-edge IoT application is built using two kinds of building blocks: +* At the system level, an application is built as *a dynamic assemblage of unix processes* that exchange JSON messages over an MQTT bus. +* Internally, a thin-edge executable is built as *a static assemblage of rust plugins* that exchange Rust-typed messages over in-memory channels. + +Thin-edge is shipped with general purpose executables, mappers and agent, aimed to ease on-boarding +with support for Cumulocity, Azure, collectd, external software-management plugins, thin-edge json, etc. +By using these main executables, an IoT-application developer can easily connect his device to the cloud +and other local tools like `apt`, `collectd` or `apama`. + + +``` + # +┌────────────────┐ # ┌─────────────────┐ ┌─────────────────┐ +│ │ # │ │ │ │ +│ C8Y │ # │ Mapper │ │ Agent │ +│ │ # │ │ │ │ +│ │ # │ │ │ │ +│ │ # │ │ │ │ +│ │ # │ │ │ │ +│ │ # │ │ │ │ +└───────┬─▲──────┘ # └──────┬─▲────────┘ └──────▲─┬────────┘ + │ │ # │ │ │ │ + │ │ SmartRest # │ │ JSON,CSV,SmartRest │ │ JSON + │ │ # │ │ │ │ +┌───────▼─┴─────────────#─────────────▼─┴─────────────────────┴─▼────────────────┐ +│ MQTT # │ +│ # │ +└───────────────────────#─────────────▲───────────────────────▲──────────────────┘ + # │ │ + # │ CSV │ JSON + # │ │ + # ┌──────┴──────────┐ ┌─────┴──────────┐ + # │ │ │ │ + # │ Collectd │ │ Third-party │ + # │ │ │ │ + # │ │ │ │ + # │ │ │ │ + # │ │ │ │ + # │ │ │ │ + # └─────────────────┘ └────────────────┘ + # + # +``` + +If we zoom into a built-in thin-edge executable, then we have a different kind of components, Rust actors, +that exchange typed messages over in-memory channels. + +For instance, the generic mapper provides support for Cumulocity, Azure, collectd +and telemetry data (measurements, events, alarms) collected over MQTT using the thin-edge JSON format. + +``` +┌──────────────────────────────────────────────────────────┐ +│ │ +│ Generic Mapper │ +│ │ +│ │ +│ ┌─────────────────┐ │ +│ │ c8y plugin ├────► operations ──────┐ │ +│ │ │ │ │ +│ │ │ │ │ +│ │ ◄──┬─── telemetry ◄───┐ │ │ +│ └─▲─┬─────────────┘ │ ▲ │ │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ +│ │ │ ┌─────────────▼───┐ │ ┌───────┴─▼───────┐ │ +│ │ │ │ az plugin │ │ │ thin-edge JSON │ │ +│ │ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ +│ │ │ └──▲─┬────────────┘ │ └───────▲─┬───────┘ │ +│ │ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ +│ │ │ │ │ ┌────────┴────────┐ │ │ │ +│ │ │ │ │ │ collectd plugin │ │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ │ │ └────────▲────────┘ │ │ │ +│ │ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ +│ ┌─┴─▼─────┴─▼──────────────┴────────────┴─▼─────────┐ │ +│ │ MQTT Connection plugin │ │ +│ │ │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────┘ +``` + +The main motivation for this internal design is the ability to build specific executables that are smaller, +tuned for a specific use-case, consuming less memory and offering a reduced attack surface. + +For instance, note that the generic mapper provides support for several clouds, even if the device will connect to only one. +Note also that MQTT is used to send operations to the agent via JSON over MQTT. +An application developer can easily reassemble cherry-picked thin-edge plugins into a highly tuned executable. + +``` +┌───────────────────────────────────────────────────────────────┐ +│ │ +│ tuned mapper + agent │ +│ │ +│ ┌────────────────┐ ┌─────────────────┐ │ +│ │ │ │ │ │ +│ │ c8y plugin ├─► operations───► apt plugin │ │ +│ │ │ │ │ │ +│ │ │ │ │ │ +│ │ │ │ │ │ +│ └────▲─┬───▲─────┘ └─────────────────┘ │ +│ │ │ │ │ +│ │ │ │ ┌─────────────────┐ │ +│ │ │ │ │ │ │ +│ │ │ └────────telemetry ◄───┤ thin-edge JSON │ │ +│ │ │ │ │ │ +│ │ │ │ │ │ +│ │ │ │ │ │ +│ │ │ └───────▲─────────┘ │ +│ │ │ │ │ +│ │ │ │ │ +│ │ │ │ │ +│ ┌─────┴─▼──────────────────────────────────┴────────────┐ │ +│ │ │ │ +│ │ MQTT Connection plugin │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ └─────▲─┬──────────────────────────────────▲────────────┘ │ +│ │ │ │ │ +│ │ │ │ │ +└─────────┼─┼──────────────────────────────────┼────────────────┘ + │ │ │ + │ │ │ + │ │ │ + │ ▼ │ + + + C8y Sensors +``` + +The key points to be highlighted are that: +* To connect to thin-edge via MQTT, a component is not required to follow this design, not even to be written in Rust. +* The mapper and the agent provided by thin-edge out of the box can be used without any modifications. +* Building a tuned mapper or agent requires a Rust compiler but not a deep expertise in Rust. + What has to be done is mostly to list the plugins to be included and to connect message producers and consumers. \ No newline at end of file From 5e233203ad465176cadb57fbe2a513aac74947e1 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Wed, 29 Jun 2022 17:45:54 +0100 Subject: [PATCH 3/8] Make stronger and clearer the vision introduction Signed-off-by: Didier Wenzek --- design/thin-edge-core.md | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/design/thin-edge-core.md b/design/thin-edge-core.md index 0951c1a492a..f1c1da4267c 100644 --- a/design/thin-edge-core.md +++ b/design/thin-edge-core.md @@ -4,24 +4,31 @@ A typical IoT application has to address: * __sophisticated business-cases__, with applications involving several vendors, actors and users; * __very diverse integration needs__ over operating systems, protocols, data sources, processing tools, actuators, cloud end-points; -* __constraint environments__ with low-resources devices, large-scale deployments, high exposure to security risks, - prohibitive manual operations, long-term supports; -* __safety related requirements__ with devices operating machines in hazardous contexts. +* __constraint environments__ with low-resources devices, high exposure to security risks, prohibitive manual operations; +* __particular non-functional requirements__ safety of devices operating machines in hazardous contexts, + scalability over large fleet of devices, long-term supports of scattered devices. The forces behind these requirements are pushing in opposite directions. -* On one side, from the use-case and integration perspective, one needs a dynamic and open setting with a large set of features that can be easily extended and combined. +* On one side, to address the diversity of use-cases and integration requirements, one needs a large open set of features that can be easily extended and combined. [NodeRed](https://nodered.org/) is the archetype of such tools facilitating connections of components. * On the other side, to meet resource and security constraints, one needs a minimal system specifically built for a task with cherry-picked components. - On the extreme side this leads to the idea of [unikernel](https://en.wikipedia.org/wiki/Unikernel) with sealed, single-purpose software images. + On the extreme side, this leads to the idea of [unikernel](https://en.wikipedia.org/wiki/Unikernel) with sealed, single-purpose software images. -Can these two poles be reconciled? +What makes thin-edge unique is its approach to reconcile these two poles with two levels of building blocks. +* To maximize flexibility and interoperability, thin-edge provides the tools to build an agent from independent executables that interact over MQTT using JSON messages. +* To minimize resources and vulnerabilities, thin-edge features fine-grain Rust components as well as the rules to combine them into purpose-specific agents. +* To make feasible the assemblage of fine-grain and MQTT-based components into IIoT agents, + thin-edge comes with an extensible data model for IIoT - cloud connectivity, telemetry data, device management, child devices, ... - + and defines the rules to exchange related messages over MQTT as well as between fine-grain components and at the boundary between the internal and MQTT worlds. -The approach of thin-edge is to ease the development of IoT applications on edge devices with a smooth transition between: -* prototyping use-cases - when the aim is to easily onboard devices for IIoT, -* production use-cases - when the need is to deploy a hardened specific software on a large fleet of devices, -* as well as intermediate use-cases - when the application is build by several vendors with components written using different programming languages; - or when a manufacturer assembles his tools on the devices while letting open to his customers the option to add their own modules. +With this approach, thin-edge eases the development of IoT applications on edge devices with a smooth transition between: +* prototyping use-cases - when the need is to easily onboard devices for IIoT with batteries-included tools, +* production use-cases - when the need is to deploy a hardened specific software on a large fleet of devices, +* IIoT agent development - when the aim is to implement an application-specific agent that integrates tools and services provided by independent vendors. +* Hardware specific software - when a manufacturer assembles his tools on the devices while letting open to his customers the option to add their own modules. + +## Design Principles To achieve this goal, the foundations of thin-edge address the hardened case first. * The core of thin-edge and its components are written using the *Rust* programming languages. @@ -48,8 +55,7 @@ To open this static core, thin-edge provides bridge components opening channels * to handle specific south-bound protocols as Modbus or OPC UA, * to trigger operations on the devices through a command line interface, * and, last but not least, to connect to specific cloud end-point with mapper components. - - + ## Building an application with thin-edge A thin-edge IoT application is built using two kinds of building blocks: From a5648eebc3c3b0327e37a953ba291194062e91e8 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Tue, 4 Oct 2022 18:53:02 +0200 Subject: [PATCH 4/8] Make clearer the context behind thin-edge Signed-off-by: Didier Wenzek --- design/thin-edge-core.md | 62 +++++++++++++++++++++++++--------------- 1 file changed, 39 insertions(+), 23 deletions(-) diff --git a/design/thin-edge-core.md b/design/thin-edge-core.md index f1c1da4267c..57c01fd619f 100644 --- a/design/thin-edge-core.md +++ b/design/thin-edge-core.md @@ -1,33 +1,49 @@ -# Thin-edge Core Vision +# Thin-edge Design Principles +__Thin-edge makes it easy the integration of cloud services, edge computing and operational technologies, +with the foundations to develop business-specific IIoT gateways +from a catalog of generic and use-case specific components assembled +on top of a framework that enables connectivity and interoperability.__ + +With IIoT, there is a fantastic opportunity for innovative use-cases and business models +that are more reactive, flexible, and efficient. +However, the challenges are many and each require a different expertise. A typical IoT application has to address: -* __sophisticated business-cases__, with applications involving several vendors, actors and users; -* __very diverse integration needs__ over operating systems, protocols, data sources, processing tools, actuators, cloud end-points; -* __constraint environments__ with low-resources devices, high exposure to security risks, prohibitive manual operations; -* __particular non-functional requirements__ safety of devices operating machines in hazardous contexts, - scalability over large fleet of devices, long-term supports of scattered devices. +* __sophisticated business-cases__, with applications involving several vendors, actors and users + and combining connectivity, device management, telemetry, monitoring, analytics; +* __very diverse integration needs__ over operating systems, protocols, data sources, processing tools, + actuators, cloud end-points, legacy systems; +* __constraint environments__ with low-resources devices, high exposure to security risks, + prohibitive manual operations, restricted upgrades; +* __business-critical or even safety-critical requirements__ with large fleet of devices + operating in hazardous contexts and requesting long-term support. -The forces behind these requirements are pushing in opposite directions. +Furthermore, the forces behind these requirements are pushing in opposite directions. -* On one side, to address the diversity of use-cases and integration requirements, one needs a large open set of features that can be easily extended and combined. +* On one side, to address the diversity of use-cases and integration requirements, + one needs a large open set of features that can be easily extended and combined. [NodeRed](https://nodered.org/) is the archetype of such tools facilitating connections of components. -* On the other side, to meet resource and security constraints, one needs a minimal system specifically built for a task with cherry-picked components. - On the extreme side, this leads to the idea of [unikernel](https://en.wikipedia.org/wiki/Unikernel) with sealed, single-purpose software images. +* On the other side, to meet resource and security constraints, + one needs a minimal system specifically built for a task with cherry-picked components. + Taken to the extreme, this leads to the idea of [unikernel](https://en.wikipedia.org/wiki/Unikernel) + with sealed, single-purpose software images. + +What makes thin-edge unique is its approach to reconcile these two poles +with two levels of building blocks that combine along an IIoT specific API. +* To maximize flexibility and interoperability, + thin-edge provides the tools to build an agent from independent executables + that interact over MQTT and HTTP using JSON messages. +* To minimize resources and vulnerabilities, + thin-edge features fine-grain Rust components + as well as the rules to combine them into hardened executables. +* To ease incremental developments, + thin-edge give the developers the freedom to combine both MQTT and Rust-based components + into purpose-specific gateways. +* To make feasible the interoperability of components provided by different tiers, + thin-edge comes with an extensible data model for IIoT - + cloud connectivity, telemetry data, device management, child devices, ... -What makes thin-edge unique is its approach to reconcile these two poles with two levels of building blocks. -* To maximize flexibility and interoperability, thin-edge provides the tools to build an agent from independent executables that interact over MQTT using JSON messages. -* To minimize resources and vulnerabilities, thin-edge features fine-grain Rust components as well as the rules to combine them into purpose-specific agents. -* To make feasible the assemblage of fine-grain and MQTT-based components into IIoT agents, - thin-edge comes with an extensible data model for IIoT - cloud connectivity, telemetry data, device management, child devices, ... - - and defines the rules to exchange related messages over MQTT as well as between fine-grain components and at the boundary between the internal and MQTT worlds. - -With this approach, thin-edge eases the development of IoT applications on edge devices with a smooth transition between: -* prototyping use-cases - when the need is to easily onboard devices for IIoT with batteries-included tools, -* production use-cases - when the need is to deploy a hardened specific software on a large fleet of devices, -* IIoT agent development - when the aim is to implement an application-specific agent that integrates tools and services provided by independent vendors. -* Hardware specific software - when a manufacturer assembles his tools on the devices while letting open to his customers the option to add their own modules. - ## Design Principles To achieve this goal, the foundations of thin-edge address the hardened case first. From 431b62b60bd2722ed02d3c295b635e7cec987cc5 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Wed, 12 Oct 2022 15:14:59 +0200 Subject: [PATCH 5/8] Improve *design principles* description Signed-off-by: Didier Wenzek --- design/thin-edge-core.md | 66 ++++++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 26 deletions(-) diff --git a/design/thin-edge-core.md b/design/thin-edge-core.md index 57c01fd619f..492c319a461 100644 --- a/design/thin-edge-core.md +++ b/design/thin-edge-core.md @@ -43,34 +43,48 @@ with two levels of building blocks that combine along an IIoT specific API. * To make feasible the interoperability of components provided by different tiers, thin-edge comes with an extensible data model for IIoT - cloud connectivity, telemetry data, device management, child devices, ... - + ## Design Principles -To achieve this goal, the foundations of thin-edge address the hardened case first. -* The core of thin-edge and its components are written using the *Rust* programming languages. -* The set of components used by an application is defined at *build time*. -* These components cooperate using a streaming, asynchronous message passing, *internal* API. -* Connections to the outside are delegated to specific bridge components - that abstract the actual protocol (MQTT, HTTP, Modbus, OPC UA) - while making these external channels accessible to the other components. -* The *internal* messages exchanged by the components are *predefined* and cover the domain of telemetry and IoT - (measurements, events, alarms, operation requests, operation outcomes ...). - Messages sent to the outside are freely defined by the respective bridge components. -* The core of thin-edge provides the tools to configure the components as well as the internal message routes. -* An executable for an IoT application is statically defined by an assemblage of components and their configuration. - -To open this static core, thin-edge provides bridge components opening channels to external end-points and message buses. -* Notably, thin-edge provides an MQTT component to connect external processes - that are not necessarily part of the core, can be written using any programming languages - and can run on other devices. -* This MQTT bus works as an extension of the channels used internally by the core components. - For that purpose, the internal thin-edge messages are serialized over MQTT using the thin-edge JSON schema. -* On top of this MQTT bus, thin-edge provides plugins to connect specific application, - *e.g.* `collectd` or Apama. -* Most of the extensions of thin-edge will be provided by such bridge components: - * to handle specific south-bound protocols as Modbus or OPC UA, - * to trigger operations on the devices through a command line interface, - * and, last but not least, to connect to specific cloud end-point with mapper components. +* Thin-edge provides the tools to develop an IIoT gateway by assembling components + that have been implemented independently, + possibly by different vendors and using different programming languages. +* There are two levels of components: + * MQTT-based components that are processes running on the device and the local network + and interacting over MQTT and HTTP using JSON messages. + * Rust-based components that are actors running inside a process + and interacting over in-memory channels using statically typed messages. +* These two levels of components serve different purposes and users: + * The Rust-based components and their assemblage are designed for robustness. + They follow strict combination rules enforced at compile time, + notably with compatibility checks between message consumers and producers. + These components provide the building blocks: + * connections to IoT cloud end-points, + * connections to various protocols (MQTT, HTTP, Modbus, OPC UA, ...), + * interactions with the operating systems (files, commands, software updates, ...), + * making sense of telemetry data (measurements, events, alarms, set points). + * The MQTT-based components bring the flexibility to interact + with external systems running on a different device or inside a container + and without enforcing a programming language or an operating system. + These components also provide the flexibility to experiment + and to add missing features without having to implement a full-fledged Rust component. +* To enable interactions between the MQTT-components, thin-edge provides an MQTT bus made of: + * a local MQTT server, + * an MQTT bridge that relays messages between the gateway and the cloud end-points, + * an MQTT API that defines topics and message payloads + * to exchange telemetry data, + * to monitor components health, + * to trigger operations and monitor progress, + * a local HTTP server for operations where a REST API is more adapted than a Pub/Sub protocol. +* In practice, the software for an IIoT agent is build using a combination of MQTT and Rust components. + * Thin-edge itself is released as an MQTT-based component built from Rust-based components. + * A batteries included thin-edge executable is available to let the users experiment + with all the available building-blocks. + * An application-specific thin-edge can be built by cherry-picking building blocks + and adding custom blocks for the business logic. + * Along the main thin-edge executable, are deployed MQTT-based components over the local network, + on external devices, controllers, PLCs, containers ... or even on the gateway + connecting all the data sources, actuators, and data processors that make the application on the edge. ## Building an application with thin-edge From 96fe93cce56f3de0b34ec4420d781d6f224c9c12 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Fri, 14 Oct 2022 19:44:54 +0200 Subject: [PATCH 6/8] Clarify the two levels of components. - Use the term *actor* instead of *plugin*. - Stress the role of the thin-edge JSON actor. Signed-off-by: Didier Wenzek --- design/thin-edge-core.md | 107 ++++++++++++++++++++++++--------------- 1 file changed, 67 insertions(+), 40 deletions(-) diff --git a/design/thin-edge-core.md b/design/thin-edge-core.md index 492c319a461..a2f41d92973 100644 --- a/design/thin-edge-core.md +++ b/design/thin-edge-core.md @@ -88,31 +88,31 @@ with two levels of building blocks that combine along an IIoT specific API. ## Building an application with thin-edge -A thin-edge IoT application is built using two kinds of building blocks: -* At the system level, an application is built as *a dynamic assemblage of unix processes* that exchange JSON messages over an MQTT bus. -* Internally, a thin-edge executable is built as *a static assemblage of rust plugins* that exchange Rust-typed messages over in-memory channels. - -Thin-edge is shipped with general purpose executables, mappers and agent, aimed to ease on-boarding -with support for Cumulocity, Azure, collectd, external software-management plugins, thin-edge json, etc. -By using these main executables, an IoT-application developer can easily connect his device to the cloud -and other local tools like `apt`, `collectd` or `apama`. - +Thin-edge is shipped with a batteries-included executable, the `tedge` command, that eases on-boarding +with support for various IoT clouds, monitoring tools, software-management plugins, OT protocols ... +On top of `tedge`, an IoT-application developer can easily build a purpose-specific IoT gateway +to connect his devices to the cloud and local resources. +This IoT gateway is made of independent processes that interact over MQTT using JSON messages, +and that are deployed over the devices on the edge as well as the OT network. +The IoT-application developer can implement and deploy his own components, +using his programming language of choice, +and leveraging the thin-edge MQTT API to interact with the components of the gateway. ``` # ┌────────────────┐ # ┌─────────────────┐ ┌─────────────────┐ │ │ # │ │ │ │ -│ C8Y │ # │ Mapper │ │ Agent │ +│ C8Y │ # │ tedge ├────►│ apt │ │ │ # │ │ │ │ │ │ # │ │ │ │ │ │ # │ │ │ │ │ │ # │ │ │ │ │ │ # │ │ │ │ -└───────┬─▲──────┘ # └──────┬─▲────────┘ └──────▲─┬────────┘ - │ │ # │ │ │ │ - │ │ SmartRest # │ │ JSON,CSV,SmartRest │ │ JSON - │ │ # │ │ │ │ -┌───────▼─┴─────────────#─────────────▼─┴─────────────────────┴─▼────────────────┐ +└───────┬─▲──────┘ # └──────┬─▲────────┘ └─────────────────┘ + │ │ # │ │ + │ │ SmartRest # │ │ JSON,CSV,SmartRest + │ │ # │ │ +┌───────▼─┴─────────────#─────────────▼─┴────────────────────────────────────────┐ │ MQTT # │ │ # │ └───────────────────────#─────────────▲───────────────────────▲──────────────────┘ @@ -121,10 +121,10 @@ and other local tools like `apt`, `collectd` or `apama`. # │ │ # ┌──────┴──────────┐ ┌─────┴──────────┐ # │ │ │ │ - # │ Collectd │ │ Third-party │ - # │ │ │ │ - # │ │ │ │ - # │ │ │ │ + # │ Collectd │ │ OT device │ + # │ │ │ - IPC │ + # │ │ │ - PLC │ + # │ │ │ - μ controller │ # │ │ │ │ # │ │ │ │ # └─────────────────┘ └────────────────┘ @@ -132,20 +132,46 @@ and other local tools like `apt`, `collectd` or `apama`. # ``` -If we zoom into a built-in thin-edge executable, then we have a different kind of components, Rust actors, -that exchange typed messages over in-memory channels. +This design provides the flexibility to interact with various sub-systems on the edge, +to experiment easily and to address application specific needs. +However, this also lead to a system that is too heavy and more fragile than expected for most use cases, +with unused features embarked by the batteries-included `tedge`, +and numerous independent components to operate consistently. + +Hence, the need for fine-grain components. These are provided as rust components. +Internally, a thin-edge executable is built as *a static assemblage of rust actors* +that exchange statically-typed messages over in-memory channels. -For instance, the generic mapper provides support for Cumulocity, Azure, collectd -and telemetry data (measurements, events, alarms) collected over MQTT using the thin-edge JSON format. +Each actor provides a very specific feature that most of the time doesn't make sense in isolation, +but only in combination with the other actors. For instance, +* The `collectd` actor role is to translate messages received from `collectd` + into `Measurement` Rust values that can be then consumed by any other actor + that accepts this type of data, as the `c8y` actor does. +* Similarly, the `c8y` actor acts as a translator between Cumulocity IoT and the other actors. + It consumes `Measurement` Rust values and translates them into `MQTTMessage` for Cumulocity IoT. + In the reverse direction, the `c8y` actor consumes `MQTTMessage` from Cumulocity IoT, + and produces `Operations` encoded as Rust values and ready to be consumed by other actors. +* The `az` actor has a similar role, except that the translations are done for Azure IoT. +* Neither the `collectd` actor nor the `c8y` actor have to handle an MQTT connection. + They simply produce and consume, in-memory representations for `MQTTMessage` + that are sent over the wire by the `MQTT` actor, accordingly to the MQTT protocol. +* Connected to each others in a batteries-included `tedge` executable, + these actors provide support for Cumulocity, Azure, collectd + and telemetry data (measurements, events, alarms). +* Among all the actor, one play a key role. This is the `thin-edge JSON` actor. + This actor materializes the thin-edge MQTT API, + defining topics and message payloads that are exchanged by the MQTT-bases components, + and translating these messages into Rust-values ready to be consumed by the other actors. + The `thin-edge JSON` actor is the interface between the two levels of thin-edge components. ``` ┌──────────────────────────────────────────────────────────┐ │ │ -│ Generic Mapper │ +│ batteries-included `tedge` │ │ │ │ │ │ ┌─────────────────┐ │ -│ │ c8y plugin ├────► operations ──────┐ │ +│ │ c8y actor ├────► operations ──────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ ◄──┬─── telemetry ◄───┐ │ │ @@ -153,15 +179,15 @@ and telemetry data (measurements, events, alarms) collected over MQTT using the │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────▼───┐ │ ┌───────┴─▼───────┐ │ -│ │ │ │ az plugin │ │ │ thin-edge JSON │ │ -│ │ │ │ │ │ │ │ │ +│ │ │ │ az actor │ │ │ thin-edge JSON │ │ +│ │ │ │ │ │ │ actor │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └──▲─┬────────────┘ │ └───────▲─┬───────┘ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌────────┴────────┐ │ │ │ -│ │ │ │ │ │ collectd plugin │ │ │ │ +│ │ │ │ │ │ collectd actor │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ @@ -169,7 +195,7 @@ and telemetry data (measurements, events, alarms) collected over MQTT using the │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌─┴─▼─────┴─▼──────────────┴────────────┴─▼─────────┐ │ -│ │ MQTT Connection plugin │ │ +│ │ MQTT Connection actor │ │ │ │ │ │ │ │ │ │ │ └───────────────────────────────────────────────────┘ │ @@ -180,18 +206,18 @@ and telemetry data (measurements, events, alarms) collected over MQTT using the The main motivation for this internal design is the ability to build specific executables that are smaller, tuned for a specific use-case, consuming less memory and offering a reduced attack surface. -For instance, note that the generic mapper provides support for several clouds, even if the device will connect to only one. -Note also that MQTT is used to send operations to the agent via JSON over MQTT. -An application developer can easily reassemble cherry-picked thin-edge plugins into a highly tuned executable. +An application developer can easily reassemble cherry-picked thin-edge actors into a highly tuned executable, +keeping only the feature actually required on the IIoT gateways, +and possibly adding Rust actors that have been implemented specification for his application. ``` ┌───────────────────────────────────────────────────────────────┐ │ │ -│ tuned mapper + agent │ +│ tuned `tedge` │ │ │ │ ┌────────────────┐ ┌─────────────────┐ │ │ │ │ │ │ │ -│ │ c8y plugin ├─► operations───► apt plugin │ │ +│ │ c8y actor ├─► operations───► apt actor │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ @@ -200,7 +226,7 @@ An application developer can easily reassemble cherry-picked thin-edge plugins i │ │ │ │ ┌─────────────────┐ │ │ │ │ │ │ │ │ │ │ │ └────────telemetry ◄───┤ thin-edge JSON │ │ -│ │ │ │ │ │ +│ │ │ │ actor │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └───────▲─────────┘ │ @@ -209,7 +235,7 @@ An application developer can easily reassemble cherry-picked thin-edge plugins i │ │ │ │ │ │ ┌─────┴─▼──────────────────────────────────┴────────────┐ │ │ │ │ │ -│ │ MQTT Connection plugin │ │ +│ │ MQTT Connection actor │ │ │ │ │ │ │ │ │ │ │ │ │ │ @@ -227,7 +253,8 @@ An application developer can easily reassemble cherry-picked thin-edge plugins i ``` The key points to be highlighted are that: -* To connect to thin-edge via MQTT, a component is not required to follow this design, not even to be written in Rust. -* The mapper and the agent provided by thin-edge out of the box can be used without any modifications. -* Building a tuned mapper or agent requires a Rust compiler but not a deep expertise in Rust. - What has to be done is mostly to list the plugins to be included and to connect message producers and consumers. \ No newline at end of file +* An MQTT-bases component is not required to follow this design, not even to be written in Rust. +* The executables provided by thin-edge out of the box are MQTT-based components, + built as an assemblage of Rust actors. They can be used without any modifications. +* Building a tuned thin-edge executable requires a Rust compiler but not a deep expertise in Rust. + What has to be done is mostly to list the actors to be included and to connect message producers and consumers. \ No newline at end of file From f21fdbaaee2207ed90e5d829eaefaeef9976a820 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Tue, 25 Oct 2022 15:45:19 +0200 Subject: [PATCH 7/8] Add a pros/cons table comparison between component kinds Signed-off-by: Didier Wenzek --- design/thin-edge-core.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/design/thin-edge-core.md b/design/thin-edge-core.md index a2f41d92973..e054383b6d8 100644 --- a/design/thin-edge-core.md +++ b/design/thin-edge-core.md @@ -257,4 +257,22 @@ The key points to be highlighted are that: * The executables provided by thin-edge out of the box are MQTT-based components, built as an assemblage of Rust actors. They can be used without any modifications. * Building a tuned thin-edge executable requires a Rust compiler but not a deep expertise in Rust. - What has to be done is mostly to list the actors to be included and to connect message producers and consumers. \ No newline at end of file + What has to be done is mostly to list the actors to be included and to connect message producers and consumers. + +## What kind of component for my use case? + +What are the pros & cons of Rust-based and MQTT-based components? +When use one or the other? + +| MQTT-based thin-edge executable | Rust-based thin-edge actor | +|--------------------------------------------------------------------------------|-------------------------------------------------------------------------| +| Coarse grain component used to build IIoT agents | Fine grain component used to build MQTT-based thin-edge executables | +| Process running on the local network | Actor running inside a process | +| Interact over MQTT and HTTP using JSON messages | Interact over in-memory channels using statically typed messages | +| Can be written in any language | Must be written in Rust | +| Deployed over hosts and containers on the edge local network | Integrated into an executable in combination with other actors | +| Required to enable interactions over several devices and cloud end-points | Leverage a thin-edge-json actor to interact with MQTT-based executables | +| Facilitate prototyping and interactivity | Build for robustness and frugality | +| Might lead to a resource greedy agent with too many daemon processes | Help to optimize resource utilisation within a single process | +| Might lead to deployment and dependency issues with loosely-coupled components | Dependencies and compatibilities are checked at compile-time | +| The `tedge` command is an MQTT-based executable | The `tedge` command is an assemblage of Rust-based thin-edge actors | From 588a631c01aec88f7d0ba9b927cfb4c290745922 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Fri, 4 Nov 2022 14:54:29 +0100 Subject: [PATCH 8/8] Use the word "agent" instead of "gateway" Signed-off-by: Didier Wenzek --- design/thin-edge-core.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/design/thin-edge-core.md b/design/thin-edge-core.md index e054383b6d8..7ce5e8e4211 100644 --- a/design/thin-edge-core.md +++ b/design/thin-edge-core.md @@ -1,7 +1,7 @@ # Thin-edge Design Principles __Thin-edge makes it easy the integration of cloud services, edge computing and operational technologies, -with the foundations to develop business-specific IIoT gateways +with the foundations to develop business-specific IIoT agents from a catalog of generic and use-case specific components assembled on top of a framework that enables connectivity and interoperability.__ @@ -39,14 +39,14 @@ with two levels of building blocks that combine along an IIoT specific API. as well as the rules to combine them into hardened executables. * To ease incremental developments, thin-edge give the developers the freedom to combine both MQTT and Rust-based components - into purpose-specific gateways. + into purpose-specific agents. * To make feasible the interoperability of components provided by different tiers, thin-edge comes with an extensible data model for IIoT - cloud connectivity, telemetry data, device management, child devices, ... ## Design Principles -* Thin-edge provides the tools to develop an IIoT gateway by assembling components +* Thin-edge provides the tools to develop an IIoT agent by assembling components that have been implemented independently, possibly by different vendors and using different programming languages. * There are two levels of components: @@ -70,7 +70,7 @@ with two levels of building blocks that combine along an IIoT specific API. and to add missing features without having to implement a full-fledged Rust component. * To enable interactions between the MQTT-components, thin-edge provides an MQTT bus made of: * a local MQTT server, - * an MQTT bridge that relays messages between the gateway and the cloud end-points, + * an MQTT bridge that relays messages between the agent and the cloud end-points, * an MQTT API that defines topics and message payloads * to exchange telemetry data, * to monitor components health, @@ -90,13 +90,13 @@ with two levels of building blocks that combine along an IIoT specific API. Thin-edge is shipped with a batteries-included executable, the `tedge` command, that eases on-boarding with support for various IoT clouds, monitoring tools, software-management plugins, OT protocols ... -On top of `tedge`, an IoT-application developer can easily build a purpose-specific IoT gateway +On top of `tedge`, an IoT-application developer can easily build a purpose-specific IIoT agent to connect his devices to the cloud and local resources. -This IoT gateway is made of independent processes that interact over MQTT using JSON messages, +This IIoT agent is made of independent processes that interact over MQTT using JSON messages, and that are deployed over the devices on the edge as well as the OT network. The IoT-application developer can implement and deploy his own components, using his programming language of choice, -and leveraging the thin-edge MQTT API to interact with the components of the gateway. +and leveraging the thin-edge MQTT API to interact with the components of the agent. ``` # @@ -207,7 +207,7 @@ The main motivation for this internal design is the ability to build specific ex tuned for a specific use-case, consuming less memory and offering a reduced attack surface. An application developer can easily reassemble cherry-picked thin-edge actors into a highly tuned executable, -keeping only the feature actually required on the IIoT gateways, +keeping only the feature actually required on the IIoT agents, and possibly adding Rust actors that have been implemented specification for his application. ```