iBKS Card Beacon GATT Reference Manual

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.

1. GATT Table. Characteristics
2. Configuration Mode
3. Services Definition
   1. Eddystone Service
   2. iBeacon Service
   3. Card Beacon Service
   4. Global Service

1. GATT Table. Characteristics

2. Configuration Mode

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.

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