Table of contents:

Introduction

A system is a group of inter-connected modules which can be updated via a special module i.e., a gateway. A system has a unique Id and is created on the basis of a System Report. If the constellation of modules changes, the system identification algorithm decides whether the existing system is updated, or marked as out-dated and a new system is created. Modules are represented as targets in the IoT Rollouts service.

System report and identification

Introduction

A system report contains information about all modules within the system including its gateway. Typically, the gateway sends a system report to the Install API to notify it about the system it is connected to. Based on the received system report

a corresponding digital twin of that system is created (if the system is still unknown) or
the existing digital twin of that system is updated

Furthermore, for each reported module, part of the system, a corresponding target in Bosch IoT Rollouts is created.

System report format

On the Install API level, the modules of a system are listed in the values array of the JSON-based report (see codeblock below). Each value entry is a JSON object which declares the properties of the respective module.

All reported properties of a module are stored along with the corresponding target in Bosch IoT Rollouts. That way you can use target filter queries to select modules based on their properties.

Furthermore, the properties of a module can be used to assemble the module match definitions which are specified in a recipe.

The following listing outlines a sample system report.

{
  "timestamp": "1684201667",
  // Module ID of gateway module 
  "gatewayId": "123456789",
  "values": [
    {
      // Module type, i.e. target type
      "type": "42",
 
      // Module ID, i.e. controller/target Id
      "id": "123456789",
 
 	  // list of additional key-value pairs stored as controller attributes
	  "key1": "value1"
    },
    {
       "type": "4711",
	   "key": "987654321"
	}
  ]
}

Constraints

Both, property keys and values, need to be of type "String".
Mandatory properties:
- One of the properties needs to specify the unique module ID also used as a target ID in Bosch IoT Rollouts.
- One of the properties needs to specify the module type and map to a target type in IoT Rollouts.
  
  Both property keys are configurable per subscription.
For properties representing version information it is required to use a property key with a -Version suffix (e.g. hardwareVersion). This naming convention enables the SOUP service to apply natural sort ordering when it comes to comparing version numbers.

System identification

When a system report is uploaded via the Install API, the module information it contains is the bases for the system identification process.This process involves (re-)identifying the system based on the provided module details (i.e., module ID and type). Based on the module type, a module belongs to on of the following classes:

Primary modules: 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 modules: 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 outdated.
Removable modules: 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.

images/confluence/download/attachments/3585029173/soup_sys_ident_samples-version-2-modificationdate-1700062635000-api-v2.png

Update report and status

Introduction

The update report serves as a comprehensive record of a successfully completed system update process, carried out by applying a recipe. Typically, this report is transmitted from the system's gateway to the Install API, serving as a notification of the completed update. The update report is utilized to monitor the overall system update status, as well as the update status of the individual modules. For each module updates, the corresponding deployment actions within Bosch IoT Rollouts are generated, leveraging the Action state machine. This functionality enables module responsibles to easily trace the update history of the system's constituent modules.

Update report format

The update report encompasses crucial details, including:

ID of the applied recipe
ID of the gateway
Overall status, denoted as either SUCCESS or ERROR, accompanied by system-level logs

Furthermore, for each executed module update, the report provides a module-specific breakdown, featuring:

ID of the updated module
ID of the installed distribution set
Status of the module update, such as SUCCESS, ERROR, or CANCELED (cf. Action state machine)
Module-level logs

This comprehensive information within the update report ensures a thorough understanding of the applied recipe, gateway details, system status, and individual module updates, facilitating effective troubleshooting and analysis.

{
  "timestamp": "1713854668",
  "recipeId": "TVteq1hJRO",
  "gatewayId": "35-AD-8C-2C-78-D5",
  "status": "SUCCESS",
  "statusCode": "200",
  "logs": [
    {
      "message": "string",
      "timestamp": "1713854678607"
    }
  ],
  "values": [
    {
      "moduleId": "35-AD-8C-2C-78-D5",
      "distributionSetId": "269084",
      "status": "SUCCESS",
      "statusCode": "200",
      "timestamp": "1713854692",
      "log": [
        {
          "message": "Switched bootloader mode",
          "timestampMs": "1713854692607"
        },
        {
          "message": "Installed firmware",
          "timestampMs": "1713854692608"
        }
      ]
    },
    {
      "moduleId": "35-AD-8C-60-8A-C2",
      "distributionSetId": "272564",
      "status": "SUCCESS",
      "statusCode": "200",
      "timestamp": "1713854692",
      "log": [
        {
          "message": "Module update started",
          "timestampMs": "1713854692607"
        },
        {
          "message": "Module updated finished",
          "timestampMs": "1713854692608"
        }
      ]
    }
  ]
}

Defined system update statuses

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

images/confluence/download/attachments/4031680507/system-update-status-version-1-modificationdate-1710417316000-api-v2.png

System action statuses

Icon	Status	Description
	SUCCESS	The system update was successful, i.e. the software updates on all (update-relevant) modules being part of the system were successful.
	ERROR	The system update failed, since there was at least one failing module software update.