Skip to content

Tutorial

This tutorial walks you through how to integrate a meter device into SmartHQ cloud using the SmartHQ Meter Service.

Goal of This Tutorial

By the end, you will be confident using the Device Adapter API and understand how to set up your adapter to start connecting your devices.

Prerequisites

Before you begin this tutorial:

  1. Complete our Get Started steps.
  2. Follow our Adapter Set Up to:
    • Obtain an Adapter ID and an Adapter Secret.
    • Set up a Device Adapter endpoint (HTTPS or Amazon SNS) where SmartHQ will send callbacks.

1. Provision a Gateway

The gateway is a processing unit that monitors the state of the physical meter, in this example, or any device connected to SmartHQ. It sends API requests to SmartHQ to report device information and receive commands. The gateway can be the device itself, a separate hardware component, or a virtual hub in the cloud. Its main role is to act as an intermediary between the device and SmartHQ.

Step 1: Get a Gateway Provisioning Token (GPT)

Call the Digital Twin API endpoint POST /v2/gateway using your access token from Get Started steps.

Example Response
{
  "gatewayProvisioningToken": "aue1vDEFFZwEsimPF53KbgM4I4p4BPw1"
}

Step 2: Pass the GPT to your Adapter

Take the Gateway Provisioning Token (GPT) you received and pass it to your adapter. Your adapter will use the GPT to register the gateway with SmartHQ.

Step 3: Adapter registers the gateway

Your adapter should call the Device Adapter API provisioning endpoint: POST /v2/gateway/provision.

Important

All requests to the Device Adapter API must use the following base URL: https://device.mysmarthq.com

In the request body, include the adapter credentials from SmartHQ administrator in the prerequisite step, the GPT from the previous step, and your unique adapterGatewayId.

Tip

For more information on adapterGatewayId, see Adapter Gateway ID.

Example Request Body
{
  "gatewayProvisioningToken": "aue1vDEFFZwEsimPF53KbgM4I4p4BPw1",
  "kind": "gateway#provision",
  "adapterGatewayId": "rt9e83niwhgp2s2",
  "adapterId": "17dffe71c103907c32cf57f6beb7e96a87100000",
  "adapterSecret": "EXAMPLESECRETcfa4596f255be720bd788b8592fd767db1f2267876d3b86356f"
}
Example Response
{
  "gatewayAccessToken": "2a6c656d8d105fefd37337mno",
  "kind": "gateway#provision"
}

Step 4: Adapter receives Gateway Access Token (GAT)

Return the GAT from the adapter to your gateway. Your gateway will use this GAT to authenticate API calls.

Important

All requests made to Device Adapter API must have an "Authorization" header set to the GAT value. Review Gateway Provisioning Process for more details.

2. Syncing Meter Device

Devices are added, updated, or removed from a gateway using the Device Adapter API.

This tutorial demonstrates how to integrate a meter device, but SmartHQ supports many device types for integration.

How to Find Supported Device Types

To see the full list of device types currently supported by SmartHQ, call the following endpoint and pass "client.get.deviceInfo" as the schemaName parameter:

Note

The schema name client.get.deviceInfo is a special value used with the GET /v2/schema/{schemaName} endpoint to retrieve the full list of device types supported by SmartHQ. For a complete list of available schema names, you can call GET /v2/schema.

This endpoint returns the JSON Schema used by an API request, starting with all device types available for integration. The information in the response is part of our data model. To learn more about our data model in general, see Data Model Overview.

Note: The example response shown below is truncated for brevity and only includes a subset of the supported device types.

