iBKS GATT Reference Manual

ABSTRACT

This document explains the Generic Attributes (GATT) of iBKS beacon services and characteristics which include iBeacon Service, Eddystone Service and Global Service.

AUDIENCE

This document is primarily for App developers and advanced users.

IMPORTANT:
Firmware version related: EDSTEID V5.2016.06.29.1 or newer versions
  1. GATT Table. Characteristics
  2. Configuration Mode
  3. Services Definition
    1. Eddystone Service
    2. iBeacon Service
    3. Global Service

1. GATT Table. Characteristics

Name UUID N. bytes
Beacon Slot Service 0xa3c87500-8ed3-4bdf-8a39-a012bebede295
Broadcast Capabilities 7501 >=7
Active Slot 7502 1
Advertising Interval 7503 2
Radio Tx Power 7504 1
(Advanced) Advertised Tx Power 7505 1
Lock State 7506 1 or 17
Unlock 7507 16
Public ECDH Key 7508 32
EID Identity Key 7509 16
Read/Write ADV Slot 750A <=34
(Advanced) Factory Reset 750B 1
(Advanced) Remain Connectable 750C 1

 

Name UUID N. bytes
iBeacon Service 0xFA00
iBeacon slot active 0xFA01 1
iBeacon advertising interval 0xFA02 2
iBeacon Cal power 0xFA04 1
iBeacon UUID:Major:Minor 0xFA05 1 or 20
iBeacon Extra byte 0xFA06 1
Name UUID N. bytes
Global Service 0xFF00
Device Name 0xFF01 <=20
GATT version 0xFF02 <=20
Connectable period 0xFF03 3
Connectable window 0xFF04 3
Firmware update 0xFF05 1
Actual hour 0xFF06 2
Advertising On hour 0xFF07 1
Advertising Off hour 0xFF08 1

2. Configuration Mode

After the power up and during 30 seconds, the beacon is in connectable mode and advertises the configured slots and an additional packet with the Eddystone Service UUID.

After these first 30 seconds, the beacon returns to configured state (connectable/non-connectable/connectable window) and starts the advertising of the active slots.

3. Services Definition

3.1 EDDYSTONE SERVICE

Service definition
Name
Eddystone Configuration Service
UUID
a3c87500-8ed3-4bdf-8a39-a01bebede295
Notes
Where not explicitly stated, written and readable data is defined in terms of big-endian arrays of signed bytes.
Characteristic 1
Name
Broadcast Capabilities
UUID
a3c87501-8ed3-4bdf-8a39-a01bebede295
Properties
byte array (read) {
version_byte (0x00),
max_supported_total_slots (0x04),
max_supported_eid_slots (0x01),
capabilities_bit_field (0x03),
supported_frame_types_bit_field[0] (0x00),
supported_frame_types_bit_field[1] (0x0F),
supported_radio_tx_power[0] … supported_radio_tx_power[N1] (E2:EC:F0:F4:F8:FC:00:04)
}
Length: >= 7 bytes
Description
Only Read: It returns a byte array that encodes:

  • 8bit version of this spec, 0x00 in this instance.
  • 8bit value of the maximum number of slots this beacon is capable of broadcasting concurrently, including EID slots. This is the total number of advertisement frames the beacon is capable of broadcasting concurrently.
  • 8bit value of the maximum number of independent EID slots this beacon is capable of broadcasting. (Independent in this context means full ECDH key exchange to generate the EID with separate identity keys and clock values.)
  • 8bit bit field encoding the following properties:
    • 0x01: IS_VARIABLE_ADV_SUPPORTED set if the beacon supports individual per slot advertising intervals; unset if the beacon supports only a global advertising interval.
    • 0x02: IS_VARIABLE_TX_POWER_SUPPORTED set if the beacon supports individual per slot Tx powers; unset if the beacon supports only a single global Tx power.
    • 0x04 through 0x80: RFU and must be unset.
  • 16bit
    bit field encoding the supported frame types:

    • 0x0001: UID
    • 0x0002: URL
    • 0x0004: TLM
    • 0x0008: EID
    • 0x0010 through 0x8000 RFU and must be unset
  • A variable length array of the supported radio Tx power absolute (dBm) values.
