Sample description

The Central ESL sample acts as Access Point(AP) defined in Electronic Shelf Label Profile which controls and manages numbers of ESL Tag. It uses the library Electronic Shelf Label Service (ESLS) client to communicates with ESLs connectionlessly when one or more ESLs are in the Synchronized state.

Note

This sample is experimental and currently in its testing phase. It has been primarily developed for estimation and experimental purposes and is not yet optimized or sufficiently tested for production use. While it provides valuable insight into potential features and functions, its current state may not reflect the final product’s quality or stability. Therefore, it should not be used for production until further updates and refinements are made.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Build target
nRF5340 DK	PCA10095	nrf5340dk_nrf5340_cpuapp	nrf5340dk_nrf5340_cpuapp
Thingy:53	PCA20053	thingy53_nrf5340_cpuapp	thingy53_nrf5340_cpuapp

The sample also requires another development kit running a compatible sample (see Bluetooth: Peripheral ESL).

Overview

In this sample, Nordic provides host interface architecture and full set of Central ESL subcommands to control the AP and auto onboarding feature.

This Sample is an easy-to-use Serialized Access Point which can be used as a development platform to help customers test and develop ESL Tags (Bluetooth: Peripheral ESL).

Beside this, this sample can be used also in combination with more powerful hosts(e.g.: Linux PC) in order to develop/implement a full ESL AP application. The AP provides serial connection to the HOST (PC/Linux) via USB interface (nRF USB – J3 connector on nRF5340 DK; USB-C connector on Nordic Thingy:53). Two virtual COMs are associated this the USB port:

• Shell command COM port (used for shell commands)

• SMP/mcumgr COM port (used for transfer images from PC to AP)

When booting up, the Access Point starts periodic advertising with response(PAwR) with predefined PAwR parameters. At this point, the AP is ready to scan for new tags, connect / configure / synchronize new tags, send encrypted commands, receive encrypted responses (refer to ESL Service and ESL profile). All such functionalities are exposed via Central ESL subcommands. However, since this process may involve many decisions and many shell commands inputs, in order to make testing / developing process easier, this sample provides also a auto onboarding feature.

Auto Onboarding and Auto PAST

Auto Onboarding feature , which associates Tags automatically to the AP, by continuously & automatically performing the following tasks in the background:

1. Scan for new unsynchronized ESL Tags(new ones or previously associated)

2. Connect and configure them one by one: e.g. read/write characteristics (including AP sync maetiral, ESL Address, etc), send pre-loaded images (i.e. images previously transferred from the PC to the AP)

Note

Max number of devices that can be handled by the automatic onboarding feature is depending on these Kconfig. CONFIG_ESL_CLIENT_MAX_GROUP (default 128), CONFIG_ESL_CLIENT_DEFAULT_GROUP_ID (default 0), CONFIG_ESL_CLIENT_DEFAULT_ESL_ID (default 0), CONFIG_BT_ESL_AP_AUTO_TAG_PER_GROUP (default 8).

With default configuration, Tags are added from Group 0 with increasing ESL_ID (0,1,2,3,4,5,6,7) until reaching 8th. Then, the next Tag will be added to Group 1 with ESL_ID 0, and so on. For handling more devices, shell commands should be used.

Note

The AP will store information of associated ESL Tags into non-volatile database (external SPI flash) with CONFIG_BT_ESL_TAG_STORAGE enabled. This option is mandatory reruired for auto onboarding feature.

Note

During association, the AP sends images only to those tags that are running the EPD variant Bluetooth: Peripheral ESL sample (AP reads characteristics of the new associated tags, and only if it is recognized as specific tag type , it will transfer the image)

Note

You can observe the output log of auto onboarding process on the shell terminal. Here an example of successful onboarding of ESL Tag (ESL Peripheral without EPD):

