STMicroelectronics' M24SR NFC Dynamic Tag Library.

Dependencies:   ST_INTERFACES

Dependents:   X_NUCLEO_NFC01A1

Fork of M24SR by ST Expansion SW Team

Embed: (wiki syntax)

« Back to documentation index

M24SR Class Reference

Class representing a M24SR component. More...

#include <M24SR.h>

Data Structures

class  Callbacks
 Object that contains all the callbacks fired by this class, each command has its own callback. More...
struct  M24SR_command_data_t
 User parameter used to invoke a command, it is used to provide the data back with the response. More...

Public Types

enum  NFC_GPO_MGMT
 

GPO state structure.

More...
enum  PasswordType_t { ReadPwd, WritePwd, I2CPwd }
 

Possible password to set.

More...
typedef void(* gpoEventCallback )(void)
 Function that will be called when an interrupt is fired, this function must be set if you want use the component in async mode.

Public Member Functions

 M24SR (const uint8_t address, I2C &I2C, gpoEventCallback eventCallback, const PinName &GPOPinName, const PinName &RFDISPinName)
 Constructor.
virtual ~M24SR (void)
 Destructor.
virtual int init (void *ptr)
 This function initializes the M24SR device.
virtual StatusTypeDef get_session (void)
 lock the tag channel
StatusTypeDef force_get_session (void)
 Force to open an I2C connection , abort the RF connection.
StatusTypeDef select_application (void)
 Select the application file.
StatusTypeDef select_CC_file (void)
 Select the CC file.
StatusTypeDef select_NDEF_file (uint16_t NDEFfileId)
 Select the NDEF file.
StatusTypeDef select_system_file (void)
 Select the system file.
StatusTypeDef ST_read_binary (uint16_t Offset, uint8_t NbByteToRead, uint8_t *pBufferRead)
 Same as NFC#read_binary, however permitting to read more bytes than available.
StatusTypeDef state_control (uint8_t uSetOrReset)
 Set the gpo output pin.
StatusTypeDef manage_I2C_GPO (NFC_GPO_MGMT GPO_I2Cconfig)
 This function configures GPO for I2C session.
StatusTypeDef manage_RF_GPO (uint8_t GPO_RFconfig)
 This function configures GPO for RF session.
StatusTypeDef RF_config (uint8_t OnOffChoice)
 This function enables or disables the RF communication.
StatusTypeDef send_interrupt (void)
 Generates a negative pulse on the GPO pin.
StatusTypeDef manage_event ()
 Function to call when the component fire an interrupt.
void set_callback (Callbacks *commandCallback)
 Change the function to call when a command ends.
StatusTypeDef enable_read_password (const uint8_t *pCurrentWritePassword, const uint8_t *pNewPassword)
 Enable the request of a password before reading the tag.
StatusTypeDef disable_read_password (const uint8_t *pCurrentWritePassword)
 Disable the request of a password before reading the tag.
StatusTypeDef enable_write_password (const uint8_t *pCurrentWritePassword, uint8_t *pNewPassword)
 Enable the request of a password before writing to the tag.
StatusTypeDef disable_write_password (const uint8_t *pCurrentWritePassword)
 Disable the request of a password before writing the tag.
StatusTypeDef disable_all_password (const uint8_t *pSuperUserPassword)
 This function disables both read and write passwords.
StatusTypeDef enable_read_only (const uint8_t *pCurrentWritePassword)
 This function enables read only mode.
StatusTypeDef disable_read_only (const uint8_t *pCurrentWritePassword)
 This function disables read only mode.
StatusTypeDef enable_write_only (const uint8_t *pCurrentWritePassword)
 This function enables write only mode.
StatusTypeDef disable_write_only (const uint8_t *pCurrentWritePassword)
 This function disables write only mode.
NDefLib::NDefNfcTag & get_NDef_tag ()
 Get an implementation of NDefNfcTag to use the library NDefLib.

Static Public Attributes

static const uint8_t DEFAULT_PASSWORD [16]
 Default password used to change the write/read permission.
static const NFC_GPO_MGMT DEFAULT_GPO_STATUS = HIGH_IMPEDANCE
 Default gpo status -> the gpo will remain high.

Protected Types

enum  M24SR_command_t {
  NONE, DESELECT, SELECT_APPLICATION, SELECT_CC_FILE,
  SELECT_NDEF_FILE, SELECT_SYSTEM_FILE, READ, UPDATE,
  VERIFY, MANAGE_I2C_GPO, MANAGE_RF_GPO, CHANGE_REFERENCE_DATA,
  ENABLE_VERIFICATION_REQUIREMENT, DISABLE_VERIFICATION_REQUIREMENT, ENABLE_PERMANET_STATE, DISABLE_PERMANET_STATE
}
 

Command that the component can accept.

More...
enum  M24SR_communication_t { SYNC, ASYNC }
 

Communication mode used by this device.

More...

Protected Member Functions

StatusTypeDef M24SR_Init (M24SR_InitTypeDef *)
 This function initialize the M24SR device.
StatusTypeDef M24SR_GetSession (void)
 This function sends the GetSession command to the M24SR device.
StatusTypeDef M24SR_ForceSession (void)
 This function sends the KillSession command to the M24SR device.
StatusTypeDef M24SR_Deselect (void)
 This function sends the Deselect command (S-Block format)
StatusTypeDef M24SR_SendSelectApplication (void)
 This function sends the SelectApplication command.
StatusTypeDef M24SR_SendSelectCCfile (void)
 This function sends the SelectCCFile command.
StatusTypeDef M24SR_SendSelectNDEFfile (uint16_t NDEFfileId)
 This function sends the SelectNDEFfile command.
StatusTypeDef M24SR_SendSelectSystemfile (void)
 This function sends the SelectSystemFile command.
StatusTypeDef M24SR_SendReadBinary (uint16_t Offset, uint8_t NbByteToRead, uint8_t *pBufferRead)
 This function sends a read binary command.
StatusTypeDef M24SR_SendSTReadBinary (uint16_t Offset, uint8_t NbByteToRead, uint8_t *pBufferRead)
 This function sends a ST read binary command (no error if access is not inside NDEF file)
StatusTypeDef M24SR_SendUpdateBinary (uint16_t Offset, uint8_t NbByteToWrite, uint8_t *pDataToWrite)
 This function sends a Update binary command.
StatusTypeDef M24SR_SendVerify (uint16_t uPwdId, uint8_t NbPwdByte, const uint8_t *pPwd)
 This function sends the Verify command.
StatusTypeDef M24SR_SendChangeReferenceData (uint16_t uPwdId, uint8_t *pPwd)
 This function sends the ChangeReferenceData command.
StatusTypeDef M24SR_SendEnableVerificationRequirement (uint16_t uReadOrWrite)
 This function sends the EnableVerificationRequirement command.
StatusTypeDef M24SR_SendDisableVerificationRequirement (uint16_t uReadOrWrite)
 This function sends the DisableVerificationRequirement command.
StatusTypeDef M24SR_SendEnablePermanentState (uint16_t uReadOrWrite)
 This function sends the EnablePermananentState command.
StatusTypeDef M24SR_SendDisablePermanentState (uint16_t uReadOrWrite)
 This function sends the DisablePermanentState command.
StatusTypeDef M24SR_SendInterrupt (void)
 This function generates an interrupt on GPO pin.
StatusTypeDef M24SR_StateControl (uint8_t uSetOrReset)
 This function forces GPO pin to low state or high Z.
StatusTypeDef M24SR_SendFWTExtension (uint8_t FWTbyte)
 This function sends the FWT extension command (S-Block format)
StatusTypeDef M24SR_IO_SendI2Ccommand (uint8_t NbByte, uint8_t *pBuffer)
 Send a command to the component.
StatusTypeDef M24SR_IO_ReceiveI2Cresponse (uint8_t NbByte, uint8_t *pBuffer)
 Read a command response.
StatusTypeDef M24SR_IO_PollI2C (void)
 Do an active polling on the I2C bus until the answer is ready.
void M24SR_IO_GPO_ReadPin (uint8_t *pPinState)
 Read the gpo pin.
void M24SR_IO_RFDIS_WritePin (uint8_t PinState)
 Write the gpo pin.
CallbacksgetCallback ()
 get the callback object to use

Protected Attributes

DigitalOut RFDisablePin
 Pin used to disable the rf chip functionality.
uint8_t uM24SRbuffer [0xFF]
 Buffer used to build the command to send to the chip.
uint8_t uDIDbyte
 ???
M24SR_communication_t mCommunicationType
 Type of communication being used.
M24SR_command_t mLastCommandSend
 Last pending command.
M24SR_command_data_t mLastCommandData
 Parameter used to invoke the last command.
InterruptIn mGpoEventInterrupt
 Interrupt object fired when the gpo status changes.
CallbacksmCallback
 object containing the callbacks to use
CallbacksmComponentCallback
 Object with private callbacks used to hide high level commands each calling multiple low level commands.
NDefNfcTagM24SRmNDefTagUtil
 Object implementing the interface to use the NDefLib.

Detailed Description

Class representing a M24SR component.

This component has two operation modes, sync or async. In sync mode each function call returns only after the command has completed. In async mode each function call returns immediately and the answer will be notified through a callback. The default behavior is sync mode. To enable the async mode ManageI2CGPO(I2C_ANSWER_READY) function must be called. When the component notifies an interrupt user must call ManageEvent function. Note that passing a parameter other than I2C_ANSWER_READY to ManageI2CGPO initialize the component in sync mode.

Definition at line 74 of file M24SR.h.


Member Typedef Documentation

typedef void(* gpoEventCallback)(void)

Function that will be called when an interrupt is fired, this function must be set if you want use the component in async mode.

Definition at line 148 of file M24SR.h.


Member Enumeration Documentation

enum M24SR_command_t [protected]

Command that the component can accept.

Enumerator:
NONE 

NONE.

DESELECT 

DESELECT.

SELECT_APPLICATION 

SELECT_APPLICATION.

SELECT_CC_FILE 

SELECT_CC_FILE.

SELECT_NDEF_FILE 

SELECT_NDEF_FILE.

SELECT_SYSTEM_FILE 

SELECT_SYSTEM_FILE.

READ 

READ.

UPDATE 

UPDATE.

VERIFY 

VERIFY.

MANAGE_I2C_GPO 

MANAGE_I2C_GPO.

MANAGE_RF_GPO 

MANAGE_RF_GPO.

CHANGE_REFERENCE_DATA 

CHANGE_REFERENCE_DATA.

ENABLE_VERIFICATION_REQUIREMENT 

ENABLE_VERIFICATION_REQUIREMENT.

DISABLE_VERIFICATION_REQUIREMENT 

DISABLE_VERIFICATION_REQUIREMENT.

ENABLE_PERMANET_STATE 

ENABLE_PERMANET_STATE.

DISABLE_PERMANET_STATE 

DISABLE_PERMANET_STATE.

Definition at line 823 of file M24SR.h.

enum M24SR_communication_t [protected]

Communication mode used by this device.

Enumerator:
SYNC 

SYNC wait the command response before returning.

ASYNC 

ASYNC use a callback to notify the end of a command.

Definition at line 855 of file M24SR.h.

GPO state structure.

Definition at line 115 of file M24SR.h.

Possible password to set.

Enumerator:
ReadPwd 

Password to use before reading the tag.

WritePwd 

Password to use before writing the tag.

I2CPwd 

Root password, used only through nfc.

Definition at line 127 of file M24SR.h.


Member Function Documentation

StatusTypeDef disable_all_password ( const uint8_t *  pSuperUserPassword )

This function disables both read and write passwords.

Parameters:
pSuperUserPasswordI2C super user password.
Returns:
return M24SR_SUCCESS if no errors
The password must have a length of 16 chars.

Definition at line 611 of file M24SR.h.

StatusTypeDef disable_read_only ( const uint8_t *  pCurrentWritePassword )

This function disables read only mode.

Parameters:
pCurrentWritePasswordWrite password is needed to disable read only mode.
Returns:
return M24SR_SUCCESS if no errors
The password must have a length of 16 chars.

Definition at line 636 of file M24SR.h.

StatusTypeDef disable_read_password ( const uint8_t *  pCurrentWritePassword )

Disable the request of a password before reading the tag.

Parameters:
pCurrentWritePasswordCurrent password
Returns:
return M24SR_SUCCESS if no errors
The password must have a length of 16 chars.

Definition at line 570 of file M24SR.h.

StatusTypeDef disable_write_only ( const uint8_t *  pCurrentWritePassword )

This function disables write only mode.

Parameters:
pCurrentWritePasswordWrite password is needed to disable write only mode.
Returns:
return M24SR_SUCCESS if no errors
The password must have a length of 16 chars.

Definition at line 664 of file M24SR.h.

StatusTypeDef disable_write_password ( const uint8_t *  pCurrentWritePassword )

Disable the request of a password before writing the tag.

Parameters:
pCurrentWritePasswordCurrent password.
Returns:
return M24SR_SUCCESS if no errors
The password must have a length of 16 chars.

Definition at line 598 of file M24SR.h.

StatusTypeDef enable_read_only ( const uint8_t *  pCurrentWritePassword )

This function enables read only mode.

Parameters:
pCurrentWritePasswordWrite password is needed to enable read only mode.
Returns:
return M24SR_SUCCESS if no errors
The password must have a length of 16 chars.

Definition at line 622 of file M24SR.h.

StatusTypeDef enable_read_password ( const uint8_t *  pCurrentWritePassword,
const uint8_t *  pNewPassword 
)

Enable the request of a password before reading the tag.

Parameters:
pCurrentWritePasswordCurrent password
pNewPasswordPassword to request before reading the tag.
Returns:
return M24SR_SUCCESS if no errors
The password must have a length of 16 chars.

Definition at line 555 of file M24SR.h.

StatusTypeDef enable_write_only ( const uint8_t *  pCurrentWritePassword )

This function enables write only mode.

Parameters:
pCurrentWritePasswordWrite password is needed to enable write only mode.
Returns:
return M24SR_SUCCESS if no errors
The password must have a length of 16 chars.

Definition at line 650 of file M24SR.h.

StatusTypeDef enable_write_password ( const uint8_t *  pCurrentWritePassword,
uint8_t *  pNewPassword 
)

Enable the request of a password before writing to the tag.

Parameters:
pCurrentWritePasswordCurrent password
pNewPasswordPassword to request before reading the tag.
Returns:
return M24SR_SUCCESS if no errors
The password must have a length of 16 chars.

Definition at line 584 of file M24SR.h.

StatusTypeDef force_get_session ( void   )

Force to open an I2C connection , abort the RF connection.

Returns:
M24SR_SUCCESS if the session is acquired

Definition at line 366 of file M24SR.h.

virtual StatusTypeDef get_session ( void   ) [virtual]

lock the tag channel

Definition at line 358 of file M24SR.h.

Callbacks* getCallback (  ) [protected]

get the callback object to use

Returns:
callback object to use

Definition at line 899 of file M24SR.h.

virtual int init ( void *  ptr ) [virtual]

This function initializes the M24SR device.

Parameters:
ptrConfigure parameters, not used.
Returns:
M24SR_SUCCESS if no errors

Definition at line 349 of file M24SR.h.

void M24SR_IO_GPO_ReadPin ( uint8_t *  pPinState ) [protected]

Read the gpo pin.

Parameters:
[out]pPinStateVariable to store the pin state into.

Definition at line 770 of file M24SR.h.

void M24SR_IO_RFDIS_WritePin ( uint8_t  PinState ) [protected]

Write the gpo pin.

Parameters:
pPinStatePin state to write.

Definition at line 778 of file M24SR.h.

StatusTypeDef manage_I2C_GPO ( NFC_GPO_MGMT  GPO_I2Cconfig )

This function configures GPO for I2C session.

Parameters:
GPO_I2CconfigGPO configuration to set.
Returns:
M24SR_SUCCESS if no errors
if the configuration is I2C_ANSWER_READY, the component will start to work
in async mode.

Definition at line 489 of file M24SR.h.

StatusTypeDef manage_RF_GPO ( uint8_t  GPO_RFconfig )

This function configures GPO for RF session.

Parameters:
GPO_RFconfigGPO configuration to set.
Returns:
M24SR_SUCCESS if no errors

Definition at line 499 of file M24SR.h.

StatusTypeDef RF_config ( uint8_t  OnOffChoice )

This function enables or disables the RF communication.

Parameters:
OnOffChoiceGPO configuration to set.
Returns:
M24SR_SUCCESS if no errors

Definition at line 511 of file M24SR.h.

StatusTypeDef select_application ( void   )

Select the application file.

Returns:
M24SR_SUCCESS if the application is selected

Definition at line 380 of file M24SR.h.

StatusTypeDef select_CC_file ( void   )

Select the CC file.

Returns:
M24SR_SUCCESS if the CC file is selected.

Definition at line 388 of file M24SR.h.

StatusTypeDef select_NDEF_file ( uint16_t  NDEFfileId )

Select the NDEF file.

Parameters:
NDEFfileIdFile id to open.
Returns:
M24SR_SUCCESS if the file is selected

Definition at line 397 of file M24SR.h.

StatusTypeDef select_system_file ( void   )

Select the system file.

Returns:
M24SR_SUCCESS if the system file is selected

Definition at line 405 of file M24SR.h.

StatusTypeDef send_interrupt ( void   )

Generates a negative pulse on the GPO pin.

Pulse starts immediately after the command is issued and ends at the end of the RF response.

Returns:
M24SR_SUCCESS if no errors

Definition at line 521 of file M24SR.h.

void set_callback ( Callbacks commandCallback )

Change the function to call when a command ends.

Parameters:
commandCallbackObject containing the callback, if NULL it will use empty callback

Definition at line 536 of file M24SR.h.

StatusTypeDef ST_read_binary ( uint16_t  Offset,
uint8_t  NbByteToRead,
uint8_t *  pBufferRead 
)

Same as NFC#read_binary, however permitting to read more bytes than available.

Parameters:
Offsetread offset.
NbByteToReadNumber of bytes to read.
[out]pBufferReadBuffer to store the read data into.
Returns:
M24SR_SUCCESS if no errors

Definition at line 456 of file M24SR.h.

StatusTypeDef state_control ( uint8_t  uSetOrReset )

Set the gpo output pin.

Parameters:
uSetOrResetNew pin status.
Returns:
M24SR_SUCCESS if no errors

Definition at line 478 of file M24SR.h.


Field Documentation

const NFC_GPO_MGMT DEFAULT_GPO_STATUS = HIGH_IMPEDANCE [static]

Default gpo status -> the gpo will remain high.

Definition at line 141 of file M24SR.h.

const uint8_t DEFAULT_PASSWORD [static]
Initial value:
 { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }

Default password used to change the write/read permission.

default password, also used to enable super user mode through the I2C channel

Definition at line 136 of file M24SR.h.

Callbacks* mCallback [protected]

object containing the callbacks to use

Definition at line 881 of file M24SR.h.

Type of communication being used.

Definition at line 863 of file M24SR.h.

Object with private callbacks used to hide high level commands each calling multiple low level commands.

This callbacks object has higher priority comparing to the user callbacks.

Definition at line 888 of file M24SR.h.

InterruptIn mGpoEventInterrupt [protected]

Interrupt object fired when the gpo status changes.

Definition at line 878 of file M24SR.h.

Parameter used to invoke the last command.

Definition at line 873 of file M24SR.h.

Last pending command.

Definition at line 868 of file M24SR.h.

Object implementing the interface to use the NDefLib.

Definition at line 893 of file M24SR.h.

DigitalOut RFDisablePin [protected]

Pin used to disable the rf chip functionality.

Definition at line 807 of file M24SR.h.

uint8_t uDIDbyte [protected]

???

Definition at line 817 of file M24SR.h.

uint8_t uM24SRbuffer[0xFF] [protected]

Buffer used to build the command to send to the chip.

Definition at line 812 of file M24SR.h.