Skip to content

D-Bus API

Klas communicates with the system using D-Bus and exposes the following APIs:

Telemetries D-Bus API

node /com/witekio/klas/telemetries { interface com.witekio.klas.Telemetries { methods: sendUserTelemetriesJson(in s userTelemetriesJson); } }

Methods

sendUserTelemetriesJson()
Send a payload as telemetries to Kamea.
- userTelemetriesJson (in s) is a JSON string containing the telemetries to send.

Errors

com.witekio.klas.Telemetries.Error.InvalidJSONFormat
Indicates that the provided JSON string is not valid.

Configuration D-Bus API

``` node /com/witekio/klas/configuration { interface com.witekio.klas.Configuration { methods: sendUserConfigurationJson(in s userConfigurationJson);

signals:
  b connectionChanged;
  s receivedDesiredJson;

properties:
  readonly b connected;

} } ```

Methods

sendUserConfigurationJson()
Send user Json as a reported configuration to Kamea.
- userConfigurationJson (in s) is a JSON string containing the user configuration to report.

Signals

connectionChanged()
Signal emitted when the MQTT connection status changes.

receivedDesiredJson()
Signal emitted when a new user desired configuration is received from Kamea.

Properties

connected
Indicates if the agent is connected to Kamea.

Errors

com.witekio.klas.Configuration.Error.InvalidJSONFormat
Indicates that the provided JSON string is not valid.

Firmware D-Bus API

``` node /com/witekio/klas/firmware { interface com.witekio.klas.Firmware { methods: downloadFirmware(in (ss) firmwareVersion); reportFirmwareUpdated(in (ss) firmwareVersion);

signals:
  a(ss)  newFirmwareVersionsAvailable;
  a(sss) newFirmwareFilesDownloaded;
  a(ss)  newFirmwareDownloadFailed;

properties:
  readonly a(ss)  latestFirmwareVersionAvailables;
  readonly a(sss) allFirmwareVersionAvailables;
  readonly a(sss) latestFirmwareFilesDownloaded;
  readonly a(sss) allFirmwareFilesDownloaded;
  readonly a(ss)  failedFirmwareDownloads;
  readonly a(sss) installedFirmwareVersions;

} } ```

Methods

downloadFirmware()
Request the download of a firmware version. KLAS will start the download asynchronously and emit newFirmwareFilesDownloaded on success or newFirmwareDownloadFailed on failure.

firmwareVersion: in (ss) Structure containing:

  • name (string) — the firmware name (must match a name previously announced via newFirmwareVersionsAvailable).
  • version (string) — the version to download. Example: ('app', '1.0.0')

Errors:

  • com.witekio.klas.Firmware.Error.InvalidFirmwareName — the firmware name is unknown.
  • com.witekio.klas.Firmware.Error.InvalidFirmwareVersion — the version is unknown for that firmware name.

reportFirmwareUpdated()
Confirm that a firmware version has been successfully installed. KLAS reports the installed version to Kamea and clears the downloaded file from the system.

firmwareVersion: in (ss) Structure containing:

  • name (string) — the name of the installed firmware.
  • version (string) — the installed version. Example: ('app', '1.0.0')

Errors:

  • com.witekio.klas.Firmware.Error.InvalidFirmwareName — the firmware name is unknown.
  • com.witekio.klas.Firmware.Error.InvalidFirmwareVersion — the version is unknown for that firmware name.

Signals

newFirmwareVersionsAvailable()
Emitted when the set of latest available firmware versions changes (i.e. a new version supersedes the previous one for at least one firmware).
Contains an array of (name, version) pairs: a(ss) Example: [('app', '2.0.0'), ('os', '1.5.0')]

newFirmwareFilesDownloaded()
Emitted when a firmware file download completes successfully and the set of latest downloaded files changes.
Contains an array of (name, version, file_path) triples: a(sss) Example: [('app', '2.0.0', '/var/download/app_firmware.bin')]

newFirmwareDownloadFailed()
Emitted when one or more firmware downloads fail.
Contains an array of (name, version) pairs for the failed downloads: a(ss) Example: [('os', '1.5.0')]

Properties

latestFirmwareVersionAvailables
The most recently announced version per firmware: a(ss) — (name, version).
Mirrors the data emitted by newFirmwareVersionsAvailable.

allFirmwareVersionAvailables
All known firmware versions with their availability date: a(sss) — (name, version, available_date).
Persists across restarts.

latestFirmwareFilesDownloaded
The most recently downloaded file per firmware: a(sss) — (name, version, file_path).
Mirrors the data emitted by newFirmwareFilesDownloaded.
Cleared for a firmware entry once reportFirmwareUpdated() is called for it.

allFirmwareFilesDownloaded
All successfully downloaded files across all versions: a(sss) — (name, version, file_path).
Cleared for a firmware entry once reportFirmwareUpdated() is called for it.

failedFirmwareDownloads
All versions whose download has failed: a(ss) — (name, version).

installedFirmwareVersions
All firmware versions that have been confirmed installed via reportFirmwareUpdated(): a(sss) — (name, version, install_date).
Persists across restarts. Useful to avoid re-downloading or re-installing versions already handled.

Errors

com.witekio.klas.Firmware.Error.InvalidFirmwareName
Indicates that the firmware name provided to the method is unknown (no version has been announced for it yet).

com.witekio.klas.Firmware.Error.InvalidFirmwareVersion
Indicates that the firmware version provided to the method is not known for that firmware name.