Vehicle Update Manager

• 1: Configuration
• 2: Message Flow

1 - Configuration

Config file

The default location for the VUM service on the Leda Distro image can be found at /etc/update-manager/config.json. The location of the config file is specified with the --cfg-file [PATH] flag when starting the binary.

Minimal configuration

A minimal configuration (that is used by the Leda Distro) is the following:

{
    "log": {
      "logFile": "/var/log/update-manager/update-manager.log"
    },
    "domain": "vehicle",
    "agents": {
        "containers": {
            "name": "containers",
            "rebootRequired": false,
            "readTimeout": "30s"
        },
        "self-update": {
            "name": "self-update",
            "rebootRequired": true,
            "readTimeout": "30s"
        }
    },
    "thingsEnabled": false
}

Where:

• “domain”: specifies the prefix for the MQTT topic, e.g. in this case it’s set to vehicle, so all VUM related topic are prefixed with vehicleupdate/[TOPIC]
• “agents”: configures the update agents that would be available to VUM. Here the “readTimeout” key specifies how long should VUM wait for a response from the configured agent.
• “thingsEnabled”: whether VUM should use the Kanto Things API for communication or not.

Full configuration

An example configuration file for VUM with all available options is the following one:

{
  "log": {
    "logFile": "log/update-manager.log",
    "logLevel": "ERROR",
    "logFileSize": 3,
    "logFileCount": 6,
    "logFileMaxAge": 29
  },
  "connection": {
    "broker":"www",
    "keepAlive": 500,
    "disconnectTimeout": 500,
    "username":"username",
    "password":"pass",
    "connectTimeout": 500,
    "acknowledgeTimeout": 500,
    "subscribeTimeout": 500,
    "unsubscribeTimeout": 500
  },
  "domain": "vehicle",
  "thingsEnabled": false,
  "rebootEnabled": true,
  "rebootAfter": "1m",
  "reportFeedbackInterval": "2m",
  "currentStateDelay": "1m",
  "phaseTimeout": "2m",
  "agents": {
    "self-update": {
      "rebootRequired": false,
      "readTimeout": "20s"
    },
    "containers": {
      "rebootRequired": true,
      "readTimeout": "30s"
    }
  }
}

Here keys (other the ones above) are self-explanatory. The “connection” section object specifies configuration options for the MQTT connection. Allowed log leves (in order of increasing verbosity)are: ERROR, WARN, INFO, DEBUG, TRACE.

2 - Message Flow

Note: This part of the Leda OSS stack is still in active development and there might be differences between the documented and the current version.

As described in Vehicle Update Manager takes a full update message for all domains, identifies the domains affected, the current component versions, actions to be taken, etc., and delegates those actions to the correct update agent (e.g. self-update/container update).

The update manager (UM) in Leda-distro is configured as specified in UM’s config.json, which on the final image is usually located in /etc/update-manager/config.json. The standard two domains supported are containers and self-update, with the latter requiring a reboot on a successful update.

Note: UM allows a custom prefix for all of its topics to be defined (“domain”) in its config.json On the Leda Distro image the default prefix is “vehicle”. If you decide to change it, replace “vehicle” in all MQTT topics mentioned below with your custom prefix.

A full specification of UM’s API and the relevant MQTT topics can be found in its documentation.

Update Message

The general structure of the update message is as follows:

{
  "activityId": "correlation-activity-uuid",
  "timestamp": 123456789,
  "payload": {
    "domains": [
      {
        "id": "domain",
        "config": [],
        "components": [
            {
                "id": "component1",
                "version": "component1-version",
                "config": [
                    {
                        "key": "component1-config-key-1",
                        "value": "component1-config-value-1"
                    }
                ]
            }
        ]
      }
    ]
  }
}

Where multiple domains and components per domain (each with multiple configuration key-value pairs) are allowed. To trigger an update, publish your full update message on the vehicleupdate/desiredstate MQTT topic. When UM receives your message, it splits it across the required domains and publishes messages to the topics that the domain-specific agents are monitoring.

Similarly, update progress can be monitored on the vehicleupdate/desiredstatefeedback topic.

Self-update

The messages for triggering a self-update (image update) are the same as in The Self Update Tutorial. The only difference here is that when you publish a self-update message on the vehicleupdate/desiredstate topic, UM will automatically take care to forward your message to the self-update agent, including forwarding back the update feedback on the vehicleupdate/-namespaced topics.

Containers update (desired state)

Similarly to the self-update, you should start by understanding the operation of the Container Update Agent. After constructing the desired state message you can publish it on the vehicleupdate/desiredstate and UM will, again, forward it to CUA automatically, based on the domain specified in the update message.

Combined update messages

The real strength of UM is deploying updates accross multiple domains with a single update message. For example, if you’d like to deploy an image update bundle (self-update) and a single hello-world container image with the environment variable FOO=BAR set, you can construct the following message:

{
   "activityId":"random-uuid-as-string",
   "timestamp":123456789,
   "payload":{
      "domains":[
         {
            "id":"self-update",
            "components":[
               {
                  "id":"os-image",
                  "version":"${VERSION_ID}",
                  "config":[
                     {
                        "key":"image",
                        "value":"https://leda-bundle-server/sdv-rauc-bundle-minimal-qemux86-64.raucb"
                     }
                  ]
               }
            ]
         },
         {
            "id":"containers",
            "config":[],
            "components":[
               {
                  "id":"hello-world",
                  "version":"latest",
                  "config":[
                     {
                        "key":"image",
                        "value":"docker.io/library/hello-world:latest"
                     },
                     {
                        "key":"env",
                        "value":"FOO=BAR"
                     }
                  ]
               }
            ]
         }
      ]
   }
}

And publish the message on the MQTT topic vehicleupdate/desiredstate. UM will take actions to identify the affected update domains and publish the correct messages on the respective topics. All feedback from the specific update agents will be forwarded back to the UM and published on the vehicleupdate/desiredstatefeedback topic. All these messages will use the same activityId so they can be correlated with each other.