Skip to content

Requirements

This page describes the technical requirements for integrating gateways and adapters with the Device Adapter API. It covers gateway specifications, adapter responsibilities, and message handling.

Architecture

There are a couple of common configurations that utilize the Device Adapter API:

  • Gateway accessing the Device Adapter API directly
  • Gateway accessing the Device Adapter API through an adapter

A gateway utilizes different resources and is provisioned into the system in different ways depending on the configuration. In the configuration where the gateway is behind an adapter, the adapter handles parts of the gateway provisioning process, and the gateway should reference the adapter-specific documentation for provisioning.

Adapter Specifications

In practice, an adapter is a server-side application responsible for:

  • Handling registration of gateways of a single type to a user's SmartHQ account
  • Managing communication between the gateway and SmartHQ
  • Forwarding outbound requests from SmartHQ to the gateway
  • Handling inbound messages if the gateway does not directly send HTTP requests to the Device Adapter API
  • Setting the gateway's presence to OFFLINE in SmartHQ if it becomes disconnected

Adapters may be protocol-specific (e.g., MQTT, cloud-to-cloud integrations) and are designed to centralize authentication, configuration management, and scalable deployment across many users and devices.

Messages or commands generated from SmartHQ are sent to the adapter for which a gateway is registered. The adapter then forwards the message to the gateway using the appropriate mechanism.

Adapter Callbacks

There are five types of incoming messages from SmartHQ that an adapter should handle, outlined below. All messages should be forwarded to the corresponding gateway, except the notification of a gateway removal.

Important

In all adapter callback messages from SmartHQ, the gatewayId field will contain the adapterGatewayId value.

1. Notification of Gateway Removal

The notification of a gateway removal is the only inbound message that does not require a response to SmartHQ. This message simply notifies the adapter that a Gateway was removed from a user's account. The adapter should handle any internal housekeeping for a gateway removal when it receives this message.

Example Payload
{
    "kind": "gateway#deprovision",
    "gatewayId": "rt9e83niwhgp2s2"
}

2. Request for Full Gateway Device Configuration Sync

This request should be forwarded to the corresponding gateway, and the gateway should send both service state (/v2/device/state) and presence (/v2/device/presence) for all of its devices. The response should include the correlationId that it received to acknowledge the request was successfully processed.

Example Payload
{
    "kind": "request#fullstate",
    "correlationId": "3fc3d1e0-58f2-46ca-91e0-e3d4be61c829",
    "gatewayId": "rt9e83niwhgp2s2"
}

3. Request for Single Device Configuration Sync

This request should be forwarded to the corresponding gateway, and the gateway should send both service state (/v2/device/state) and presence (/v2/device/presence) for the requested device. The response should include the correlationId that it received to acknowledge the request was successfully processed.

Example Payload
{
    "kind": "request#state",
    "correlationId": "3fc3d1e0-58f2-46ca-91e0-e3d4be61c829",
    "gatewayId": "rt9e83niwhgp2s2",
    "deviceId": "D8280000000"
}

4. Request for Gateway to Remove Device

This request should be forwarded to the corresponding gateway, and the gateway should respond with either a request to the /v2/device endpoint with the kind of device#delete, or a full synchronization of all its devices and their configurations to the /v2/gateway endpoint. The response should include the correlationId that it received to acknowledge the request was successfully processed. If the gateway is not able to remove the device, it should not respond to the request and should instead let it time out to the client.

An optional force parameter may be provided if the client requests to indicate that the device should be removed from the gateway. This is a boolean value that, if provided, will always be "true". The specific interpretation of what this additional signal means is left to the implementation of the gateway.

Example Payload
{
    "kind": "request#removedevice",
    "correlationId": "3fc3d1e0-58f2-46ca-91e0-e3d4be61c829",
    "gatewayId": "rt9e83niwhgp2s2",
    "deviceId": "D8280000000"
}

5. Request to Run Command on a Device Service

This request should be forwarded to the corresponding gateway, and the gateway should attempt to run the requested command on the device. The result of the command should be sent to the /v2/command endpoint with the same correlationId received in the request to acknowledge the command was processed. Running the command and posting the response to the Device Adapter API should occur within 20 seconds, or a timeout will be returned to the client. Each command supports different outcomes; see Supported Outcomes for Services, such as Supported Outcomes for the Trigger Service, for example. These supported outcomes are listed in each service's documentation for the corresponding command.