Lock requirement
Readable only when unlocked. Never writable.
Characteristic 2
Name
Active Slot
UUID
a3c87502-8ed3-4bdf-8a39-a01bebede295
Properties
uint8_t get_active_slot (read)
uint8_t set_active_slot (write)
Length: 1 byte
Description
Read/Write: It reads and writes the active slot number, 0-indexed.
The default value is 0 when a new connection is made from a configuration client.
Subsequent writing to other characteristics will act on this slot number, configuring the Tx power, advertising interval, and data for it.
Lock requirement
Must be unlocked for both reading and writing.
Characteristic 3
Name
Advertising Interval
UUID
a3c87503-8ed3-4bdf-8a39-a01bebede295
Properties
uint16_t get_adv_interval (read)
uint16_t set_adv_interval (write)
Length: 2 byte
Description
Read/Write: It reads and writes the advertising interval (ms) for the active slot.
If two slots are scheduled to broadcast at the same time, or the time between two transmissions is less than the shortest permissible advertising interval, then the advertisings will be transmitting in order at the shortest AI (40ms).
The minimum value for advertising interval is 100ms, and 1000ms for TLM frame. The maximum is 10000ms except for the TLM slot that allows setting until 65535ms if there’s more than one slot configured.
Lock requirement
Must be unlocked for both reading and writing.
Characteristic 4
Name
Radio Tx Power
UUID
a3c87504-8ed3-4bdf-8a39-a01bebede295
Properties
Int8_t get_radio_tx_power (read)
Int8_t set_ radio_tx_power (write)
Length: 1 byte
Description
Read/Write: It reads and writes the desired radio Tx power for the active slot (in two’s complement). If it writes any value different from the supported radio Tx power values, it gets an error.
Lock requirement
Must be unlocked for both reading and writing.
Characteristic 5
Name
(Advanced) Advertised Tx Power
UUID
a3c87505-8ed3-4bdf-8a39-a01bebede295
Properties
int8_t get_advertised_tx_power (read)
int8_t set_advertised_tx_power (write)
Length: 1 byte
Description
Read/Write: It writes a value that is used as the Tx power that is advertised in the EddystoneUID, URL, and EID frame types. If it is not set, the Tx power advertised in those frames is the value set in the Radio Tx Power characteristic. The values range is from -126dBm to 127dBm.
This value is used to calibrate the advertised power at 0m received by the central (takes into account the antenna loss).
This characteristic is available as an advanced deployed option and always keeps the last modified one: If after changing this characteristic (7505), the Tx power characteristic (7504) is modified, the advertised Tx power (7505) will also modify its value to the same introduced in 7504 and, therefore, in 7505 we will read the same value as in 7504. However, if 7505 is the latest modified for both, the Tx power advertised would be the one defined in 7505.
Lock requirement
Must be unlocked for both reading and writing.
Characteristic 6
Name
Lock State
UUID
a3c87506-8ed3-4bdf-8a39-a01bebede295
Properties
uint8_t lock_state (read)

byte_array (write) {
lock_byte,
encrypted_key[0] … encrypted_key[15]
}

Length (read): 1 byte
Length (write): 1 or 17 byte

Description
Read: It reads a byte value that indicates the current lock state. Status
values are:

  • 0x00: LOCKED
  • 0x01: UNLOCKED
  • 0x02: UNLOCKED AND AUTOMATIC RELOCK DISABLED

Write: Write 1 byte or 17 bytes to transition to a new lock state:

  • 0x00: A single byte of 0x00 written to this characteristic will transition the interface to the LOCKED state without changing the current security key value.
  • 0x00 + key[16]: A single byte of 0x00 followed by a 16 byte encrypted key value written for this characteristic will transition the interface to the LOCKED state and update the security key to the unencrypted value of key[16]. To prevent the new lock code from being broadcast in the clear, the client shall AES128ECB encrypt the new code with the existing lock code:
    (key[16] = encrypt(key=actual_lock_code[16], text=new_lock_code[16]))
  • 0x02: A single byte of 0x02 written to this characteristic will disable the automatic relocking capacity of the interface.

By default, the lock state is 0x02.

