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

Diff: m24sr/m24sr_class.h

Revision:

7:19fc04b8fec6

Parent:

6:96389fb79676

Child:

9:9f2e2e68d695

Child:

11:a798ebea69fa

--- a/m24sr/m24sr_class.h	Tue Dec 22 15:34:24 2015 +0000
+++ b/m24sr/m24sr_class.h	Mon Jan 11 12:37:28 2016 +0000
@@ -63,13 +63,19 @@
 
 public:
 
+	/**
+	 * default password uesed for change the write/read permission
+	 */
 	static const uint8_t DEFAULT_PASSWORD[16];
+	
 	/*** Constructor and Destructor Methods ***/
 
 	/**
 	 * @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 
 	 */
 	M24SR(const uint8_t address, I2C &i2c, const PinName& GPOPinName,
 			const PinName& RFDISPinName) :
@@ -96,6 +102,12 @@
 	}
 
 	/*** Public Component Related Methods ***/
+	
+	/**
+	 * @brief  This function initialize the M24SR device
+	 * @param ptr configure paramiters, not used
+     * @return NFC_SUCCESS if no error happen
+	 */
 	virtual int Init(void *ptr) {
 		return (NFC_StatusTypeDef) M24SR_Init((NFC_InitTypeDef*)ptr);
 	}
@@ -117,7 +129,8 @@
 		return (NFC_StatusTypeDef) M24SR_Deselect();
 	}
 
-	/** tag4 command */
+	////////// tag4 command ////////////////////
+	
 	virtual NFC_StatusTypeDef SelectApplication(void) {
 		return (NFC_StatusTypeDef) M24SR_SelectApplication();
 	}
@@ -146,7 +159,8 @@
 				(uint8_t) NbByteToWrite, (uint8_t *) pDataToWrite);
 	}
 
-	/** iso 7816-4 commands */
+	/////////////////// iso 7816-4 commands //////////////////////////
+	
 	virtual NFC_StatusTypeDef Verify(PasswordType_t pwdId, uint8_t NbPwdByte,
 			const uint8_t *pPwd) {
 		return (NFC_StatusTypeDef) M24SR_Verify((uint16_t) pwdId,
@@ -171,7 +185,10 @@
 				(uint16_t) uReadOrWrite);
 	}
 
-	/** st proprietary */
+    ////////////////////// ST proprietary //////////////////////////////////
+    /**
+     * as 
+     */
 	virtual NFC_StatusTypeDef STReadBinary(uint16_t Offset,
 			uint8_t NbByteToRead, uint8_t *pBufferRead) {
 		return (NFC_StatusTypeDef) M24SR_STReadBinary((uint16_t) Offset,
@@ -188,7 +205,7 @@
 				(uint16_t) uReadOrWrite);
 	}
 
-	/** chip configuration */
+	///////////////////// chip configuration /////////////////////////////////
 	virtual NFC_StatusTypeDef StateControl(uint8_t uSetOrReset) {
 		return (NFC_StatusTypeDef) M24SR_StateControl((uint8_t) uSetOrReset);
 	}
@@ -207,23 +224,51 @@
 		return (NFC_StatusTypeDef) M24SR_RFConfig((uint8_t) OnOffChoice);
 	}
 
-	/*** Public Interrupt Related Methods ***/
+	/**
+	 * 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
+	 */
 	virtual NFC_StatusTypeDef SendInterrupt(void) {
 		return (NFC_StatusTypeDef) M24SR_SendInterrupt();
 	}
 
 	/////////////////// hight level/utility function /////////////////////
 
+	/**
+	 * get an implementation of NDefNfcTag for use the library NDefLib
+	 * @retrun object of type NdefNfcTag for use this M24SR component
+	 */
 	NDefLib::NDefNfcTag& getNDefTag(){
 		return NDefTagUtil;
 	}
 
 
+	/**
+	 * 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
+	 */
 	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
+	 */
 	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
+	 */
 	NFC_StatusTypeDef enableWritePassword(const uint8_t* pCurrentWritePassword,
 			uint8_t* pNewPassword);
 
@@ -231,41 +276,41 @@
 
 	/**
 	 * @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
-	 * @retval SUCCESS : M24SR access is now free (no password needed)
-	 * @retval ERROR : operation does not complete
+	 * @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
 	 */
 	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
-	 * @retval SUCCESS : M24SR access is now forbidden in write mode
-	 * @retval ERROR : operation does not complete
+	 * @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
 	 */
 	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
-	 * @retval SUCCESS : M24SR write access is now allowed
-	 * @retval ERROR : operation does not complete
+	 * @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
 	 */
 	NFC_StatusTypeDef disableReadOnly();
 
 	/**
 	 * @brief  This fonction enable write only mode
-	 * @param	pCurrentWritePassword : Write password is needed to have right to enable write only mode
-	 * @retval SUCCESS : M24SR access is now forbidden in read mode
-	 * @retval ERROR : operation does not complete
+	 * @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
 	 */
 	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
-	 * @retval SUCCESS : M24SR read access is now allowed
-	 * @retval ERROR : operation does not complete
+	 * @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
 	 */
 	NFC_StatusTypeDef disableWriteOnly();
 
@@ -304,15 +349,38 @@
 	NFC_StatusTypeDef M24SR_RFConfig(uint8_t OnOffChoice);
 	NFC_StatusTypeDef M24SR_FWTExtension(uint8_t FWTbyte);
 
-
-	// platform specific IO method
+	/**
+	 * wait until the answer is not 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
+	 */
 	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
+	 */
 	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
+	 */
 	NFC_StatusTypeDef M24SR_IO_PollI2C(void);
 
+	/**
+	 * read the gpo pin
+	 * @param[out] pPinState variable where store the pin state
+	 */
 	void M24SR_IO_GPO_ReadPin(GPIO_PinState *pPinState) {
 		if (GPOPin == 0)
 			(*pPinState) = GPIO_PIN_RESET;
@@ -320,6 +388,10 @@
 			(*pPinState) = GPIO_PIN_SET;
 	}
 
+	/**
+	 * write the gpo pin
+	 * @param pPinState state to write
+	 */
 	void M24SR_IO_RFDIS_WritePin(GPIO_PinState PinState) {
 		if (PinState == GPIO_PIN_RESET)
 			RFDisablePin = 0;
@@ -327,6 +399,10 @@
 			RFDisablePin = 1;
 	}
 
+	/**
+	 * set how wait the command answer
+	 * @param mode how to wait the i2c rensponse
+	 */
 	void M24SR_IO_SetI2CSynchroMode(M24SR_WAITINGTIME_MGMT mode) {
 		syncMode = mode;
 	}
@@ -386,6 +462,9 @@
 	 */
 	volatile bool interruptIsFired;
 	
+	/**
+	 * Object implementing the interface for use the NDefLib
+	 */
 	NDefNfcTagM24SR NDefTagUtil;
 };