SOUP System and module
Table of contents:
Introduction
SOUP tracks and manages systems composed of interconnected modules. These systems are dynamically created or updated based on system reports you provide. Updatable modules are represented as targets within the IoT Rollouts service, allowing efficient updates and management. The following image provides a high-level overview of the system and module identification and provisioning within SOUP and IoT Rollouts.
Understanding modules
A module is the basic building block of a system in SOUP. Each module is defined by the following attributes:
ID: SOUP generated ID for reference within the UI and API.
Reported ID: Module reported unique identifier within your tenant. This is typically a serial number. For non-updatable modules a secondary ID can be added for further disambiguation if the primary ID is insufficient . All modules within a tenant must have a unique reported ID (primary or primary+secondary). Updatable modules must have a unique primary ID amongst other updatable modules, as their reported ID is used as the target`s controller ID.
Type: Categorizes the module (e.g., sensor, actuator, controller). This is crucial for compatibility checks with distribution sets (see Type compatibility) and role-based access control for updatable modules.
Name: A human-readable name for the module.
Properties: Key-value pairs providing additional module information. For updatable modules, these properties are also stored as target attributes in IoT Rollouts (see Entity definitions). If a property key contains a version string, configure it using soup.systemreport.version.property.names in your tenant configuration to ensure correct version comparison. See the SOUP Tenant configuration section for more details.
Module updatability and roles
Modules are categorized as either updatable or non-updatable and do have a specific roles assigned, to determine how they influence system identification and updates. Module updatability and roles can be configured, with the soup.module.identification setting in the tenant configuration (see SOUP Tenant configuration).
Updatable vs. non-updatable modules
By default, all modules are considered updatable and are represented as 
targets in IoT Rollouts. Marking a module as non-updatable prevents target creation, saving resources but limiting features like target filtering, distribution set assignment, update history, and role-based access control via target type.
Module roles
Each module is assigned one of the following roles:
|
Icon |
Role |
Description |
|
|
Primary |
These modules represent the primary functions of a system. Any changes made to primary modules, such as removal, replacement, or addition, result in a different system configuration with a new system identifier. |
|
|
Default |
Also known as optional or standard modules, these modules represent additional system functions that can be removed or replaced. While default modules do not directly contribute to system identification, they are considered when tracking the evolution of a system. For instance, if a default module is removed from one system (i.e. a new system report does not include it, or it is included in the system report of another system), the system configuration that previously included the module is marked as |
|
|
Removable |
Also known as transient modules, these modules are neither taken into account for system identification nor determining system obsolescence. They do not impact the system's identification or evolution tracking processes. |
|
|
Tracked |
Non-updatable modules that are not used for system identification or matching but are still tracked in SOUP. |
|
|
Ignored |
Modules that are completely ignored by SOUP. |
outdated. 
Configuration overview
The table below highlights the different configuration options for a module and the resulting effect on:
Module: A module is managed in SOUP.
Match: The module is considered for identifying a matching recipe (see SOUP Recipe).
Identification: The module is considered for identifying the system, its evolution, or obsolescence.
Target: An update target is managed in IoT Rollouts.
|
Role |
Updatable |
Module |
Match |
Identification |
Target |
|
Ignored |
N/A |
|
|
|
|
|
Tracked |
N/A |
|
|
|
|
|
Removable |
No |
|
|
|
|
|
Default |
No |
|
|
|
|
|
Primary |
No |
|
|
|
|
|
Removable |
Yes |
|
|
|
|
|
Default |
Yes |
|
|
|
|
|
Primary |
Yes |
|
|
|
|
1 Only, if no
Primary modules are present in the system.
Updating the configuration is possible and will take effect once a new system report is processed. The following consequences apply:
Changing from updatable to non-updatable:
If a secondary ID is present for the non-updatable, it will become a new module, and the previous module will be orphaned.
Therefore, the target in IoT Rollouts may continue to exist.
Changing from non-updatable to updatable is only possible, if the primary ID is unique:
If a secondary ID is present, it will get removed and it will become a new module, and the previous module will be orphaned.
A new target is provisioned in IoT Rollouts.
Understanding systems
A system is identified by a set of modules, which are taken into account to find matching system updates (i.e. SOUP Recipe). Each system is defined by the following attributes:
ID: SOUP generated ID for reference within the UI and API, based on the system identification algorithm (see System identification).
Update status: Reflects the current status of the system state machine (see System update statuses).
Matching recipes: Matching RELEASE and RELEASE_CANDIDATE recipe as a Result of the recipe match algorithm (see SOUP Recipe).
Assigned recipe: Name and version of the recipe that is currently assigned to the system.
Installed recipe: Name and version of the recipe that is currently installed on the system.
Actions: Link to the update history of the system (see SOUP System actions).
Last reported gateway: Reported ID of the gateway module providing the system report.
Modules: List of modules contained in the system (see Understanding modules).
System identification
SOUP identifies systems based on system reports sent to the Install API. A system report describes the modules comprising a system. When a system report is received:
If the system is new, a corresponding digital twin (i.e. system and modules) is created.
If the system already exists, its digital twin is updated.
For each reported updatable module, a corresponding target is created in IoT Rollouts.
System (re-)identification logic considers module roles (
Default or
Primary) and updatability settings. See the System Identification Examples section below for detailed scenarios and how SOUP handles different changes to system composition.
System identification examples
System report includes new default module (without primary modules)
The system is identified based on default modules, as there are no primary modules available, therefore the system ID changes.
System report includes new default module (with primary modules)
The system is identified based on the primary modules, therefore, the system ID is the same and the new default module is added.
System report includes new primary module
As the primary modules changed, the report results in a new system ID that is created.
System report includes default module from another system
A default module is reported as part of another system report. This marks the previous system as outdated, as it obviously changed, without notifying the backend about its latest state.
System report for an outdated system
The outdated state of a system can be reverted when a new system report is transmitted to update the state of the modules, as long as there are primary modules and they are still the same.
System report includes a removable module from another system
A removable module is reported as part of another system report. As removable modules are not taken into consideration for the system identification, the module is moved from system 1 to system 2 without marking it outdated.
System update statuses
The system update status provides information about the current state of a system's update process or the result of the last completed update (see SOUP System actions). This status helps you understand whether a system is actively being updated, has been successfully updated, or encountered any issues during the process. It could be referred to as the Below is the list of the possible system update statuses and the corresponding state machine:
System update status definition
|
Icon |
Status |
Description |
|
|
REGISTERED |
The system is registered with the service but no recipe is assigned. |
|
|
PENDING |
Installation of the assigned recipe is not yet confirmed. |
|
|
IN SYNC |
The assigned recipe is installed. |
|
|
ERROR |
The installation of the assigned recipe failed. |
System update status transitions
