电子货架标签服务

[English]

电子货架标签服务 (Electronic Shelf Label Service, ESL) 是蓝牙 SIG 定义的 GATT 服务 (UUID 0x1857)，用于 ESL Tag。它提供配置类特性（地址、密钥材料、绝对时间）、可选能力信息（显示 / 图像 / 传感器 / LED），以及通过 ACL 收发命令与响应的 ESL Control Point。

在应用中使用本服务时，建议按以下步骤操作：

  1. 在 menuconfig 中启用 CONFIG_BLE_ESL (可选特性由相关 Kconfig 控制)。

  2. 使用 esp_ble_conn_init() 初始化 BLE 连接管理器。

  3. 在 esp_ble_conn_start() 之前调用 esp_ble_esl_init() 注册 ESL 服务。

  4. 可选用 esp_ble_esl_set_display_info()、esp_ble_esl_set_image_info() 等接口设置本机能力信息。

  5. 订阅 BLE_ESL_EVENTS (事件 ID 为被写入特性的 UUID)，处理地址、密钥、绝对时间、ECP 命令等写入。

  6. 通过 esp_ble_esl_notify_ecp_response() 发送 ECP 响应。

本服务暂无独立示例工程，初始化方式可参考其它 BLE 服务 示例。

API 参考

Header File

Functions

esp_err_t esp_ble_esl_get_address(esp_ble_esl_address_t *out_val)

Get the ESL Address characteristic value.

参数

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

返回

  • 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.

参数

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

返回

  • 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.

参数

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

返回

  • 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.

参数

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

返回

  • 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.

参数

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

返回

  • 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.

参数

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

返回

  • 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.

参数

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

返回

  • 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.

参数

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

返回

  • 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.

参数

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

  • count – [in] The number of displays

返回

  • 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.

参数

  • 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

返回

  • 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.

参数

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

返回

  • 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.

参数

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

返回

  • 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.

参数

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

  • len – [in] The length of sensor information

返回

  • 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.

参数

  • 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

返回

  • 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.

参数

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

  • count – [in] The number of LEDs

返回

  • 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.

参数

  • 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

返回

  • 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.

参数

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

  • len – [in] The length of response TLV

返回

  • 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.

返回

  • 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.

返回

  • 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.

提供有关此文档的反馈