#TAG_SCANNED: 1,C9:AC:AD:A6:E5:79 (random) to list
Connected:Conn_idx:00
#SCANNED_TAG:
#DISCOVERY: 1,0x00
#CONFIGURED: 1,0x0000,0x0001
#BASIC_STATE:1,0x0000
SERVICE_NEEDED:off
SYNCHRONIZED:off
ACTIVE_LED:off
PENDING_LED_UPDATE:off
PENDING_DISPLAY_UPDATE:off
BASIC_RFU:off
#PAST:1,00
Disconnected:Conn_idx:0x00 (reason 0x13)

Here an example of successful onboarding of ESL Tag (ESL Peripheral with EPD variant):

#TAG_SCANNED: 1,C9:AC:AD:A6:E5:79 (random) to list
Connected:Conn_idx:00
#SCANNED_TAG:
#DISCOVERY: 1,0x00
#CONFIGURED: 1,0x0000,0x0001
#BASIC_STATE:1,0x0000
SERVICE_NEEDED:off
SYNCHRONIZED:off
ACTIVE_LED:off
PENDING_LED_UPDATE:off
PENDING_DISPLAY_UPDATE:off
BASIC_RFU:off
#OTS_WRITE:1,0,0,esl_image_09
#OTS_WRITTEN:1,00,0,15006,0x1754215a
#OTS_WRITE:1,0,1,esl_image_0A
#OTS_WRITTEN:1,00,1,15006,0xdf631601
#PAST:1,00
Disconnected:Conn_idx:0x00 (reason 0x13)

0000 Is the ESL Address in hexadecimal, where two MSB are the Group ID, and two LSB are ESL ID.

3. Sends PAST info to unsynchronized ESL Tag

Note

The ESL client provides auto PAST feature. If a previously associated Tag is scanned (i.e. if ESL Tag is in database), Access Point will connect using the previously stored Bluetooth bonding information and then configure the tag accordingly to previous settings stored in the database (note: EPD images will not transferred in this case – EPD images are transferred only the first time tag gets associated to the AP, if images are available in the AP). Access Point then will send PAST automatically.

Note

if a previously associated tag is reset (i.e. it has erased also the bonding information with the AP), the AP will not be able to connect to that tag (because it will try to connect with the old bonding keys in the AP database). Erase the AP database by using Button 2 to clear all content of database or shell command to clear specified Tag to start the process again.

Once tags are onboarded and synchronized to the AP, commands can be sent/received using the User interface (either using the DK buttons features in the DK and/or the Central ESL subcommands by shell commands ). Auto onboarding feature should be used only for testing/development or as a starting point for more complex applications. For production (ESL AP), shell commend is recommended.

User interface

This sample provides two ways to control the AP. One is through buttons on the development kit, the other is through shell commands.

DK button featureShell command

Such User Interface takes advantage of the Auto Onboarding feature

Button 1:

Press to start Auto onboarding AP feature.

1. AP scan and connect unsynchonrized ESL Tag.

2. AP configure unsynchronized ESL Tag.

3. AP send image file to unsynchronized ESL Tag.

4. AP send PAST info to unsynchronized ESL Tag.

Button 2: (only on nRF5340 DK, not available on the Nordic Thingy:53)

Erase the database of associated ESL Tags which is used by Auto Onboarding and Auto PAST from the AP.

Note

If you push this button, you should also push Button 1 on the ESL Tag as well to reset the ESL Tag.

This procedure will not erase the EPD images stored in the AP (if any transferred).

Button 3: (only on nRF5340 DK, not available on the Nordic Thingy:53)

Change Image on the ESL Tag display.

By pressing this button, AP sends a Predefined ESL sync packet to a specific group. Commands rotate at each press of the button, in the following order, starting from Group CONFIG_ESL_CLIENT_DEFAULT_GROUP_ID (Default 0) to Group 2 CONFIG_BT_ESL_AP_GROUP_PER_BUTTON (Default 3)

e.g.:0x7 (display 0 image 0 broadcast) is sent to Group 0

0x8 (Display 0 image 1 broadcast) is sent to Group 0

0x12 (Tag default ESL_ID ~ ESL_ID+10 Display Img 0) is sent to Group 0

0x13 (Tag default ESL_ID ~ ESL_ID+10 Display img 1) is sent to Group 0