Lock requirement
Readable in locked or unlocked state.
Writeable only in unlocked state.
Characteristic 7
Name
Unlock
UUID
a3c87507-8ed3-4bdf-8a39-a01bebede295
Properties
byte_array (read) {
challenge[0] … challenge[15]
}
byte_array (write) {
unlock_token[0] … unlock_token[15]
}
Length: 16 bytes
Description
It writes to a beacon and sets it to the unlock state, protected from configuration changes or reading sensitive information.
Read: it returns a 128bit challenge token. This token is for one time use.
Write: it accepts a 128bit-encrypted value that verifies that the client knows the beacon’s lock code.
To create the unlocked token, it first reads the randomly generated 16 byte challenge and generates it using AES128ECB.
unlocking token = encrypt(key=beacon_lock_code[16], text=challenge[16])
If the introduced unlocking token is correct, lock state sets to 0x01.
By default, the beacon_lock_code[16] is set to 0’s.
Lock requirement
Readable only in locked state.
Writeable only in locked state.
Characteristic 8
Name
Public ECDH Hey
UUID
a3c87508-8ed3-4bdf-8a39-a01bebede295
Properties
byte_array (read) {
key[0] … key[31]
}
Length: 32 bytes
Description
Only Read: It reads the beacon’s 256bit public ECDH key.
Lock requirement
Readable only in unlocked state
Characteristic 9
Name
EID Identity Key
UUID
a3c87509-8ed3-4bdf-8a39-a01bebede295
Properties
byte array (read) {
encrypted_ik[0] … encrypted_ik[15]
}
Length: 16 bytes
Description
Only Read: It reads the identity key for the active slot. If the slot isn’t configured as EID, it returns an error.
To prevent this data being broadcast in the clear, its AES128 encrypted with the lock code for the beacon.
Lock requirement
Readable only in unlocked state
Characteristic 10
Name
Read/Write ADV Slot
UUID
a3c8750A-8ed3-4bdf-8a39-a01bebede295
Properties
byte array (read/write) {
frame_type,
data[0] … data[N]
}
Write length: 17 bytes (UID), 19 bytes (URL), 2 byte (TLM), 34 bytes (EID)
Read length: 18 bytes (UID), <=20bytes(URL), 14 bytes (TLM), 18 bytes (eTLM), 14 bytes (EID)
Description
It reads the data set in the active slot, and sets the data/parameters to be broadcast. The interpretation of the read and written data is characterized by the frame_type byte, which maps to the Eddystone frame type bytes of 0x00 (UID), 0x10 (URL), 0x20 (TLM), 0x30 (EID).
Read: In the case of a UID, URL or TLM frame, the length and data are those of the broadcast data, including any adjustments to the advertised Tx power applied via the Tx power calibration table.
If the slot is configured to advertise EID frames, the length is 14:
1 byte frame type, 1 byte exponent, 4byte clock value, 8byte EID.
These are the parameters required for registration, along with the beacon’s public key, which is exposed through a separate characteristic, and the resolver’s public key, which the provisioning/registering beacon knows.
Write: In the case of UID and URL frames, the data to be broadcast is supplied in the array after the frame type. UID is 16 bytes of namespace + instance,  the URL is up to 18 bytes.
In the case of a TLM frame, the data is just the frame type byte, 0x20.
If another slot on the beacon has been configured as an EID frame type, the beacon broadcasts the ETLM variety of telemetry. Otherwise, the plain TLM is broadcast.
In the case of an EID frame, the length is 34: frame type 0x30, the
32byte service’s public ECDH key and the exponent byte.
Writing an empty array clears the slot and stops Tx. If it has been configured as an EID beacon this will also destroy the peripheral’s state for this frame data and it will generate a new public ECDH key and the device will return to the original MAC.
The maximum number of slots that can be configured as TLM is 1 (as EID frame). The URL and UID frames can be configured in multiple slots.
Lock requirement
Must be unlocked for both reading and writing.
Characteristic 11
Name
(Advanced) Factory reset
UUID
a3c8750B-8ed3-4bdf-8a39-a01bebede295
Properties
uint8_t reset_bool (write)
Length: 1 byte
Description
Only Write: If a value of 0x0B is written, the beacon resets it to its factory state. This does not include the unlock key, which remains set to its current value. All slot data (including EID identity keys) are destroyed.
In addition, any writing shall be ignored if the lock state is different from 0x01.
Lock requirement
Must be unlocked to write. Lock state must be 0x01.
Characteristic 12
Name
(Advanced) Remain Connectable
UUID
a3c8750C-8ed3-4bdf-8a39-a01bebede295
Properties
uint8_t is_non_connectable_supported (read)
uint8_t remain_connectable_bool (write)
Length: 1 byte
Description
Read: On read, returning a non-zero value indicates that the beacon is capable of becoming non-connectable. Returning a zero value indicates that the beacon is limited to running in an always connectable state. In our case, the beacon is capable of becoming non-connectable.
Write: Writing a zero value will transition the beacon to a non-connectable state after the client disconnects. If any non-zero value is written, the beacon shall remain in its connectable state until any other value is written.
If a zero value is written, the beacon shall resume its normal operation of becoming non-connectable after the central disconnects.
This characteristic is not compatible with Characteristics 3 and 4 of Global Service, and always remains the last one to be configured. If a connectable window is configured and after this characteristic is set, the state defined in this characteristic will remain. If this characteristic is set and after a connectable window is configured, the connectable window will remain. To know more about different cases, look at Table 1 of characteristic 3(0xFF03) of Global Service.
By default the beacon is always connectable and the connectable window disabled.
Lock requirement
Must be unlocked for writing.

