Skip to content

Configuration

Changing configuration of Kontakt.io devices involves not only direct communication with beacons over Bluetooth, but also requires specific preparation on the backend side as well.

Overview

On a higher level, the configuration process can be dividend into few steps:

  • Manager of a beacon creates a new pending configuration for a specific device using Kontakt.io backend (through Kontakt.io Panel or API)
  • Encrypted pending configuration is downloaded from Kontakt.io servers to by an intermediary device (e.g. a smartphone with Kontakt.io Administration app, or a Gateway GW17-2) that can connect to a beacon via Bluetooth
  • Intermediary device writes the encrypted package with a pending configuration to a beacon
  • Beacon verifies if the configuration is valid and change its parameters if everything checks out
  • If everything goes well, intermediary device receives an encrypted confirmation from a beacon that it needs to forward to Kontakt.io backend
  • Kontakt.io servers verify whether the response from a beacon is OK or not, and delete pending configuration and update records for a given beacons if the process ended without an error

Info

If you use tools provided by Kontakt.io, like Panel, Administration App and/or mobile SDKs, you don't have to worry about the intricacies of this process. They are handled for your by our tools. Nevertheless, it's good to know what happens "under-the-hood" in case you will need to troubleshoot some issues.

Device attributes

If you were to check a configuration of any device assigned to your account, you would see a number of various attributes that describe all of your beacons. These attributes come in one of three flavors:

  • Physical device attributes
  • Virtual device attributes
  • Read-only device attributes

Physical attributes belong to a device. txPower is a good example - a value of this parameter determines the power that device uses to transmits Bluetooth advertising packets. The txPower value is stored on the physical device, in its local memory. Additionally, a copy is stored in the Kontakt.io cloud.

Virtual attributes are device attributes that do not belong to physical device, but are associate with the extended presence of the device on the Kontakt.io backend. For example, the device's alias - an alternative name or a description - only exists in the Kontakt.io cloud, it isn't stored physically on the device.

Read-only attributes are values that cannot be changed, either by a Manager or at all. For example, the device type (BEACON, GATEWAY, etc.) cannot be changed. Read-only attributes can be both physical or virtual.

Note

Following instructions refer only to changing physical attributes. The rest is described at the end of this article.

Creating a new configuration

You can create a new configuration in Kontakt.io Panel, Administration Apps for iOS and Android or in your own application, thanks to Kontakt.io Mobile SDKs. Underneath, all these solutions use Kontakt.io API to communicate with Kontakt.io backend, where configs are ultimately created. 3rd-party developers can also freely use this method.

Documentation for the relevant API endpoint is available in Kontakt.io API Reference.

Example:

POST /config/create HTTP/1.1
Accept: application/vnd.com.kontakt+json;version=10
Api-Key: yourSuperSecretAPIKey
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: api.kontakt.io
Connection: close
User-Agent: Paw/3.1.4 (Macintosh; OS X/10.13.2) GCDHTTPRequest
Content-Length: 126

uniqueId=vbsU&deviceType=BEACON&powerSaving.features=&minor=55&accelerometer.doubleTap.detectionFlags=X_AXIS%2CY_AXIS%2CZ_AXIS

Encrypting a config

The result of creating a config for a beacon with the aforementioned API endpoint is just a JSON with new parameters. However, an actual device will not accept a configuration in such form. It needs to be encrypted first. In order to get it you need to call this endpoint:

GET /config/encrypt?uniqueId=vbsU HTTP/1.1
Accept: application/vnd.com.kontakt+json;version=10
Api-Key: yourSuperSecretAPIKey
Host: api.kontakt.io
Connection: close
User-Agent: Paw/3.1.4 (Macintosh; OS X/10.13.3) GCDHTTPRequest

Important

A configuration for a given beacon first has to be created before it can be encrypted

Secure commands

A command is a secure configuration packet that can force a beacon to do one of following actions:

  • restart
  • enter non-connectable mode (nRF51-based devices only)
  • enter bootloader mode

To create a command that can be sent to beacon, a request to GET /command/encrypt must be made. In response there will be encrypted packet, similar to a secure configuration packet. The only difference between secure config and secure command is that secure commands trigger no response from beacon that needs to be sent back to Kontakt.io Cloud (more about this in next paragraphs).

Applying the config

From the GET /config/encrypt endpoint you will get Base64-encoded binary that contains the encrypted configuration. It needs to be written to beacon's Configuration Service, specifically to Request Characteristic - 81F1. Once that Request (encrypted config) is processed, a Secure Response will be available from the Response Characteristic - 81F2. Polling Control Point Characteristic - 81F4 lets us know when the Request processing has ended and Secure Response became available in the Response Characteristic.

Updating API

When a configuration is applied, all that's left is to update Kontakt.io backend about this event. Without doing this the backend will still return old configuration value and the configuration that you've created will still be pending.

In order to synchronize the state of the newly configured beacon with Kontakt.io Cloud, the Secure Response that has been read from the Response Characteristic has to be sent in the POST /device/update request:

POST /device/update HTTP/1.1
Accept: application/vnd.com.kontakt+json;version=10
Api-Key: yourSuperSecretAPIKey
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: api.kontakt.io
Connection: close
User-Agent: Paw/3.1.4 (Macintosh; OS X/10.13.4) GCDHTTPRequest
Content-Length: 112

uniqueId=pf86&response=AAEQIgCMnNRaGS0vnGIgiJ0MkGxT9fJH91ocb8WpFy4YPm3Ckz4B&updated=1523883321&deviceType=BEACON

Once that's done and properly verified, the pending config gets deleted and Kontakt.io API and Panel will present new configuration values.

Updating with raw values

The POST /device/update endpoint allows directly specifying new values for certain beacon attributes. However, this should be only use to update virtual attributes, like tags or notes. Modifying e.g. iBeacon Major or Minor values would only cause a discrepancy between a beacon and its representation in Kontakt.io backend.