Manager for reading/writing/verifying small identity records on 24LC02 EEPROMs over I²C. More...

#include <I2cCardIdMgr.h>

Collaboration diagram for I2cCardIdMgr:

Classes
struct	CardInfo
	Container describing presence/programming state and raw record. More...

struct	CardRecord
	Binary record stored at EEPROM offset 0x00. More...

struct	EepromConfig
	Runtime parameters describing the target EEPROM device. More...

Public Types
enum class	CardType : uint8_t
	Canonical card type identifiers (serialized as 1 byte). More...

Public Member Functions
	I2cCardIdMgr ()
	Construct with default `Wire` instance.

	I2cCardIdMgr (TwoWire &wire)
	Construct with an explicit `TwoWire` reference. More...

	I2cCardIdMgr (TwoWire *wire)
	Construct with an explicit `TwoWire` pointer. More...

	I2cCardIdMgr (int sdaPin, int sclPin, uint32_t freqHz=400000)
	Construct and initialize `Wire` with custom pins and frequency. More...

bool	read (uint8_t offset, CardInfo *pCardInfo)
	Read a card identity record from EEPROM into a CardInfo container. More...

bool	verify (CardType expectedType, uint8_t offset=0xFF)
	Verify that the programmed I²C card matches the expected type. More...

bool	program ()
	One-shot interactive programmer: scan, (optionally) confirm overwrite, prompt fields, write record, and report result. More...

Static Public Member Functions
static constexpr uint8_t	getCardIdFromType (CardType t)
	Convert CardType to its 1-byte serialized id. More...

static constexpr CardType	getCardTypeFromId (uint8_t b)
	Convert serialized id (u8) to CardType. More...

static const char *	convertCardTypeToString (CardType t)
	Get the ASCII name of a CardType. More...

Static Public Attributes
static constexpr size_t	EepromMemorySize = 256
	Maximum storage available on the target EEPROM (bytes).

Private Member Functions
bool	_eepromFound ()
	Probe the EEPROM at i2cAddress_ with a short timeout. More...

char *	convertToChar (char buf, const char src, size_t len)
	Convert a fixed-width, non-NUL-terminated field into a safe C string. More...

template<size_t N>
bool	_promptForData (char(&dst)[N], const __FlashStringHelper *prompt)
	Prompt the user and fill a fixed-size character field. More...

bool	_isProgrammed (CardType *pCardType=nullptr)
	Check if EEPROM appears programmed and optionally return its CardType. More...

bool	_write (uint8_t offset, const CardRecord &cardRecord)
	Write a full `CardRecord` blob to EEPROM (binary). More...

bool	_writeEepromRecord (uint8_t mem, const uint8_t *data, size_t len)
	Low-level page-aware EEPROM writer. More...

bool	_readEepromRecord (uint8_t mem, uint8_t *data, size_t len)
	Read a contiguous range of bytes from EEPROM. More...

String	_readLine ()
	Read a trimmed line from the serial command buffer. More...

CardType	_promptCardType ()
	Interactively prompt the user to select a CardType. More...

Private Attributes
TwoWire *	pWire_
	I²C bus handle used for EEPROM transactions.

EepromConfig	eepromConfig_
	Runtime EEPROM parameters (page size, magic, etc.).

uint8_t	i2cAddress_
	Current I²C address of the target EEPROM (base + offset).

Detailed Description

Manager for reading/writing/verifying small identity records on 24LC02 EEPROMs over I²C.

Designed for Arduino/ESP32 environments. Uses a compact, binary-stable CardRecord stored at EEPROM address 0x00. Helper methods map between raw enum ids and CardType, and assist with end-user interactive programming.

Definition at line 69 of file I2cCardIdMgr.h.

Member Enumeration Documentation

◆ CardType

enum class I2cCardIdMgr::CardType : uint8_t

strong

Canonical card type identifiers (serialized as 1 byte).

Note: Enum is explicitly 1 byte to ensure on-EEPROM stability.

Definition at line 78 of file I2cCardIdMgr.h.

