Electronic Shelf Label Service

[中文]

The Electronic Shelf Label Service (ESL) is a Bluetooth SIG GATT service (UUID 0x1857) used by ESL Tags. It exposes configuration characteristics (address, key material, absolute time), optional capability information (display / image / sensor / LED), and the ESL Control Point for command and response exchange over ACL.

To use this service in an application:

  1. Enable CONFIG_BLE_ESL in menuconfig (optional characteristics are controlled by related Kconfig options).

  2. Initialize the BLE connection manager with esp_ble_conn_init().

  3. Call esp_ble_esl_init() to register the ESL service before esp_ble_conn_start().

  4. Optionally set local capability values with esp_ble_esl_set_display_info(), esp_ble_esl_set_image_info(), and related setters.

  5. Subscribe to BLE_ESL_EVENTS (event id is the written characteristic UUID) to handle writes such as address, keys, absolute time, and ECP commands.

  6. Send ECP responses with esp_ble_esl_notify_ecp_response().

There is no dedicated example project for this service yet; follow the initialization pattern used in other BLE service examples.

API Reference

Header File

Functions

esp_err_t esp_ble_esl_get_address(esp_ble_esl_address_t *out_val)

Get the ESL Address characteristic value.

Parameters

out_val – [out] The pointer to store the ESL Address

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_esl_set_address(const esp_ble_esl_address_t *in_val)

Set the ESL Address characteristic value.

Parameters

in_val – [in] The pointer to store the ESL Address

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_esl_get_ap_sync_key(esp_ble_esl_key_material_t *out_val)

Get the AP Sync Key Material characteristic value.

Parameters

out_val – [out] The pointer to store the key material

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_esl_set_ap_sync_key(const esp_ble_esl_key_material_t *in_val)

Set the AP Sync Key Material characteristic value.

Parameters

in_val – [in] The pointer to store the key material

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_esl_get_resp_key(esp_ble_esl_key_material_t *out_val)

Get the ESL Response Key Material characteristic value.

Parameters

out_val – [out] The pointer to store the key material

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_esl_set_resp_key(const esp_ble_esl_key_material_t *in_val)

Set the ESL Response Key Material characteristic value.

Parameters

in_val – [in] The pointer to store the key material

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_esl_get_current_abs_time(esp_ble_esl_abs_time_t *out_val)

Get the ESL Current Absolute Time characteristic value.

Parameters

out_val – [out] The pointer to store the absolute time

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_esl_set_current_abs_time(const esp_ble_esl_abs_time_t *in_val)

Set the ESL Current Absolute Time characteristic value.

Parameters

in_val – [in] The pointer to store the absolute time

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_esl_set_display_info(const esp_ble_esl_display_info_t *displays, uint8_t count)

Set the Display Information characteristic value.

Call this before esp_ble_esl_init() when CONFIG_BLE_ESL_DISPLAY_INFO is enabled.

Parameters

  • displays – [in] The pointer to store the display records

  • count – [in] The number of displays

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

  • ESP_ERR_NOT_SUPPORTED on disabled characteristic

esp_err_t esp_ble_esl_get_display_info(esp_ble_esl_display_info_t *displays, uint8_t max_count, uint8_t *out_count)

Get the Display Information characteristic value.

Parameters

  • displays – [out] The pointer to store the display records

  • max_count – [in] The capacity of displays

  • out_count – [out] The pointer to store the number of displays copied

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

  • ESP_ERR_NOT_SUPPORTED on disabled characteristic

esp_err_t esp_ble_esl_set_image_info(const esp_ble_esl_image_info_t *info)

Set the Image Information characteristic value.

Parameters

info – [in] The pointer to store the image information

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

  • ESP_ERR_NOT_SUPPORTED on disabled characteristic

esp_err_t esp_ble_esl_get_image_info(esp_ble_esl_image_info_t *info)

Get the Image Information characteristic value.

Parameters

info – [out] The pointer to store the image information

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

  • ESP_ERR_NOT_SUPPORTED on disabled characteristic

esp_err_t esp_ble_esl_set_sensor_info(const uint8_t *data, uint16_t len)

Set the Sensor Information characteristic value.

Parameters

  • data – [in] The pointer to store the sensor information

  • len – [in] The length of sensor information

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

  • ESP_ERR_NOT_SUPPORTED on disabled characteristic

esp_err_t esp_ble_esl_get_sensor_info(uint8_t *data, uint16_t max_len, uint16_t *out_len)

Get the Sensor Information characteristic value.

Parameters

  • data – [out] The pointer to store the sensor information

  • max_len – [in] The capacity of data

  • out_len – [out] The pointer to store the length copied

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

  • ESP_ERR_NOT_SUPPORTED on disabled characteristic

esp_err_t esp_ble_esl_set_led_info(const uint8_t *leds, uint8_t count)

Set the LED Information characteristic value.

Parameters

  • leds – [in] The pointer to store the LED information

  • count – [in] The number of LEDs

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

  • ESP_ERR_NOT_SUPPORTED on disabled characteristic

esp_err_t esp_ble_esl_get_led_info(uint8_t *leds, uint8_t max_count, uint8_t *out_count)

Get the LED Information characteristic value.

Parameters

  • leds – [out] The pointer to store the LED information

  • max_count – [in] The capacity of leds

  • out_count – [out] The pointer to store the number of LEDs copied

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

  • ESP_ERR_NOT_SUPPORTED on disabled characteristic

esp_err_t esp_ble_esl_notify_ecp_response(const uint8_t *data, uint16_t len)

Notify an ESL Control Point response to the remote client.

len must be in [2, BLE_ESL_ECP_MAX_SIZE] and equal to BLE_ESL_TLV_TOTAL_LEN(data[0]) for a single response TLV.

Parameters

  • data – [in] The pointer to store the response TLV

  • len – [in] The length of response TLV

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_esl_init(void)

Initialization Electronic Shelf Label Service.

Call esp_ble_esl_set_display_info() first when CONFIG_BLE_ESL_DISPLAY_INFO is enabled.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_STATE on wrong initialization

  • ESP_FAIL on error

esp_err_t esp_ble_esl_deinit(void)

Deinitialization Electronic Shelf Label Service.

Returns

  • ESP_OK on successful

  • Error code from esp_ble_conn_remove_svc() on failure

Structures

struct esp_ble_esl_address_t

ESL Address Characteristic.

Public Members

uint8_t esl_id

ESL ID, 0x00 to 0xFE, 0xFF is broadcast

uint8_t group_id_rfu

Group_ID in bits [6:0], RFU in bit 7

struct esp_ble_esl_key_material_t

Key Material Characteristic.

Public Members

uint8_t session_key[BLE_ESL_SESSION_KEY_SIZE]

128-bit AES session key

uint8_t iv[BLE_ESL_IV_SIZE]

64-bit initialization vector

struct esp_ble_esl_display_info_t

Display Information Record.

Public Members

uint16_t width

Display width in pixels

uint16_t height

Display height in pixels

uint8_t display_type

Display type enumeration

struct esp_ble_esl_image_info_t

Image Information Characteristic.

Public Members

uint8_t max_image_index

Highest supported Image_Index

Macros

BLE_ESL_UUID16
BLE_ESL_CHR_UUID16_ADDRESS
BLE_ESL_CHR_UUID16_AP_SYNC_KEY
BLE_ESL_CHR_UUID16_RESP_KEY
BLE_ESL_CHR_UUID16_CURRENT_ABS_TIME
BLE_ESL_CHR_UUID16_DISPLAY_INFO
BLE_ESL_CHR_UUID16_IMAGE_INFO
BLE_ESL_CHR_UUID16_SENSOR_INFO
BLE_ESL_CHR_UUID16_LED_INFO
BLE_ESL_CHR_UUID16_ECP
BLE_ESL_SESSION_KEY_SIZE
BLE_ESL_IV_SIZE
BLE_ESL_KEY_MATERIAL_SIZE
BLE_ESL_DISPLAY_INFO_RECORD_SIZE
BLE_ESL_ECP_MAX_SIZE
BLE_ESL_PAYLOAD_MAX_SIZE

