Libelium's library
It is mandatory to include the RFID library when using this module. The following line must be introduced at the beginning of the code:
#include <WaspRFID13.h>
Waspmote's API RFID/NFC files:
WaspRFID13.cpp
WaspRFID13.h
API functions
Private functions:
The following functions are executed inside the API functions. In normal conditions, the user must NOT manage or use them.
Function | Brief description |
| set internal parameters of the PN532 |
| Send data stored in dataTX |
| Wait for ACK response |
| Wait the response of the module |
| Get data from the module |
| Calculates the checksum |
| Calculates the length checksum |
*To avoid the hang of the module this function will wait for 5 seconds approximately. If no tag is detected, the program will continue after this time. The waiting time can be configured in the library.
It is the class constructor. It is only executed inside the API's function init().
Public functions:
The following functions are public and therefore they can be executed in the loop() or setup() functions. They provide the tools to perform all the features of the RFID/NFC module.
Function | Brief description |
| switches the module off |
| switches the module on, in one of the 2 sockets |
| inits the module, configures it and searches for new cards |
| authenticates one card’s sector |
| The PN532 sends back the version of the embedded firmware. |
| reads one card’s block |
| authenticates one card's sector and reads one block |
| writes one card’s block |
| authenticates one card's sector and writes one block |
| writes one card's block and checks that |
| authenticates one card's sector, writes one block and checks that |
| put the module into Power Down mode |
| wake up from power dowm mode. |
| print data stored in vectors |
| changes both keys and access conditions to one card's sector |
| compares 2 UIDs |
| searches one UID inside one group of UIDs |
| converts from a string to a uint8_t vector |
| converts from a uint8_t vector to a integer |
This function takes the RFID/NFC module out of the power-down mode by starting the wake up procedure.
If you connected the RFID/NFC module into the usual XBee socket, please use SOCKET0; if you connected the RFID/NFC module into the Expansion Board, you must use SOCKET1.
Example of use:
{RFID13.ON(SOCKET0); // switches the module on with the socket 0 (the normal socket, without// using the Expansion Board)}
This function takes the RFID/NFC module to the software power-down mode.
Example of use:
{RFID13.OFF(); // switches the module off}
This function initializes the necessary variables, requests if there is an ISO/IEC 14443-A card in the field, does the anti-collision loop and selects the card to operate.
This function is enough for those applications which just require to get the UID of cards, since most of the ISO/IEC 14443-A processes are executed inside.
It is highly advised to execute this function in the beginning of each loop, just as shown in any of the examples. Even if the module is already initialized, it is good to start from the same point every time.
This function initializes many internal registers and variables. All the settings are optimized for the best operation. Changing those settings may result in a defective operation.
Example of use:
{uint8_t state; // stores the status of the executed commanduint8_t ATQ[2]; // stores the ATQ-A (answer to request, type 14443- A). Generally stored in a// bigger buffer (16B)uint8_t UID[4]; // stores the UID (unique identification) of a card...state = RFID13.init(UID, ATQ); // The goal of this command is to detect as many targets // (maximum MaxTg) as possible in passive mode.}
This function authenticates a sector of the card thanks to the key or password. It is important to remark that before doing any read or write in a block, it is mandatory to authenticate us in it.
The only exception is the UID, which can be read without authentication; it is returned by the init() function.
One authentication is enough to validate all the 4 blocks in a sector.
Example of use:
{uint8_t state; // stores the status of the executed commanduint8_t ATQ[2]; // stores the ATQ-Auint8_t UID[4]; // stores the UID (unique identification) of a carduint8_t key[6]; // stores the key or password...memset(key, 0xFF, 6); // the key by default, edit if neededstate = RFID13.init(UID, ATQ); // inits systems and look for cardsstate = RFID13.authenticate(UID, 2, key); // authenticates block number 2 (all sector 0// actually)of the selected card. State of the executed// function is stored.}
This function reads the 16 bytes stored in a block. This block must have been authenticated before reading.
Example of use:
{uint8_t state; // stores the status of the executed commanduint8_t aux[16]; // auxiliar bufferuint8_t UID[4]; // stores the UID (unique identification) of a carduint8_t key[6]; // stores the key or password...memset(key, 0xFF, 6); // the key by default, edit if neededstate = RFID13.init(UID, aux); // inits systems and look for cardsstate = RFID13.authenticate(UID, 2, key);// authenticates block 2state = RFID13.read(2, aux);// reads the block 2. Data is stored in aux.}
This function authenticates a block of the card first, and then reads the 16 bytes stored in a block. This function is useful to do these 2 steps in just one.
Example of use:
{uint8_t state; // stores the status of the executed commanduint8_t aux[16]; // auxiliar bufferuint8_t UID[4]; // stores the UID (unique identification) of a carduint8_t key[6]; // stores the key or password...memset(key, 0xFF, 6); // the key by default, edit if neededstate = RFID13.init(UID, aux); // inits systems and look for cardsstate = RFID13.readWithAuth(UID, key, aux, 2); // authenticates block 2, then reads it. Data// is stored in aux.}
This function writes 16 bytes in a block. This block must have been authenticated before writing.
Example of use:
{uint8_t state; // stores the status of the executed commanduint8_t aux[16]; // auxiliar bufferuint8_t UID[4]; // stores the UID (unique identification) of a carduint8_t key[6]; // stores the key or password...memset(key, 0xFF, 6); // the key by default, edit if neededstate = RFID13.init(UID, aux); // inits systems and look for cardsstate = RFID13.authenticate(UID, 2, key);// authenticates block 2memset(aux, 0x00, 16); // stores 0\'s in aux, 16 bytesstate = RFID13.write(2, aux); // writes the content of aux in block number 2}
This function authenticates a block of the card first, and then writes 16 bytes in the block. This function is useful to do these 2 steps in just one.
Example of use:
{uint8_t state; // stores the status of the executed commanduint8_t aux[16]; // auxiliar bufferuint8_t UID[4]; // stores the UID (unique identification) of a carduint8_t key[6]; // stores the key or password...memset(key, 0xFF, 6); // the key by default, edit if neededstate = RFID13.init(UID, aux); // inits systems and look for cardsmemset(aux, 0x00, 16); // stores 0\'s in aux, 16 bytesstate = RFID13.writeWithAuth(UID, key, aux, 2); // authenticates block 2, then writes the// content of aux in it}
This function writes 16 bytes in a block, and then checks the correct data was written. This block must be authenticated before writing. This function is useful to do these 2 steps in just one.
Example of use:
{uint8_t state; // stores the status of the executed commanduint8_t aux[16]; // auxiliar bufferuint8_t UID[4]; // stores the UID (unique identification) of a carduint8_t key[6]; // stores the key or password...memset(key, 0xFF, 6); // the key by default, edit if neededstate = RFID13.init(UID, aux); // inits systems and look for cardsstate = RFID13.authenticate(UID, 2, key);// authenticates block 2memset(aux, 0x00, 16); // stores 0\'s in aux, 16 bytesstate = RFID13.writeAndCheck(aux, 2); // writes the content of aux in block 2, then checks // its content is OK}
This function authenticates a block of the card first, then writes 16 bytes in the block, and then checks the correct data was written. It is useful to do these 3 steps in just one.
Example of use:
{uint8_t state; // stores the status of the executed commanduint8_t aux[16]; // auxiliar bufferuint8_t UID[4]; // stores the UID (unique identification) of a carduint8_t key[6]; // stores the key or password...memset(key, 0xFF, 6); // the key by default, edit if neededstate = RFID13.init(UID, aux); // inits systems and look for cardsstate = RFID13.authenticate(UID, 2, key);// authenticates block 2memset(aux, 0x00, 16); // stores 0\'s in aux, 16 byteswriteAndCheckWithAuth(UID, key, aux, 2); // authenticates block 2, then writes the content of// aux in it and checks its content is OK}
This function authenticates a block of the card first, then sets the new keys A and B, and the access bits for a sector. After that, it authenticates again and reads the trailer block. This function is useful to do these 4 steps in just one.
This function should be executed with care because if any of the internal functions is not successfully executed, then the sector could be damaged or left unaccessible. That is why it is highly recommended to read the output status in order to check if all the process was completed. Please place the card still and close distance from the RFID/NFC module's antenna when setting new keys; if the whole process is not properly completed, the access to that sector might be lost forever.
There are many options for the configuration of the access bits. We suggest to use the same options that the card has by default: {0xFF, 0x07, 0x80, 0x69}. With this configuration:
data blocks must be authenticated with the key A, and then can be read/written
key A can only be changed (written) after an authentication with key A
access bits can be read or written after an authentication with key A
in the sector trailer, the key B has no use and can be read/written after an authentication with key A. It can be used as additional storage space, for instance.
With any configuration, the key A can never be read (the module returns 0's instead of the key) for security reasons. As we can see, the key A of each RFID/NFC card is the master key and we must avoid losing or sharing this information.
Any new card is delivered with the same A and B keys by default: 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF. That is to say, 48 logic 1's.
As shown, the key length is 6 bytes so there are more than 2.8·10¹⁴ different possible passwords.
Example of use:
{uint8_t state; // stores the status of the executed commanduint8_t aux[16]; // auxiliar bufferuint8_t UID[4]; // stores the UID (unique identification) of a carduint8_t keyA_old[6]; // stores the old key Auint8_t keyA_new[6]; // stores the new key Auint8_t keyB_new[6]; // stores the new key Buint8_t config_new[4] = {0xFF, 0x07, 0x80, 0x00}; // same cfg...memset(keyA_old, 0xFF, 6); // the key by default, edit if neededmemset(keyA_new, 0x88, 6); // the new key A, edit if neededmemset(keyB_new, 0x99, 6); // the new key B, edit if neededstate = RFID13.init(UID, aux); // inits systems and look for cardsstate = RFID13.setKeys(UID, keyA_old, keyA_new, keyB_new, config_new, aux, 2); //// authenticates block 2, then writes the new trailer block, with new key A// and B. The access bits are the same.}
This function puts the module into Power Down mode in order to save power consumption.
Example of use:
{RFID.powerDown(); // After this function you must wake up the module.}
This function wakes up the module from power down mode.
Example of use:
{RFID.wakeUp(); //Wake Up from Power Down mode.}
This function is very useful for viewing data content in vectors when you are debugging the code.
Example of use:
{RFID.print(readData , 16); // Print data read and stored in readData vector in the serial monitor}
This function compares 2 UIDs to check if they are equal. It is useful to check if the UID we have just detected is the same than a predetermined UID. One logic application could be access control for a single person.
Example of use:
{uint8_t state; // stores the status of the executed commanduint8_t ATQ[2]; // stores the ATQ-Auint8_t UID[4]; // stores the UID (unique identification) of a carduint8_t card[] = {0xXY, 0xXY, 0xXY, 0xXY}; // the UID of the card that we want to findboolean tr = false;...state = RFID13.init(UID, ATQ); // inits systems and look for cardstr = RFID13.equalUIDs(card, UID); // if the read UID is the same than the original card, tr// will be true}
This function tests if a certain UID is contained in a set or vector of UIDs. It is useful to check if the UID we have just detected is inside a predetermined set or group of UIDs. One logic application could be access control for a group of people.
Example of use:
{#define nCards 3 // edit: number of possible cardsuint8_t state; // stores the status of the executed commanduint8_t ATQ[2]; // stores the ATQ-Auint8_t UID[4]; // stores the UID (unique identification) of a card// edit: vector with the UIDs of all the cardsuint8_t vCards [nCards*4] = {0xXY, 0xXY, 0xXY, 0xXY,0xXY, 0xXY, 0xXY, 0xXY,0xXY, 0xXY, 0xXY, 0xXY};int card = -1; // stores the index of the present card...state = RFID13.init(UID, ATQ); // inits systems and look for cardscard = RFID13.searchUID(vCards, UID, nCards); // looks for the read card inside the data// base. If so, it returns its index in the vector.// If not, -1.}
This function converts from a string to a pointer to uint8_t's. When we want to write a word or phrase in an RFID card, this function is useful to convert from ASCII code to the format the RFID/NFC module can understand.
Example of use:
{uint8_t aux[16]; // auxiliar uint8_t pointerchar text [16]; // auxiliar stringint number = 3; // stores numbers...sprintf(text ,\"Its a test %d \", number*4); // add a number to a string (dynamic !! )RFID13.string2vector(text, aux); // converts from string to a uint8_t pointer}
This function converts from a pointer to uint8_t's to an integer. When we want to read a number from an RFID card, this function is useful to convert from ASCII code to the format we can understand, an integer.
Example of use:
{uint8_t aux[16] = {0x51, 0x52, 0x53, 0x00, 0x00, 0x00, 0x00, 0x00,0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; // auxiliar uint8_t pointerint number = 0; // stores numbers...number = vector2int(aux); // converts from a uint8_t pointer to an integer}