Constructor & Destructor Documentation

◆ I2cCardIdMgr() [1/3]

I2cCardIdMgr::I2cCardIdMgr ( TwoWire & wire )

inline

Construct with an explicit TwoWire reference.

Parameters

wire	Reference to the I²C bus instance to use.

Definition at line 216 of file I2cCardIdMgr.h.

◆ I2cCardIdMgr() [2/3]

I2cCardIdMgr::I2cCardIdMgr ( TwoWire * wire )

inline

Construct with an explicit TwoWire pointer.

Parameters

wire	Pointer to the I²C bus instance to use.

Definition at line 222 of file I2cCardIdMgr.h.

◆ I2cCardIdMgr() [3/3]

I2cCardIdMgr::I2cCardIdMgr	(	int	sdaPin,
		int	sclPin,
		uint32_t	freqHz = `400000`
	)

inline

Construct and initialize Wire with custom pins and frequency.

Parameters

sdaPin	SDA GPIO.
sclPin	SCL GPIO.
freqHz	I²C clock frequency (Hz). Default: 400 kHz.

Note: Calls begin(sdaPin, sclPin, freqHz) on the stored TwoWire.

Definition at line 232 of file I2cCardIdMgr.h.

Member Function Documentation

◆ _eepromFound()

bool I2cCardIdMgr::_eepromFound ( )

inlineprivate

Probe the EEPROM at i2cAddress_ with a short timeout.

Sends an I²C start/stop and considers the device present if endTransmission() returns 0 within ~30 ms.

Returns: true if the device ACKs within the timeout; false otherwise.

Definition at line 454 of file I2cCardIdMgr.h.

Here is the caller graph for this function:

◆ _isProgrammed()

bool I2cCardIdMgr::_isProgrammed ( CardType * pCardType = nullptr )

inlineprivate

Check if EEPROM appears programmed and optionally return its CardType.

Reads the first byte (stored cardType id). Values 0x00 (Unknown) and 0xFF (blank) are treated as "not programmed". Any other value is "programmed".

Parameters

pCardType Optional out-parameter to receive the decoded CardType when programmed; set to Unknown otherwise.

Returns: true if programmed; false if blank/unknown or if read/probe fails.

Definition at line 539 of file I2cCardIdMgr.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _promptCardType()

CardType I2cCardIdMgr::_promptCardType ( )

inlineprivate

Interactively prompt the user to select a CardType.

Prints a numbered list (skipping Unknown), reads the user's choice, validates range, and returns the selected enum or Unknown on error.

Returns: The chosen CardType, or CardType::Unknown if invalid.

Definition at line 661 of file I2cCardIdMgr.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _promptForData()

template<size_t N>

bool I2cCardIdMgr::_promptForData	(	char(&)	dst[N],
		const __FlashStringHelper *	prompt
	)

inlineprivate

Prompt the user and fill a fixed-size character field.

Prints prompt, reads a line from serial, and copies/truncates/pads to exactly N bytes in dst (no NUL terminator written).

Template Parameters

N	Fixed size of the destination array.

Parameters

dst	Destination fixed-size char array to fill.
prompt	Prompt to display before reading.

Returns: true if any input was provided; false if the line was empty.

Definition at line 497 of file I2cCardIdMgr.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _readEepromRecord()

bool I2cCardIdMgr::_readEepromRecord	(	uint8_t	mem,
		uint8_t *	data,
		size_t	len
	)

inlineprivate

Read a contiguous range of bytes from EEPROM.

Writes the internal address pointer, then requests len bytes into data.

Parameters

mem	EEPROM memory address to start reading from.
data	Destination buffer.
len	Number of bytes to read.

Returns: true on success; false on I²C error or short read.

Definition at line 620 of file I2cCardIdMgr.h.

Here is the caller graph for this function:

◆ _readLine()

String I2cCardIdMgr::_readLine ( )

inlineprivate

Read a trimmed line from the serial command buffer.

Blocks until a complete line is available via

