Device Provisioning

A new Konnected device must be initially provisioned or "synced" via a HTTP PUT request to the /settings device endpoint. Your application tells the Konnected device what pins (zones) to monitor as sensors, which pins (zones) are used as outputs, and the receiving API endpoint to send state changes to. Your application is responsible for the user interface to define the use for each pin (zone) and map them to user-specified device names.

PUT /settings

Make a HTTP PUT request with JSON payload to http://<device-ip>:<device-port>/settings. 

PUT /settings

{
  "endpoint_type":"rest",
  "endpoint":"http://192.168.1.123:8800/api/konnected",
  "token":"ABC123",
  "sensors":[
    {"pin":1},{"pin":2},{"pin":5},{"pin":6}
   ], 
  "actuators":[
    {"pin":8, "trigger": 1}
  ],
  "dht_sensors":[
    {"pin":7, "poll_interval":2}
  ]
}

PUT /settings

{
  "endpoint_type":"aws_iot",
  "endpoint":"wss://a35zoibxxxxxxx-ats.iot.us-east-1.amazonaws.com/mqtt",
  "aws":{ 
    "access_key":"AWS_ACCESS_KEY", 
    "secret_key":"AWS_SECRET_KEY", 
    "region":"us-east-1"
   },
  "sensors":[
    {"pin":1},{"pin":2},{"pin":5},{"pin":6}
   ],
  "dht_sensors":[
    {"pin":7, "poll_interval":2}
  ], 
  "actuators":[
    {"pin":8, "trigger": 1}
  ]
}

Parameter Reference

endpoint_type

Either rest or aws_iot depending on the integration type desired. Default rest.

endpoint

The full HTTP URI that the device will send state changes to. Your application or server must listen to this endpoint to process state changes as they are received. This address may be an internal or external host, and may use http or https.

In the case of AWS IoT integration, the endpoint is the MQTT over WebSocket endpoint provided by AWS.

token

A random string generated and stored by your application. The Konnected device will include this string in an Authorization header when calling back to your application with state updates. The application should check that the Authorization header contains the correct token to ensure the integrity of state change notifications.

This parameter is only relevant when using rest communication.

aws

The AWS parameter is a JSON object containing the access_key, secret_key, and region needed to authenticate and access the AWS platform.

Only relevant when using AWS IoT communication.

sensors

A JSON array of binary sensor definitions. This defines the pins (zones) that are connected to analog open/close sensors such as door/window sensors, motion detectors, and other simple open/close circuits.

Each JSON object represents an input on the Konnected device defined by the pin number. See the Pin Mapping documentation for a mapping of zones to pins.

actuators

A JSON array of actuator definitions. This defines the pins (zones) that are to be used as outputs for triggering a siren, relay, buzzer or other switched trigger.

Each JSON object represents an output on the Konnected device defined by the pin number and trigger level. See the Pin Mapping documentation for a mapping of zones to pins. By default trigger is assumed 1 (high) if not specified.

dht_sensors

A JSON array of DHT sensor definitions. This defines the pins (zones) that are to be used as digital inputs for reading a DHT compatible sensor and reporting the current temperature/humidity every specified interval.

Each JSON object represents an input on the Konnected device defined by the pin number and an optional poll_interval. See the Pin Mapping documentation for a mapping of zones to pins. poll_interval is specified in minutes and defaults to 3 minutes.

ds18b20_sensors

A JSON array of DS18B20 sensor definitions. This defines the pins (zones) that are to be used as digital inputs for reading one or more DS18B20 compatible one-wire sensors. Multiple sensors can be connected to the same pin. They are uniquely identified by a serial number when reporting readings.

Each JSON object represents an input on the Konnected device defined by the pin number and an optional poll_interval. See the Pin Mapping documentation for a mapping of zones to pins. poll_interval is specified in minutes and defaults to 3 minutes.

blink

true or false defining whether or not to blink the status LED on each state change successful transmission. Default true.

discovery

true or false defining whether or not to listen for and respond to SSDP requests. Default true.

Notes

After receiving a provisioning sync, the device will automatically reboot and immediately begin to report sensor state.