Example Response Body
{
  "$schema": "http://json-schema.org/draft-07/schema#",
    "additionalProperties": false,
    "type": "object",
    "definitions": {
        "deviceDefinition": {
            "type": "string",
            "enum": [
                "cloud.smarthq.device.account",
                "cloud.smarthq.device.advantium.android",
                "cloud.smarthq.device.airconditioner",
                "cloud.smarthq.device.airconditioner.fan",
                "cloud.smarthq.device.airconditioner.outdoorunit",
                "cloud.smarthq.device.airfilter",
                "cloud.smarthq.device.android",
                "cloud.smarthq.device.appliance",
                "cloud.smarthq.device.autofill.pitcher",
                "cloud.smarthq.device.avs",
                "cloud.smarthq.device.battery",
                "cloud.smarthq.device.bluetooth",
                "cloud.smarthq.device.bridge",
                "cloud.smarthq.device.bridge.philipshue",
                "cloud.smarthq.device.clock",
                "cloud.smarthq.device.coffeebrewer",
                "cloud.smarthq.device.combilaundry",
                "cloud.smarthq.device.combioven",
                "cloud.smarthq.device.cooktop",
                "cloud.smarthq.device.cooktop.electric",
                "cloud.smarthq.device.cooktop.gas",
                "cloud.smarthq.device.cooktop.induction",
            ]
        }
    }
}

Warning

If the device type you want to add is not defined in the response from the endpoint above, you will need to contact SmartHQ to have it added before integration can proceed.

Adding the Meter Device

To add a new device, you need to provide SmartHQ with a detailed request body describing the device, its services, and the domains those services operate in. Here’s how to build this request:

1. Select Services for Your Device

Services are a construct in SmartHQ that can represent different functionalities of your device. Each device type can communicate its state and data through many different services, sent as an array of services to SmartHQ in an API request.

For more information on services, please see the SmartHQ Service Documentation. (See Navigating the Data Model for how to access the services).

2. Find the Domain for Each Service

Services operate within specific domains (e.g., voltage, temperature, etc.). The domain defines the context or measurement type for the service.

  • To find the domains associated with a service, look up your selected service in the JSON schema returned from the endpoint GET /v2/schema/client.get.deviceInfo in the previous section.

  • Within the schema, each service lists the possible domains it supports under the domainType property.

  • Review these options and select the domain that best matches your device’s functionality.

Finding Domains for Meter Service
{
  "serviceType": {
                   "type": "string",
                    "enum": [
                        "cloud.smarthq.service.meter"
                    ]
                },
                "lastSyncTime": {
                    "pattern": "^[0-9]{4}(-[0-9]{2}){2}T([0-9]{2}:){2}[0-9][0-9]{3}Z$",
                    "type": "string"
                 },
                 "domainType": {
                     "type": "string",
                    "enum": [
                        "cloud.smarthq.domain.energy",
                        "cloud.smarthq.domain.voltage",
                        "cloud.smarthq.domain.gas.natural",
                        "cloud.smarthq.domain.water",
                        "cloud.smarthq.domain.gas",
                        "cloud.smarthq.domain.water.cold",
                        "cloud.smarthq.domain.amperage",
                        "cloud.smarthq.domain.energy.v2",
                        "cloud.smarthq.domain.gas.propane",
                        "cloud.smarthq.domain.power",
                        "cloud.smarthq.domain.water.hot"
                    ]
                 },
  ...
}
  • This tutorial will use the meter service domain type cloud.smarthq.domain.voltage.

Warning

If the domain type needed to represent your device's service is not defined in the response from the endpoint above, contact SmartHQ to have it added.

3. Construct the Request Body

When building your device request body, use the JSON schema returned from the GET /v2/schema/client.get.deviceInfo endpoint to determine all required and optional properties for each service. The schema will list:

  • serviceId: A unique string identifier for the service instance.

Tip

Use a UUID (Universally Unique Identifier) for serviceId and deviceId to ensure global uniqueness. UUIDs are a standard way to generate identifiers that are extremely unlikely to repeat, making them ideal for SmartHQ.

  • state: An object describing the real-time state properties your device should report. The schema will specify required fields (e.g., meterValue) and optional fields (e.g., meterValueDelta, disabled, updateFrequencySeconds).

  • serviceDeviceType: The device type associated with the service (should match your device type).

  • supportedCommands: An array of supported command strings for the service.

  • config: An object containing configuration details for the service. The schema will specify required properties (such as meterUnits, reading, measurement) and any optional properties (like circuitId, supportResourceManagement, or sources).

