Skip to content


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


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 backend (through Panel or API)
  • Encrypted pending configuration is downloaded from servers to by an intermediary device (e.g. a smartphone with 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 backend
  • 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


If you use tools provided by, 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 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 backend. For example, the device's alias - an alternative name or a description - only exists in the 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.


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 Panel, Administration Apps for iOS and Android or in your own application, thanks to Mobile SDKs. Underneath, all these solutions use API to communicate with backend, where configs are ultimately created. 3rd-party developers can also freely use this method.

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


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


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/;version=10
Api-Key: yourSuperSecretAPIKey
Connection: close
User-Agent: Paw/3.1.4 (Macintosh; OS X/10.13.3) GCDHTTPRequest


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 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 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 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/;version=10
Api-Key: yourSuperSecretAPIKey
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Connection: close
User-Agent: Paw/3.1.4 (Macintosh; OS X/10.13.4) GCDHTTPRequest
Content-Length: 112


Once that's done and properly verified, the pending config gets deleted and 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 backend.