RESUMEN

Este documento explica los Atributos Genéricos (GATT) de los servicios y características del iBKS Card Beacon, que incluye Servicio iBeacon, Servicio Eddystone, Servicio Card Beacon y Servicio Global

PÚBLICO

Este documento es principalmente para desarrolladores de aplicaciones y usuarios avanzados.

1. Tabla GATT. Características
2. Modo de Configuración
3. Definición de Servicios
   1. Servicio Eddystone
   2. Servicio iBeacon
   3. Servicio Card Beacon
   4. Servicio Global

1. Tabla GATT. Características

2. Modo de Configuración

3. Definición de Servicios

3.1 SERVICIO EDDYSTONE

Definición del servicio

Nombre

Servicio de Configuración Eddystone

UUID

a3c87500-8ed3-4bdf-8a39-a01bebede295

Notas

Donde no se indique explícitamente, los datos escritos y leídos se definen en términos de matrices big-endian de bytes con signo.

Característica 1

Nombre

Capacidades de Transmisión

UUID

a3c87501-8ed3-4bdf-8a39-a01bebede295

Propiedades

matriz de bytes (lectura) {
versión_byte (0x00),
ranuras_totales_soportadas_max (0x04),
ranuras_eid_soportadas_max (0x01),
campo_de_bits_de_capacidades (0x03),
campo_de_bits_de_tipos_de_trama_soportados[0] (0x00),
campo_de_bits_de_tipos_de_trama_soportados[1] (0x0F),
potencias_de_radio_tx_soportadas[0] … potencias_de_radio_tx_soportadas[N1] (D8:EC:F0:F4:F8:FC:00:03:04)
}
Longitud: >= 7 bytes

Descripción

Solo Lectura: Devuelve una matriz de bytes que codifica:

• Versión de 8 bits de esta especificación, 0x00 en esta instancia.
• Valor de 8 bits del número máximo de ranuras que este beacon es capaz de transmitir. (Independiente en este contexto significa intercambio completo de claves ECDH para generar el EID con claves de identidad y valores de reloj separados.)
• Valor de 8 bits del número máximo de ranuras EID independientes que este beacon es capaz de transmitir. (Independiente en este contexto significa intercambio completo de claves ECDH para generar el EID con claves de identidad y valores de reloj separados.)
• Campo de bits de 8 bits que codifica las siguientes propiedades:
  • 0x01: IS_VARIABLE_ADV_SUPPORTED establecido si el beacon admite intervalos de publicidad individuales por ranura; no establecido si el beacon solo admite un intervalo de publicidad global.
  • 0x02: IS_VARIABLE_TX_POWER_SUPPORTED establecido si el beacon admite potencias Tx individuales por ranura; no establecido si el beacon solo admite una única potencia Tx global.
  • 0x04 a 0x80: RFU y debe estar no establecido.

• Campo de bits de 16 bits que codifica los tipos de trama soportados:
  • 0x0001: UID
  • 0x0002: URL
  • 0x0004: TLM
  • 0x0008: EID
  • 0x0010 a 0x8000 RFU y debe estar no establecido
• Una matriz de longitud variable de los valores absolutos (dBm) de potencia de radio Tx soportada.

Requisito de bloqueo

Solo legible cuando está desbloqueado. Nunca escribible.

Característica 2

Nombre

Ranura Activa

UUID

a3c87502-8ed3-4bdf-8a39-a01bebede295

Propiedades

uint8_t get_active_slot (lectura)
uint8_t set_active_slot (escritura)
Longitud: 1 byte

Descripción

Lectura/Escritura: Lee y escribe el número de ranura activa, indexado desde 0.
El valor predeterminado es 0 cuando se establece una nueva conexión desde un cliente de configuración.
Las escrituras subsiguientes a otras características actuarán sobre este número de ranura, configurando la potencia Tx, el intervalo de publicidad y los datos para ella.

Requisito de bloqueo

Debe estar desbloqueado para lectura y escritura.

Característica 3

Nombre

Intervalo de Publicidad

UUID

a3c87503-8ed3-4bdf-8a39-a01bebede295

Propiedades

uint16_t get_adv_interval (lectura)
uint16_t set_adv_interval (escritura)
Longitud: 2 bytes

Descripción

