STMicroelectronics ST25RU3993 ST UHF User Manual
UM2618
User manual
ST25RU3993 ST UHF library
Introduction
The ST UHF library (STSW-ST25RU-SDK) is a middleware software stack written in ANSI C, to build RAIN® RFID enabled
applications for reader devices based on ST25RU3993. This document describes the usage of the ST UHF library software API.
Along with this package, a comprehensive demonstration source code is available to illustrate the usage of the ST UHF library
for Windows® and Linux® platforms. The complete software stack is ANSI C and POSIX compatible and enables fast and
straightforward porting to other operating systems and/or toolchains.
UHF application
STUHFL
Standards
EPC UHF
Gen2V2
...
Device
HAL
ST25RU3993-HPEV board firmware
Protocol
Bus
UM2618 - Rev 4 - April 2021
For further information contact your local STMicroelectronics sales office.
www.st.com
1 System overview
The ST UHF library (STUHFL) design is a classic middleware software stack running on a host system. It
provides a simple software API to abstract low-level communication details. As shown in the simplified system
overview the system is made up of two hardware components running the involved software components.
UM2618
System overview
Figure 1. System overview
UHF application
Host
STUHFL
STUHFL EVAL API
ST25RU3993 firmware
SPI
Device/reader module
The first component (device/reader module) runs the firmware with low-level driver implementation to operate
the ST25RU3993 reader IC and various protocols. The firmware implements a software interface to the ST UHF
library.
The second component (host side) runs the ST UHF library and abstracts the low-level functionality. It provides a
clean software API for UHF applications.
The ST UHF library runs on host systems with an operating system as well as on embedded systems (with OS
or native), with limited resources. Even a design without a dedicated host module is possible, where the complete
system runs on the reader module only.
1.1
Note: Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.
General information
The software described in this document supports Arm®-based device.
ST25RU3993
IRQ
1.2 Features
• Comprehensive middleware to build RAIN® RFID enabled applications for reader devices based on
ST25RU3993
• Mirrored host and device library API
• Written in pure ANSI C99
• POSIX compatible
UM2618 - Rev 4
page 2/24
• Straightforward portability across different platforms (MCUs/RTOSs/OSs)
• Compatible with main UHF standards
– EPC UHF Gen2v2
– GB/T 29768
• Source code example implementation available
– Windows
– Linux® (Raspberry Pi 3B)
– Further sample platform implementations underway
®
1.3 Hardware requirements
The main purpose of the ST UHF library is to simplify the ST25RU3993 low-level hardware driver, and to provide
an easy-to-use software interface. Therefore, the ST UHF software library operates only with the ST25RU3993based demonstration boards listed below and their corresponding firmware:
• ST25RU3993 EVAL board
• ST25RU3993 ELANCE module
It is anyway possible to port the low-level hardware driver to other devices hosting a suitable MCU to drive the
firmware.
UM2618
Hardware requirements
1.4 Building environment
Currently all host side software components and demonstration codes are generated by using Microsoft Visual
Studio 2017 (VS2017). The package contains a VS2017 solution hosting projects for two different platforms. The
first project for Win32 platforms is suitable for generating code running on Windows 7 platform (and newer ones).
The second project is for Arm platforms running on Linux devices. The Arm project uses the possibility to do
remote compilation with VS2017. This requires a properly configured Arm device accessible in the same network.
Note: The available ST UHF library project for Arm and the corresponding example project use Raspberry Pi 3B
hardware for development. For more details about project configuration, refer to the appropriate project solution
files.
UM2618 - Rev 4
page 3/24
2 Software architecture
The ST UHF library follows a classic stacked middleware software design and consists of components that run on
a reader module and on a host system as the default use case.
The complete ST UHF library is ANSI-C and POSIX compliant, resulting in easy porting to several other operating
systems and platforms.
The ST UHF library currently supports the most common UHF standards. Extensions and more protocols will be
released in upcoming versions.
Working sample source code is available for Windows and Linux, to use different library modules.
UM2618
Software architecture
2.1
ST UHF library API
The exposed ST UHF library API allows the user to build RAIN applications on ST25RU3993 reader devices.
Three stacked layers represent the complete exposed ST UHF library API.
• Activity
• Session
• Device
In this arrangement abstraction and complexity increase starting from device moving up to activity. The purpose
of the device layer is to abstract the hardware specific functionalities, such as direct register access. The session
layer uses the device layer to implement entire protocols such as the EPC Gen2V2 standard or other UHF
standards and protocols. The activity layer uses the device and session layers to abstract functionalities for
automated inventory of tags running in the background.
Table 1. Main layers
Layer Description
Activity Functionality like background inventory lookup via a build-in "Inventory Runner"
Session Implementation of different standards or protocols like EPC Gen2V2
Device Abstraction of hardware specific functionalities like register access
2.2 STUHFL EVAL API
On the device/reader module side the STUHFL EVAL API provides a basic software interface to ST25RU3993
low-level drivers. The ST UHF library builds on top of this low-level interface and derives its ST25RU3993
dependent functionalities. Applications where no host system is involved directly call the low-level STUHFL EVAL
API on reader/device side.
Note: Applications not using the ST UHF library stack may be directly attached to this interface.
2.3 ST UHF library wrappers
On top of the ST UHF library host interface, multiple wrappers are available for fast prototyping.
• Java/C#/Python
• ST EVAL API
Java, C# and Python are state of the art programming languages and enable software developers to implement
fast and efficiently different kinds of UHF application. In addition to wrappers for different software development
languages it is also possible to implement other custom interface wrapper like ST EVAL API wrapper.
Note: Software wrappers for others languages can easily be implemented when these programming languages
support calling native C code.
UM2618 - Rev 4
page 4/24
UM2618
Not exposed layers
The STUHFL EVAL API wrapper (host side) fully emulates the STUHFL EVAL API on the device side. This allows
users to start developing firmware applications on host systems and finish their task by porting the firmware
to the device/reader side. The advantage of this approach is that the host side offers debuggers, advanced
code tracers and many other host system development features. These host tools speed-up and simplify code
development. When the firmware code development on the host side is completed, simply "copy and paste" the
firmware application code to the device/reader side. No additional source code modifications are required to run
the firmware on the MCU.
Note: The STUHFL EVAL API wrapper fully emulates the STUHFL EVAL API, exactly as available on the device side.
2.4 Not exposed layers
Underneath the exposed ST UHF library layer, several other layers work on the host with their counterparts on the
device side. This layer stack is taking care of the data transfer between the host and the reader device.
• Dispatcher
• Protocol
• Bus
These layers follow a stack design and depend only on their direct neighbours. The main purpose of the
dispatcher layer is to bundle the ST UHF library API function calls in one single module and to forward it to
the protocol layer.
The protocol layer transfers the abstracted function calls into transferable data chunks and forwards these data
packets to the bus layer.
Finally, the bus layer sends the data chunks over a physical interface and receives them on the device/reader
module side. For the data transfer in the opposite direction from device/reader side to the host side, the protocol
and the dispatcher layers do their task inversely.
Layer Description
Dispatcher Merge and divide from API layers
Protocol Encodes and decodes data into TLV formatted data chunks ready for transfer between host and device
Bus Platform depended transfer layer handling data exchange
2.4.1 Support and helper
In addition to the above mentioned not exposed layers the library implements support and helper layers, which
provide relevant functionalities and expose their interface to almost all other modules.
Layer Description
TLV Tag-Length-Value encoding and decoding support
Logging Logging helper
Table 2. Not exposed layers
Table 3. Helper modules
UM2618 - Rev 4
page 5/24
Figure 2. ST UHFL library system architecture
STUHFL wrappers
UM2618
Not exposed layers
Host side
· STUHFL_F_Start(…)
· STUHFL_F_Stop(…)
· STUHFL_F_RegisterHandler(…)
· …
· STUHFL_F_Gen2Inventory(…)
· STUHFL_F_Gen2Select(…)
· STUHFL_F_Gen2Read(…)
· …
· STUHFL_F_GB29768Inventory(…)
· …
· STUHFL_F_Gen2Inventory(…)
· STUHFL_F_Gen2Select(…)
· STUHFL_F_gen2Read(…)
· …
· STUHFL_F_GBT29768Inventory(…)
· …
· STUHFL_F_Connect(…)
· STUHFL_F_SetParam(…)
· STUHFL_F_GetParam(…)
· STUHFL_F_Reboot(…)
· ...
STUHFL
EVA API
Java/C#/... ...
STUHFL API
Activity layer
Inventory runner
Session layer
Gen2V2 GB/T 29768
Device layer
ST25RU3993
EVAL board
ST25RU3993
Dispatcher
Protocol layer
Bus layer
UART
... ... ...
... ...
module
...
...
Support and helpers
Logging ... ...
Device/reader module side
Bus layer
TLV
Protocol layer
Dispatcher
STUHFL EVAL API
Platform dependent
ST25RU3993 low level drivers
SPI TIMER GPIO ...
Platform dependent drivers
UM2618 - Rev 4
page 6/24
2.5 Host side usage
The functionality exposed by the ST UHF library API enables the development of RAIN applications based on
ST25RU3993 reader IC devices or modules on host devices. Host systems running the OS Windows or Linux are
supported by default. As the whole library is ANSI-C and POSIX compatible, it also easily builds for other POSIX
compatible platform.
The following figure shows an example of host side usage.
Figure 3. ST UHF library usage overview
UHF application
Host
e.g. RPi
STUHFL
UM2618
Host side usage
Device/reader module
e.g. STM32L476 based EVAL board
ST25RU3993
device firmware
STUHFL EVAL API
Device drivers
ST25RU3993 drivers
SPI
ST25RU3993
IRQ
UM2618 - Rev 4
page 7/24
2.6 Device side usage
The functionalities exposed by STUHFL EVAL API provide an abstract interface to the full UHF functionalities
provided by the ST25RU3993 reader IC, without the burden of manually handling low-level register access.
Therefore, this interface is device-independent and enables the implementation of any abstract UHF application.
The following figure shows an example of device side usage.
UM2618
Device side usage
Figure 4. ST UHF library EVAL API device side usage
UHF application
STUHFL EVAL API
Device drivers
Device/reader module
e.g. STM32L476 based EVAL board
ST25RU3993 module based firmware
ST25RU3993 drivers
SPI
ST25RU3993
IRQ
UM2618 - Rev 4
page 8/24
Loading...