0x7 (display 0 image 0 broadcast) is sent to Group 1 and so on, until reaching Group CONFIG_BT_ESL_AP_GROUP_PER_BUTTON (Default 3) then turning back CONFIG_ESL_CLIENT_DEFAULT_GROUP_ID (Default 0)

Button 4: (only on nRF5340 DK, not available on the Nordic Thingy:53)

Flash ESL Tag LED in predefined pattern.

By pressing this button, AP sends a predefined Predefined ESL sync packet to a specific group. Commands rotate at each press of the button, in the following order, starting from Group CONFIG_ESL_CLIENT_DEFAULT_GROUP_ID (Default 0) to Group CONFIG_BT_ESL_AP_GROUP_PER_BUTTON (Default 3)

Note

Button 3 and 4 will continually send ESL command through PAwR and cycles from group 0 to CONFIG_BT_ESL_AP_GROUP_PER_BUTTON

LED 1:

Stable on means AP is booted-up.

Start blinking, signaling the Auto Onboarding feature on the AP is activate: AP is scanning for ESL tags, connecting one by one to them, configuring them and transferring synchronization (PAST).

Setup - Transfer Images from PC to AP over USB

One of major task of Access Point is to provide images to ESL Tag in configuring and updating state. Before activating auto onboarding (Button 1) or, anytime before sending images using Object Transfer Service via shell commands between AP and Tag, it is necessary to transfer the images from PC to the AP (in external flash) over USB. mcumgr_smp_protocol_specification is used over the other COM port available over USB. Here example:

1. Install Mcumgr Command-line Tool tool

2. Prepare the images to be transferred. The image format is depending on what EPD and color depth your are using.

Note

Nordic provides two sample files that can be used with the Bluetooth: Peripheral ESL 2.13” EPD variant.

• EPD format: Use this format on Access Point esl_image_bt esl_image_nordic

• BMP format: This format is only for reference esl_image_00_240x120_bt.BMP esl_image_01_240x120_nordic_logo.BMP

Nordic provides two sample files that can be used with the Bluetooth: Peripheral ESL 4.2” EPD variant.

• EPD format: Use this format on Access Point esl_image_empower esl_image_mcu_block

• BMP format: This format is only for reference esl_image_09_400x300_empower.BMP esl_image_0A_400x300_mcu_block.BMP

3. Transfer images from the PC to the AP: run from cmd /command line

   mcumgr --conntype="serial" --connstring="COM4,baud=115200,mtu=512" fs upload esl_image_bt /ots_image/esl_image_00
   mcumgr --conntype="serial" --connstring="COM4,baud=115200,mtu=512" fs upload esl_image_nordic /ots_image/esl_image_01
   mcumgr --conntype="serial" --connstring="COM4,baud=115200,mtu=512" fs upload esl_image_empower /ots_image/esl_image_09
   mcumgr --conntype="serial" --connstring="COM4,baud=115200,mtu=512" fs upload esl_image_mcu_block /ots_image/esl_image_0A
   

   Note

   Remember to change COM4 to the right COM port in your PC. Images are stored in external non-volatile flash.

   Non-volatile external flash is kept even after reset of DK (power cycle), or after programming or after AP database erase (Button 2)

   Once the images are in the AP, it is possible to transfer them to the tags at any time using shell commands, assuming the AP and Tag are in an ACL connection. Refer to Central ESL subcommands for this.

#. As an alternative, for demo purposes, Auto Onboarding feature can be used: If auto onboarding is started after the transfer of image (i.e. a new Tag is associated for the first time after transferring the image to the AP and after pushing Button 1), the AP will transfer automatically these images to the ESL Tag DevKit with EPD shield, during the associating procedure.

Configuration options

Check and configure the following Kconfig options:

BT_ESL_SECURITY_ENABLED

This enables BT SMP and bonding which are security requirement of ESL Profile. Disable BLE security of the ESL service for debugging purposes.

BT_ESL_AP_AUTO_MODE