Lectura/Escritura: Lee y escribe el intervalo de publicidad (ms) para la ranura activa.
Si dos ranuras están programadas para transmitirse al mismo tiempo, o el tiempo entre dos transmisiones es menor que el intervalo de publicidad más corto permitido, entonces las publicidades se transmitirán en orden al AI más corto (40ms).
El valor mínimo para el intervalo de publicidad es 100ms, y 1000ms para el marco TLM. El máximo es 10000ms excepto para la ranura TLM que permite establecer hasta 65535ms si hay más de una ranura configurada.

Requisito de bloqueo

Debe estar desbloqueado para lectura y escritura.

Característica 4

Nombre

Potencia de Radio Tx

UUID

a3c87504-8ed3-4bdf-8a39-a01bebede295

Propiedades

Int8_t get_radio_tx_power (lectura)
Int8_t set_ radio_tx_power (escritura)
Longitud: 1 byte

Descripción

Lectura/Escritura: Lee y escribe la potencia de radio Tx deseada para la ranura activa (en complemento a dos). Si escribe cualquier valor diferente de los valores de potencia de radio Tx soportados, obtiene un error.

Requisito de bloqueo

Debe estar desbloqueado para lectura y escritura.

Característica 5

Nombre

(Avanzado) Potencia Tx Publicitada

UUID

a3c87505-8ed3-4bdf-8a39-a01bebede295

Propiedades

int8_t get_advertised_tx_power (lectura)
int8_t set_advertised_tx_power (escritura)
Longitud: 1 byte

Descripción

Lectura/Escritura: Escribe un valor que se utiliza como la potencia Tx que se anuncia en los tipos de trama EddystoneUID, URL y EID. Si no se establece, la potencia Tx anunciada en esos marcos es el valor establecido en la característica Potencia de Radio Tx. El rango de valores es de -126dBm a 127dBm.
Este valor se utiliza para calibrar la potencia anunciada a 0m recibida por el central (tiene en cuenta la pérdida de la antena).
Esta característica está disponible como una opción avanzada implementada y siempre mantiene la última modificada: Si después de cambiar esta característica (7505), la característica de potencia Tx (7504) se modifica, la potencia Tx anunciada (7505) también modificará su valor al mismo introducido en 7504 y, por lo tanto, en 7505 leeremos el mismo valor que en 7504. Sin embargo, si 7505 es la última modificada para ambas, la potencia Tx anunciada sería la definida en 7505.

Requisito de bloqueo

Debe estar desbloqueado para lectura y escritura.

Característica 6

Nombre

Estado de Bloqueo

UUID

a3c87506-8ed3-4bdf-8a39-a01bebede295

Propiedades

uint8_t lock_state (lectura)

matriz_de_bytes (escritura) {
lock_byte,
encrypted_key[0] … encrypted_key[15]
}

Longitud (lectura): 1 byte
Longitud (escritura): 1 o 17 bytes

Descripción

Lectura: Lee un valor de byte que indica el estado de bloqueo actual. Los valores de estado son:

• 0x00: BLOQUEADO
• 0x01: DESBLOQUEADO
• 0x02: DESBLOQUEADO Y REBLOQUEO AUTOMÁTICO DESACTIVADO

Escritura: Escribe 1 byte o 17 bytes para pasar a un nuevo estado de bloqueo:

• 0x00: Un solo byte de 0x00 escrito en esta característica pasará la interfaz al estado BLOQUEADO sin cambiar el valor de clave de seguridad actual.
• 0x00 + key[16]: Un solo byte de 0x00 seguido de un valor de clave cifrada de 16 bytes escrito para esta característica pasará la interfaz al estado BLOQUEADO y actualizará la clave de seguridad al valor no cifrado de key[16]. Para evitar que el nuevo código de bloqueo se transmita en claro, el cliente debe cifrar AES128ECB el nuevo código con el código de bloqueo existente:
  (key[16] = encrypt(key=actual_lock_code[16], text=new_lock_code[16]))
• 0x02: Un solo byte de 0x02 escrito en esta característica desactivará la capacidad de rebloqueo automático de la interfaz.

Por defecto, el estado de bloqueo es 0x02.

Requisito de bloqueo

Legible en estado bloqueado o desbloqueado.
Escribible solo en estado desbloqueado.

Característica 7

Nombre

Desbloquear

UUID

a3c87507-8ed3-4bdf-8a39-a01bebede295

Propiedades

matriz_de_bytes (lectura) {
challenge[0] … challenge[15]
}
matriz_de_bytes (escritura) {
unlock_token[0] … unlock_token[15]
}
Longitud: 16 bytes

Descripción

Escribe en un beacon y lo establece en el estado de desbloqueo, protegido de cambios de configuración o lectura de información sensible.
Lectura: devuelve un token de desafío de 128 bits. Este token es para un solo uso.
Escritura: acepta un valor cifrado de 128 bits que verifica que el cliente conoce el código de bloqueo del beacon.
Para crear el token de desbloqueo, primero lee el desafío de 16 bytes generado aleatoriamente y lo genera usando AES128ECB.
token de desbloqueo = encrypt(key=beacon_lock_code[16], text=challenge[16])
Si el token de desbloqueo introducido es correcto, el estado de bloqueo se establece en 0x01.
Por defecto, el beacon_lock_code[16] está establecido en 0’s.

Requisito de bloqueo

Legible solo en estado bloqueado.
Escribible solo en estado bloqueado.

Característica 8

Nombre

Clave Pública ECDH

UUID

a3c87508-8ed3-4bdf-8a39-a01bebede295

Propiedades

matriz_de_bytes (lectura) {
key[0] … key[31]
}
Longitud: 32 bytes

Descripción

Solo Lectura: Lee la clave pública ECDH de 256 bits del beacon.

Requisito de bloqueo

Legible solo en estado desbloqueado

Característica 9

Nombre

Clave de Identidad EID

UUID

a3c87509-8ed3-4bdf-8a39-a01bebede295

Propiedades

matriz de bytes (lectura) {
encrypted_ik[0] … encrypted_ik[15]
}
Longitud: 16 bytes

Descripción

Solo Lectura: Lee la clave de identidad para la ranura activa. Si la ranura no está configurada como EID, devuelve un error.
Para evitar que estos datos se transmitan en claro, está cifrado con AES128 con el código de bloqueo del beacon.

Requisito de bloqueo

Legible solo en estado desbloqueado

Característica 10

Nombre

Leer/Escribir Ranura ADV

UUID

a3c8750A-8ed3-4bdf-8a39-a01bebede295

Propiedades

matriz de bytes (lectura/escritura) {
frame_type,
data[0] … data[N]
}
Longitud de escritura: 17 bytes (UID), 19 bytes (URL), 2 bytes (TLM), 34 bytes (EID)
Longitud de lectura: 18 bytes (UID), <=20bytes(URL), 14 bytes (TLM), 18 bytes (eTLM), 14 bytes (EID)

Descripción

Lee el conjunto de datos en la ranura activa y establece los datos/parámetros para ser transmitidos. La interpretación de los datos leídos y escritos está caracterizada por el byte frame_type, que se asigna a los bytes de tipo de trama Eddystone de 0x00 (UID), 0x10 (URL), 0x20 (TLM), 0x30 (EID).
Lectura: En el caso de un marco UID, URL o TLM, la longitud y los datos son los de los datos transmitidos, incluidos los ajustes a la potencia Tx anunciada aplicados a través de la tabla de calibración de potencia Tx.
Si la ranura está configurada para anunciar marcos EID, la longitud es 14:
1 byte de tipo de trama, 1 byte de exponente, valor de reloj de 4 bytes, EID de 8 bytes.
Estos son los parámetros requeridos para el registro, junto con la clave pública del beacon, que se expone a través de una característica separada, y la clave pública del resolutor, que el beacon de aprovisionamiento/registro conoce.
Escritura: En el caso de marcos UID y URL, los datos a transmitir se suministran en la matriz después del tipo de trama. UID es 16 bytes de espacio de nombres + instancia, la URL es de hasta 18 bytes.
En el caso de un marco TLM, los datos son solo el byte de tipo de trama, 0x20.
Si otra ranura en el beacon ha sido configurada como un tipo de marco EID, el beacon transmite la variedad ETLM de telemetría. De lo contrario, se transmite el TLM simple.
En el caso de un marco EID, la longitud es 34: tipo de trama 0x30, la
clave pública ECDH de 32 bytes del servicio y el byte de exponente.
Escribir una matriz vacía borra la ranura y detiene la Tx. Si ha sido configurado como un beacon EID, esto también destruirá el estado del periférico para estos datos de trama y generará una nueva clave pública ECDH y el dispositivo volverá a la MAC original.
El número máximo de ranuras que se pueden configurar como TLM es 1 (como marco EID). Los marcos URL y UID se pueden configurar en múltiples ranuras.

