ESL Tag core#
Implements the ESL Tag role of the Bluetooth Electronic Shelf Label Profile. It contains the mandatory ESL Tag characteristics, only. Optional features has to be added to the project as separate components, if needed. This component implements all the core functionalities, while also declares the interface of the optional features (and provides the WEAK implementations for them). This is a No-Code component, any additional feature can be added as a component.
Typedefs#
ESL Display Info Display Type.
ESL Display Info first class abstract data pointer type.
ESL Service Specification d09r18, Section 3.7.2.4: 48 bit Image Object ID.
ESL LED type.
ESL LED color gamut control type.
ESL LED repeats type.
Functions#
ESL LED flashing pattern ESL Service Spec. d09r18, Section 3.10.2.10.2.2.
ESL LED Control parameter, ESL Service Spec. d09r18, Section 3.10.2.10.1.
Macros#
Definition for unknown battery voltage level (an implausible value)
ESL Display Type Assigned Numbers.
Invalid Opcode: The opcode was not recognized.
Invalid State: The request was not valid for the present ESL state.
Invalid Image Index: The Image_Index value was out of range.
Image Not Available: The requested image contained no image data.
ESL Service Specification d09r18, Section 3.7.2.4: 48 bit Image Object ID.
ESL LED type definition: sRGB.
ESL LED type definition: Monochrome.
ESL LED color gamut / brightness values.
ESL LED color gamut / brightness step percentage.
The command could not be processed successfully.
Acknowledgment of a request to control an LED.
General acknowledgment containing ESL status data.
Acknowledgment of a request to display an image.
Sensor report.
Response data as specified by the vendor of the ESL.
Mask for getting the Tag value from an ESL TLV.
Mask for getting the Length value from an ESL TLV.
ESL Display extra parameters count for init_func esl_va_method function.
ESL Display extra parameters count for write_func esl_va_method function.
Typedef Documentation#
esl_display_info_p#
typedef struct esl_display_info_t* esl_display_info_p
ESL Display Info first class abstract data pointer type.
esl_image_object_id_t#
typedef uint8_t esl_image_object_id_t[6] [6]
ESL Service Specification d09r18, Section 3.7.2.4: 48 bit Image Object ID.
Function Documentation#
esl_sensor_battery_init#
sl_status_t esl_sensor_battery_init (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
esl_sensor_battery_read#
sl_status_t esl_sensor_battery_read (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
esl_sensor_get_battery_voltage_mv#
uint32_t esl_sensor_get_battery_voltage_mv (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
esl_sensor_core_check_battery_level#
void esl_sensor_core_check_battery_level (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
esl_core_encrypt_message#
void * esl_core_encrypt_message (void * msg, uint8_t * len)
Type | Direction | Argument Name | Description |
---|---|---|---|
void * | [in] | msg | Pointer to the message to be encrypted |
uint8_t * | N/A | len | len Pointer to a variable containing the length of the message to be encrypted [in bytes] |
Message encryption function Returns
void* Pointer to the encrypted message on success, NULL otherwise.
Note
Also changes the value of *len to the resulting length on successful operation.
esl_core_decrypt_message#
void * esl_core_decrypt_message (void * msg, uint8_t * len)
Type | Direction | Argument Name | Description |
---|---|---|---|
void * | [in] | msg | Pointer to the message to be decrypted |
uint8_t * | N/A | len | len Pointer to a variable containing the length of the message to be decrypted [in bytes] |
Message decryption function Returns
void* Pointer to the decrypted message on success, NULL otherwise.
Note
Also changes the value of *len to the resulting length on successful operation.
esl_display_init#
void esl_display_init (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
ESL Tag display component init function. ESL Core component will call this during the initialization of application. This call is hidden and happens automatically.
esl_display_refresh#
sl_status_t esl_display_refresh (uint8_t display_index, uint8_t * image_index)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | [in] | display_index | Selects the display to show the image on. |
uint8_t * | [out] | image_index | Returns last image set on the refreshed display. |
Refresh the content of the ESL Tag Display. Re-displays the image which was previously set on the given screen. Returns
sl_status_t
esl_display_update#
sl_status_t esl_display_update (uint8_t display_index, uint8_t image_index)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | [in] | display_index | Selects the display to show the image on. |
uint8_t | [in] | image_index | Selects the image to be shown on the display. |
Update image data on ESL Tag Display. Returns
sl_status_t
esl_display_get_count#
uint8_t esl_display_get_count ()
ESL Display: display count getter Returns
Number of available displays
esl_core_get_last_error#
esl_error_t esl_core_get_last_error (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
Gets the last error code Returns
esl_error_t_t
esl_core_set_last_error#
void esl_core_set_last_error (esl_error_t error_code)
Type | Direction | Argument Name | Description |
---|---|---|---|
esl_error_t | [in] | error_code | error code |
Sets the last error code
esl_image_init#
void esl_image_init (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
ESL Tag image init function. ESL Core component will call this during the initialization of application. This call is hidden and happens automatically.
esl_image_characteristic_update#
void esl_image_characteristic_update (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
ESL Tag image characteristic update. ESL Core component will call this automatically on the bluetooth stack boot event. The real implementation in the ESL Tag Image component will get the display info and write it to the ESL Image Information Characteristic value for the lifecycle of the tag.
esl_image_get_data#
sl_status_t esl_image_get_data (uint8_t image_index, uint16_t * offset, uint16_t buf_size, uint8_t * target_buf)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | [in] | image_index | image_index Index of the image to get raw data chunk of |
uint16_t * | [out] | offset | *offset Size of data already read out |
uint16_t | [in] | buf_size | buf_size Actual size of the target buffer |
uint8_t * | [out] | target_buf | *target_buf Buffer address to copy the image chunk into |
Getter for an ESL Tag image raw data chunk
Note
To get full image data this function needs to be called repeatedly until the offset value increases - offset in caller has to be persistent during the process, and usually its value must be set to 0, initially
Returns
sl_status_t
esl_image_get_count#
uint8_t esl_image_get_count (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
ESL Tag maximum image count getter Returns
Number of available images
Note
: To be implemented with each custom image storage implementation!
esl_image_reset_storage#
void esl_image_reset_storage (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
Reset image storage objects Note
: To be implemented with each custom image storage implementation!
esl_display_get_width#
sl_status_t esl_display_get_width (uint8_t display_index, uint16_t * width)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | [in] | display_index | Selects the display to get the width of. |
uint16_t * | [out] | width | Horizontal pixel count of the selected display. |
Get a display width based on display index. Returns
sl_status_t SL_STATUS_OK if display_index is valid, error otherwise.
Note
: The function is only defined in esl_tag_display component (if added)
Display width getter. Returns
sl_status_t
esl_display_get_height#
sl_status_t esl_display_get_height (uint8_t display_index, uint16_t * height)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | [in] | display_index | Selects the display to get the height of. |
uint16_t * | [out] | height | Vertical pixel count of the selected display. |
Get a display height based on display index. Returns
sl_status_t SL_STATUS_OK if display_index is valid, error otherwise.
Note
: The function is only defined in esl_tag_display component (if added)
Display height getter Returns
sl_status_t
esl_display_get_type#
sl_status_t esl_display_get_type (uint8_t display_index, esl_display_type_t * type)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | [in] | display_index | Selects the display to get the type of. |
esl_display_type_t * | [out] | type | esl_display_type_t Display type defined in BT SIG. |
Get a display type based on display index. Returns
sl_status_t SL_STATUS_OK if display_index is valid, error otherwise.
Note
: The function is only defined in esl_tag_display component (if added)
Display type getter. Returns
sl_status_t
esl_image_select_object#
sl_status_t esl_image_select_object (void const * data, uint16_t length)
Type | Direction | Argument Name | Description |
---|---|---|---|
void const * | [in] | data | Pointer to ESL OTS object ID 48 bit value in little endian. |
uint16_t | [in] | length | Must be sizeof(esl_image_object_id_t) |
Select an image storage OTS object. Returns
sl_status_t SL_STATUS_OK if select successful, error code otherwise.
Note
: The function is only defined in esl_tag_image component (if added)
esl_image_chunk_received#
sl_status_t esl_image_chunk_received (uint8_t const * data, uint32_t offset, uint16_t length)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t const * | [in] | data | Pointer to image chunk data. |
uint32_t | [in] | offset | Start offset of received chunk. |
uint16_t | [in] | length | Actual length of received chunk. |
Callback on image chunk received event. Returns
sl_status_t SL_STATUS_OK if stored successfully, error otherwise.
Note
: The function is defined in esl_tag_image component (if added), and is used externally only by esl_tag_cli_test_harness to mimic the image transfer during ESL PTS tests where OTS data transfer itself is far out of scope.
esl_core_update_complete#
sl_status_t esl_core_update_complete (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
Request ESL to return the Synchronized state from a connection if it's already synchronized to the AP's PAwR train. Note
: Defined in esl_core but not exposed to the public ESL API
esl_core_start_advertising#
sl_status_t esl_core_start_advertising (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
Start ESL service advertisement. Note
: Defined in esl_core but not exposed to the public ESL API
esl_core_purge_responses#
void esl_core_purge_responses (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
Purge any pending responses that aren't sent yet. Note
: Defined in esl_tag_response.c but not exposed to the public ESL API
esl_reschedule_delayed_commands#
void esl_reschedule_delayed_commands (uint32_t current_absolute_time)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint32_t | [in] | current_absolute_time | current_absolute_time New ESL Current Absolute Time value after the clock drift adjustment. |
Re-schedule pending commands if there're any. Note
: Called by esl core internally after absolute time has been adjusted. The function is defined in esl_tag_opcodes.c
esl_core_get_sync_handle#
uint16_t esl_core_get_sync_handle (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
Get sync handle. Returns
The PAwR sync hanle or SL_BT_INVALID_SYNC_HANDLE if ESL is out of sync.
Note
: Called by esl core internally on opcodes parsing. The function is defined in esl_tag_core.c
esl_core_get_request_event#
uint16_t esl_core_get_request_event (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
Get request event value for PAwR response. Returns
The most recent PAwR sync request event value.
Note
: Called by esl core internally on opcodes parsing. The function is defined in esl_tag_core.c
esl_core_get_request_subevent#
uint8_t esl_core_get_request_subevent (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
Get request subevent value for PAwR response. Returns
The most recent PAwR sync request subevent value.
Note
: Called by esl core internally on opcodes parsing. The function is defined in esl_tag_core.c
esl_core_invalidate_config#
void esl_core_invalidate_config (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
Invalidate entire ESL configuration to prevent later opcode processing. Note
: Called by esl core internally on factory reset opcode execution. The function is defined in esl_tag_core.c
typedef#
typedef (struct { uint8_t data[5];uint8_t bit_off_period;uint8_t bit_on_period;} )
ESL LED flashing pattern ESL Service Spec. d09r18, Section 3.10.2.10.2.2.
Type | Direction | Argument Name | Description |
---|---|---|---|
struct { uint8_t data[5];uint8_t bit_off_period;uint8_t bit_on_period;} | N/A |
typedef#
typedef (struct { uint8_t index;esl_led_gamut_control_t gamut;esl_led_flashing_pattern_t pattern;esl_led_repeats_type_t repeats;} )
ESL LED Control parameter, ESL Service Spec. d09r18, Section 3.10.2.10.1.
Type | Direction | Argument Name | Description |
---|---|---|---|
struct { uint8_t index;esl_led_gamut_control_t gamut;esl_led_flashing_pattern_t pattern;esl_led_repeats_type_t repeats;} | N/A |
esl_led_init#
void esl_led_init (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
ESL Tag LED init function. ESL Core component will call this during the initialization of application. This call is hidden and happens automatically.
esl_led_control#
sl_status_t esl_led_control (esl_led_control_t * control_param)
Type | Direction | Argument Name | Description |
---|---|---|---|
esl_led_control_t * | [in] | control_param | ESL LED control parameters defined by the ESL standard - excluding the ESL ID. |
ESL Tag LED control function Note
updates the active LED bit in ESL basic state register according to the actual status of all LEDs
Returns
sl_status_t
esl_led_is_srgb#
bool esl_led_is_srgb (uint8_t led_index)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | N/A | led_index |
Get ESL Tag LED count Returns
Number of available LEDs
esl_core_respones_init#
void esl_core_respones_init ()
Init ESL Tag responses queue. ESL Core component will call this during the initialization of application. This call is hidden and happens automatically.
esl_core_build_response#
sl_status_t esl_core_build_response (tlv_t tlv, const void * input_data)
Type | Direction | Argument Name | Description |
---|---|---|---|
tlv_t | [in] | tlv | The TLV to create the response stream for |
const void * | [in] | input_data | can be a pointer to the basic status, led status etc. |
Create response byte stream for single TLV based on input data and error status (if any) then puts the response stream into a circular buffer. The resulting output length of a single TLV will be the length encoded in that particular TLV + 1 byte as per ESL specification. Multiple response streams will be then concatenated on consecutive calls up to the maximum length limit of 48 bytes for multiple response data. Note
the actual length of the input data length MUST be in correspondence with the TLV passed as the first parameter!
Returns
sl_tatus_t
esl_core_get_responses#
uint8_t esl_core_get_responses (uint8_t remaining_length, uint8_t * buf_p)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | [in] | remaining_length | size of data out buffer |
uint8_t * | [out] | buf_p | pointer to data buffer to copy the responses into |
Copy all possible responses from internal circular buffer to a temporary linear buffer. Circular buffer drops the successfully read out data, while it might keep remaining responses which doesn't fit into the target buffer. Consistency of any response will be kept, that is, it might copy less data than the allowed maximum length passed as the first parameter, if there are responses left still in the internal circular buffer which otherwise wont fit into the target buffer. Returns
overall length of responses, might be 0 if there's no response
esl_sensor_init#
void esl_sensor_init (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
ESL Tag sensor init function. ESL Core component will call this during the initialization of application. This call is hidden and happens automatically.
esl_sensor_read#
sl_status_t esl_sensor_read (uint8_t index)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | N/A | index |
Read interface (only) for ESL Sensor. Returns
sl_status_t SL_NOT_SUPPORTED if the ESL Sensor component is missing.
esl_sensor_get_count#
uint8_t esl_sensor_get_count (void )
Type | Direction | Argument Name | Description |
---|---|---|---|
void | N/A |
Get ESL Tag Sensor count Returns
Number of available sensors
esl_display_create#
sl_status_t esl_display_create (uint16_t width, uint16_t height, esl_display_type_t type, esl_display_info_p * info)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint16_t | [in] | width | Display horizontal pixel count. |
uint16_t | [in] | height | Display vertical pixel count. |
esl_display_type_t | [in] | type | Display type defined in BT SIG Assigned Numbers. |
esl_display_info_p * | [out] | info | esl_display_info_p type pointer to the newly created display info data. This value needs to pass to esl_display_add call, which has to follow the invocation of esl_display_create for any new display to be created, fully and properly. |
Create an ESL Tag display. Any display which a Tag wants to implement needs to becreated properly in the first place.
Returns
sl_status_t
esl_display_add#
sl_status_t esl_display_add (esl_display_info_p info, esl_va_method_p init_func, esl_va_method_p write_func)
Type | Direction | Argument Name | Description |
---|---|---|---|
esl_display_info_p | [in] | info | esl_display_info_p type pointer, can be get by calling esl_display_create previously. |
esl_va_method_p | [in] | init_func | esl_va_method_p type pointer to the low-level init function of the display driver. Driver implementation, however, it's up to the user to implement it properly - the only rule is to follow the interface specification defined by the esl_va_method_p type. If the 'init' method is not necessary for the given display, then a NULL pointer can be passed. |
esl_va_method_p | [in] | write_func | esl_va_method_p type pointer to the low-level write function of the display driver. Has to be implemented by the users, and it's mandatory (can't be NULL). |
Add an ESL Tag display to the list of available displays after creation. Any display on a Tag can be only used after adding it to the list.
Returns
sl_status_t
esl_display_bt_on_event#
void esl_display_bt_on_event (sl_bt_msg_t * evt)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_bt_msg_t * | [in] | evt | Event coming from the Bluetooth stack. |
ESL display's bluetooth stack event handler. This one runs by the user implementation (usually in app.c) in parallel.
esl_display_set_image#
sl_status_t esl_display_set_image (uint8_t display_index, uint8_t image_index)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | [in] | display_index | Selects the display to show the image on. |
uint8_t | [in] | image_index | Selects the image to be shown on the display. |
ESL Display: chose an image to show. Invokes the users write_func passed to esl_display_add as its 3rd parameter. Returns
sl_status_t
esl_led_add#
sl_status_t esl_led_add (esl_led_type_t type, uint8_t red_value, uint8_t green_value, uint8_t blue_value)
Type | Direction | Argument Name | Description |
---|---|---|---|
esl_led_type_t | [in] | type | Possible ESL LED type defined by ESL standard |
uint8_t | [in] | red_value | ESL LED (initial, in case of sRGB type) red color value. |
uint8_t | [in] | green_value | ESL LED (initial, if sRGB) green color value. |
uint8_t | [in] | blue_value | ESL LED (initial, if sRGB) blue color value. |
Add an ESL Tag LED to the list of available LEDs after creation. Any LED on a Tag can be only used after adding it to the internal LED registry.
Returns
sl_status_t
esl_led_on#
sl_status_t esl_led_on (uint8_t led_index, esl_led_gamut_control_t gamut)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | N/A | led_index | |
esl_led_gamut_control_t | N/A | gamut |
ESL Tag LED on function. Simple turn on function with given brightness and color values, to be implemented by end users. It's the users responsibility to actually turn given LED on with the given brightness and color parameters (if applicable) and the function shall return SL_STATUS_OK in case of success. Return SL_STATUS_FAIL on any other case (e.g. index out of bound, detectable HW error etc. Returns
sl_status_t
esl_led_off#
sl_status_t esl_led_off (uint8_t led_index)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | N/A | led_index |
ESL Tag LED off function. Simple turn off function, similar to sl_esl_led_on method except it omits the gamut parameter entirely. To be implemented by end users. It's the users responsibility to actually turn given LED off and the function shall return SL_STATUS_OK in case of success. Return SL_STATUS_FAIL on any other case (e.g. index out of bound, detectable HW error etc. Returns
sl_status_t
esl_led_create_color#
esl_led_gamut_control_t esl_led_create_color (uint8_t red_value, uint8_t green_value, uint8_t blue_value, uint8_t brightness)
Type | Direction | Argument Name | Description |
---|---|---|---|
uint8_t | [in] | red_value | ESL LED red color level |
uint8_t | [in] | green_value | ESL LED red color level |
uint8_t | [in] | blue_value | ESL LED red color level |
uint8_t | [in] | brightness | ESL LED red color level |
Assembly ESL Tag LED gamut value from input parameters for esl_led_gamut_control_t type Returns
esl_led_gamut_control_t Resulting ESL LED gamut value
esl_led_bt_on_event#
void esl_led_bt_on_event (sl_bt_msg_t * evt)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_bt_msg_t * | [in] | evt | Event coming from the Bluetooth stack. |
ESL LED's bluetooth stack event handler. This one runs by the user implementation (usually in app.c) in parallel.