Build your own simple endpoint server to interact with a Konnected device.
This API definition will guide you to build a custom endpoint or server to interact with a Konnected device on the LAN or over the internet. You can also use this guide to integrate Konnected into a smart home platform or application, as long as that platform/app allows the creation of HTTP(s) endpoints.
A Konnected device is provisioned with the endpoint URL of your server or home automation hub/platform. You must implement a few simple HTTP endpoints to:
- Receive state updates from the Konnected device
- Respond with the current state of switches or actuators.
Endpoint Design
Your application should expose an endpoint at an IP address or hostname accessible by the Konnected device. This can either be on your LAN, or on a server hosted somewhere on the internet. Choose a root endpoint that is dedicated for receiving communication from Konnected, and pass that endpoint to the device in the provisioning step.
Example endpoints:
http://192.168.2.100:8000/api/konnectedhttp://my-home-automation-hub.local/https://my-cloud-server.org/api/konnected
The Konnected will add /device/<DEVICE_ID> to the root endpoint, so your application should accept path parameters and store information about each device by its 12-character hexadecimal Device ID. This Device ID is unique and cannot change.
Authentication
In the device provisioning step, a token is required. This is a shared secret that is provisioned to the Konnected device, and also should be stored on your endpoint application. When Konnected makes HTTP calls to your endpoint, the token will be passed in an Authentication: Bearer <token> HTTP header.
Your application should check for this token and make sure that the token passed matches the shared secret stored in your application. Only requests with a valid token should be honored.
Receive State Updates
When a Konnected device sensor zone state changes, the device will PUT an update to the endpoint with a JSON payload of the current state of the zone. See Get State for details.
Respond With Current State
The desired state of switches and actuators (such as sirens, buzzers, on/off switches) wired to a Konnected output zone is controlled by your application. When the Konnected device boots or reboots, it will issue a GET request to the endpoint to refresh the desired current state of every switch, siren and actuator. Your application should respond with the desired state of the switch. See Update State for details.