3.2 IBEACON SERVICE

This service is used to configure 1 or 2 additional slots (Max. 2 ibeacon slots) as an iBeacon frame. These slots are added to the queue of the Eddystone slots.

Service definition
Name
iBeacon Service
UUID
0xFA00
Notes
The characteristics of this service are locked when the Eddystone service is locked.
Characteristic 1
Name
iBeacon Active
UUID
0xFA01
Properties
uint8_t is_ibeacon_active (write/read)
Length: 1 byte
Description
Write/Read: It reads and writes the active slot number, 0-indexed.
The default value is 0 when a new connection is made from a configuration client.
Subsequent writing to other characteristics will act on this slot number, configuring the Tx power, advertising interval, UUID, Major and Minor and extra byte for it.
Characteristic 2
Name
iBeacon advertising interval
UUID
0xFA02
Properties
uint16_t get_adv_interval (read)
uint16_t set_adv_interval (write)
Length: 2 byte
Description
Read/Write: It reads and writes the advertising interval (ms) for the iBeacon slot. The minimum value admitted is 100ms.
Characteristic 3
Name
iBeacon Tx power
UUID
0xFA03
Properties
Int8_t get_radio_tx_power (read)
Int8_t set_ radio_tx_power (write)
Length: 1 byte
Description
Read/Write:It reads and writes the desired radio Tx power for the iBeacon slot (in two’s complement)
Characteristic 4
Name
iBeacon Cal power
UUID
0xFA04
Properties
int8_t get_advertised_tx_power (read)
int8_t set_advertised_tx_power (write)
Length: 1 byte
Description
Read/Write: It writes a value that is used as the Tx power that is advertised in iBeacon packet. If it is not set, the Tx power advertised is the value set in the Radio Tx Power characteristic.
This value is used to calibrate the advertised power at 1m received by the central (takes into account the antenna loss).
This characteristic is available as an advanced deployed option and always remains the last one to be modified (between Txpower and Cal power). If after changing this characteristic (FA04), the Tx power characteristic (FA03) is modified, the cal power (FA04) will also modify its value to the same one introduced in FA03 and, therefore, in FA04 the same value as in FA03 will be read. However, if FA04 is the latest modified for both, the Tx power advertised will be the defined in FA04.
Characteristic 5
Name
iBeacon UUID:Major:Minor
UUID
0xFA05
Properties
byte_array (read/write) {
UUID[0] … UUID[15],
Major[0],Major[1],
Minor[0],Minor[1]
}
Length: 20 bytes
Description
Read: It reads the desired UUID, Major and Minor for the iBeacon slot. If the read value is an only byte with value ‘0’, the slot is deactivated.
Write: It writes the desired UUID, Major and Minor for the iBeacon slot. Writing a unique byte (length=1) with value ‘0’, clears the slot and stops the advertising of this slot.
Characteristic 6
Name
iBeacon Extra Byte
UUID
0xFA06
Properties
uint8_t get_extrabyte_active (read)
uint8_t set_extrabyte_active (write)
Length: 1 byte
Description
Read/Write:It reads and writes the activation of an extra byte (sets an additional byte to the ibeacon packet with % of battery level). If any non-zero value is written, the extra byte is active. If a zero value is written the extra byte is inactive.

3.3 GLOBAL SERVICE