See also: g_serialIO, returns the trimmed string, and clears the command buffer.

Returns: The next trimmed command line from serial.

Definition at line 641 of file I2cCardIdMgr.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _write()

bool I2cCardIdMgr::_write	(	uint8_t	offset,
		const CardRecord &	cardRecord
	)

inlineprivate

Write a full CardRecord blob to EEPROM (binary).

Sets i2cAddress_ from offset, probes the device, guards against oversize records, then writes sizeof(CardRecord) bytes starting at address 0x00 using page-aware bursts.

Parameters

offset	EEPROM address offset (0..7 maps to 0x50+offset or similar).
cardRecord	The record to serialize and store.

Returns: true on success; false on probe/write failure.

Note: Relies on _writeEepromRecord for page handling.

Definition at line 568 of file I2cCardIdMgr.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _writeEepromRecord()

bool I2cCardIdMgr::_writeEepromRecord	(	uint8_t	mem,
		const uint8_t *	data,
		size_t	len
	)

inlineprivate

Low-level page-aware EEPROM writer.

Splits the buffer across EEPROM page boundaries, issuing multiple write cycles as needed and polling for write completion.

Parameters

mem	EEPROM memory address to start writing from.
data	Pointer to data buffer to write.
len	Number of bytes to write.

Returns: true on success; false on I²C error or device not ready.

Definition at line 592 of file I2cCardIdMgr.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ convertCardTypeToString()

static const char * I2cCardIdMgr::convertCardTypeToString ( CardType t )

inlinestatic

Get the ASCII name of a CardType.

Parameters

t	Card type enum.

Returns: Pointer to a string view's data for the enum name (e.g., "BOD").

Warning: The returned pointer refers to static storage owned by magic_enum.

Definition at line 204 of file I2cCardIdMgr.h.

Here is the caller graph for this function:

◆ convertToChar()

char * I2cCardIdMgr::convertToChar	(	char *	buf,
		const char *	src,
		size_t	len
	)

inlineprivate

Convert a fixed-width, non-NUL-terminated field into a safe C string.

Copies len bytes from src into buf and appends a trailing '\0' so it can be safely printed with s. Spaces are preserved.

Parameters

[out]	buf	Destination buffer (must be at least len+1 bytes).
[in]	src	Source field (exactly len bytes on chip).
[in]	len	Length of the source field.

Returns: Pointer to buf for convenience.

Definition at line 478 of file I2cCardIdMgr.h.

Here is the caller graph for this function:

◆ getCardIdFromType()

static constexpr uint8_t I2cCardIdMgr::getCardIdFromType ( CardType t )

inlinestaticconstexpr

Convert CardType to its 1-byte serialized id.

Parameters

t	Card type enum.

Returns: Unsigned 8-bit identifier to store in EEPROM.

Definition at line 178 of file I2cCardIdMgr.h.

◆ getCardTypeFromId()

static constexpr CardType I2cCardIdMgr::getCardTypeFromId ( uint8_t b )

inlinestaticconstexpr

Convert serialized id (u8) to CardType.

Parameters

b	Raw 8-bit id read from EEPROM.

Returns: Decoded CardType or CardType Unknown if invalid.

Definition at line 188 of file I2cCardIdMgr.h.

Here is the caller graph for this function:

◆ program()

bool I2cCardIdMgr::program ( )

inline

One-shot interactive programmer: scan, (optionally) confirm overwrite, prompt fields, write record, and report result.

Workflow: 1) Scans 0x50..0x57 (A2:A0 = 0..7) and requires exactly one EEPROM device. 2) If an existing record is detected (first byte not 0x00/0xFF), displays the current type/refId/version and prompts the user to confirm overwrite. 3) Prompts for the new fields (CardType, refId[3], version[3], description[30]). 4) Writes a binary CardRecord at address 0x00 using page-aware writes. 5) Emits a programming summary and returns success/failure.

Returns: true If exactly one device was found, user confirmed (when needed), all prompts succeeded, and the record was written successfully.; false If no device or multiple devices were found, user declined to overwrite, an I²C error occurred, or writing failed.

