Skip to content

TL321x Electronic Shelf Label User Guide

Overview

This document introduces how to use Telink TL321x chip to implement the electronic shelf label (ESL) application.

Introduction of ESL

The Electronic Shelf Label is a Bluetooth profile based on Core v5.4 specification. There are two roles defined in specification, Access Point and Electronic Shelf Label. Each ESL device may be associated to a single Access Point device. Access Point may configure multiple ESL devices.

ESL topology

The ESL device configured by Access Point has a unique ESL address. ESL address consists of a GROUP ID and ESL ID.

The Group ID is mapped to a specific Periodic advertising subevent. There may be as many groups as subevents during Periodic advertising interval. I.e. there are 4 subevents, and 4 groups (0, 1, 2, 3):

Four subevents during periodic advertising interval

Access Point may communicate with ESL device through:

  • GATT, by writing/reading ESL service attributes and updating images on ESL device (it is called Updating State)
  • PAwR, by sending ESL payload in subevents and receiving responses (it is called Synchronized State)

Because there may be hundreds of ESL devices, Synchronized State allows control more devices than in Updating State. As previously stated, each subevent is mapped to group id. Below is an example of such mapping:

Each subevent carries data valid for single group

The ESL devices may respond to Commands included in subevent’s ESL payload in response slots (response slots timing may be obtained in PAST packet received from Access Point).

Response slots in subevent

The Single ESL payload may contain multiple commands, each may be addressed to other ESL devices. They send response in assigned response slot. To protect the data transmitted in PAwR events, the Access Point uses AP Key to encrypt messages to ESL devices. Each ESL device has its own key to encrypt the response.

Hardware preparation

ESL board

ESL board

The ESL board consists of a display and a board. In order to flash the board, connect the Flash Tool as the picture below:

BDT tool connection

Write ESL binary (eslp_esl_demo.bin) to board using BDT tool. After reset, the display will be refreshed.

Access Point board

Access Point board

The Access point is the TL3218 dongle device which utilize USB CDC to communicate with host. Connect Telink Flash tool to the board and download firmware (eslp_ap_demo.bin). After downloading the bin, plug the dongle into host’s USB port. It should be visible as COM\ device on Windows or /dev/ttyACM\ on Linux system.

Runnning the demonstration

Tools content

Directory esl_ap_tool contains python scripts which can communicate with Access Point device.

ap_tool directory

This guide covers usage of start_ap_client.pyw, and script may be run from command line (python start_ap_client.py) or as windowed python application. When running from command line, additional logs will be printed out (communication between host and access point). Tools require following packages to be installed: pyserial-asyncio, Pillow (python image library) and tkinter. The minimum required python version is 3.12.

Start access point application

Run start_ap_client.pyw with dongle attached to host and select port from list:

Select port window on Windows

Select port window on Linux

Then press "Start" button. It will open a new window as below:

Main Access Point client window

It is also possible to run GUI application without selecting UART/USB CDC port – it may be passed as an argument to ap_client_gui.py application. It will print out logs in console, so it is useful for debugging purposes.

Start ap_client_gui.py from console

Configuration pane

Configuration pane

Scan button

After pressing "Scan" button device starts discovering nearby ESL devices, as below:

Scan results after pressing "Scan" button

Clear button

The "Clear" button stops discovery and clears Scan Results array.

Configure button

If Scan Results array is not empty, then after pressing "Configure" button a new window will pop up. It allows to select device from list and assign Group ID (0 - 1) and ESL ID (1 – 20).

Configure device window

After selecting device, group id and esl id, user may press Done button. If configuration has been finished successfully, then device will appear in Group pane:

Device successfully configured and assigned to group 0

Configuration will fail if i.e.:

  • ESL device in unreachable
  • Given group ID and ESL ID has been used

Save configuration and Load configuration

Save configuration

Configuration file (in .json format) may simplify searching and setup of ESL devices. To store the current configuration, press Save configuration button and select file path. It will write down data in following format:

Configuration file format

When user wants to associate devices using saved configuration, it may be loaded with Load configuration button.

Operation pane

Operation pane allows communication with ESL devices within the group.

Operation pane

Setup labels

Setup labels allows to set the content of label displayed on ESL device.

Setup labels window

Description of fields, form the left column:

  • Checkbox indicating if the label setup should be applied (checked) or not
  • ESL ID
  • Entry with product name (name will be automatically converted to uppercase)
  • Entry with product description (description will be automatically converted to uppercase)
  • Entry with currency (currency code like CNY, USD, EUR, etc. shall be used. For CNY, EUR, USD, GBP currency symbol will be displayed. Other currencies will be shown as a currency code.)
  • Entry with product price major and minor
  • Unit entry (unit of measure like g, kg, l, piece, letters supported now are: b,c,e,g,i,k,l,n,p,u)
  • Checkbox indicating if label shows bar code (randomly generated)
  • Checkbox indicating if label shows bar code number (randomly generated)
  • Checkbox indicating if label shows the icon
  • Icon - valid if "Icon present" checkbox selected

Note:

Only latin alphabet is supported now.

After pressing "Done" button, values will be stored in the application. Please note that not all letters are supported on ESL device – i.e. supported low letters which appears in unit are: c, e, g, i, k, l, n, p, u.

Apply labels

After pressing this button, values set in Setup labels window will be sent through PawR Vendor packets and applied on ESL side. For example for following labels setup:

Example labels setup

After "Apply labels" button press, access point will send PawR commands. ESL ID 1 will display:

Sample label

Send image

This function allows sending image to ESL device. Due to the size of images, it requires ACL connection.

Send image window

After selecting files (each of size 4736 bytes, other values are not allowed), user may select ESL device to receive the images and image ids where images will be located. Additionally, "Display" checkbox will request ESL to display given image.

This command sends broadcast message to all devices in group to blink LEDs (green and red) three times. This command it sent through PAwR.

Display image

After pressing this button, user may select ESL device from group and set which image index should be displayed on them:

Display image window

Unassociate

This command allows to remove ESL device from group. Device may be configured as others group member or stay in unassociated state.

Implementation details

Commands described above use different way of communication between Access Point and ESL. Below is list of features used in their implementation:

No. Command Features
1 Apply labels PAwR vendor commands addressed to each selected ESL device
2 Send image Connection establishment (GAP Periodic Advertising Connection proc), image transfer through custom L2CAP CoC, ESL commands through ESL Control Point characteristic.
3 Blink LEDs PAwR command (LED Control) with broadcast address
4 Display image PAwR command (Display Image) with selected ESL IDs
5 Unassociate Connection establishment (GAP Periodic Advertising Connection proc) and ESL commands through ESL Control Point characteristic.