Eddystone Documentation

The Eddystone Configuration Service is a GATT service that runs on an Eddystone beacon when it is in a connectable state. It allows for the configuration of:

• Advertised data
• Broadcast power levels
• Advertising intervals

It also plays a role in the configuration and registration of Eddystone-EID beacons with a trusted resolver.

Eddystone is a Bluetooth Low Energy (BLE) protocol specification that defines message formats for proximity beacons. It supports various frame types that can be used individually or in combination. Key features include:

• Flexible Frame Types: Supports multiple frame formats for different applications.
• Eddystone-EID (Ephemeral ID): A frame type providing a cryptographically secure method for broadcasting information that only authorized users can decrypt.
• GATT Configuration Service: A service that enables interoperability by allowing beacons to report capabilities and allowing applications to reconfigure broadcast data. This is also required for secure configuration and registration of Eddystone-EID beacons.

The Eddystone Validator is a simple Android application used to perform basic validation of Eddystone frame types. It is intended to help implementers identify potential problems with their Eddystone format implementation.

Note: Testing is not exhaustive, and passing the validation tests does not constitute official certification.

The Eddystone Configuration Service is a GATT service used to configure Eddystone beacons. It allows for managing advertisement slots, setting advertising intervals, adjusting radio Tx power, and handling security/locking.

Service UUID: a3c87500-8ed3-4bdf-8a39-a01bebede295

Important Data Formats:

• Most data is handled as big-endian byte arrays.
• Exceptions (Little-Endian): The Public ECDH Key (Characteristic 8), the Identity Key (Characteristic 9), and the service's public ECDH key when writing an EID slot in Characteristic 10 are little-endian due to the elliptic curve-25519 reference design.

TxEddystone-UID is an Android application that enables a phone to broadcast Eddystone-UID Bluetooth Low Energy (BLE) packets. It allows you to separately configure the namespace and instance parts of the beacon ID.

Device Compatibility Notes:

• The app requires a device capable of using the BluetoothLeAdvertiser classes.
• Known compatible devices include Nexus 6, Nexus 9, and Android One devices.
• The app will display an error dialog if the device is incompatible.
• Note on MAC Addresses: The advertised device address uses private resolvable addresses that are randomly generated. This address rotates every time advertising starts and automatically rotates every few minutes during active advertising.

Eddystone-TLM (Telemetry) frames allow beacons to transmit operational data about their own health and status. This is used for monitoring fleets of beacons.

Important Implementation Notes:

• Identification: TLM frames do not contain a beacon ID. To identify which beacon sent the telemetry, you must pair the TLM frame with an identifying frame (either Eddystone-UID or Eddystone-URL) received from the same device.
• Security: TLM frames can be broadcast in the clear (unencrypted) or encrypted if the beacon is configured as Eddystone-EID.
• Integrity: When broadcast in the clear, there is no message integrity validation. Applications should be designed to be tolerant of the open nature of unencrypted broadcasts.

The Eddystone-URL Configuration Service is a Bluetooth Low Energy (BLE) service used to configure Eddystone-URL beacons.

Key Constraints:

• Connectivity: The service must only be available during Configuration Mode (connectable). It must not be available during regular URI Advertising Mode (non-connectable) to prevent Denial of Service (DoS) attacks.
• Transport: Supported on Low Energy (BLE); not supported on Classic Bluetooth.
• Configuration Mode Entry: Beacons should enter Configuration Mode via an administrator action, such as pressing a physical button or automatically for a short window (e.g., 30 seconds) after power-on.
• Advertising in Config Mode: When in Configuration Mode, the beacon should advertise a different ADV packet using the ADV long name parameter, the Eddystone-URL configuration service 128-bit UUID, and an ADV TxPower parameter.

This directory provides source code for various Eddystone-URL beacon implementations. These implementations are designed to be compiled with publicly available SDKs and development boards and serve as a guide for writing your own Eddystone-URL beacon code.

Available implementations include:

• Arduino (BLEPeripheral): Compatible hardware list available in the arduino-BLEPeripheral repository.
• BBC micro:bit
• BlueGiga BLED112
• Cambridge Silicon Radio CSR1010 (Beacon Development Board)
• PyBeacon (Python Package): For latest builds, refer to the Nirmanakarta/PyBeacon repository.
• Linux (bluez)
• ARM mbed (Nordic nRF51-dongle, nRF51-DK)
• Node.js (node-eddystone-beacon)
• RFduino
• TI-CC2640

To build the application from source, follow these steps:

1. Open Android Studio.
2. Import the TxEddystone-UID project located in this directory.
3. Select Run > Run app to build and deploy to your device.

Alternatively, you can download a pre-built APK from the project's releases.

You can modify the transmitted URL via the GATT Configuration Service:

1. Replug the dongle.
2. Within 30 seconds, scan for BLE tags. Look for a device named ES Change URL (use RSSI values to identify the closest one).
3. Connect to the device to access its services.
4. Select the Eddystone-URL Configuration Service (GATT service).
5. To change the URL, read or write to the Data characteristic.
6. Note: You must use the compression codes described in the open Eddystone specification to ensure the URL does not exceed 18 characters.
7. Disconnect from the GATT service to see the new URL transmitted by the beacon.

To develop for the BlueGiga BLED112, you must set up the BlueGiga SDK. This project was built using Bluegiga SDK 1.3.2-122.

1. Create an account at BlueGiga (use the gear icon at the top right).
2. Install the BlueGiga Development Environment.
3. By default, the installation directory is c:/Bluegiga/ble-1.3.2-122.
4. Add the BlueGiga bin directory to your Windows Path environment variable via the 'System Properties' dialog.