UM2751
User manual
ST25DV-I2C Linux
®
user space driver
Introduction
This document explains how to use the STSW-ST25DV007 software package to control a ST25DV-I2C series dynamic NFC tag from a Linux ® platform.
The STSW-ST25DV007 software package provides Linux user space driver and some examples that can be configured to run on any Linux platform.
The ST25DV-I2C is an NFC dynamic tag, which can be managed by an RFID reader or by an NFC phone, it also has an I2C interface to communicate with an MCU or MPU. The ST25DV-I2C is available, for example, on the X-NUCLEO-NFC04A1 expansion board.
Information and documentation related to the NFC components, the X-NUCLEO ‑ NFC04A1 expansion board and the
STSW ‑ ST25DV007 software are available on www.st.com
.
UM2751 - Rev 1 - August 2020
For further information contact your local STMicroelectronics sales office.
www.st.com
1
UM2751
Purpose
Purpose
ST25DV-I2C series dynamic NFC/RFID tags are integrated circuits that can communicate with both:
• RFID readers and NFC phones, based on the ISO/IEC 15693 and NFC Forum Type 5 tag specifications.
• An MCU or MPU using an I2C interface.
These devices can be used on a Linux platform to enable a wireless communication, to easily transfer data from a
Linux platform to a smartphone (for instance: URL, GPS coordinates, Out-Of-Band pairing data, etc…). Moreover, the fast transfer mode feature from the ST25DV ‑ I2C allows to effectively download and upload a file from or to a smartphone.
The STSW ‑ ST25DV007 software package provides the required code to control a ST25DV ‑ I2C device from the user space of a Linux platform having an I2C controller.
UM2751 - Rev 1 page 2/11
UM2751
Software structure
2
2.1
2.2
2.2.1
2.2.2
Software structure
•
•
•
•
The STSW-ST25DV007 software is divided in several layers:
• ST25DV-I2C component driver
Board support package
NDEF library middleware
Fast transfer mode middleware
Sample project codes
ST25DV-I2C component driver
The ST25DV-I2C component driver provides the methods to configure and control a ST25DV-I2C device. This part of the code is independent from the hardware, and it requires some basic IO functions to be implemented
(see the Section 2.2 Board support package ) such as I2C read/write, gpio control, etc…
The ST25DV-I2C component driver files are in the Drivers/BSP/Components/st25dv-i2c directory.
Board support package
The board support package implements two different aspects:
• The low-level IO functions called by the ST25DV-I2C component driver
• An API to the ST25DV-I2C component driver methods
The board support package files are in the Drivers/BSP/Linux directory.
Low-level IO functions
The low-level IO layer implements all the low-level functions required by the ST25DV-I2C driver. This layer is implemented in the Drivers/BSP/Linux directory with the following files:
Table 1. Board support package files overview
Files Description st25dv-i2c_linux.c
st25dv-i2c_linux.h
•
•
These files implement the functions to: configure, read and write the I2C interface get a millisecond tick
This code relies on the /dev/i2c-X file to take control of the I2C peripheral.
st25dv-i2c-gpo.c
st25dv-i2c-gpo.h
st25dv-i2c-lpd.c
st25dv-i2c-lpd.h
These files implement the functions to configure and receive interruptions from the GPO pin of the
ST25DV-I2C.
This code uses the /dev/gpiochipX file and a dedicated thread to poll for an event on the GPIO.
These files implement the functions to configure and control the low power down pin of the ST25DV-I2C.
•
•
•
This code uses the following files to control the GPIO:
/sys/class/gpio/export
/sys/class/gpio/gpioXX/direction
/sys/class/gpio/gpioXX/value.
These functions are specific to the board used and must be adapted to the platform on which they are used (see
Section 3 How to configure a board
).
API to the ST25DV-I2C driver methods
This API is only a wrapper around the ST25DV-I2C component driver.
It is implemented in Drivers/BSP/Linux/bsp_nfctag.c and Drivers/BSP/Linux/bsp_nfctag.h files.
UM2751 - Rev 1 page 3/11
UM2751
NDEF library middleware
2.3
2.4
2.5
2.5.1
2.5.2
2.5.3
2.5.4
NDEF library middleware
•
•
The NFC Forum defines a standard format to use when reading/writing an NFC device. This format is known as
NDEF messages. The NDEF library implements high level methods to easily format data into a NDEF compliant manner. This STMicroelectronics library is delivered as a middleware, fully independent from the hardware and coming with an interface file to be implemented for the targeted platform.
In the STSW-ST25DV007 software package these interface files are implemented in:
Projects\NDEF_URI\Src\lib_NDEF_config.c
Projects\NDEF_BLUETOOTH\Src\lib_NDEF_config.c
The NDEF library middleware files are in the Middlewares/ST/lib_nfc directory.
Fast transfer mode middleware
The ST25DV-I2C device implements a fast transfer mode feature, which allows a fast communication with a NFC reader or smartphone over its NFC interface. The length of the messages sent through the fast transfer mode is limited, and a protocol has been defined to chain the messages in order to transfer a large amount of data. The fast transfer mode middleware is an implementation of this protocol which enables an efficient message chaining and an error detection and recovery mechanism.
This middleware is independent from the hardware and is coming with an interface file to be implemented for the targeted platform. The ST25FTM middleware examples for ST25R NFC readers can be found on www.st.com
.
In the STSW-ST25DV007 software package this interface file is implemented in the following files:
• Projects/FTM/Src/st25dv-i2c_ftm.c
• Projects/FTM/Src/st25dv-i2c_ftm.h
The fast transfer mode middleware files are in the Middlewares/ST/FTM directory.
Sample projects
In this section, a short overview of the sample projects included in the STSW-ST25DV007 pack is provided.
The sample projects:
• must be adapted to the targeted Linux platform (as explained in
Section 3 How to configure a board
)
• show to the user how to use the APIs to correctly initialize and use the dynamic NFC/RFID tag IC (ST25DV-
I2C device)
The sample projects are in the ./Projects directory.
NDEF_URI
This application shows how to write a simple URI NDEF message to the ST25DV-I2C EEPROM using the NDEF lib middleware. A message is displayed when the message has been successfully written.
A smartphone or a NFC reader can be used to read the NDEF_URI message.
NDEF_BLUETOOTH
This application shows how to write a Bluetooth OOB NDEF message to the ST25DV-I2C EEPROM using the
NDEF lib middleware. A message is displayed when the message has been successfully written.
A smartphone or a NFC reader can be used to read the NDEF_BLUETOOTH message.
GPO (General purpose output)
This example shows how to enable and use the GPO.
After initialization, an interrupt is programmed to detect field changes in proximity of the ST25DV-I2C.
A message is displayed when the field is detected and when the field disappears.
I2CPROTECTION
This example shows how to create areas in the ST25DV-I2C and how to protect them.
Text is displayed on the console.
UM2751 - Rev 1 page 4/11
UM2751
Sample projects
2.5.5
2.5.6
2.5.7
LPD (Low power down)
This example shows how to activate low power down (LPD) pin.
By entering 1 or 0, the LPD pin is activated or deactivated.
When the LPD pin is activated, the ST25D-I2C VCC is cut off, the power consumption is minimum and communication via I 2 C is not available.
Mailbox
This example shows how to write a message into the mailbox and how to read mailbox status register of
ST25DV ‑ I2C device. The text is displayed.
FTM (Fast transfer mode)
This example shows how to use the FTM library middleware to transmit a file over NFC. The user can choose to either receive, transmit or retransmit a file. In case of reception or retransmission the received data are stored in a file: ./ftm_rx.
To run ST25FTM example it is required to use a ST25R NFC reader.
UM2751 - Rev 1 page 5/11
3
UM2751
How to configure a board
How to configure a board
The board support package layer must be slightly adapted to the targeted Linux platform, in order to select the
I2C peripheral to be communicate with ST25DV ‑ I2C and the GPIOs is connected to the ST25DV ‑ I2C GPO and
LPD pins.
All the required definitions are listed in the following file: Drivers/BSP/Linux/hwconfig.h.
Table 2. Hardware configuration definition
Feature
I2C
GPO
LPD
Define
ST25DV_I2C_NR
ST25DV_GPO_GPIOCHIP
ST25DV_GPO_PIN
Description
It defines the I2C peripheral number used to communicate with the ST25DV-I2C.
The value is used to complete the path to the /dev/i2c-X file.
It defines the GPIOCHIP number connected to the ST25DV-I2C GPO pin.
The value is used to complete the path to the /dev/gpiochipX file.
It defines the GPIO pin number of the GPIOCHIP connected to the ST25DV-I2C GPO pin.
ST25DV_LPD_PIN
ST25DV_LPD_VALUE
It defines the global GPIO pin number connected to the ST25DV-I2C LPD pin.
It is used to export this GPIO.
ST25DV_LPD_DIRECTION
It defines the path to the Linux file defining the GPIO direction connected to the
ST25DV-I2C LPD pin such as:
/sys/class/gpio/gpioXX/direction
It defines the path to the Linux file defining the GPIO value connected to the ST25DV-
I2C LPD pin such as:
/sys/class/gpio/gpioXX/value
UM2751 - Rev 1 page 6/11
4
UM2751
Compiling and running the sample projects
Compiling and running the sample projects
•
•
The STSW-ST25DV007 sample projects come with a Makefile and can be compiled using a C compiler like GCC.
Some extra libraries are required for the link:
The pthread Linux library is used to create a thread detecting an event on the GPO line
The ZLIB library is used by the FTM project to compute the CRC
The following commands can be used to compile a sample project: cd Projects/<Project name> make
It creates a st25dv-i2c_<project name> executable, that the user can run by calling the following commands.
• chmod +x st25dv-i2c_<projectname>
• ./st25dv-i2c_<projectname>
UM2751 - Rev 1 page 7/11
Revision history
Date
04-Aug-2020
Table 3. Revision history
Revision
1 Initial release
Changes
UM2751
UM2751 - Rev 1 page 8/11
UM2751
Contents
Contents
1 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
2 Software structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
2.1
ST25DV-I2C component driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2
Board support package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2.1
2.2.2
Low-level IO functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
API to the ST25DV-I2C driver methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3
NDEF library middleware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4
Fast transfer mode middleware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.5
Sample projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.5.1
2.5.2
2.5.3
2.5.4
2.5.5
2.5.6
2.5.7
NDEF_URI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
NDEF_BLUETOOTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
GPO (General purpose output) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
I2CPROTECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
LPD (Low power down) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
FTM (Fast transfer mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 How to configure a board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
4 Compiling and running the sample projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
List of tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
UM2751 - Rev 1 page 9/11
UM2751
List of tables
List of tables
Table 1. Board support package files overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Table 2. Hardware configuration definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Table 3. Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
UM2751 - Rev 1 page 10/11
UM2751
IMPORTANT NOTICE – PLEASE READ CAREFULLY
STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.
Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of
Purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.
ST and the ST logo are trademarks of ST. For additional information about ST trademarks, please refer to www.st.com/trademarks . All other product or service names are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2020 STMicroelectronics – All rights reserved
UM2751 - Rev 1 page 11/11
