ABSTRACT
This document explains the Generic Attributes (GATT) of iBKS Card Beacon services and characteristics which includes iBeacon Service, Eddystone Service, Card Beacon Service and Global Service
AUDIENCE
This document is primarily for App developers and advanced users.
Firmware version related: EDSTEID V5.2016.06.29.1 or newer versions
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 |
---|---|---|
Card Beacon Service | 0xFB00 | |
Static Mode | 0xFB01 | 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 resumes to configured state (connectable/non-connectable/connectable window/static mode) and start 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, data written and read 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] (D8:EC:F0:F4:F8:FC:00:03: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. (Independent in this context means full ECDH key exchange to generate the EID with separate identity keys and clock values.)
- 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 CARD BEACON 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
- Card Beacon Service
- UUID
- 0xFB00
- Notes
- The characteristics of this service are locked when the Eddystone service is locked.
Characteristic 1
- Name
- Static Mode
- UUID
- 0xFB01
- Properties
- uint8_t get_static_mode (read)
uint8_t set_static_mode (write)
Length: 1 byte - Description
- Read: Reads a byte value that indicates the current static mode. Static mode values are:
0x00: OFF (Default)
0x01: ONWrite: Write 1 byte to set the static mode
0x00: Turns Off the static mode (Card Beacon always advertises)
0x01: Turns On the static mode (Card Beacon only advertises when moving). - Lock requirement
- Must be unlocked for write.
3.4 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: January 15, 2018