Use the information above to build your request.

Add your new device by calling POST /v2/device with your request body as shown in the example below.

Adding Meter Device Request Body
{
  "deviceType": "cloud.smarthq.device.meter",
  "kind": "device#sync",
  "deviceId": "e7b8a9c2-4f3a-4c1e-9a2d-2c8e2b7f8d1a",
  "removable": true,
  "services": [
    {
      "serviceId": "a3c1f2d4-5b6e-7c8d-9e0f-1a2b3c4d5e6f",
      "serviceType": "cloud.smarthq.service.meter",
      "domainType": "cloud.smarthq.domain.voltage",
      "serviceDeviceType": "cloud.smarthq.device.meter",
      "supportedCommands": [],
      "config": {
        "circuitId": "CIRCUIT-101",
        "measurement": "cloud.smarthq.type.measurement.instantaneous",
        "meterUnits": "cloud.smarthq.type.meterunits.volts",
        "reading": "cloud.smarthq.type.reading.measured",
        "supportResourceManagement": true
      }
    }
  ]
}
Because the deviceId does not match an existing device, expect the response status to be created.
Adding New Meter Device Response
{
  "syncTime": "2019-07-08T19:21:56.005Z",
  "kind": "device#sync",
  "success": true,
  "status": "created"
}
Once your new device is processed, SmartHQ will send a sync request back to the gateway.

3. Responding to SmartHQ Sync Requests

When SmartHQ requests a full configuration sync or a single device configuration sync from your device, forward the request from your adapter to the gateway.

The gateway should respond to SmartHQ's sync request with the following endpoints:

  1. POST /v2/device/state
  2. POST /v2/device/presence

Each response must include the correlationId from the original request so SmartHQ can confirm it corresponds to the right sync event.

Meter Device State Request Body
{
  "kind": "device#services",
  "deviceId": "e7b8a9c2-4f3a-4c1e-9a2d-2c8e2b7f8d1a",
  "services": [
    {
      "serviceId": "a3c1f2d4-5b6e-7c8d-9e0f-1a2b3c4d5e6f",
      "serviceType": "cloud.smarthq.service.meter",
      "state": {
        "meterValue": 223.3,
        "updateFrequencySeconds": 60
      }
    }
  ]
}
For further explanation of this JSON object, see our Data Model Overview example.

Tip

Review message types for more information on SmartHQ requests.

4. Update Device State

Once a device has been provisioned and synced, your gateway can send state updates to keep SmartHQ current with live readings.

For the meter device example, your gateway would update the meter state by calling POST /v2/device/state with the new meter value in the request body.

Request Body Parameters:

  • kind: Always set to device#services for service state updates.

  • deviceId: The unique identifier for your device.

  • services: An array of objects, each describing the state of a service for the device.

    • Each service object should include:
      • serviceId: Unique identifier for the service instance.
      • serviceType: The type of service (See list of services).
      • state: The current state values for the service.

  • alertTypes (optional): List of alert types triggered by the state change.

  • timestamp (optional): The time of the state report in ISO 8601 format (YYYY-MM-DDThh:mm:ss.sTZD).

  • correlationId (optional): Include this if responding to a sync state request from SmartHQ, so the event can be tracked.

Example Request Body
{
  "kind": "device#services",
  "deviceId": "e7b8a9c2-4f3a-4c1e-9a2d-2c8e2b7f8d1a",
  "services": [
    {
      "serviceId": "a3c1f2d4-5b6e-7c8d-9e0f-1a2b3c4d5e6f",
      "serviceType": "cloud.smarthq.service.meter",
      "state": {
        "meterValue": 230.5,
        "updateFrequencySeconds": 60
      }
    }
  ]
}