Postcondition: On success, the EEPROM at the discovered offset contains the new CardRecord blob. A summary message is printed via g_serialIO.

Warning: Requires an interactive serial session. The routine assumes the card’s EEPROM is writable (WP not asserted) and that the I²C bus is idle.; Text fields written to EEPROM are not NUL-terminated on-chip; they are stored as fixed-width, space-padded fields.

Note: This routine expects exactly one card connected during programming to prevent addressing collisions.

Definition at line 354 of file I2cCardIdMgr.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ read()

bool I2cCardIdMgr::read	(	uint8_t	offset,
		CardInfo *	pCardInfo
	)

inline

Read a card identity record from EEPROM into a CardInfo container.

Sets the internal I²C address to (EEPROM base + offset), probes the device, and, if present, reads a binary CardRecord starting at memory address 0x00. The pCardInfo->present and pCardInfo->programmed flags are updated based on bus presence and the first byte of the stored record (cardType).

Programming state heuristic:

Considered programmed if the first byte (cardType id) is neither 0x00 (Unknown) nor 0xFF (blank). Otherwise not programmed.

Parameters

[in]	offset	EEPROM address offset (A2:A0, 0..7 → 0x50 + offset).
[out]	pCardInfo	Non-null pointer that receives presence/program state, the offset, and a copy of the raw CardRecord.

Returns: true If the EEPROM was successfully accessed and (when present) the CardRecord was read into pCardInfo.; false On I²C/addressing errors (probe or read failed), or if arguments are invalid (e.g., pCardInfo is null).

Postcondition

On success, pCardInfo->addressOffset == offset.
pCardInfo->present == true iff the EEPROM ACKed on the bus.
If present:
- pCardInfo->cardRecord contains the raw on-chip bytes.
- pCardInfo->programmed reflects the first-byte check described above.

Warning: Text fields inside CardRecord (e.g., description[30]) are NOT NUL-terminated on chip. NUL-terminate a local copy before printing with s or use a precision specifier (e.g., "%.*s", 30, field).

Note: This function reads exactly sizeof(CardRecord) bytes from 0x00. Ensure sizeof(CardRecord) ≤ EepromMemorySize at compile time.

Definition at line 273 of file I2cCardIdMgr.h.

Here is the call graph for this function:

◆ verify()

bool I2cCardIdMgr::verify	(	CardType	expectedType,
		uint8_t	offset = `0xFF`
	)

inline

Verify that the programmed I²C card matches the expected type.

Reads the card ID from the 24LC02 at EEPROM_BASE_ADDRESS + offset using a non-destructive random read. If offset is the scan-all sentinel, all valid offsets are tried until a match is found. Internally relies on _isProgrammed() for diagnostics (no extra log spam added here).

Parameters

[in]	expectedType	The card type you expect (e.g., CardType::UOD).
[in]	offset	EEPROM address offset (A2:A0, 0..7 → 0x50 + offset). Don't pass offset to scan all offsets.

Returns: true if a matching, programmed card is found; false otherwise.

Definition at line 307 of file I2cCardIdMgr.h.

Here is the call graph for this function:

Here is the caller graph for this function:

The documentation for this class was generated from the following file:

C:/Users/patfl/AppData/Local/Arduino15/libraries/LccFusionCore/src/I2cCardIdMgr.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ CardType

Constructor & Destructor Documentation

◆ I2cCardIdMgr() [1/3]

◆ I2cCardIdMgr() [2/3]

◆ I2cCardIdMgr() [3/3]

Member Function Documentation

◆ _eepromFound()

◆ _isProgrammed()

◆ _promptCardType()

◆ _promptForData()

◆ _readEepromRecord()

◆ _readLine()

◆ _write()

◆ _writeEepromRecord()

◆ convertCardTypeToString()

◆ convertToChar()

◆ getCardIdFromType()

◆ getCardTypeFromId()

◆ program()

◆ read()

◆ verify()