Michael Sapozhnikov
123
Diff: MFRC522.h
- Revision:
- 1:63d729186747
- Parent:
- 0:efd786b99a72
--- a/MFRC522.h Wed Dec 18 00:39:55 2013 +0000
+++ b/MFRC522.h Mon Jan 06 15:00:15 2014 +0000
@@ -146,11 +146,14 @@
* }
* @endcode
*/
+
class MFRC522 {
public:
- // MFRC522 registers. Described in chapter 9 of the datasheet.
- // When using SPI all addresses are shifted one bit left in the "SPI address byte" (section 8.1.2.3)
+ /**
+ * MFRC522 registers (described in chapter 9 of the datasheet).
+ * When using SPI all addresses are shifted one bit left in the "SPI address byte" (section 8.1.2.3)
+ */
enum PCD_Register {
// Page 0: Command and status
// 0x00 // reserved for future use
@@ -333,6 +336,12 @@
* MFRC522 destructor
*/
~MFRC522();
+
+
+ // ************************************************************************************
+ //! @name Functions for manipulating the MFRC522
+ // ************************************************************************************
+ //@{
/**
* Initializes the MFRC522 chip.
@@ -426,6 +435,7 @@
* @param validBits The number of valid bits in the last byte. 0 for 8 valid bits. Default NULL.
* @param rxAlign Defines the bit position in backData[0] for the first bit received. Default 0.
* @param checkCRC True => The last two bytes of the response is assumed to be a CRC_A that must be validated.
+ *
* @return STATUS_OK on success, STATUS_??? otherwise.
*/
uint8_t PCD_TransceiveData (uint8_t *sendData,
@@ -437,6 +447,22 @@
bool checkCRC = false);
+ /**
+ * Transfers data to the MFRC522 FIFO, executes a commend, waits for completion and transfers data back from the FIFO.
+ * CRC validation can only be done if backData and backLen are specified.
+ *
+ * @param command The command to execute. One of the PCD_Command enums.
+ * @param waitIRq The bits in the ComIrqReg register that signals successful completion of the command.
+ * @param sendData Pointer to the data to transfer to the FIFO.
+ * @param sendLen Number of bytes to transfer to the FIFO.
+ * @param backData NULL or pointer to buffer if data should be read back after executing the command.
+ * @param backLen In: Max number of bytes to write to *backData. Out: The number of bytes returned.
+ * @param validBits In/Out: The number of valid bits in the last byte. 0 for 8 valid bits.
+ * @param rxAlign In: Defines the bit position in backData[0] for the first bit received. Default 0.
+ * @param checkCRC In: True => The last two bytes of the response is assumed to be a CRC_A that must be validated.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t PCD_CommunicateWithPICC(uint8_t command,
uint8_t waitIRq,
uint8_t *sendData,
@@ -447,47 +473,296 @@
uint8_t rxAlign = 0,
bool checkCRC = false);
-
+ /**
+ * Transmits a REQuest command, Type A. Invites PICCs in state IDLE to go to READY and prepare for anticollision or selection. 7 bit frame.
+ * Beware: When two PICCs are in the field at the same time I often get STATUS_TIMEOUT - probably due do bad antenna design.
+ *
+ * @param bufferATQA The buffer to store the ATQA (Answer to request) in
+ * @param bufferSize Buffer size, at least two bytes. Also number of bytes returned if STATUS_OK.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t PICC_RequestA (uint8_t *bufferATQA, uint8_t *bufferSize);
+
+ /**
+ * Transmits a Wake-UP command, Type A. Invites PICCs in state IDLE and HALT to go to READY(*) and prepare for anticollision or selection. 7 bit frame.
+ * Beware: When two PICCs are in the field at the same time I often get STATUS_TIMEOUT - probably due do bad antenna design.
+ *
+ * @param bufferATQA The buffer to store the ATQA (Answer to request) in
+ * @param bufferSize Buffer size, at least two bytes. Also number of bytes returned if STATUS_OK.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t PICC_WakeupA (uint8_t *bufferATQA, uint8_t *bufferSize);
+
+ /**
+ * Transmits REQA or WUPA commands.
+ * Beware: When two PICCs are in the field at the same time I often get STATUS_TIMEOUT - probably due do bad antenna design.
+ *
+ * @param command The command to send - PICC_CMD_REQA or PICC_CMD_WUPA
+ * @param bufferATQA The buffer to store the ATQA (Answer to request) in
+ * @param bufferSize Buffer size, at least two bytes. Also number of bytes returned if STATUS_OK.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t PICC_REQA_or_WUPA (uint8_t command, uint8_t *bufferATQA, uint8_t *bufferSize);
+
+ /**
+ * Transmits SELECT/ANTICOLLISION commands to select a single PICC.
+ * Before calling this function the PICCs must be placed in the READY(*) state by calling PICC_RequestA() or PICC_WakeupA().
+ * On success:
+ * - The chosen PICC is in state ACTIVE(*) and all other PICCs have returned to state IDLE/HALT. (Figure 7 of the ISO/IEC 14443-3 draft.)
+ * - The UID size and value of the chosen PICC is returned in *uid along with the SAK.
+ *
+ * A PICC UID consists of 4, 7 or 10 bytes.
+ * Only 4 bytes can be specified in a SELECT command, so for the longer UIDs two or three iterations are used:
+ *
+ * UID size Number of UID bytes Cascade levels Example of PICC
+ * ======== =================== ============== ===============
+ * single 4 1 MIFARE Classic
+ * double 7 2 MIFARE Ultralight
+ * triple 10 3 Not currently in use?
+ *
+ *
+ * @param uid Pointer to Uid struct. Normally output, but can also be used to supply a known UID.
+ * @param validBits The number of known UID bits supplied in *uid. Normally 0. If set you must also supply uid->size.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t PICC_Select (Uid *uid, uint8_t validBits = 0);
+
+ /**
+ * Instructs a PICC in state ACTIVE(*) to go to state HALT.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t PICC_HaltA (void);
+
+ // ************************************************************************************
+ //@}
- /////////////////////////////////////////////////////////////////////////////////////
- // Functions for communicating with MIFARE PICCs
- /////////////////////////////////////////////////////////////////////////////////////
+ // ************************************************************************************
+ //! @name Functions for communicating with MIFARE PICCs
+ // ************************************************************************************
+ //@{
+
+ /**
+ * Executes the MFRC522 MFAuthent command.
+ * This command manages MIFARE authentication to enable a secure communication to any MIFARE Mini, MIFARE 1K and MIFARE 4K card.
+ * The authentication is described in the MFRC522 datasheet section 10.3.1.9 and http://www.nxp.com/documents/data_sheet/MF1S503x.pdf section 10.1.
+ * For use with MIFARE Classic PICCs.
+ * The PICC must be selected - ie in state ACTIVE(*) - before calling this function.
+ * Remember to call PCD_StopCrypto1() after communicating with the authenticated PICC - otherwise no new communications can start.
+ *
+ * All keys are set to FFFFFFFFFFFFh at chip delivery.
+ *
+ * @param command PICC_CMD_MF_AUTH_KEY_A or PICC_CMD_MF_AUTH_KEY_B
+ * @param blockAddr The block number. See numbering in the comments in the .h file.
+ * @param key Pointer to the Crypteo1 key to use (6 bytes)
+ * @param uid Pointer to Uid struct. The first 4 bytes of the UID is used.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise. Probably STATUS_TIMEOUT if you supply the wrong key.
+ */
uint8_t PCD_Authenticate (uint8_t command, uint8_t blockAddr, MIFARE_Key *key, Uid *uid);
+
+ /**
+ * Used to exit the PCD from its authenticated state.
+ * Remember to call this function after communicating with an authenticated PICC - otherwise no new communications can start.
+ */
void PCD_StopCrypto1 (void);
+
+ /**
+ * Reads 16 bytes (+ 2 bytes CRC_A) from the active PICC.
+ *
+ * For MIFARE Classic the sector containing the block must be authenticated before calling this function.
+ *
+ * For MIFARE Ultralight only addresses 00h to 0Fh are decoded.
+ * The MF0ICU1 returns a NAK for higher addresses.
+ * The MF0ICU1 responds to the READ command by sending 16 bytes starting from the page address defined by the command argument.
+ * For example; if blockAddr is 03h then pages 03h, 04h, 05h, 06h are returned.
+ * A roll-back is implemented: If blockAddr is 0Eh, then the contents of pages 0Eh, 0Fh, 00h and 01h are returned.
+ *
+ * The buffer must be at least 18 bytes because a CRC_A is also returned.
+ * Checks the CRC_A before returning STATUS_OK.
+ *
+ * @param blockAddr MIFARE Classic: The block (0-0xff) number. MIFARE Ultralight: The first page to return data from.
+ * @param buffer The buffer to store the data in
+ * @param bufferSize Buffer size, at least 18 bytes. Also number of bytes returned if STATUS_OK.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t MIFARE_Read (uint8_t blockAddr, uint8_t *buffer, uint8_t *bufferSize);
+
+ /**
+ * Writes 16 bytes to the active PICC.
+ *
+ * For MIFARE Classic the sector containing the block must be authenticated before calling this function.
+ *
+ * For MIFARE Ultralight the opretaion is called "COMPATIBILITY WRITE".
+ * Even though 16 bytes are transferred to the Ultralight PICC, only the least significant 4 bytes (bytes 0 to 3)
+ * are written to the specified address. It is recommended to set the remaining bytes 04h to 0Fh to all logic 0.
+ *
+ * @param blockAddr MIFARE Classic: The block (0-0xff) number. MIFARE Ultralight: The page (2-15) to write to.
+ * @param buffer The 16 bytes to write to the PICC
+ * @param bufferSize Buffer size, must be at least 16 bytes. Exactly 16 bytes are written.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t MIFARE_Write (uint8_t blockAddr, uint8_t *buffer, uint8_t bufferSize);
+
+ /**
+ * Writes a 4 byte page to the active MIFARE Ultralight PICC.
+ *
+ * @param page The page (2-15) to write to.
+ * @param buffer The 4 bytes to write to the PICC
+ * @param bufferSize Buffer size, must be at least 4 bytes. Exactly 4 bytes are written.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
+ uint8_t MIFARE_UltralightWrite(uint8_t page, uint8_t *buffer, uint8_t bufferSize);
+
+ /**
+ * MIFARE Decrement subtracts the delta from the value of the addressed block, and stores the result in a volatile memory.
+ * For MIFARE Classic only. The sector containing the block must be authenticated before calling this function.
+ * Only for blocks in "value block" mode, ie with access bits [C1 C2 C3] = [110] or [001].
+ * Use MIFARE_Transfer() to store the result in a block.
+ *
+ * @param blockAddr The block (0-0xff) number.
+ * @param delta This number is subtracted from the value of block blockAddr.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t MIFARE_Decrement (uint8_t blockAddr, uint32_t delta);
+
+ /**
+ * MIFARE Increment adds the delta to the value of the addressed block, and stores the result in a volatile memory.
+ * For MIFARE Classic only. The sector containing the block must be authenticated before calling this function.
+ * Only for blocks in "value block" mode, ie with access bits [C1 C2 C3] = [110] or [001].
+ * Use MIFARE_Transfer() to store the result in a block.
+ *
+ * @param blockAddr The block (0-0xff) number.
+ * @param delta This number is added to the value of block blockAddr.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t MIFARE_Increment (uint8_t blockAddr, uint32_t delta);
+
+ /**
+ * MIFARE Restore copies the value of the addressed block into a volatile memory.
+ * For MIFARE Classic only. The sector containing the block must be authenticated before calling this function.
+ * Only for blocks in "value block" mode, ie with access bits [C1 C2 C3] = [110] or [001].
+ * Use MIFARE_Transfer() to store the result in a block.
+ *
+ * @param blockAddr The block (0-0xff) number.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t MIFARE_Restore (uint8_t blockAddr);
+
+ /**
+ * MIFARE Transfer writes the value stored in the volatile memory into one MIFARE Classic block.
+ * For MIFARE Classic only. The sector containing the block must be authenticated before calling this function.
+ * Only for blocks in "value block" mode, ie with access bits [C1 C2 C3] = [110] or [001].
+ *
+ * @param blockAddr The block (0-0xff) number.
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t MIFARE_Transfer (uint8_t blockAddr);
- uint8_t MIFARE_UltralightWrite(uint8_t page, uint8_t *buffer, uint8_t bufferSize);
+
+ // ************************************************************************************
+ //@}
- /////////////////////////////////////////////////////////////////////////////////////
- // Support functions
- /////////////////////////////////////////////////////////////////////////////////////
+ // ************************************************************************************
+ //! @name Support functions
+ // ************************************************************************************
+ //@{
+
+ /**
+ * Wrapper for MIFARE protocol communication.
+ * Adds CRC_A, executes the Transceive command and checks that the response is MF_ACK or a timeout.
+ *
+ * @param sendData Pointer to the data to transfer to the FIFO. Do NOT include the CRC_A.
+ * @param sendLen Number of bytes in sendData.
+ * @param acceptTimeout True => A timeout is also success
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t PCD_MIFARE_Transceive(uint8_t *sendData, uint8_t sendLen, bool acceptTimeout = false);
+
+ /**
+ * Translates the SAK (Select Acknowledge) to a PICC type.
+ *
+ * @param sak The SAK byte returned from PICC_Select().
+ *
+ * @return PICC_Type
+ */
uint8_t PICC_GetType (uint8_t sak);
+
+ /**
+ * Returns a string pointer to the PICC type name.
+ *
+ * @param type One of the PICC_Type enums.
+ *
+ * @return A string pointer to the PICC type name.
+ */
char* PICC_GetTypeName (uint8_t type);
+
+ /**
+ * Returns a string pointer to a status code name.
+ *
+ * @param code One of the StatusCode enums.
+ *
+ * @return A string pointer to a status code name.
+ */
char* GetStatusCodeName (uint8_t code);
+
+ /**
+ * Calculates the bit pattern needed for the specified access bits. In the [C1 C2 C3] tupples C1 is MSB (=4) and C3 is LSB (=1).
+ *
+ * @param accessBitBuffer Pointer to byte 6, 7 and 8 in the sector trailer. Bytes [0..2] will be set.
+ * @param g0 Access bits [C1 C2 C3] for block 0 (for sectors 0-31) or blocks 0-4 (for sectors 32-39)
+ * @param g1 Access bits [C1 C2 C3] for block 1 (for sectors 0-31) or blocks 5-9 (for sectors 32-39)
+ * @param g2 Access bits [C1 C2 C3] for block 2 (for sectors 0-31) or blocks 10-14 (for sectors 32-39)
+ * @param g3 Access bits [C1 C2 C3] for the sector trailer, block 3 (for sectors 0-31) or block 15 (for sectors 32-39)
+ */
void MIFARE_SetAccessBits (uint8_t *accessBitBuffer,
uint8_t g0,
uint8_t g1,
uint8_t g2,
uint8_t g3);
+
+ // ************************************************************************************
+ //@}
- /////////////////////////////////////////////////////////////////////////////////////
- // Convenience functions - does not add extra functionality
- /////////////////////////////////////////////////////////////////////////////////////
+ // ************************************************************************************
+ //! @name Convenience functions - does not add extra functionality
+ // ************************************************************************************
+ //@{
+
+ /**
+ * Returns true if a PICC responds to PICC_CMD_REQA.
+ * Only "new" cards in state IDLE are invited. Sleeping cards in state HALT are ignored.
+ *
+ * @return bool
+ */
bool PICC_IsNewCardPresent(void);
+
+ /**
+ * Simple wrapper around PICC_Select.
+ * Returns true if a UID could be read.
+ * Remember to call PICC_IsNewCardPresent(), PICC_RequestA() or PICC_WakeupA() first.
+ * The read UID is available in the class variable uid.
+ *
+ * @return bool
+ */
bool PICC_ReadCardSerial (void);
+
+ // ************************************************************************************
+ //@}
private:
@@ -495,6 +770,15 @@
DigitalOut m_CS;
DigitalOut m_RESET;
+ /**
+ * Helper function for the two-step MIFARE Classic protocol operations Decrement, Increment and Restore.
+ *
+ * @param command The command to use
+ * @param blockAddr The block (0-0xff) number.
+ * @param data The data to transfer in step 2
+ *
+ * @return STATUS_OK on success, STATUS_??? otherwise.
+ */
uint8_t MIFARE_TwoStepHelper(uint8_t command, uint8_t blockAddr, uint32_t data);
};