Telink B91 Electronic Shelf Label User Guide
Introduction
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 said, each subevent is mapped to group id. Below is example of such mapping:
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).
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, 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 consists of display and board. In order to flash the board, connect Flash Tool like on picture below:
Write ESL binary (eslp_esl_demo.bin) to board using BDT tool. After reset display will be refreshed.
Access Point Board
Access point it the B91 dongle device which utilize USB CDC to communicate with host. Connect Telink Flash tool to board and download firmware (eslp_ap_demo.bin). After writing the image, plug the dongle info host’s USB port. It should be visible as COM\
Runnning the Demonstration
Tools Content
Directory ap_tool contains python scripts which can communicate with Access Point device.
This guide covers usage of start_ap_client.pyw and image_convert_gui.pyw. Both scripts 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. 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 new window like 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, like 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 new window will pop up. It allows to select device from list and assign Group ID (0 - 1) and ESL ID (1 – 8).
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 send image (or multiple images) 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:
Table: List of features used in 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.
image_convert_gui.pyw Tool
Tool allows convert image file (like .png or .jpeg) to format readable by ESL device. It accepts format of the label (296px width / 128px height) and icon (48px width / 48px height).
Load File Button
This button allows select file to be converted. It opens select file window. After file selection, its path will be displayed in main widow:
Save as Button
Press this button to select file path where new image will be stored. New file can also be created. New file path will also appear in main window.
Convert Button
After pressing this button input file will be converted to new format and written to output file.
If there will be an issue like – wrong resolution, non existing file path, it will appear in status label (below "Convert" button), i.e.:
