Firmware library for the X-NUCLEO-NFC01A1 Dynamic NFC Tag board.
Dependencies: M24SR
Dependents: NFC M2M_2016_STM32 MyongjiElec_capstone1 IDW01M1_Cloud_IBM ... more
Fork of X_NUCLEO_NFC01A1 by
X-NUCLEO-NFC01A1 Dynamic NFC Tag Expansion Board Firmware Package
Introduction
This firmware package includes Components Device Drivers, Board Support Package and example applications for STMicroelectronics X-NUCLEO-NFC01A1 Dynamic NFC Tag Expansion Board based on M24SR.
Firmware Library
Class X_NUCLEO_NFC01A1 is intended to represent the Dynamic NFC Tag Expansion Board with the same name.
It provides an API to access to the M24SR component and to the three onboard LEDs.
It is intentionally implemented as a singleton because only one X_NUCLEO_NFC01A1 at a time might be deployed in a HW component stack.
The library also provides an implementation of the NDEF library API for M24SR, providing an simple way to read/write NDEF formatted messages from/to the M24SR dynamic NFC tag.
Example applications
1. Hello World
2. Asynchronous Hello World
Revision 7:19fc04b8fec6, committed 2016-01-11
- Comitter:
- giovannivisentini
- Date:
- Mon Jan 11 12:37:28 2016 +0000
- Parent:
- 6:96389fb79676
- Child:
- 8:5e637c71cbb3
- Commit message:
- update docs
Changed in this revision
--- a/Interfaces/Nfc_class.h Tue Dec 22 15:34:24 2015 +0000
+++ b/Interfaces/Nfc_class.h Mon Jan 11 12:37:28 2016 +0000
@@ -75,38 +75,38 @@
virtual NFC_StatusTypeDef GetSession(void) = 0;
/**
* force to open an i2c connection , abort the RF connection
- * @return
+ * @return NFC_SUCCESS if the session is acquired
*/
virtual NFC_StatusTypeDef KillSession(void) = 0;
/**
* close an i2c connection
- * @return
+ * @return NFC_SUCCESS if the session is release
*/
virtual NFC_StatusTypeDef Deselect(void) = 0;
/**
* Select the application file
- * @return
+ * @return NFC_SUCCESS if the application is selected
*/
virtual NFC_StatusTypeDef SelectApplication(void) = 0;
/**
* select the CC file
- * @return
+ * @return NFC_SUCCESS if the cc file is selected
*/
virtual NFC_StatusTypeDef SelectCCfile(void) = 0;
/**
* select the ndef file
* @param NDEFfileId file id to open
- * @return
+ * @return NFC_SUCCESS if the file is selected
*/
virtual NFC_StatusTypeDef SelectNDEFfile(uint16_t NDEFfileId) = 0;
/**
* select the system file
- * @return
+ * @return NFC_SUCCESS if the system file is selected
*/
virtual NFC_StatusTypeDef SelectSystemfile(void) = 0;
@@ -115,7 +115,7 @@
* @param Offset offset where start to read
* @param NbByteToRead number of byte to read
* @param[out] pBufferRead buffer where store the read data
- * @return
+ * @return NFC_SUCCESS if no error happen
*/
virtual NFC_StatusTypeDef ReadBinary(uint16_t Offset, uint8_t NbByteToRead, uint8_t *pBufferRead) = 0;
@@ -124,7 +124,7 @@
* @param Offset offset where start to write
* @param NbByteToWrite number of byte to write
* @param pDataToWrite buffer to write
- * @return
+ * @return NFC_SUCCESS if no error happen
*/
virtual NFC_StatusTypeDef UpdateBinary(uint16_t Offset, uint8_t NbByteToWrite, uint8_t *pDataToWrite) = 0;
@@ -133,7 +133,7 @@
* @param uPwdId password type
* @param NbPwdByte password size ( must be 0x10)
* @param pPwd password buffer
- * @return
+ * @return NFC_SUCCESS if no error happen, and you have the permission to write/read
*/
virtual NFC_StatusTypeDef Verify(PasswordType_t uPwdId, uint8_t NbPwdByte,const uint8_t *pPwd) = 0;
@@ -146,12 +146,57 @@
virtual NFC_StatusTypeDef ChangeReferenceData(PasswordType_t uPwdId,const uint8_t *pPwd) = 0;
virtual NFC_StatusTypeDef EnableVerificationRequirement(PasswordType_t uReadOrWrite) = 0;
virtual NFC_StatusTypeDef DisableVerificationRequirement(PasswordType_t uReadOrWrite) = 0;
+
+ /**
+ * as {@link Nfc#ReadBinary} but it doesn't give error if you read more byte than the ones
+ * that are available
+ * @param Offset offset where start to read
+ * @param NbByteToRead number of byte to read
+ * @param[out] pBufferRead buffer where store the read data
+ * @return NFC_SUCCESS if no error happen
+ */
virtual NFC_StatusTypeDef STReadBinary(uint16_t Offset, uint8_t NbByteToRead, uint8_t *pBufferRead) = 0;
+
+ /**
+ * set the tag as read/write only and write it in the eeprom
+ * @param uReadOrWrite ReadPwd if you need a write only, WritePwd if you need a read only
+ * @return NFC_SUCCESS if no error happen
+ */
virtual NFC_StatusTypeDef EnablePermanentState(PasswordType_t uReadOrWrite) = 0;
+ /**
+ * unset the tag as read/write only and write it in the eeprom
+ * @param uReadOrWrite ReadPwd if you need a write only, WritePwd if you need a read only
+ * @return NFC_SUCCESS if no error happen
+ * @par you must be in i2csuper user state for call this function
+ */
virtual NFC_StatusTypeDef DisablePermanentState(PasswordType_t uReadOrWrite) = 0;
+
+ /**
+ * set the gpo output pin
+ * @param uSetOrReset new pin status
+ * @return NFC_SUCCESS if no error happen
+ */
virtual NFC_StatusTypeDef StateControl(uint8_t uSetOrReset) = 0;
+
+ /**
+ * @brief This function configure GPO purpose for I2C session
+ * @param GPO_I2Cconfig: GPO configuration to set
+ * @return NFC_SUCCESS if no error happen
+ */
virtual NFC_StatusTypeDef ManageI2CGPO(uint8_t GPO_I2Cconfig) = 0;
+
+ /**
+ * @brief This function configure GPO purpose for RF session
+ * @param GPO_RFconfig: GPO configuration to set
+ * @return NFC_SUCCESS if no error happen
+ */
virtual NFC_StatusTypeDef ManageRFGPO(uint8_t GPO_RFconfig) = 0;
+
+ /**
+ * @brief This function enable or disable RF communication
+ * @param OnOffChoice: GPO configuration to set
+ * @return NFC_SUCCESS if no error happen
+ */
virtual NFC_StatusTypeDef RFConfig(uint8_t OnOffChoice) = 0;
virtual ~Nfc(){};
--- a/X_NUCLEO_NFC01A1.h Tue Dec 22 15:34:24 2015 +0000
+++ b/X_NUCLEO_NFC01A1.h Mon Jan 11 12:37:28 2016 +0000
@@ -73,14 +73,23 @@
mNfcLed1(led1Name),mNfcLed2(led2Name),mNfcLed3(led3Name){}
public:
- static const PinName DEFAULT_SDA_PIN;
- static const PinName DEFAULT_SDL_PIN;
- static const PinName DEFAULT_GPO_PIN;
- static const PinName DEFAULT_RF_DISABLE_PIN;
- static const PinName DEFAULT_LED1_PIN;
- static const PinName DEFAULT_LED2_PIN;
- static const PinName DEFAULT_LED3_PIN;
+ static const PinName DEFAULT_SDA_PIN; //!< default pin used for the M24SR SDA signal
+ static const PinName DEFAULT_SDL_PIN; //!< default pin used for the M24SR SDL signal
+ static const PinName DEFAULT_GPO_PIN; //!< default pin used for the M24SR GPO signal
+ static const PinName DEFAULT_RF_DISABLE_PIN; //!< default pin used for M24SR RF_DISABLE signal
+ static const PinName DEFAULT_LED1_PIN; //!< default pin for controll the led 1
+ static const PinName DEFAULT_LED2_PIN; //!< default pin for controll the led 2
+ static const PinName DEFAULT_LED3_PIN; //!< default pin for controll the led 3
+ /**
+ * create or return an instance of X_NUCLEO_NFC01A1
+ * @param devI2C i2c channel used for communicate with the board
+ * @param gpoName pin of the gpio pin of the M24SR chip
+ * @param RFDisableName pin for disable the rf antenna
+ * @param led1Name pin for control the led1 status
+ * @param led2Name pin for control the led1 status
+ * @param led3Name pin for control the led1 status
+ */
static X_NUCLEO_NFC01A1* Instance(I2C &devI2C,
const PinName &gpoName = DEFAULT_GPO_PIN,
const PinName &RFDisableName = DEFAULT_RF_DISABLE_PIN,
--- a/m24sr/NDefNfcTagM24SR.h Tue Dec 22 15:34:24 2015 +0000
+++ b/m24sr/NDefNfcTagM24SR.h Mon Jan 11 12:37:28 2016 +0000
@@ -57,7 +57,6 @@
0xFF) {
}
-
virtual bool openSession(bool force = false);
virtual bool closeSession();
--- a/m24sr/m24sr_class.cpp Tue Dec 22 15:34:24 2015 +0000
+++ b/m24sr/m24sr_class.cpp Mon Jan 11 12:37:28 2016 +0000
@@ -62,7 +62,7 @@
/** value return by the NFC chip when a command is successfully done */
#define NFC_COMMAND_SUCCESS 0x9000
-/** call the fCall funtion and check that the return status is NFC_COMMAND_SUCCESS,
+/** call the fCall funtion and check that the return status is NFC_SUCCESS,
* otherwise return the error status*/
#define errchk(fCall) {\
const NFC_StatusTypeDef status = (fCall); \
@@ -248,8 +248,8 @@
/**
* @brief This function return M24SR_STATUS_SUCCESS if the pBuffer is an s-block
* @param pBuffer : pointer of the data
- * @retval M24SR_STATUS_SUCCESS : the data is a S-Block
- * @retval M24SR_ERROR_DEFAULT : the data is not a S-Block
+ * @retval NFC_SUCCESS : the data is a S-Block
+ * @retval NFC_ERROR : the data is not a S-Block
*/
static NFC_StatusTypeDef IsSBlock(uint8_t *pBuffer) {
@@ -264,8 +264,7 @@
/**
* @brief This function sends the FWT extension command (S-Block format)
* @param FWTbyte : FWT value
- * @retval Status (SW1&SW2) : Status of the operation to complete.
- * @retval M24SR_ERROR_I2CTIMEOUT : The I2C timeout occurred.
+ * @return NFC_SUCCESS if no error happen
*/
NFC_StatusTypeDef M24SR::M24SR_FWTExtension(uint8_t FWTbyte) {
uint8_t pBuffer[M24SR_STATUSRESPONSE_NBBYTE];
@@ -300,8 +299,7 @@
/**
* @brief This function sends the KillSession command to the M24SR device
* @param None
- * @retval NFC_SUCCESS : the function is successful.
- * @retval M24SR_ERROR_I2CTIMEOUT : The I2C timeout occurred.
+ * @return NFC_SUCCESS if no error happen
*/
NFC_StatusTypeDef M24SR::M24SR_KillSession(void) {
uint8_t commandBuffer[] = M24SR_KILLSESSION_COMMAND;
@@ -318,8 +316,7 @@
/**
* @brief This function sends the Deselect command (S-Block format)
- * @retval NFC_SUCCESS : the function is successful.
- * @retval M24SR_ERROR_I2CTIMEOUT : The I2C timeout occurred.
+ * @return NFC_SUCCESS if no error happen
*/
NFC_StatusTypeDef M24SR::M24SR_Deselect(void) {
uint8_t pBuffer[] = M24SR_DESELECTREQUEST_COMMAND;
@@ -336,8 +333,7 @@
/**
* @brief This function sends the SelectApplication command
- * @retval NFC_SUCCESS : the function is successful.
- * @retval M24SR_ERROR_I2CTIMEOUT : The I2C timeout occurred.
+ * @return NFC_SUCCESS if no error happen
*/
NFC_StatusTypeDef M24SR::M24SR_SelectApplication(void) {
@@ -449,7 +445,7 @@
/* copy the number of byte of the data field */
command.Body.LC = sizeof(pDataOut);
command.Body.pData = pDataOut;
- /* build the I²C command */
+ /* build the I2C command */
M24SR_BuildIBlockCommand(M24SR_CMDSTRUCT_SELECTCCFILE, &command, uDIDbyte,
&NbByte, pBuffer);
@@ -1068,11 +1064,7 @@
return status;
}
-/**
- * @brief This function configure GPO purpose for I2C session
- * @param GPO_I2Cconfig: GPO configuration to set
- * @retval Status (SW1&SW2) : Status of the operation to complete.
- */
+
NFC_StatusTypeDef M24SR::M24SR_ManageI2CGPO(M24SR_GPO_MGMT GPO_I2Cconfig) {
uint8_t GPO_config = 0;
@@ -1103,12 +1095,6 @@
return NFC_SUCCESS;
}
-/**
- * @brief This function configure GPO purpose for RF session
- *
- * @param GPO_RFconfig: GPO configuration to set
- * @retval Status (SW1&SW2) : Status of the operation to complete.
- */
NFC_StatusTypeDef M24SR::M24SR_ManageRFGPO(M24SR_GPO_MGMT GPO_RFconfig) {
uint8_t GPO_config;
@@ -1130,11 +1116,6 @@
return NFC_SUCCESS;
}
-/**
- * @brief This function enable or disable RF communication
- * @param OnOffChoice: GPO configuration to set
- * @retval Status (SW1&SW2) : Status of the operation to complete.
- */
NFC_StatusTypeDef M24SR::M24SR_RFConfig(uint8_t OnOffChoice) {
/* Disable RF */
if (OnOffChoice != 0) {
@@ -1163,7 +1144,8 @@
}
#define M24SR_POLL_DELAY 10
-#define M24SR_I2C_POLLING 200 /* In case M24SR will reply ACK failed allow to perform retry before returning error (HAL option not used) */
+/* In case M24SR will reply ACK failed allow to perform retry before returning error (HAL option not used) */
+#define M24SR_I2C_POLLING 200
NFC_StatusTypeDef M24SR::M24SR_IO_PollI2C(void) {
--- 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;
};

X-NUCLEO-NFC01A1 Dynamic NFC Tag