Requisito de bloqueo

Debe estar desbloqueado para lectura y escritura.

Característica 11

Nombre

(Avanzado) Restablecimiento de Fábrica

UUID

a3c8750B-8ed3-4bdf-8a39-a01bebede295

Propiedades

uint8_t reset_bool (escritura)
Longitud: 1 byte
Descripción
Solo Escritura: Si se escribe un valor de 0x0B, el beacon se restablece a su estado de fábrica. Esto no incluye la clave de desbloqueo, que permanece establecida en su valor actual. Todos los datos de ranura (incluidas las claves de identidad EID) se destruyen.
Además, cualquier escritura será ignorada si el estado de bloqueo es diferente de 0x01.

Requisito de bloqueo

Debe estar desbloqueado para escribir. El estado de bloqueo debe ser 0x01.

Característica 12

Nombre

(Avanzado) Permanecer Conectable

UUID

a3c8750C-8ed3-4bdf-8a39-a01bebede295

Propiedades

uint8_t is_non_connectable_supported (lectura)
uint8_t remain_connectable_bool (escritura)
Longitud: 1 byte

Descripción

Lectura: Al leer, devolver un valor distinto de cero indica que el beacon es capaz de volverse no conectable. Devolver un valor cero indica que el beacon está limitado a funcionar en un estado siempre conectable. En nuestro caso, el beacon es capaz de volverse no conectable.
Escritura: Escribir un valor cero hará que el beacon pase a un estado no conectable después de que el cliente se desconecte. Si se escribe cualquier valor distinto de cero, el beacon permanecerá en su estado conectable hasta que se escriba cualquier otro valor.
Si se escribe un valor cero, el beacon reanudará su operación normal de volverse no conectable después de que el central se desconecte.
Esta característica no es compatible con las Características 3 y 4 del Servicio Global, y siempre permanece como la última en configurarse. Si se configura una ventana conectable y después se establece esta característica, el estado definido en esta característica permanecerá. Si se establece esta característica y después se configura una ventana conectable, la ventana conectable permanecerá. Para saber más sobre diferentes casos, consulte la Tabla 1 de la característica 3 (0xFF03) del Servicio Global.
Por defecto, el beacon siempre es conectable y la ventana conectable está desactivada.

Requisito de bloqueo

Debe estar desbloqueado para escribir.

3.2 SERVICIO IBEACON

Este servicio se utiliza para configurar 1 o 2 ranuras adicionales (Máx. 2 ranuras ibeacon) como un marco iBeacon. Estas ranuras se añaden a la cola de las ranuras Eddystone.

Definición del servicio

Nombre

Servicio iBeacon

UUID

0xFA00

Notas

Las características de este servicio están bloqueadas cuando el servicio Eddystone está bloqueado.

Característica 1

Nombre

iBeacon Activo

UUID

0xFA01

Propiedades

uint8_t is_ibeacon_active (escritura/lectura)
Longitud: 1 byte

Descripción

Escritura/Lectura: Lee y escribe el número de ranura activa, indexado desde 0.
El valor predeterminado es 0 cuando se establece una nueva conexión desde un cliente de configuración.
Las escrituras subsiguientes a otras características actuarán sobre este número de ranura, configurando la potencia Tx, el intervalo de publicidad, UUID, Major y Minor y byte extra para ella.

Característica 2

Nombre

Intervalo de publicidad iBeacon

UUID

0xFA02

Propiedades

uint16_t get_adv_interval (lectura)
uint16_t set_adv_interval (escritura)
Longitud: 2 bytes

Descripción

Lectura/Escritura: Lee y escribe el intervalo de publicidad (ms) para la ranura iBeacon. El valor mínimo admitido es 100ms.

Característica 3

Nombre

Potencia Tx iBeacon

UUID

0xFA03

Propiedades

Int8_t get_radio_tx_power (lectura)
Int8_t set_ radio_tx_power (escritura)
Longitud: 1 byte

