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.
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):
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:
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).
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
The ESL board consists of a display and a board. In order to flash the board, connect the Flash Tool as the picture below:
Write ESL binary (eslp_esl_demo.bin) to board using BDT tool. After reset, the display will be refreshed.
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\
Runnning the demonstration
Tools content
Directory esl_ap_tool contains python scripts which can communicate with Access Point device.
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:
Then press "Start" button. It will open a new window as below:
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.
Configuration pane
Scan button
After pressing "Scan" button device starts discovering nearby ESL devices, as below:
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).
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:
Configuration will fail if i.e.:
- ESL device in unreachable
- Given group ID and ESL ID has been used
Save configuration and Load 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:
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.
Setup labels
Setup labels allows to set the content of label displayed on ESL device.
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:
After "Apply labels" button press, access point will send PawR commands. ESL ID 1 will display:
Send image
This function allows sending image to ESL device. Due to the size of images, it requires ACL connection.
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.
Blink LEDs
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:
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. |