SOUP Recipe file
Table of contents:
Introduction
The install representation of a recipe, also known as recipe file, is specifically designed to optimize the execution of system updates through a system update handler, typically operating within a gateway. This representation is derived from the management representation and subsequently enhanced with essential information required by the system update handler. While, for example, the management representation of a recipe solely references distribution sets, the recipe file provides comprehensive details about the individual artifacts contained within these distribution sets. This includes information such as byte size, hashes, and download information. The recipe file is generated, when promoting the recipe from DRAFT stage to WAITING_FOR_SIGNATURE.
Default recipe file format
By default, the recipe adheres to a SWupdate-compatible format (sw-description.json), augmented with custom attributes. However, it is important to note that the install representation can be customized to meet specific customer requirements, ensuring flexibility and adaptability. Properties starting with an _ (e.g. _noImage) are ignored by SWupdate.
The recipe file format is configurable per subscription (see soup.recipe.template in SOUP Tenant configuration).
|
Key |
Source |
Comment |
|
_recipe.id |
Recipe Id |
|
|
_recipe.schema-version |
Template |
Hard-coded version of the current template. If the template is changed later on, the version should be adapted as well. |
|
_recipe.name |
Recipe name |
|
|
_recipe.description |
Recipe description |
|
|
_recipe.published |
Recipe published dated |
Date is set, when the recipe is promoted from draft to release candidate |
|
software.version |
Recipe version |
|
|
software.scripts |
refer to scripts |
The scripts section contains all artifacts within software modules within a distribution set of type "scripts" referenced as System distribution set Functional System-level scripts that are executed by the SWUpdate application on the gateway (e.g. example.lua). |
|
software.images |
refer to images |
The images section contains all modules of the Module update definitions with a distribution set reference. Functional Modules that are updated in the scope of the system update including their cardinality, and the software that is to be installed on them. |
|
software._noImage |
refer to _noImage |
The _noImage section contains all modules of the Module update definitions without a distribution set reference. Functional Modules are not updated in the scope of the system update including their cardinality. |
|
software._systemArtifacts |
refer to _systemArtifacts |
The _systemArtifacts section contains all artifacts within software modules within distribution sets referenced as System distribution set (incl. scripts). Functional System-level artifacts which are downloaded by the System update-app (e.g. system release notes, scripts or license agreements) |
scripts
The scripts section contains all artifacts within software modules within a distribution set of type "scripts" referenced as System distribution set
|
Key |
Source |
Comment |
|
software.scripts[].id |
Id of file |
Used for retrieval of file via Install API |
|
software.scripts[].type |
Software module type key |
The software module type key has to correspond to the required SWUpdate handler that handles the script |
|
software.scripts[].byteSize |
Size of file |
|
|
software.scripts[].filename |
Name of file |
|
|
software.scripts[].sha256 |
SHA256 of file |
|
images
The images section contains all modules of the Module update definitions with a distribution set reference.
|
Key |
Source |
Comment |
|
software.images[]._module.name |
Module update definition name |
|
|
software.images[]._module.description |
Module update definition description |
|
|
software.images[]._module.match |
Module update definition match query |
"attribute." prefix is removed. Query is then transformed from a RSQL to MongoDB query. |
|
software.images[]._module.matchCount |
Module update definition count query |
|
|
software.images[]._software.softwareId |
Distribution set Id |
|
|
software.images[]._software.name |
Distribution set name |
|
|
software.images[]._software.artifacts |
List of all artifacts with all software modules within this distribution set. |
|
|
software.images[]._software.artifacts[].id |
Id of file |
Used for retrieval of file via Install API |
|
software.images[]._software.artifacts[].type |
Software module type key |
|
|
software.images[]._software.artifacts[].byteSize |
Size of file |
|
|
software.images[]._software.artifacts[].filename |
Name of file |
|
|
software.images[]._software.artifacts[].sha256 |
SHA256 of file |
|
|
software.images[].type |
Template |
Module update definition meta data imageType |
|
software.images[].filename |
Filename of artifact within software module of software module type "firmware" |
Module update definition meta data imageFileName |
|
software.images[].version |
Distribution set version |
|
|
software.images[].sha256 |
SHA256 of file "software.images[].filename" |
|
_noImage
The _noImage section contains all modules of the Module update definitions without a distribution set reference.
|
Key |
Source |
Comment |
|
software._noImage[]._module.name |
Module update definition name |
|
|
software._noImage[]._module.description |
Module update definition description |
|
|
software._noImage[]._module.match |
Module update definition match query |
"attribute." prefix is removed. Query is then transformed from a RSQL to MongoDB query. |
|
software._noImage[]._module.matchCount |
Module update definition count query |
|
_systemArtifacts
The _systemArtifacts section contains all artifacts within software modules within distribution sets referenced as System distribution set (incl. scripts).
|
Key |
Source |
Comment |
|
software._systemArtifacts[].softwareId |
Distribution set Id |
|
|
software._systemArtifacts[].name |
Distribution set name |
|
|
software._systemArtifacts |
List of all artifacts with all software modules within this distribution set |
|
|
software._systemArtifacts[].artifacts[].id |
Id of file |
Used for retrieval of file via Install API |
|
software._systemArtifacts[].artifacts[].type |
Software module type key |
|
|
software._systemArtifacts[].artifacts[].byteSize |
Size of file |
|
|
software._systemArtifacts[].artifacts[].filename |
Name of file |
|
|
software._systemArtifacts[].artifacts[].sha256 |
SHA256 of file |
|
Recipe file signature
Once a recipe is promoted from the DRAFT stage to WAITING_FOR_SIGNATURE, the recipe file becomes available for downloading and signing. To ensure the authenticity and integrity of the recipe file, signatures can be uploaded either through the Recipe UI or Management API. This allows systems or the system update app to verify the validity of the downloaded recipe file. When accessing the recipe file via the Install API, the corresponding signatures can also be downloaded. In scenarios where multiple signatures are available, it is the responsibility of the gateway to select the appropriate signature that it can confirm. This mechanism enhances the security and trustworthiness of the recipe file, ensuring that only authorized and verified updates are executed by the system.
The signature can be created using the Bosch IoT Rollouts Extension - Sign & Encrypt.