Firmware update

Klas enables Over-The-Air (OTA) firmware updates by acting as a bridge between the Kamea cloud and the local system. When Kamea signals that a new firmware version is available, Klas notifies the system over D-Bus. The system can then choose to delegate the file download to Klas or handle it independently — in both cases, it confirms installation by calling a single D-Bus method, and Klas reports the result back to Kamea.

Key characteristics:

D-Bus is the primary interface. All interaction with the system goes through D-Bus signals and method calls.
Download is optional. The system may fetch the firmware file itself and skip downloadFirmware() entirely.
State is persisted. Version information, download results, and timestamps survive Klas restarts.

A detailed description of the D-Bus API is available in the DBus API documentation.

sequenceDiagram
    actor Kamea
    participant Klas
    actor System

    Kamea->>Klas: new firmware version available (MQTT)
    Klas->>System: newFirmwareVersionsAvailable [(name, version)]

    opt System delegates download to Klas
        System->>Klas: downloadFirmware(name, version)
        alt Download succeeds
            Klas->>System: newFirmwareFilesDownloaded [(name, version, file_path)]
        else Download fails
            Klas->>System: newFirmwareDownloadFailed [(name, version)]
        end
    end

    System->>System: install firmware
    System->>Klas: reportFirmwareUpdated(name, version)
    Klas->>Kamea: reported installed version (MQTT)

New firmware version available
Kamea notifies Klas about a new firmware version. Klas emits the newFirmwareVersionsAvailable D-Bus signal to the system.
The version is also readable at any time via the latestFirmwareVersionAvailables and allFirmwareVersionAvailables properties.
Download (optional)
The system may call downloadFirmware(name, version) to delegate the download to Klas.
The local name of the file is name_version. On success, Klas emits newFirmwareFilesDownloaded with the local file path (also in latestFirmwareFilesDownloaded / allFirmwareFilesDownloaded).
On failure, Klas emits newFirmwareDownloadFailed (also in failedFirmwareDownloads). The system may alternatively handle the download itself and skip this step entirely.
Confirm installation
Once the firmware is installed, the system calls reportFirmwareUpdated(name, version).
Klas reports the installed version to Kamea. This is the only mandatory D-Bus call.
If Klas previously downloaded the firmware file, it is automatically deleted from disk at this point.