Software Updatable

Customize the deployment and management of software artifacts.

1: Software update configuration
2: Software Updatable API

1 - Software update configuration

Customize the deployment and management of software artifacts.

Properties

To control all aspects of the software update behavior.

Property	Type	Default	Description
featureId	string	SoftwareUpdatable	Feature unique identifier in the scope of the edge digital twin
moduleType	string	software	Type of the software that is managed by this feature
artifactType	string	archive	Type of the artifact that is to be processed: archive or plain
install	string[]		Absolute path to the install script/command and an optional sequence of additional flags/parameters
storageLocation	string	./	Path to the storage directory where the working files are stored
installDirs	string[]		File system directories where the local artifacts are stored
mode	string	strict	Restriction where the local artifacts can be stored on the file system, the supported modes are: strict, lax and scope
Download
downloadRetryCount	int	0	Number of retries, in case of a failed download
downloadRetryInterval	string	5s	Interval between retries, in case of a failed download as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as: 300ms, 1.5h, 10m30s, etc., time units are: ns, us (or µs), ms, s, m, h
Download - TLS
serverCert	string		PEM encoded certificate file for secure downloads
Local connectivity
broker	string	tcp://localhost:1883	Address of the MQTT server/broker that the software update will connect for the local communication, the format is: `scheme://host:port`
username	string		Username that is a part of the credentials
password	string		Password that is a part of the credentials
Local connectivity - TLS
caCert	string		PEM encoded CA certificates file
cert	string		PEM encoded certificate file to authenticate to the MQTT server/broker
key	string		PEM encoded unencrypted private key file to authenticate to the MQTT server/broker
Logging
logFile	string	log/software-update.log	Path to the file where log messages are written
logLevel	string	INFO	All log messages at this or higher level will be logged, the log levels in descending order are: ERROR, WARN, INFO, DEBUG and TRACE
logFileCount	int	5	Log file maximum rotations count
logFileMaxAge	int	28	Log file rotations maximum age in days, use 0 to not remove old log files
logFileSize	int	2	Log file size in MB before it gets rotated

Example

The minimal required configuration that sets the software type to firmware.

