API Reference
These docs are for v1.0. Click to read the latest docs for v2.0.

Overview of how Konnected devices connect to AWS IoT and how you can build a private cloud application for your Konnected devices.

📘

This section assumes you are familiar with the basics of AWS IoT, a cloud hosted Internet of Things platform by Amazon Web Services.

Konnected's cloud service is built on AWS IoT and other AWS services including Lambda and DynamoDB. Developers and custom integrators can leverage the same AWS IoT connection that securely connects tens of thousands of Konnected devices around the globe for their own private cloud platform, service, or app.

Getting Started with AWS IoT and Konnected

Konnected's firmware already has built-in support for AWS IoT connectivity. All you need to do is set up your AWS IoT Core to authenticate devices and act upon messages. This guide will walk you through the general setup of AWS IoT Core so that you can start building a custom application on AWS that interacts with Konnected devices in real-time.

Endpoint

Start by signing in to your AWS console and navigate to Services > Internet of Things > IoT Core.

Find your IoT Device data endpoint on the Settings page within IoT Core. This is the hostname of the Endpoint value to pass to the Konnected device in the Device Provisioning step.

1341

For ESP8266 based devices only, set the endpoint value in the device provisioning step to the endpoint hostname from the IoT Core settings wrapped in the wss:// protocol and /mqtt path, for example: wss://a35zoixxxxxxxx-ats.iot.us-east-1.amazonaws.com/mqtt

ESP32 based devices should be passed only the endpoint hostname as-is.

See example provisioning payloads for AWS IoT here

MQTT Topics

Konnected devices will publish messages to a MQTT Topic any time a sensor state changes, and subscribes to a separate topic to receive commands to turn on/off a switch, siren, piezo, or other actuator.

In addition, Konnected will send a heartbeat to a separate topic every 5 minutes with some device diagnostic data, so that your cloud platform can keep track of devices online and their state.

You pass the topics to be used by the Konnected device in the Device Provisioning step as part of the aws configuration object. We recommend provisioning a unique topic string for each device, using the device ID in the topic string. For example, a device with ID 8840f5209948 may be provisioned topics as shown:

{
  ...
  "aws":{
    ...
    "topics":{
      "sensor":"konnected/8840f5209948/sensor",
      "switch":"konnected/8840f5209948/switch",
      "heartbeat":"konnected/8840f5209948/hb"
    }
  }
}

Konnected will publish to the sensor and heartbeat topics, and will subscribe to the switch topic.

Using Basic Ingest

You can save on AWS IoT messaging costs by using Basic Ingest topic strings if you don't need full-blown publish/subscribe capability on your Konnected sensor state changes or heartbeats. For example, if you only need to invoke a Lambda function or insert a record into a database upon receiving a message published from Konnected, you can use a basic ingest topic string to trigger an AWS IoT rule action directly.

In this case, your topic configuration may look something like:

{
  ...
  "aws":{
    ...
    "topics":{
      "sensor":"$aws/rules/iot_sensor_rule/8840f5209948/sensor",
      "switch":"konnected/8840f5209948/switch",
      "heartbeat":"$aws/rules/iot_heartbeat_rule/8840f5209948/hb"
    }
  }
}

Authentication and Identity

AWS IoT devices, or "Things" as they're called, must authenticate with your IoT Core services. Authenticating with AWS IoT grants the Konnected device permission to connect to the IoT Core, publish, and subscribe to topics via AWS policies.

ESP8266 and ESP32 based devices connect and authenticate to AWS IoT core differently.

  • ESP8266 based devices, including the Konnected Alarm Panel, Add-on Panel, and Garage Door Opener v1 connect to AWS using MQTT over WebSocket protocol and authenticate using Custom authentication .
  • ESP32 based devices, including the Konnected Alarm Panel Pro, connect to AWS using MQTT and authenticate via an X.509 client certificate.

More details on AWS IoT Device communication protocols here.