nfc_st25dv16kc.h

Go to the documentation of this file.

/*
 * nfc_st25dv16kc.h
 *
 *  Created on: 9. 3. 2026
 *      Author: Milan
 *
 *  ST25DV16KC Dynamic NFC/RFID Tag with 16Kbit EEPROM
 *  Datasheet: https://www.st.com/resource/en/datasheet/st25dv16kc.pdf
 *
 *  I2C User memory address  : 0x53 (7-bit) = 0xA6 / 0xA7 (8-bit R/W)
 *  I2C System config address: 0x57 (7-bit) = 0xAE / 0xAF (8-bit R/W)
 *  Default I2C password     : 8 x 0x00
 *
 *  EEPROM: 2048 bytes (4-byte page write)
 *  Mailbox: 256-byte Fast Transfer Mode buffer
 */
 
#ifndef INC_NFC_ST25DV16KC_H_
#define INC_NFC_ST25DV16KC_H_
 
#include "stm32wlxx_hal.h"
 
/* ===========================================================================
 * Public API
 * =========================================================================== */
 
/**
 * @brief Check whether the ST25DV16KC has been successfully initialised.
 * @param hi2c    Pointer to I2C handle.
 * @param tryInit When 1, attempt Init() if not yet initialised; 0 – no retry.
 * @retval 1 – NFC present and ready, 0 – not available.
 */
int8_t nfc_st25dv16kc_Is(I2C_HandleTypeDef *hi2c, int8_t tryInit);
 
/**
 * @brief Check the I2C bus and try to find the NFC chip.
 *        Enables the mailbox, clears it, and turns GPO off (low-power state).
 * @param hi2c Pointer to I2C handle.
 * @retval HAL_OK – NFC found and initialised, HAL_ERROR – not on the bus.
 */
HAL_StatusTypeDef nfc_st25dv16kc_Init(I2C_HandleTypeDef *hi2c);
 
/**
 * @brief Turn the NFC GPO ON (all events: MsgReady, FieldChange, RFWrite).
 *        Enables host-side reading/writing via the Mailbox.
 * @param hi2c Pointer to I2C handle.
 * @retval HAL_OK on success, HAL_ERROR if NFC not available.
 */
HAL_StatusTypeDef nfc_st25dv16kc_On(I2C_HandleTypeDef *hi2c);
 
/**
 * @brief Turn the NFC GPO OFF and enable GPO RF to achieve minimum current (~1 µA).
 * @param hi2c Pointer to I2C handle.
 * @retval HAL_OK on success, HAL_ERROR if NFC not available.
 */
HAL_StatusTypeDef nfc_st25dv16kc_Off(I2C_HandleTypeDef *hi2c);
 
/**
 * @brief Write data to the EEPROM user memory (4-byte page writes).
 * @param hi2c  Pointer to I2C handle.
 * @param addr  Start address within EEPROM (0x0000–0x07FF for 16Kbit).
 * @param pData Pointer to data buffer to write.
 * @param len   Number of bytes to write.
 * @retval HAL_OK on success, HAL_ERROR on failure or NFC absent.
 */
HAL_StatusTypeDef nfc_st25dv16kc_WriteEEPROM(I2C_HandleTypeDef *hi2c, uint16_t addr, uint8_t *pData, uint16_t len);
 
/**
 * @brief Read data from the EEPROM user memory.
 * @param hi2c  Pointer to I2C handle.
 * @param addr  Start address within EEPROM.
 * @param pData Pointer to destination buffer.
 * @param len   Number of bytes to read.
 * @retval HAL_OK on success, HAL_ERROR on failure or NFC absent.
 */
HAL_StatusTypeDef nfc_st25dv16kc_ReadEEPROM(I2C_HandleTypeDef *hi2c, uint16_t addr, uint8_t *pData, uint16_t len);
 
/**
 * @brief Process incoming data from the RF Mailbox.
 *        Checks MB_CTRL_DYN for an RF message; if present reads it and
 *        invokes nfc_st25dv16kc_OnMailboxData().
 * @param hi2c Pointer to I2C handle.
 * @retval HAL_OK – message read, HAL_ERROR – no message or NFC absent.
 */
HAL_StatusTypeDef nfc_st25dv16kc_ProcessMailBox(I2C_HandleTypeDef *hi2c);
 
/**
 * @brief Write raw data into the Mailbox so the RF reader (phone) can retrieve it.
 * @param hi2c  Pointer to I2C handle.
 * @param pData Pointer to data buffer.
 * @param len   Number of bytes to write (max ST25DV16KC_MB_SIZE).
 * @retval HAL_OK on success, HAL_ERROR on failure or NFC absent.
 */
HAL_StatusTypeDef nfc_st25dv16kc_WriteMailBox(I2C_HandleTypeDef *hi2c, uint8_t *pData, uint16_t len);
 
/**
 * @brief Weak callback invoked by nfc_st25dv16kc_ProcessMailBox() when new
 *        data has arrived in the Mailbox.  Override in main.c or application
 *        code to process the received message.
 * @param data Pointer to received data buffer.
 * @param len  Number of bytes received.
 */
__weak void nfc_st25dv16kc_OnMailboxData(uint8_t *data, uint16_t len);
 
 
#endif /* INC_NFC_ST25DV16KC_H_ */