{
    "moduleType": "firmware",
    "storageLocation": "/var/lib/software-update",
    "logFile": "/var/log/software-update/software-update.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "featureId": "SoftwareUpdatable",
    "moduleType": "software",
    "artifactType": "archive",
    "install": [],
    "storageLocation": "./",
    "installDirs": [],
    "mode": "strict",
    "downloadRetryCount": 0,
    "downloadRetryInterval": "5s",
    "serverCert": "",
    "broker": "tcp://localhost:1883",
    "username": "",
    "password": "",
    "caCert": "",
    "cert": "",
    "key": "",
    "logFile": "log/software-update.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

2 - Software Updatable API

The software updatable service provides the ability to install given list of software modules and to download modules.

Install

Install given list of software modules.

Request

Hono Command: command//<name>:<namespace>/req//install

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/install Information about the affected Thing and the type of operation
path /features/SoftwareUpdatable/inbox/messages/install A path to the SoftwareUpdatable Feature, it’s message channel, and install command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id UUID Used for correlating protocol messages, the same correlation-id as the response message
Value JSON presentation of software module that will be installed
correlationId Unique identifier that is used to associate and track the series of messages
weight The weight is the priority in case of multiple, parallel instructions
metadata The metadata is any other information which should be passed to the device
forced true/false Forced to remove the software modules
softwareModules An array of software modules to be installed
metadata The metadata is any other information which should be passed to the device
softwareModule An unique identifier for the software module
name The name of the software module
version The version of the software module
artifacts An array of artifacts contained in the software module
filename The file name of the artifact
size Artifact file size in bytes
download A map with protocols and links for downloading the artifacts
key HTTP/HTTPS/FTP/SFTP Available transport protocols
url URL to download the artifact
md5url MD5URL to download the MD5SUM file
checksums A map with checksums to verify the proper download
MD5 MD5 checksum
SHA1 MD5 checksum
SHA256 MD5 checksum

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/install`	Information about the affected Thing and the type of operation
path	`/features/SoftwareUpdatable/inbox/messages/install`	A path to the `SoftwareUpdatable` Feature, it’s message channel, and `install` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	UUID	Used for correlating protocol messages, the same correlation-id as the response message
Value		JSON presentation of software module that will be installed
correlationId		Unique identifier that is used to associate and track the series of messages
weight		The weight is the priority in case of multiple, parallel instructions
metadata		The metadata is any other information which should be passed to the device
forced	true/false	Forced to remove the software modules
softwareModules		An array of software modules to be installed
metadata		The metadata is any other information which should be passed to the device
softwareModule		An unique identifier for the software module
name		The name of the software module
version		The version of the software module
artifacts		An array of artifacts contained in the software module
filename		The file name of the artifact
size		Artifact file size in bytes
download		A map with protocols and links for downloading the artifacts
key	HTTP/HTTPS/FTP/SFTP	Available transport protocols
url		URL to download the artifact
md5url		MD5URL to download the MD5SUM file
checksums		A map with checksums to verify the proper download
MD5		MD5 checksum
SHA1		MD5 checksum
SHA256		MD5 checksum

Example : Install a hello-world software module.

Topic: command//edge:device/req//install

{
	"topic":"edge/device/things/live/messages/install",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/SoftwareUpdatable/inbox/messages/install",
	"value":{
		"correlationId":"other_correlation_id",
		"softwareModules":[
			{
				"softwareModule":{
					"name":"install-hello",
					"version":"1.0.0"
				},
				"artifacts":[
					{
						"checksums":{
							"SHA256":"db954c633393c1402f145a60fd58d312f5af96ce49422fcfd6ce42a3c4cceeca",
							"MD5":"8c5a0fa2c01e218262d672bf643652fd",
							"SHA1":"7539b451d818d94bcd97d401a5467b3e1c0b8981"
						},
						"download":{
							"HTTPS":{
								"url":"https://github.com/eclipse-kanto/kanto/raw/main/quickstart/install_hello.sh"
							}
						},
						"filename":"install.sh",
						"size":544
					}
				]
			}
		]
	}
}

Response

Hono Command : command//<name>:<namespace>/res//install

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/install Information about the affected Thing and the type of operation
path /features/SoftwareUpdatable/outbox/messages/install A path to the SoftwareUpdatable Feature, it’s message channel, and install command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the sent request message
Status Status of the operation install software modules

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/install`	Information about the affected Thing and the type of operation
path	`/features/SoftwareUpdatable/outbox/messages/install`	A path to the `SoftwareUpdatable` Feature, it’s message channel, and `install` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the sent request message
Status		Status of the operation install software modules

Example : The response of the install software modules operation.

Topic: `command//edge:device/res//install``

{
	"topic":"edge/device/things/live/messages/install",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/SoftwareUpdatable/outbox/messages/install",
	"status": 204
}

Download

Download software modules.

Request

Hono Command: command//<name>:<namespace>/req//download

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/download Information about the affected Thing and the type of operation
path /features/SoftwareUpdatable/inbox/messages/download A path to the SoftwareUpdatable Feature, it’s message channel, and download command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id UUID Used for correlating protocol messages, the same correlation-id as the sent back response message
Value JSON representation of the software modules that will be downloaded
correlationId Unique identifier that is used to associate and track the series of messages
weight The weight is the priority in case of multiple, parallel instructions
metadata The metadata is any other information which should be passed to the device
forced true/false Remove the software modules forcefully
softwareModules An array of software modules that will be downloaded
metadata The metadata is any other information which should be passed to the device
softwareModule A unique identifier for the software module
name The name of the software module
version The version of the software module
artifacts An array of artifacts contained in the software module
filename The file name of the artifact
size Artifact file size in bytes
download A map with protocols and links for downloading the artifacts
key HTTP/HTTPS/FTP/SFTP Available transport protocols
url URL to download the artifact
md5url MD5URL to download the MD5SUM file
checksums A map with checksums to verify the proper download
MD5 MD5 checksum
SHA1 MD5 checksum
SHA256 MD5 checksum

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/download`	Information about the affected Thing and the type of operation
path	`/features/SoftwareUpdatable/inbox/messages/download`	A path to the `SoftwareUpdatable` Feature, it’s message channel, and `download` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	UUID	Used for correlating protocol messages, the same correlation-id as the sent back response message
Value		JSON representation of the software modules that will be downloaded
correlationId		Unique identifier that is used to associate and track the series of messages
weight		The weight is the priority in case of multiple, parallel instructions
metadata		The metadata is any other information which should be passed to the device
forced	true/false	Remove the software modules forcefully
softwareModules		An array of software modules that will be downloaded
metadata		The metadata is any other information which should be passed to the device
softwareModule		A unique identifier for the software module
name		The name of the software module
version		The version of the software module
artifacts		An array of artifacts contained in the software module
filename		The file name of the artifact
size		Artifact file size in bytes
download		A map with protocols and links for downloading the artifacts
key	HTTP/HTTPS/FTP/SFTP	Available transport protocols
url		URL to download the artifact
md5url		MD5URL to download the MD5SUM file
checksums		A map with checksums to verify the proper download
MD5		MD5 checksum
SHA1		MD5 checksum
SHA256		MD5 checksum

Example : Download a hello-world software module.

Topic: command//edge:device/req//download

{
	"topic":"edge/device/things/live/messages/download",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/SoftwareUpdatable/inbox/messages/download",
	"value": {
		"correlationId":"other_correlation_id",
        "softwareModules":[
			{
				"softwareModule":{
					"name":"install-hello",
					"version":"1.0.0"
				},
				"artifacts":[
					{
						"checksums":{
							"SHA256":"db954c633393c1402f145a60fd58d312f5af96ce49422fcfd6ce42a3c4cceeca",
							"MD5":"8c5a0fa2c01e218262d672bf643652fd",
							"SHA1":"7539b451d818d94bcd97d401a5467b3e1c0b8981"
						},
						"download":{
							"HTTPS":{
								"url":"https://github.com/eclipse-kanto/kanto/raw/main/quickstart/install_hello.sh"
							}
						},
						"filename":"install.sh",
						"size":544
					}
				]
			}
		],
	}
}

Response

Hono Command : command//<name>:<namespace>/res//download

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/download Information about the affected Thing and the type of operation
path /features/SoftwareUpdatable/outbox/messages/download A path to the SoftwareUpdatable Feature, it’s message channel, and download command
Headers Additional headers
correlation-id container UUID The same correlation id as the request message
Status Status of the download operation

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/download`	Information about the affected Thing and the type of operation
path	`/features/SoftwareUpdatable/outbox/messages/download`	A path to the `SoftwareUpdatable` Feature, it’s message channel, and `download` command
Headers		Additional headers
correlation-id	container UUID	The same correlation id as the request message
Status		Status of the `download` operation

Example : Successful download response.

Topic: `command//edge:device/res//download``

{
	"topic":"edge/device/things/live/messages/download",
	"headers":{
		"correlation-id":"<UUID>"
	},
	"path":"/features/SoftwareUpdatable/outbox/messages/download",
	"status":204
}