Max ESL Payload size in Synchronized / PAwR state

BLE_ESL_BROADCAST_ADDRESS
BLE_ESL_OBJECT_ID_BASE

Object ID = base + Image_Index

BLE_ESL_SENSOR_SIZE_SHORT

16-bit Property ID

BLE_ESL_SENSOR_SIZE_LONG

32-bit vendor Sensor_Type

BLE_ESL_SENSOR_SHORT_LEN
BLE_ESL_SENSOR_LONG_LEN
BLE_ESL_LED_TYPE_SRGB
BLE_ESL_LED_TYPE_MONOCHROME
BLE_ESL_LED_TYPE(octet)
BLE_ESL_CMD_PING
BLE_ESL_CMD_UNASSOCIATE
BLE_ESL_CMD_SERVICE_RESET
BLE_ESL_CMD_FACTORY_RESET
BLE_ESL_CMD_UPDATE_COMPLETE
BLE_ESL_CMD_READ_SENSOR
BLE_ESL_CMD_REFRESH_DISPLAY
BLE_ESL_CMD_DISPLAY_IMAGE
BLE_ESL_CMD_DISPLAY_TIMED_IMAGE
BLE_ESL_CMD_LED_CONTROL
BLE_ESL_CMD_LED_TIMED_CONTROL
BLE_ESL_RESP_ERROR
BLE_ESL_RESP_LED_STATE
BLE_ESL_RESP_SENSOR_VALUE

Tag nibble; Length in MSN encodes Sensor_Data size

BLE_ESL_RESP_VENDOR

Vendor-specific response Tag nibble

BLE_ESL_RESP_BASIC_STATE
BLE_ESL_RESP_DISPLAY_STATE
BLE_ESL_ECP_PROCEDURE_TIMEOUT_S
BLE_ESL_ERR_UNSPECIFIED
BLE_ESL_ERR_INVALID_OPCODE
BLE_ESL_ERR_INVALID_STATE
BLE_ESL_ERR_INVALID_IMAGE_INDEX
BLE_ESL_ERR_IMAGE_NOT_AVAILABLE
BLE_ESL_ERR_INVALID_PARAMS
BLE_ESL_ERR_CAPACITY_LIMIT
BLE_ESL_ERR_INSUFFICIENT_BATTERY
BLE_ESL_ERR_INSUFFICIENT_RESOURCES
BLE_ESL_ERR_RETRY
BLE_ESL_ERR_QUEUE_FULL
BLE_ESL_ERR_IMPLAUSIBLE_ABS_TIME
BLE_ESL_BASIC_STATE_SERVICE_NEEDED
BLE_ESL_BASIC_STATE_SYNCHRONIZED
BLE_ESL_BASIC_STATE_ACTIVE_LED
BLE_ESL_BASIC_STATE_PENDING_LED_UPDATE
BLE_ESL_BASIC_STATE_PENDING_DISP_UPDATE
BLE_ESL_TLV_TAG(opcode)
BLE_ESL_TLV_LENGTH(opcode)
BLE_ESL_TLV_PARAMS_LEN(opcode)
BLE_ESL_TLV_TOTAL_LEN(opcode)
BLE_ESL_ADDR_GROUP_ID(addr)
BLE_ESL_ADDR_SET_GROUP_ID(addr, gid)

Type Definitions

typedef uint32_t esp_ble_esl_abs_time_t

ESL Current Absolute Time Characteristic.

Provide feedback about this document