X-NUCLEO-NFC01A1 Dynamic NFC Tag Expansion Board Firmware Package

Diff: m24sr/m24sr_class.h

Revision:

9:9f2e2e68d695

Parent:

7:19fc04b8fec6

Child:

12:d1f5eaa85deb

Child:

13:840a9c7f90b9

--- a/m24sr/m24sr_class.h	Mon Jan 11 13:06:23 2016 +0000
+++ b/m24sr/m24sr_class.h	Thu Jan 14 07:54:59 2016 +0000
@@ -2,6 +2,7 @@
  ******************************************************************************
  * @file    m24sr_class.h
  * @author  ST Central Labs
+ * @version V1.0.0
  * @date    05 Nov 2015
  * @brief   This file provides a set of functions to interface with the M24SR
  *          device.
@@ -57,14 +58,15 @@
 
 /* Classes -------------------------------------------------------------------*/
 
-/** Class representing a M24SR component.
+/**
+ * Class representing a M24SR component.
  */
 class M24SR: public Nfc {
 
 public:
 
 	/**
-	 * default password uesed for change the write/read permission
+	 * Default password used to change the write/read permission
 	 */
 	static const uint8_t DEFAULT_PASSWORD[16];
 	
@@ -73,13 +75,13 @@
 	/**
 	 * @brief Constructor.
 	 * @param address I2C address of the component.
-	 * @param i2c     I2C device to be used for communication.
-	 * @param GPOPinName pin used as GPIO
-	 * @param RFDISPinName pin used for disable the RF function 
+	 * @param I2C     I2C device to be used for communication.
+	 * @param GPOPinName Pin used as GPIO.
+	 * @param RFDISPinName Pin used to disable the RF function.
 	 */
-	M24SR(const uint8_t address, I2C &i2c, const PinName& GPOPinName,
+	M24SR(const uint8_t address, I2C &I2C, const PinName& GPOPinName,
 			const PinName& RFDISPinName) :
-			Nfc(), address(address), dev_i2c(i2c), GPOPin(GPOPinName), RFDisablePin(
+			Nfc(), address(address), dev_I2C(I2C), GPOPin(GPOPinName), RFDisablePin(
 					RFDISPinName), answerReadyInterrupt(GPOPinName), interruptIsFired(
 					false),NDefTagUtil(*this) {
 
@@ -104,9 +106,9 @@
 	/*** Public Component Related Methods ***/
 	
 	/**
-	 * @brief  This function initialize the M24SR device
-	 * @param ptr configure paramiters, not used
-     * @return NFC_SUCCESS if no error happen
+	 * @brief  This function initializes the M24SR device.
+	 * @param ptr Configure parameters, not used.
+     * @return NFC_SUCCESS if no errors
 	 */
 	virtual int Init(void *ptr) {
 		return (NFC_StatusTypeDef) M24SR_Init((NFC_InitTypeDef*)ptr);
@@ -186,9 +188,7 @@
 	}
 
     ////////////////////// ST proprietary //////////////////////////////////
-    /**
-     * as 
-     */
+
 	virtual NFC_StatusTypeDef STReadBinary(uint16_t Offset,
 			uint8_t NbByteToRead, uint8_t *pBufferRead) {
 		return (NFC_StatusTypeDef) M24SR_STReadBinary((uint16_t) Offset,
@@ -226,8 +226,8 @@
 
 	/**
 	 * Generates a negative pulse on the GPO pin.
-	 * It starts at the end of the command and ends at the end of the RF response
-  	 * @return NFC_SUCCESS if no error happen
+	 * Pulse starts immediately after the command is issued and ends at the end of the RF response.
+  	 * @return NFC_SUCCESS if no errors
 	 */
 	virtual NFC_StatusTypeDef SendInterrupt(void) {
 		return (NFC_StatusTypeDef) M24SR_SendInterrupt();
@@ -236,8 +236,8 @@
 	/////////////////// hight level/utility function /////////////////////
 
 	/**
-	 * get an implementation of NDefNfcTag for use the library NDefLib
-	 * @retrun object of type NdefNfcTag for use this M24SR component
+	 * Get an implementation of NDefNfcTag to use the library NDefLib.
+	 * @return an object of type NdefNfcTag 
 	 */
 	NDefLib::NDefNfcTag& getNDefTag(){
 		return NDefTagUtil;
@@ -245,72 +245,78 @@
 
 
 	/**
-	 * enable the request of a password before read the tag
-	 * @param pCurrentWritePassword current password ( use M24SR::DEFAULT_PASSWORD if it is the first time)
-	 * @param pNewPassword password to request before read the tag
-	 * @return return NFC_SUCCESS if no error happen
-	 * @par the password must have a length of 16 char
+	 * Enable the request of a password before reading the tag.
+	 * @param  pCurrentWritePassword Current password (the first time use M24SR::DEFAULT_PASSWORD ).
+	 * @param  pNewPassword Password to request before reading the tag.
+	 * @return return NFC_SUCCESS if no errors
+	 * @par The password must have a length of 16 chars.
 	 */
 	NFC_StatusTypeDef enableReadPassword(const uint8_t* pCurrentWritePassword,
 			const uint8_t* pNewPassword);
 
 	/**
-	 * disable the request of a password before read the tag
-	 * @param pCurrentWritePassword current password ( use M24SR::DEFAULT_PASSWORD if it is the first time)
-	 * @return return NFC_SUCCESS if no error happen
-	 * @par the password must have a length of 16 char
+	 * Disable the request of a password before reading the tag.
+	 * @param  pCurrentWritePassword Current password (the first time use M24SR::DEFAULT_PASSWORD).
+	 * @return return NFC_SUCCESS if no errors
+	 * @par The password must have a length of 16 chars.
 	 */
 	NFC_StatusTypeDef disableReadPassword(const uint8_t* pCurrentWritePassword=M24SR::DEFAULT_PASSWORD);
 
 	/**
-	 * enable the request of a password before write the tag
-	 * @param pCurrentWritePassword current password ( use M24SR::DEFAULT_PASSWORD if it is the first time)
-	 * @param pNewPassword password to request before read the tag
-	 * @return return NFC_SUCCESS if no error happen
-	 * @par the password must have a length of 16 char
+	 * Enable the request of a password before writing to the tag.
+	 * @param  pCurrentWritePassword Current password (the first time use M24SR::DEFAULT_PASSWORD).
+	 * @param  pNewPassword Password to request before reading the tag.
+	 * @return return NFC_SUCCESS if no errors
+	 * @par The password must have a length of 16 chars.
 	 */
 	NFC_StatusTypeDef enableWritePassword(const uint8_t* pCurrentWritePassword,
 			uint8_t* pNewPassword);
 
+	/**
+	 * Disable the request of a password before writing the tag.
+	 * @param  pCurrentWritePassword Current password (the first time use M24SR::DEFAULT_PASSWORD).
+	 * @return return NFC_SUCCESS if no errors
+	 * @par The password must have a length of 16 chars.
+	 */
 	NFC_StatusTypeDef disableWritePassword(const uint8_t* pCurrentWritePassword=M24SR::DEFAULT_PASSWORD);
 
 	/**
-	 * @brief  This function deactivate the need of read and write password for next access
-	 * @param	pSuperUserPassword I2C super user password to overwrite read and write password
-	 * @return return NFC_SUCCESS if no error happen
-	 * @par the password must have a length of 16 char
+	 * @brief   This function disables both read and write passwords.
+	 * @param	pSuperUserPassword I2C super user password.
+	 * @return  return NFC_SUCCESS if no errors
+	 * @par The password must have a length of 16 chars.
 	 */
 	NFC_StatusTypeDef disableAllPassword(const uint8_t* pSuperUserPassword=M24SR::DEFAULT_PASSWORD);
 
 	/**
-	 * @brief  This function enable read only mode
-	 * @param	pCurrentWritePassword Write password is needed to have right to enable read only mode
-	 * @return return NFC_SUCCESS if no error happen
-	 * @par the password must have a length of 16 char
+	 * @brief   This function enables read only mode.
+	 * @param	pCurrentWritePassword Write password is needed to enable read only mode.
+	 * @return  return NFC_SUCCESS if no errors
+	 * @par The password must have a length of 16 chars.
 	 */
 	NFC_StatusTypeDef enableReadOnly(const uint8_t* pCurrentWritePassword=M24SR::DEFAULT_PASSWORD);
 
 	/**
-	 * @brief  This fonction disable read only mode
-	 * @param	pCurrentWritePassword Write password is needed to have right to disable read only mode
-	 * @return return NFC_SUCCESS if no error happen
-	 * @par the password must have a length of 16 char
+	 * @brief   This function disables read only mode.
+	 * @param	pCurrentWritePassword Write password is needed to disable read only mode.
+	 * @return  return NFC_SUCCESS if no errors
+	 * @par The password must have a length of 16 chars.
 	 */
 	NFC_StatusTypeDef disableReadOnly();
 
 	/**
-	 * @brief  This fonction enable write only mode
-	 * @param	pCurrentWritePassword Write password is needed to have right to enable write only mode
-	 * @return return NFC_SUCCESS if no error happen
-	 * @par the password must have a length of 16 char
+	 * @brief   This function enables write only mode.
+	 * @param	pCurrentWritePassword Write password is needed to enable write only mode.
+	 * @return  return NFC_SUCCESS if no errors
+	 * @par The password must have a length of 16 chars.
 	 */
 	NFC_StatusTypeDef enableWriteOnly(const uint8_t* pCurrentWritePassword=M24SR::DEFAULT_PASSWORD);
 
 	/**
-	 * @brief  This fonction disable write only mode
-	 * @param	pCurrentWritePassword Write password is needed to have right to disable write only mode
-	 * @return return NFC_SUCCESS if no error happen
-	 * @par the password must have a length of 16 char
+	 * @brief   This function disables write only mode.
+	 * @param	pCurrentWritePassword Write password is needed to disable write only mode.
+	 * @return  return NFC_SUCCESS if no errors
+	 * @par The password must have a length of 16 chars.
 	 */
 	NFC_StatusTypeDef disableWriteOnly();
 
@@ -350,36 +356,36 @@
 	NFC_StatusTypeDef M24SR_FWTExtension(uint8_t FWTbyte);
 
 	/**
-	 * wait until the answer is not ready
+	 * Wait until the answer is ready.
 	 */
 	NFC_StatusTypeDef M24SR_IO_IsAnswerReady(void);
 	
 	/**
-	 * send a command to the component
-	 * @param NbByte lenght of the command
-	 * @param pBuffer buffer containing the command
-	 * @return NFC_SUCCESS if no error happen
+	 * Send a command to the component.
+	 * @param NbByte Lenght of the command.
+	 * @param pBuffer Buffer containing the command.
+	 * @return NFC_SUCCESS if no errors
 	 */
 	NFC_StatusTypeDef M24SR_IO_SendI2Ccommand(uint8_t NbByte, uint8_t *pBuffer);
 	
 	/**
-	 * read a command renspose
-	 * @param NbByte number of byte to read
-	 * @param pBuffer buffer where store the rensponse
-	 * @return NFC_SUCCESS if no error happen
+	 * Read a command response.
+	 * @param NbByte Number of bytes to read.
+	 * @param pBuffer Buffer to store the response into.
+	 * @return NFC_SUCCESS if no errors
 	 */
 	NFC_StatusTypeDef M24SR_IO_ReceiveI2Cresponse(uint8_t NbByte,
 			uint8_t *pBuffer);
 
 	/**
-	 * do and active polling on the i2c bus until the answer is not ready
-	 * @return NFC_SUCCESS if no error happen
+	 * Do an active polling on the I2C bus until the answer is ready.
+	 * @return NFC_SUCCESS if no errors
 	 */
 	NFC_StatusTypeDef M24SR_IO_PollI2C(void);
 
 	/**
-	 * read the gpo pin
-	 * @param[out] pPinState variable where store the pin state
+	 * Read the gpo pin.
+	 * @param[out] pPinState Variable to store the pin state into.
 	 */
 	void M24SR_IO_GPO_ReadPin(GPIO_PinState *pPinState) {
 		if (GPOPin == 0)
@@ -389,8 +395,8 @@
 	}
 
 	/**
-	 * write the gpo pin
-	 * @param pPinState state to write
+	 * Write the gpo pin.
+	 * @param pPinState Pin state to write.
 	 */
 	void M24SR_IO_RFDIS_WritePin(GPIO_PinState PinState) {
 		if (PinState == GPIO_PIN_RESET)
@@ -400,15 +406,15 @@
 	}
 
 	/**
-	 * set how wait the command answer
-	 * @param mode how to wait the i2c rensponse
+	 * Set the command synchronous answer mode.
+	 * @param mode How to wait the I2C rensponse.
 	 */
 	void M24SR_IO_SetI2CSynchroMode(M24SR_WAITINGTIME_MGMT mode) {
 		syncMode = mode;
 	}
 
 	/**
-	 * callback trigger when the chip finish to do a command
+	 * Callback triggers when a command is completed.
 	 */
 	void M24SR_AnswerReadyInterruptCallback() {
 		interruptIsFired = true;
@@ -420,37 +426,37 @@
 	/* Identity */
 	uint8_t who_am_i;
 
-	/* Type. */
+	/* Type */
 	uint8_t type;
 
 	/* I2C address */
 	uint8_t address;
 
 	/* IO Device. */
-	I2C &dev_i2c;
+	I2C &dev_I2C;
 
 	/* GPIO */
 	DigitalIn GPOPin;
 
 	/**
-	 * pin used for disable the rf chip functionality
+	 * Pin used to disable the rf chip functionality.
 	 */
 	DigitalOut RFDisablePin;
 
 	/**
-	 * pin used as interrupt
+	 * Pin used as interrupt.
 	 */
 	InterruptIn answerReadyInterrupt;
 
 	/**
-	 * method used for wait the chip response
+	 * Method used to wait the chip response.
 	 */
 	M24SR_WAITINGTIME_MGMT syncMode;
 
 	/**
-	 * buffer used for build the command to send to the chip
+	 * Buffer used to build the command to send to the chip.
 	 */
-	uint8_t uM24SRbuffer[0xFF];
+	uint8_t uM24SRbuffer[0xFF];//max command length is 255
 
 	/**
 	 * ???
@@ -458,12 +464,12 @@
 	uint8_t uDIDbyte;
 
 	/**
-	 * state variable change when the interrupt is fired
+	 * State variable changes when the interrupt is fired.
 	 */
 	volatile bool interruptIsFired;
 	
 	/**
-	 * Object implementing the interface for use the NDefLib
+	 * Object implementing the interface to use the NDefLib.
 	 */
 	NDefNfcTagM24SR NDefTagUtil;
 };