Descripción

Lectura/Escritura:Lee y escribe la potencia de radio Tx deseada para la ranura iBeacon (en complemento a dos)

Característica 4

Nombre

Potencia Cal iBeacon

UUID

0xFA04

Propiedades

int8_t get_advertised_tx_power (lectura)
int8_t set_advertised_tx_power (escritura)
Longitud: 1 byte

Descripción

Lectura/Escritura: Escribe un valor que se utiliza como la potencia Tx que se anuncia en el paquete iBeacon. Si no se establece, la potencia Tx anunciada es el valor establecido en la característica Potencia de Radio Tx.
Este valor se utiliza para calibrar la potencia anunciada a 1m recibida por el central (tiene en cuenta la pérdida de la antena).
Esta característica está disponible como una opción avanzada implementada y siempre permanece como la última en modificarse (entre Txpower y Cal power). Si después de cambiar esta característica (FA04), la característica de potencia Tx (FA03) se modifica, la cal power (FA04) también modificará su valor al mismo introducido en FA03 y, por lo tanto, en FA04 se leerá el mismo valor que en FA03. Sin embargo, si FA04 es la última modificada para ambas, la potencia Tx anunciada será la definida en FA04.

Característica 5

Nombre

iBeacon UUID:Major:Minor

UUID

0xFA05

Propiedades

matriz_de_bytes (lectura/escritura) {
UUID[0] … UUID[15],
Major[0],Major[1],
Minor[0],Minor[1]
}
Longitud: 20 bytes

Descripción

Lectura: Lee el UUID, Major y Minor deseados para la ranura iBeacon. Si el valor leído es un solo byte con valor ‘0’, la ranura está desactivada.
Escritura: Escribe el UUID, Major y Minor deseados para la ranura iBeacon. Escribir un único byte (longitud=1) con valor ‘0’, borra la ranura y detiene la publicidad de esta ranura.

Característica 6

Nombre

Byte Extra iBeacon

UUID

0xFA06

Propiedades

uint8_t get_extrabyte_active (lectura)
uint8_t set_extrabyte_active (escritura)
Longitud: 1 byte

Descripción

Lectura/Escritura:Lee y escribe la activación de un byte extra (establece un byte adicional en el paquete ibeacon con % de nivel de batería). Si se escribe cualquier valor distinto de cero, el byte extra está activo. Si se escribe un valor cero, el byte extra está inactivo.

3.3 SERVICIO CARD BEACON

Este servicio se utiliza para configurar 1 o 2 ranuras adicionales (Máx. 2 ranuras ibeacon) como un marco iBeacon. Estas ranuras se añaden a la cola de las ranuras Eddystone.

Definición del servicio

Nombre

Servicio Card Beacon

UUID

0xFB00

Notas

Las características de este servicio están bloqueadas cuando el servicio Eddystone está bloqueado.

Característica 1

Nombre

Modo Estático

UUID

0xFB01

Propiedades

uint8_t get_static_mode (lectura)
uint8_t set_static_mode (escritura)
Longitud: 1 byte

Descripción

Lectura: Lee un valor de byte que indica el modo estático actual. Los valores del modo estático son:
0x00: APAGADO (Predeterminado)
0x01: ENCENDIDOEscritura: Escribe 1 byte para establecer el modo estático
0x00: Apaga el modo estático (Card Beacon siempre anuncia)
0x01: Enciende el modo estático (Card Beacon solo anuncia cuando se mueve).

Requisito de bloqueo

Debe estar desbloqueado para escribir.

3.4 SERVICIO GLOBAL

Definición del servicio

Nombre

Servicio Global

UUID

0xFF00

Notas

Las características de este servicio están bloqueadas cuando el servicio Eddystone está bloqueado.

Característica 1

Nombre

Nombre del Dispositivo

UUID

0xFF01

Propiedades

matriz_de_bytes (lectura) {
char[0]…char[20]
}
Longitud <= 20 bytes

Descripción

Escritura/Lectura:Escribe y lee el nombre del dispositivo. Si este valor se cambia, el beacon se reinicia después de la desconexión.

Característica 2

Nombre

Versión GATT

UUID

0xFF02

Propiedades

matriz_de_bytes (lectura) {
char[0]…char[19]
}
Longitud <= 20 bytes