Service definition
Name
Gobal Service
UUID
0xFF00
Notes
The characteristics of this service are locked when the Eddystone service is locked.
Characteristic 1
Name<
Device Name
UUID
0xFF01
Properties
byte_array (read) {
char[0]…char[20]
}
Length <= 20 bytes
Description
Write/Read:It writes and reads the device name. If this value is changed the beacon resets after disconnection.
Characteristic 2
Name
GATT version
UUID
0xFF02
Properties
byte_array (read) {
char[0]…char[19]
}
Length <= 20 bytes
Description
Only read: It returns the GATT version used in this firmware.
Characteristic 3
Name
Connectable period
UUID
0xFF03
Properties
byte_array (read/write) {
period[0]…period[2]
}
Length: 3 bytes
Description
The “connectable period” and “connectable window” characteristics allow us to configure a window of time while the device is in connectable mode.
Read/Write: It writes the period of how often the beacon starts the connectable window (in seconds). Reads the same value.
The connectable window is not compatible with Characteristics 12 (0x750C) of Eddystone Service, and always remains the last one to be configured. If a connectable window is configured and after, the char 0x750C is set, the state defined in char 0x750C will remain. If char 0x750C is set and after, a connectable window is configured, the connectable window will remain.
Table1: Configuration cases
Characteristic Case1 Case2 Case 3
Last activated Remain conn. Remain conn. Conn. window
Remain connectable 0x00 0x01
Connectable period 0xFFFFFF 0x000000 Desired conn. period
Connectable window 0xFFFFFF 0x000000 Desired conn. window
Advertising Always non-connectable Always connectable Connectable window active
Characteristic 4
Name
Connectable window
UUID
0xFF04
Properties
byte_array (read/write) {
window[0]…window[2]
}
Length: 3 bytes
Description
Read/Write: It writes how long the connectable window is (in seconds). It reads the same value.
The connectable window is not compatible with Characteristics 12 (0x750C) of Eddystone Service, and always remains the last one to be configured. If a connectable window is configured and after, the char 0x750C is set, the state defined in char 0x750C will remain. If char 0x750C is set and after, a connectable window is configured, the connectable window will remain. To know more about different cases, look at Table 1 of characteristic 3 (0xFF03).
Characteristic 5
Name
Firmware update mode
UUID
0xFF05
Properties
uint8_t set_fw_update (write)
Length: 1 byte
Description
Only Write: Writing a 0x01, the beacon starts in DFU mode after the user disconnects from the beacon. When entering in DFU mode, be sure that you will upgrade FW, the beacon only returns to beacon mode after the upgrade.
Characteristic 6
Name
Actual hour
UUID
0xFF06
Properties
byte_array (read/write) {
act_hour[0]…act_hour[1]
}
Length: 2 bytes
Description
Read/Write: It writes the current hour in minutes (i.e. 17:18h = 0x040E). Using the characteristics 0xFF06, 0xFF07 and 0xFF08, it’s possible to program the on and off of the advertising. This characteristic (x0FF06) allows us to synchronize the beacon with the real time and should be written after configuring characteristics 0xFF07 and 0xFF08 to activate this function.
If characteristics 0xFF06, 0xFF07 and 0xFF08 are set to zero value the advertising ON/OFF is deactivated.
When the beacon is power-down, these 3 characteristics are set to ‘0’ and advertising always remains active until these 3 characteristics are configured again.
Characteristic 7
Name
Advertising On hour
UUID
0xFF07
Properties
uint8_t get_on_hour_active (read)
uint8_t set_on_hour_active (write)
Length: 1 byte
Description
Read/Write: It writes the hour (in resolution of hours) that the advertising should start. After the modification of this characteristic the char 0xFF06 should be set to be synchronized. For more information on this feature, look at characteristic 0xFF06.
Note: The difference between ON and OFF must be lower than 17 hours.
Characteristic 8
Name
Advertising Off hour
UUID
0xFF08
Properties
uint8_t get_off_hour_active (read)
uint8_t set_off_hour_active (write)
Length: 1 byte
Description
Read/Write: It writes the hour (in resolution of hours) that the advertising should stop. After the modification of this characteristic the char 0xFF06 should be set to be synchronized. For more information on this feature, look at characteristic 0xFF06.
Note: The difference between ON and OFF must be lower than 17 hours.

Last modified: November 11, 2016

CONTACT US

Lead Source
Lead Status
Lead Status

Max File(s) size limit is 20 MB