Enable auto onboarding feature. With this feature AP will scan and connect unsynchonrized ESL Tag, configure and send predefined image to unsynchronized ESL Tag, send PAST info to unsynchronized ESL Tag automatically. This feature also stores response key material for all of associated ESL tags. The key material will be used to decrypt response EAD from ESL Tag when using predefined ESL packet.

Note

Auto onboarding feature is meant to be used for small scale testing and development purposes. For larger scale, Central ESL subcommands give more flexibility and control over the AP functionalities.

BT_ESL_AP_AUTO_TAG_PER_GROUP

How many tags should keep in same group for auto onboarding. Tag number exceeds this number should be in next group. Otherwise, response key material slot is not enough for all tags in same group.

How to choose this number depends on what scenario we want to show. Less or equal to CONFIG_ESL_CLIENT_MAX_RESPONSE_SLOT_BUFFER demostrates decrypts response EAD on-the-fly. Greater than CONFIG_ESL_CLIENT_MAX_RESPONSE_SLOT_BUFFER demostrates ESL AP able to control large amount of tags at the same time.”

BT_ESL_AP_GROUP_PER_BUTTON

Button 3 and Button 4 could be used as user interface. Button 3 will send Predefined ESL sync packet to all tags in group x to change image on display. Button 4 will send predefined command to all tags in group x to flash LED in predefined pattern. This option defines how many groups should be used for this feature. For example, if this option is set to 2, Button 3 and Button 4 will send Predefined ESL sync packet to all tags in group 0 and 1 alternatively.

BT_ESL_AP_AUTO_PAST_TAG

Enable auto PAST feature. With this feature AP will send PAST automatically if connected ESL Tag is in database.

Note

Auto PAST feature is meant to be used for small scale testing and development purposes. For larger scale, Central ESL subcommands give more flexibility and control over the AP functionalities.

BT_ESL_AP_PTS

Enable PTS feature. With this feature AP will send PTS command to connected ESL Tag. This feature is used for PTS test only.

BT_ESL_AP_AUTO_PING

Enable auto ping feature. With this feature AP will send ping command to all grounp of ESL Tag periodically through PAwR. This feature is used to keep tags in synchronized state automatically. Full ESL AP application should implement this feature to keep tags in synchronized state.

BT_ESL_AP_PING_INTERVAL

Interval of auto PAwR ping command. This option is used when BT_ESL_AP_AUTO_PING is enabled. Unit is second.

Building and running

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Building and programming an application <https://developer.nordicsemi.com/nRF_Connect_SDK/doc/2.5.0/nrf/getting_started/programming.html#gs-programming> for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Testing with other DevKits

After programming the sample to your development kit, complete the following steps to test it:

1. Connect the computer to the connecter labeled nRF USB on DevKit or the USB connector on the Thingy:53 using a USB cable. Turn on the kit; the computer will assign to the kit two virtual COM ports (Windows) or ttyACM devices (Linux), which are visible in the Device Manager. One port is for Central ESL subcommands. The other port is for EPD image transfer (SMP protocol).

2. Connect to the kit that runs this sample with a terminal emulator (for example, PuTTY or the Serial Terminal in nRF Connect for Desktop). Connect with the following settings:

• Baud rate: 115200

• 8 data bits

• 1 stop bit

• No parity

• HW flow control: None

Note

To know if the right port is selected, enter new line and “ESL_AP:~$” should show up.

3. Optionally, connect the RTT console to display debug messages.

4. Optionally (required for out of the box testing in combination ESL Tag sample with EPD), transfer the images from PC to the AP.

5. Test the sample either by by auto onboarding feature or using Central ESL subcommands manually as described in User interface.

Dependencies

This application uses the following nRF Connect SDK libraries:

• Electronic Shelf Label Service (ESLS) client

In addition, it uses the following Zephyr libraries:

• include/zephyr/types.h

• boards/arm/nrf*/board.h

• Kernel Services

  • include/kernel.h

• Bluetooth APIs:

  • include/bluetooth/bluetooth.h

  • include/bluetooth/gatt.h

  • include/bluetooth/hci.h

  • include/bluetooth/uuid.h