Descripción

Solo lectura: Devuelve la versión GATT utilizada en este firmware.

Característica 3

Nombre

Período Conectable

UUID

0xFF03

Propiedades

matriz_de_bytes (lectura/escritura) {
period[0]…period[2]
}
Longitud: 3 bytes

Descripción

Las características «período conectable» y «ventana conectable» nos permiten configurar una ventana de tiempo mientras el dispositivo está en modo conectable.
Lectura/Escritura: Escribe el período de con qué frecuencia el beacon inicia la ventana conectable (en segundos). Lee el mismo valor.

La ventana conectable no es compatible con las Características 12 (0x750C) del Servicio Eddystone, y siempre permanece como la última en configurarse. Si se configura una ventana conectable y después, se establece el char 0x750C, el estado definido en el char 0x750C permanecerá. Si se establece el char 0x750C y después, se configura una ventana conectable, la ventana conectable permanecerá.

Característica 4

Nombre

Ventana Conectable

UUID

0xFF04

Propiedades

matriz_de_bytes (lectura/escritura) {
window[0]…window[2]
}
Longitud: 3 bytes

Descripción

Lectura/Escritura: Escribe cuánto dura la ventana conectable (en segundos). Lee el mismo valor.

La ventana conectable no es compatible con las Características 12 (0x750C) del Servicio Eddystone, y siempre permanece como la última en configurarse. Si se configura una ventana conectable y después, se establece el char 0x750C, el estado definido en el char 0x750C permanecerá. Si se establece el char 0x750C y después, se configura una ventana conectable, la ventana conectable permanecerá. Para saber más sobre diferentes casos, consulte la Tabla 1 de la característica 3 (0xFF03).

Característica 5

Nombre

Modo de actualización de firmware

UUID

0xFF05

Propiedades

uint8_t set_fw_update (escritura)
Longitud: 1 byte

Descripción

Solo Escritura: Al escribir un 0x01, el beacon comienza en modo DFU después de que el usuario se desconecta del beacon. Al entrar en modo DFU, asegúrese de que actualizará el FW, el beacon solo regresa al modo beacon después de la actualización.

Característica 6

Nombre

Hora Actual

UUID

0xFF06

Propiedades

matriz_de_bytes (lectura/escritura) {
act_hour[0]…act_hour[1]
}
Longitud: 2 bytes

Descripción

Lectura/Escritura: Escribe la hora actual en minutos (es decir, 17:18h = 0x040E). Usando las características 0xFF06, 0xFF07 y 0xFF08, es posible programar el encendido y apagado de la publicidad. Esta característica (x0FF06) nos permite sincronizar el beacon con la hora real y debe escribirse después de configurar las características 0xFF07 y 0xFF08 para activar esta función.

Si las características 0xFF06, 0xFF07 y 0xFF08 se establecen en valor cero, el encendido/apagado de la publicidad está desactivado.

Cuando el beacon se apaga, estas 3 características se establecen en ‘0’ y la publicidad siempre permanece activa hasta que estas 3 características se configuran nuevamente.

Característica 7

Nombre

Hora de Encendido de Publicidad

UUID

0xFF07

Propiedades

uint8_t get_on_hour_active (lectura)
uint8_t set_on_hour_active (escritura)
Longitud: 1 byte

Descripción

Lectura/Escritura: Escribe la hora (en resolución de horas) en que debe comenzar la publicidad. Después de la modificación de esta característica, se debe establecer el char 0xFF06 para sincronizarse. Para obtener más información sobre esta función, consulte la característica 0xFF06.
Nota: La diferencia entre ENCENDIDO y APAGADO debe ser menor de 17 horas.

Característica 8

Nombre

Hora de Apagado de Publicidad

UUID

0xFF08

Propiedades

uint8_t get_off_hour_active (lectura)
uint8_t set_off_hour_active (escritura)
Longitud: 1 byte

Descripción

Lectura/Escritura: Escribe la hora (en resolución de horas) en que debe detenerse la publicidad. Después de la modificación de esta característica, se debe establecer el char 0xFF06 para sincronizarse. Para obtener más información sobre esta función, consulte la característica 0xFF06.
Nota: La diferencia entre ENCENDIDO y APAGADO debe ser menor de 17 horas.