UM10663 NXP Reader Library User Manual based on CLRC663 and PN512 Blueboard Reader projects Rev. 1.2 — 24 July 2013 257412 User Manual COMPANY PUBLIC Document information Info Content Keywords NXP Reader Library, MFRC523, MFRC522, MFRC500, MFRC530, MFRC531, MFRC630, MFRC631, SLRC610 Abstract This document describes the implementation and usage of the NXP Reader Library Public with special stress on MIFARE Classic command and CLRC663 native command set implementation.
UM10663 NXP Semiconductors NXP Reader Library User Manual Revision history Rev Date Description 1.2 20130724 Added “PN512” in the descriptive title 1.1 20130502 Updated the URL of the NXP Reader library in the first reference. 1.0 20130301 Initial version Contact information For more information, please visit: http://www.nxp.com For sales office addresses, please send an email to: salesaddresses@nxp.
UM10663 NXP Semiconductors NXP Reader Library User Manual 1. Introduction 1.1 NXP libraries comparison NXP Reader Library This document describes the NXP Reader Library (Public), which is the software written in C language enabling the customers to create their own software stack for their contactless reader. The NXP Reader Library is available at [1]. There are another two NXP Reader Libraries giving to the developer advanced possibilities.
UM10663 NXP Semiconductors NXP Reader Library User Manual NXP Reader Library NFC P2P: is intended to run on NXP LPC1227 board which is either connected to PNEV512 v1.4 blue board or CLRC663 Blue board v2.1. It is the software support for Near Field Communication (NFC) including Data Exchange Format. Fig 2. Structure of the NXP Reader Library NFC P2P 1.1.
UM10663 NXP Semiconductors NXP Reader Library User Manual Fig 3. 1.1.1.1 Structure of the NXP Reader Library Application Layer Although this document describes the NXP Reader Library from Fig 3, in this section there is slightly introduced most of the cards (components) from (green) AL in Fig 1. The Application Layer of the NXP Reader Library implements commands for only MIFARE Classic and MIFARE Ultralight among contactless cards listed below.
UM10663 NXP Semiconductors NXP Reader Library User Manual contactless system without need for serious changes of the system. MIFARE Ultralight is fully compliant with ISO/IEC 14443 Type A. The Application Layer of the MIFARE Ultralight is closer described in Section 2.5. MIFARE Plus[4]: Migrate classic contactless smart card systems to the next security level. After the security upgrade, MIFARE Plus uses AES-128 (Advanced Encryption Standard) for authentication, data integrity and encryption.
UM10663 NXP Semiconductors NXP Reader Library User Manual ISO/IEC18000-3m3[10]: The ISO 18000-3 mode 3/EPC Class-1 HF standard allows the commercialized provision of mass adoption of HF RFID technology for passive smart tags and labels. applications are supply chain management and logistics for worldwide use.
UM10663 NXP Semiconductors NXP Reader Library User Manual • RF field management, receiver and transmitter configuration • Timers configuration • Resolving interrupt sources from reader chip • FIFO management Data passed from upper layers are packed together with command code into special order, thus reader is able to decode them as command code, address and data. Section 2.1 is focused on description of functions performing CLRC663 native commands and section 2.
UM10663 NXP Semiconductors NXP Reader Library User Manual during software running, which means triggering, enabling or disabling of particular software utilities and hardware modules. At the beginning of program, it is necessary to load data parameter structure of layer with default values by calling an initialization function of that layer.
UM10663 NXP Semiconductors NXP Reader Library User Manual 2. Exemplary explanation of the library functions A project defining a CLRC663 Blueboard communication with a MIFARE classic is herewith explained. 2.1 HAL: CLRC663 commands 2.1.1 General The reader chip is not able to execute compiled C code, but executes commands of command set. For that reason the PCD reader is controlled by host device able to execute the library code (PC or MCU) and sends particular commands to the PCD via communication bus.
UM10663 NXP Semiconductors NXP Reader Library User Manual PHHAL_HW_RC663_CMD_LPCD_MODE_POWERDOWN_GUARDED: Same as previous, but uses the timeout set with either PHHAL_HW_CONFIG_TIMING_US or PHHAL_HW_CONFIG_TIMING_MS as abort criteria. Guard-timer in this case is only running during the power-up phases, so the timeout has to be adjusted properly. PHHAL_HW_RC663_CMD_LPCD_MODE_OPTION_TRIMM_LPO: Or this bit to the desired mode to perform LPO trimming together with the LPCD command.
UM10663 NXP Semiconductors NXP Reader Library User Manual *pDataParams: pointer to the HAL layer data parameter structure. bKeyNo: key number in EEPROM in range 0x00 - 0xFF. returnValues: PH_ERR_SUCCESS - operation successful. Other: depending on implementation and underlaying component. 2.1.
UM10663 NXP Semiconductors NXP Reader Library User Manual wKeyNo exceeds half of maximum possible number of keys in the EEPROM PH_ERR_IO_TIMEOUT - Authentication command itself did not succeeded while timeout from timer1 terminated. PH_ERR_SUCCESS - operation successful. Other: depending on implementation and underlaying component. 2.1.7 Receive - phhalHw_Rc663_Cmd_Receive() This function handles receiver, then waits for eventually coming data.
UM10663 NXP Semiconductors NXP Reader Library User Manual PH_ERR_INTEGRITY_ERROR - A data integrity error has been detected. Possible cause can be a wrong parity or a wrong CRC. PH_ERR_SUCCESS - operation successful. even if waterlevel reached no error indicated also Other: depending on implementation and underlaying component. For further information of particular error see CLRC663 datasheet [2]. 2.1.
UM10663 NXP Semiconductors NXP Reader Library User Manual phStatus_t phhalHw_Rc663_Cmd_WriteE2( phhalHw_Rc663_DataParams_t * pDataParams, uint16_t wAddress, uint8_t bData ); [In] [In] [In] *pDataParams: pointer to the HAL layer data parameter structure. wAddress: address in EEPROM, where data byte shall be written to. Firmware does not verify validity of address. bData: data byte to be written.
UM10663 NXP Semiconductors NXP Reader Library User Manual phStatus_t phhalHw_Rc663_Cmd_ReadE2( phhalHw_Rc663_DataParams_t * pDataParams, uint16_t wAddress, uint16_t wNumBytes, uint8_t * pData ); [In] [In] [In] [Out] *pDataParams: pointer to the HAL layer data parameter structure. wAddress: 2 byte address; Range is 0x0000 - 0x1FFF. wNumBytes: number of data bytes to read. If wAddress+wNumBytes > EEPROM_SIZE, then function aborts before any read operation, although some addresses might be valid.
UM10663 NXP Semiconductors NXP Reader Library User Manual 2.1.13 LoadProtocol - phhalHw_Rc663_ApplyProtocolSettings() This function configures receiver and transmitter of reader to communicate according given ISO protocol. The function needs to be called before the Activation. Reader chip keeps configuration of the latest protocol set, unless changed by this function or direct command LoadProtocol or LoadRegister.
UM10663 NXP Semiconductors NXP Reader Library User Manual PH_ERR_SUCCESS - operation successful. Note: This function configures same communication protocol for both receiver and transmitter as well. If developer needs for any purpose to run them on different protocols concurrently, in this case it is necessary to do it via direct calling of lower layer function phhalHw_Rc663_Cmd_LoadProtocol() - software equivalent of native Load Protocol command.
UM10663 NXP Semiconductors NXP Reader Library User Manual PH_ERR_UNSUPPORTED_PARAMETER – attempt to store an unsupported type of key PH_ERR_INVALID_PARAMETER – wKeyNo is greater than 128 PH_ERR_SUCCESS - operation successful. Other: depending on implementation and underlaying component. 2.1.15 SoftReset - phhalHw_Rc663_Cmd_SoftReset() This function performs the SoftReset command.
UM10663 NXP Semiconductors NXP Reader Library User Manual uint16_t wFieldRecoveryTime: field recovery time in milliseconds. How long FieldReset() function (see section 2.2.9) holds the field turned on while doing nothing else. uint8_t bBalConnectionType: type of the underlying BAL connection interface. This parameter is necessary from software point of view, thus it has no impact on hardware pin configuration communication interface in the MCU.
UM10663 NXP Semiconductors NXP Reader Library User Manual wRxBufSize: size of the global receive buffer. Specify the buffer +1 byte, because one byte is reserved for SPI communication. 2.2.3 SetConfig - phhalHw_SetConfig() This function performs changing the value of the particular parameter (member) of the HAL layer data parameter structure, but it does not modify the structure itself (adding or erasing new parameters - members) because one structure is fix defined for particular reader chip.
UM10663 NXP Semiconductors NXP Reader Library User Manual uint8_t * pValue ); [Out] *pDataParams: pointer to the HAL layer data parameter structure bAddress: address of the register to be the value read from. Addresses of all the registers are defined in folder NxpRdLib_PublicRelease\intfs in phhalHw__Cmd.h file according to the reader chip datasheet. *pValue: new value of the register to be written. returnValues: PH_ERR_SUCCESS operation successful. PH_ERR_INTERFACE_ERROR hardware problem.
UM10663 NXP Semiconductors NXP Reader Library User Manual PH_ERR_SUCCESS operation successful. PH_ERR_INTERFACE_ERROR communication error. 2.2.9 FieldReset - phhalHw_FieldReset() This function performs reset of the RF field. Firstly the RF field is turned off by FieldOff() (see section 2.2.8) function and subsequently the RF field is enabled by FieldOn() (see section 2.2.7) function. Both those states are hold for a certain amount of time while doing nothing else.
UM10663 NXP Semiconductors NXP Reader Library User Manual 2.3 PAL: ISO/IEC14443-3A 2.3.1 ISO14443A part 3 The ISO/IEC 14443 part 3 defines the start of communication and how to select the PICC and resolve situations, when more cards are present in the field of reader. Sometimes this is called “Card activation Sequence”. ISO/IEC 14443-3 protocol is split into A and B version. MIFARE Classic uses A type. A particular feature of these functions is complexity.
UM10663 NXP Semiconductors NXP Reader Library User Manual *pAtqa: pointer to ATQA. If RequestA is successful, then 2 byte ATQA is written to this variable. returnValues: PH_ERR_PROTOCOL_ERROR - invalid response received. PH_ERR_SUCCESS - operation successful. Other: depending on implementation and underlaying component. Note:. If no answer to request is received nor any changes of field near subcarrier detected by receiver during dedicated time, then function is aborted with timeout error.
UM10663 NXP Semiconductors NXP Reader Library User Manual *pSak: pointer to one byte SAK. byte code specifying type of card. MIFARE card type is determined by bits according to table of SAK values in [26]. *pMoreCardsAvailable: indicates whether one or more cards are in range of PCD field at the same time. But still only one card’ UID is captured in one function run. PH_ON: more cards available. Collision occurred. PH_OFF: just one card in PCD field.
UM10663 NXP Semiconductors NXP Reader Library User Manual this function the first UID byte can equal PHPAL_I14443P3A_CASCADE_TAG, which indicates, that UID not complete yet, therefore next anti-collision loop required. *pNvbUidOut: is length of array of UID. It specifies how many bytes of UID are currently relevant. returnValues: PH_ERR_INVALID_PARAMETER – invalid cascade level or invalid bNvbUidIn. PH_ERR_PROTOCOL_ERROR - invalid response received. PH_ERR_SUCCESS - operation successful.
UM10663 NXP Semiconductors NXP Reader Library User Manual function, where SAK == 0x04 provokes next cascade level to obtain complete UID by Anti-collision function phpalI14443p3a_Anticollision(). returnValues: PH_ERR_PROTOCOL_ERROR: Disagreement between first byte of UID and SAK. First byte of UID pUidIn[0] == PHPAL_I14443P3A_CASCADE_TAG together with SAK != 0x04 or vice versa. PH_ERR_SUCCESS - operation successful. Other: depending on implementation and underlaying component. 2.3.
UM10663 NXP Semiconductors NXP Reader Library User Manual void * pDataParams ); [In] *pDataParams: pointer to the PAL layer data parameter structure. returnValues: PH_ERR_SUCCESS: card has been turned into Halt mode successfully. After Halt command has been transmitted to the card and no subsequent RF signal from card received. Time to wait is by value PHPAL_I14443P3A_HALT_TIME_US + PHPAL_I14443P3A_EXT_TIME_US in microseconds. PH_ERR_PROTOCOL_ERROR: protocol error occurred.
UM10663 NXP Semiconductors NXP Reader Library User Manual *pKeyStoreDataParams: pointer to the underlaying KeyStore parameter structure. returnValues: PH_ERR_SUCCESS - operation successful. PH_ERR_INVALID_DATA_PARAMS – wSizeOfDataParams does not agree with defined size of AL MFC component. 2.4.2 MF Authentication - phalMfc_Authenticate() This function loads a key from the key store area of PCD’s EEPROM into the Key buffer.
UM10663 NXP Semiconductors NXP Reader Library User Manual wKeyVersion: key version to be used in authentication. This is a useless variable, but must be NULL. *pUid: pointer to UID of the card to be authenticated. Each card has its own unique identification number. bUidLength: length of UID. Only lengths 4, 7 or 10 are legal.
UM10663 NXP Semiconductors NXP Reader Library User Manual - data or address bytes within the 16 byte receive buffer do not satisfy MIFARE Block data rules according to Fig 4. PH_ERR_SUCCESS - operation successful. Other: depending on implementation and underlaying component. 2.4.4 WriteValue - phalMfc_WriteValue() Firstly, this function creates from 4 byte input value and input address the 16 byte formatted structure according to Fig 4.
UM10663 NXP Semiconductors NXP Reader Library User Manual uint8_t bBlockNo, uint8_t * pValue ); [In] [In] *pDataParams: pointer MIFARE Classic the AL layer data parameter structure. bBlockNo: block number to be decremented. *pValue: pValue[4] containing value (LSB first) to be decremented on the MIFARE(R) card returnValues: PH_ERR_SUCCESS - operation successful. Other: depending on implementation and underlaying component. 2.4.
UM10663 NXP Semiconductors NXP Reader Library User Manual bSrcBlockNo: source block number in MIFARE Classic card EEPROM. Value from this block to be incremented. bDstBlockNo: destination block number. Incremented value from source block is stored to this block. *pValue: 4 byte value that is value from source block incremented by. returnValues: PH_ERR_SUCCESS - operation successful. Other: depending on implementation and underlaying component. 2.4.
UM10663 NXP Semiconductors NXP Reader Library User Manual 2.4.12 PersonalizeUID - phalMfc_PersonalizeUid() This function configures UID to given personalization option, which has direct impact on behavior during Anti-collision, Selection and. The default configuration at delivery enables the ISO/IEC 14443-3 compliant anti-collision and selection. The execution of this command requires an authentication to sector 0.
UM10663 NXP Semiconductors NXP Reader Library User Manual *pCryptoDataParams: pointer to the phCrypto data parameters structure. *pCryptoRngDataParams: pointer to the parameter structure of the CryptoRng layer. PH_ERR_SUCCESS - operation successful. PH_ERR_INVALID_DATA_PARAMS – wSizeOfDataParams does not agree with defined size of MFUL component. 2.5.2 Read - phalMful_Read This function performs MIFARE Ultralight Read command.
UM10663 NXP Semiconductors NXP Reader Library User Manual *pDataParams: pointer to the MIFARE Ultralight AL layer data parameter structure. bAddress: Address on Picc to read from. *pData: pointer to 16 byte data array containing data read from the Ultralight card. returnValues: PH_ERR_SUCCESS - operation successful. Other Depending on implementation and underlaying component. UM10663 User Manual COMPANY PUBLIC All information provided in this document is subject to legal disclaimers. Rev. 1.
UM10663 NXP Semiconductors NXP Reader Library User Manual 3. Sample code In this chapter we introduce a sample code performing basic handling with MIFARE Classic card. There are only fragments of the complete original source code presented with focus on most important parts. Main purpose of example code is to clarify functions and their aim in context of application, what are particular functions responsible for, prerequisites for some functions necessary to do or call.
UM10663 NXP Semiconductors NXP Reader Library User Manual Initialize data parameter structure for the HAL layer. The phhalHw_Rc663_DataParams_t structure is related to the card reader CLRC663 and stores some software configuration parameters which MCU controls the reader through. This function initiates PCD card reader. The third passed parameter is address of existing BAL data parameter structure.
UM10663 NXP Semiconductors NXP Reader Library User Manual Initialize the KeyStore component. We will need it to store key into EEPROM key storage area. 193 194 PH_CHECK_SUCCESS_FCT(status, phKeyStore_Rc663_Init(&Rc663keyStore, sizeof(phKeyStore_Rc663_DataParams_t), pHal)); Initialize the MIFARE Classic AL component (see section 2.4.1) - set NULL because the keys are loaded in EEPROM by the function phKeyStore_SetKey() (line 260).
UM10663 NXP Semiconductors NXP Reader Library User Manual From this point nearly to the end is branch for MIFARE Classic card detected. 242 243 244 else if (0x08 == (*bSak & 0x08)) { debug_printf_msg("Mifare Classic card detected"); Memory of MIFARE Classic is divided into 16 sectors and each sector contains 4 blocks of 16 byte length. Firstly we need to get access to sector by authentication with key. The key must agree with key stored in the card for particular sector.
UM10663 NXP Semiconductors NXP Reader Library User Manual Read just written 16 byte data and copy them into bReaderBuffer. Since we have written data into card EEPROM , we read the data without checking the format as well. 330 PH_CHECK_SUCCESS_FCT(status, phalMfc_Read(&alMfc, 4, bBufferReader)); Last possibility of SAK card type remains. If no MIFARE Classis, nor ISOp14443p4 compliant and activation was successful it must be Ultralight card.
UM10663 NXP Semiconductors NXP Reader Library User Manual 4. Appendix 4.1 Error codes The NXP Reader Library return defined return values – error codes. This approach should help the developer with error identification if it occurs and thus make easier way how to fix bugs during software development. Each error code is type of 16 uint and includes two pieces of information. Upper byte identifies the layer which an error has occurred on and lower byte is the byte code of particular error.
UM10663 NXP Semiconductors NXP Reader Library User Manual 6. References [1] Link to the NXP Reader Library http://www.nxp.com/products/identification_and_security/reader_ics/contactless_re ader_systems/series/CLRC663.html#documentation [2] Data Sheet MF1S503X MIFARE Classic 1K - Mainstream contactless smart card IC for fast and easy solution development, available on http://www.nxp.com/documents/data_sheet/MF1S503x.
UM10663 NXP Semiconductors NXP Reader Library User Manual [17] Data sheet – PN512; Transmission module, BU-ID Doc. No. 1112**, available on http://www.nxp.com/documents/data_sheet/PN512.pdf [18] Data sheet – MFRC500; Highly Integrated ISO/IEC 14443 A Reader IC, BU-ID Doc. No. 0480**, available on http://www.nxp.com/documents/data_sheet/MFRC500.pdf [19] Data sheet – MFRC530; ISO/IEC 14443 A Reader IC, BU-ID Doc. No. 0574**, available on http://www.nxp.com/documents/data_sheet/MFRC530.
UM10663 NXP Semiconductors NXP Reader Library User Manual 7. Legal information the products or of the application or use by customer’s third party customer(s). NXP does not accept any liability in this respect. 7.1 Definitions Draft — The document is a draft version only. The content is still under internal review and subject to formal approval, which may result in modifications or additions.
UM10663 NXP Semiconductors NXP Reader Library User Manual 8. Contents 1. Introduction ......................................................... 3 1.1 NXP libraries comparison ................................... 3 1.1.1 Layer Structure of the NXP Reader Library ........ 4 1.1.1.1 Application Layer................................................ 5 1.1.1.2 Protocol Abstraction Layer ................................. 6 1.1.1.3 Hardware abstraction layer ................................ 7 1.1.1.
