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);
 };