Skip to content

cloud.smarthq.service.firmware.v1

  • Configuration

    Describes boundaries and fixed properties for the service.

    Go There

  • State

    A list of the states this service can be in.

    Go There

  • Commands

    How to change the state of the service.

    Go There

  • Data Types

    All the data types used for this service.

    Go There

Description

Service to indicate pending firmware updates and allows accepting the update for it to be installed.

Example Device Response (Digital Twin API)

Service for controlling color temperature.

{
  "adapterId": "0000000000000000000000000000000000000000",
  "alertTypes": [],
  "createdDateTime": "2022-03-04T12:12:12.123Z",
  "deviceId": "0000000000000000000000000000000000000000000000000000000000000000",
  "deviceType": "cloud.smarthq.device.airconditioner",
  "gatewayId": "0000000000000000000000000000000000000000000000000000000000000000",
  "kind": "device#item",
  "lastPresenceTime": "2022-03-04T12:12:12.123Z",
  "lastSyncTime": "2022-03-04T12:12:12.123Z",
  "presence": "OFFLINE",
  "removable": true,
  "services": [
    {
      "serviceType": "cloud.smarthq.service.firmware.v1",
      "lastSyncTime": "2022-03-04T12:12:12.123Z",
      "domainType": "cloud.smarthq.domain.firmware",
      "supportedCommands": [
        "cloud.smarthq.command.firmware.v1.upgrade"
      ],
      "state": {
        "upgradeStatus": "cloud.smarthq.type.upgrade.idle",
        "versionCurrent": "0.002.11.057",
        "disabled": true
      },
      "serviceId": "0000000000000000000000000000000000000000000000000000000000000000",
      "serviceDeviceType": "cloud.smarthq.device.wifi",
      "config": {},
      "lastStateTime": "2022-03-04T12:12:12.123Z"
    }
  ],
  "userId": "000000000000000"
}

Configuration

The following are properties for the gateway/device sync as part of the "config" object for each individual service.

Field Name Property Type Required
model STRING No

State

The following are properties for the device state report as part of the "state" object for each individual service.

Field Name Property Type Required
disabled BOOLEAN Yes
upgradeStatus UPGRADE Yes
versionAvailable STRING No
versionAvailableId STRING No
versionCurrent STRING Yes

Commands

The following are properties for both the Digital Twin API to send a command to the device as well as the properties passed as part of a command to the gateway to be processed by the device itself.

cloud.smarthq.command.firmware.v1.upgrade

Command to trigger the upgrade of the firmware.

Example Commands

Example Command to trigger the upgrade of the firmware.

{
  "command": {
    "commandType": "cloud.smarthq.command.firmware.v1.upgrade"
  },
  "deviceId": "00000000000000000000000000000000000000000000000000000000000000",
  "domainType": "cloud.smarthq.domain.firmware",
  "kind": "service#command",
  "serviceDeviceType": "cloud.smarthq.device.wifi",
  "serviceType": "cloud.smarthq.service.firmware.v1"
}

Supported Outcomes

Each service has an allow listed set of outcomes that the device may return when asked to execute a command.

Outcome Documentation
cloud.smarthq.outcome.developererror Only used when there is a server side bug
cloud.smarthq.outcome.deviceoffline The device is offline.
cloud.smarthq.outcome.forbidden The request is forbidden due to permissions.
cloud.smarthq.outcome.internalerror The server had an issue processing the request
cloud.smarthq.outcome.missingconfig The service config is missing
cloud.smarthq.outcome.missingstate The service state is missing
cloud.smarthq.outcome.notallowed The command is not allowed.
cloud.smarthq.outcome.notfound The request is forbidden due to permissions.
cloud.smarthq.outcome.notsupported The command is not supported.
cloud.smarthq.outcome.servicedisabled Feature is currently disabled
cloud.smarthq.outcome.success Successful request
cloud.smarthq.outcome.timeout The server experienced timeout waiting for a response from the gateway

Data Types

BOOLEAN

Value must be either true or false.

STRING

Value must be a sequence of characters, inserted between " and " (double quotes). Field specific restrictions such as a regular expression may apply depending on the field.

UPGRADE

UPGRADE Documentation
cloud.smarthq.type.upgrade.available There is a firmware available
cloud.smarthq.type.upgrade.downloading the device is downloading the firmware
cloud.smarthq.type.upgrade.error.busy the device was “busy” when firmware update was attempted to be applied. This indicates that a firmware update is still available and should be applied
cloud.smarthq.type.upgrade.error.image Updated was attempted and failed. Device likely not functional. The device will continuously attempt to resolve issue and complete update.
cloud.smarthq.type.upgrade.error.incompatible Update was downloaded and failed. A new firmware needs to be released before another update attempt should be attempted.
cloud.smarthq.type.upgrade.error.writing The writing error status
cloud.smarthq.type.upgrade.idle No update available
cloud.smarthq.type.upgrade.updating update is actively being applied to device. Device may not be functional during this time.