Adapter Set Up¶

This page provides an overview of the setup required to integrate external gateways and devices with SmartHQ using the Device Adapter API.

Integrating with SmartHQ involves creating and hosting an adapter—a software component that acts as a bridge between SmartHQ and your devices or gateways. The adapter receives messages from SmartHQ, forwards requests to the appropriate gateway or device, and reports device state and events back to SmartHQ.

The sections below outline how register your adapter, and configure endpoints so SmartHQ can communicate with your system.

Setting Up An Adapter¶

An adapter is a software component that acts as a bridge between SmartHQ and your devices or gateways.

1. Create and Host the Adapter

Develop and deploy an adapter.
The adapter must be created and hosted by the integrator or third-party developer.

2. Obtain Adapter Credentials

Contact a SmartHQ administrator to request adapter credentials.
The administrator will generate and provide an Adapter ID and Adapter Secret for authenticating API requests.

3. Complete Credential Setup

Visit the Adapter Credentials page for instructions on how to use your credentials and complete the setup process.

The endpoints that an adapter calls directly with its own credentials are:

Note

Please review Adapter Credentials for more information.

Setting Up An Adapter Endpoint¶

The adapter must provide one callback endpoint that can handle all incoming message types from SmartHQ.

The endpoint URL must be supplied to SmartHQ so that a SmartHQ administrator can register it in the system.

Protocols Supported¶

SmartHQ supports two delivery mechanisms:

HTTPS POST
- The endpoint must accept HTTPS requests from SmartHQ.
- After successfully processing a message, the endpoint should return HTTP 200 OK.
Amazon SNS
- To receive messages via SNS, configure an SNS topic in an AWS account.
- SmartHQ must be granted permission to publish to the SNS topic by adding an appropriate policy.
Example SNS Topic Policy:
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SnsTopicPolicy",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<SHS-PROD-AWS-ID>:root"
      },
      "Action": "sns:Publish",
      "Resource": "arn:aws:sns:us-east-1:<YOUR-AWS-ID>:<SNS-TOPIC-NAME>"
    }
  ]
}
```
- Replace <SHS-PROD-AWS-ID> with SmartHQ's AWS account ID. (Contact SmartHQ)
- Replace <YOUR-AWS-ID> with the AWS account ID.
- Replace <SNS-TOPIC-NAME> with the SNS topic name.
For more details on SNS topic policies, see AWS SNS documentation.

Securing the Callback Endpoint¶

It is highly recommended to use a static, pre-shared key (PSK) for authenticating callback messages.

Why use a PSK?

It helps prevent unauthorized access by ensuring that only requests containing the correct key are accepted.
Avoids leaving the API endpoint open and unauthenticated on the Internet.

How to use:

Generate a strong, random PSK.
Securely communicate it to SmartHQ (do not send via insecure channels like email). We recommend One Time Secret.
SmartHQ will store the PSK and include it as a bearer token in Authorization header of callback requests. (e.g., Authorization: Bearer {pre-shared-key})
Configure the endpoint or SNS subscription to validate the PSK in incoming requests and reject any requests without the correct key.

Regions¶

One callback endpoint must be registered for each region where the adapter will operate:

eu-west-1
us-east-1
us-west-2

It is possible to:

Use the same endpoint URL for all regions, or
Provide a different endpoint per region.

Message Types¶

All incoming messages will be sent to the registered endpoint. The endpoint must be able to parse and route these message types internally.

Click on each message type for more information and payload examples.

Message Type	Description
gatewayRemoval	Notification that a gateway was removed from a user's account.
fullSync	Request for the gateway to resend all device/service states.
deviceSync	Request for the gateway to resend the state/configuration of a specific device.
removeDevice	Request for the gateway to remove a device and post a delete event.
runCommand	Request for the gateway to execute a command on a device service.