Example Payload
{
    "kind": "request#command",
    "timestamp": "2020-01-01T00:00:00.000Z",
    "correlationId": "355f8c05-733a-45e7-abe4-4cdd2d9a5a5a",
    "gatewayId": "rt9e83niwhgp2s2",
    "deviceId": "D82800000000",
    "serviceId": "setpoint",
    "serviceType": "cloud.smarthq.service.temperature",
    "domainType": "cloud.smarthq.domain.setpoint",
    "serviceDeviceType": "cloud.smarthq.device.refrigerator.freshfood",
    "command": {
        "commandType": "cloud.smarthq.command.temperature.set",
        "fahrenheit": 77,
        "celsiusConverted": 25
    }
}

Commands triggered based on a system rule will include an additional JSON object of rule that provides additional context for the rule that triggered the command. The ruleId will always be provided as an attribute. For rules triggered by an alert from a device, the deviceId and alertType attributes will be provided. Rules with other triggers may provide a different set of attributes to help provide context for why the command was triggered.

Example Payload:

{
    "kind": "request#command",
    "serviceType": "cloud.smarthq.service.pushnotification",
    "domainType": "cloud.smarthq.domain.fcm",
    "serviceDeviceType": "cloud.smarthq.device.mobile.android",
    "timestamp": "2020-01-01T00:00:00.000Z",
    "correlationId": "00000000-0000-0000-0000-000000000000",
    "gatewayId": "abcdefghijklmno",
    "deviceId": "qwertyuiop12",
    "serviceId": "push",
    "command": {
        "commandType": "cloud.smarthq.command.pushnotification.text",
        "pushText": "This is the text for a push notification"
    },
    "rule": {
      "ruleId": "b76ee909-6475-4c0a-ac73-83b78a2ccdff",
      "deviceId": "55d69fd134ccb6fb2db9227cd7110320859a8b1a27287cb435d0ca2d372f4a82",
      "deviceType": "cloud.smarthq.device.dishwasher",
      "alertType": "cloud.smarthq.alert.endofcycle"
    }
}

Gateway Specifications

  • A gateway is registered to a single user account and can support up to 100 devices.
  • The gateway should handle authentication and communication with SmartHQ.
  • Each device must have a unique deviceId. Recommended to use a UUID (Universally Unique Identifier).
    • Requirements:
      • Minimum length: 1 character
      • Maximum length: 64 characters
      • Pattern: Only letters, numbers, hyphens, and periods are allowed.
  • Each deviceId must persist through a power cycle of the gateway.
  • The gateway must report devices during device sync, even if they are currently offline.
  • Each service for a device must have a unique serviceId. Recommended to use a UUID.
    • Requirements:
      • Minimum length: 1 character
      • Maximum length: 64 characters
      • Pattern: Only letters, numbers, hyphens, and periods are allowed.
  • Each service for a device must have a unique serviceType and domainType combination.
    • For more information on specific services, please see the SmartHQ Service Documentation. (See Navigating the Data Model for how to access the services).
  • An optional attribute, correlationId, can be included as a response to a user-initiated command (e.g user requests a device be removed from a gateway).

Gateway and Device Presence

Gateway Presence

A gateway comes ONLINE by reporting its devices configuration. The act of syncing the configuration means that the gateway is ONLINE. After configuration is reported, the gateway's presence is updated to ONLINE. If a gateway was OFFLINE and goes ONLINE by reporting its configuration, a request will be sent to the gateway to send each of its devices state and presence.

If a gateway goes OFFLINE, it cannot report itself being offline, so it is the responsibility of the gateway's adapter to report the gateway as being OFFLINE. When a gateway is marked as OFFLINE in the SmartHQ system, all of its devices' presence are marked as OFFLINE. The history of a gateway's presence status is not captured within the SmartHQ system; instead, the adapter should maintain the presence history for a gateway if desired.

Device Presence

When a device is first added to the SmartHQ system, its presence will be in an UNKNOWN state. A request will be sent to the gateway to report its state and presence after all of the records have been created in the SmartHQ system. It is the responsibility of the gateway to report changes in a device's presence. When a device is OFFLINE, commands will not be sent. History of device presence is recorded within the SmartHQ system and can be retrieved through an API request.

Device Services

  • Service configuration must be reported and created in the SmartHQ system before state can be reported, see Syncing New Device in tutorial.
  • Configuration should not change often and is typically reported once upon device addition.

Device Alerts

A device can optionally specify alert types which can be triggered for that device in the device's configuration. Alerts are treated as events and do not have state. For example, think of an oven reaching its preheat temperature. At a certain point in time, the oven reaches its target temperature and a "preheat achieved" alert can be triggered. The alert does not hold a true/false for whether it's preheated though. The logic for what triggers an alert lives within the gateway or adapter that the device connects through, or possibly the device itself. It is the responsibility of the gateway to report the triggering of an alert.

Alerts are processed in the PubSub pipeline, and applications which are subscribed to alert events will be notified when an alert is triggered. History of alerts is recorded within the SmartHQ system and can be retrieved through an API request.