LccFusionCore Library

Namespaces
namespace	pstTestPinsMri
	Human‑readable messages for pin self‑tests.
namespace	i2cCardIdMgrMri
	Messages used by I2cCardIdMgr for card ID programming.
namespace	serialIoMri
	Messages used by the SerialIO console helper.
namespace	soundCardMri
	Help and status strings for the Sound Card firmware.
namespace	audioCardMri
	Help and status strings for the Audio Card firmware.
namespace	bsdCardMri
	Help and diagnostic strings for the Block Sensor (BSD) card.
namespace	uodCardMri
	Help and diagnostic strings for the Ultrasonic Object Detection (UOD) card.
namespace	hwCheckIdMri
	Status messages for hardware ID detection.

Classes
class	CpuCheckTimer
	A timer that periodically checks CPU load and logs a warning if it exceeds a configured threshold. More...
class	I2cCardIdMgr
	Manager for reading/writing/verifying small identity records on 24LC02 EEPROMs over I²C. More...
class	OledDisplay
	Simple text console for a 128×64 SSD1309 OLED on a dedicated I²C bus. More...
class	PstTestPins
	One-stop pin self-test utility with a single dispatcher entry point. More...
class	SerialIO
	General-purpose input handler for text-based packets over multiple transports. More...

Macros
#define	LCD_BASE_ADDRESS   0x3C
	Base I²C address for the 128x64 OLED display (SSD1306/SSD1309). More...
#define	MCP23017_BASE_ADDRESS   0x20
	Base I²C address for the MCP23017 port expander. More...
#define	SOUND_CARD_BASE_ADDRESS   0x30
	Base I²C address for the Sound Card’s DFPlayer controllers. More...
#define	PCA9685_BASE_ADDRESS   0x40
	Base I²C address for the PCA9685 16‑channel PWM driver. More...
#define	EEPROM_BASE_ADDRESS   0x50
	Base I²C address for on‑card 24LC01/02 EEPROM devices. More...
#define	BSD_CARD_BASE_ADDRESS   0x58
	Reserved base address for Block Sensor (BSD) cards.
#define	UOD_CARD_BASE_ADDRESS   0x68
	Reserved base address for Ultrasonic Object Detection (UOD) cards.
#define	AUDIO_CARD_BASE_ADDRESS   0x60
	Reserved base address for Audio Card peripherals.
#define	HASSERT(x)
	Hardware assertion with logging. More...

Enumerations
enum	CardType : uint8_t {   CARD_NODE , CARD_QUAD_NODE , CARD_DCC , CARD_SOUND ,   CARD_AUDIO , CARD_UOD , CARD_BSD , CARD_COUNT ,   CARD_NOT_FOUND = 0xFE , CARD_NOT_IDENTIFIED = 0xFF }
	Enumerates all card categories recognizable by the HW ID signature. More...

Functions
static CardType	detectHwId ()
	Detect the type of LCC Fusion card attached via the HW_ID_PIN. More...
static bool	verifyCardType (CardType expectedCard)
	Verify that the detected hardware matches the expected card type. More...

Variables
static constexpr uint8_t	NUM_REMOTE_PLAYERS_PER_CARD = 4
	number of players to be configured on each of the remote sound cards (devices)
const CardSignature	cardSignatures [CardType::CARD_COUNT]
	Lookup table of expected HW_ID voltage ranges for each card type. More...
static constexpr size_t	CMD_BUF_SIZE = 64
	Maximum buffer size for one command (excluding null)

Detailed Description

Introduction

The LccFusionCore library is the shared firmware foundation for the LCC Fusion Project. It provides common classes, helpers, and utilities used by all ESP32-based cards (Node Card, BSD, UOD, Audio, Output, Sensor, DIO, etc.), so that each card sketch can remain small and focused.

Instead of duplicating logic in every firmware sketch, LccFusionCore centralizes:

• Node setup and OpenMRN/OpenMRN-Lite integration.
• Card identification and hardware signature detection.
• Serial / Bluetooth / Web Serial console helpers.
• Self-test and diagnostic infrastructure.

Any LCC Fusion card firmware that includes LccFusionCore.h can leverage these building blocks with minimal glue code.

Key Features

The library is organized into a set of headers that each provide a specific area of functionality, including (but not limited to):

• Hardware ID and card detection
  • Detects card type using analog voltage signatures and other mechanisms.
• Node description and MRI text
  • Standardized diagnostic and message text for card banners and help text.
• LED status and error feedback
  • Simple APIs for blink patterns, error codes, and status indication.
• Serial I/O and console helpers
  • Unified input/output on hardware Serial, Bluetooth, and Web Serial, allowing cards to share a common command and diagnostic interface.
• Self-test helpers
  • Infrastructure for exercising GPIOs, checking I²C wiring, and running card-specific self-tests.

The goal is to make card sketches mostly about configuration and wiring, with common behavior implemented once in LccFusionCore.

Major Headers

Some of the key headers exposed by the library include:

• LccFusionCore.h
  • Aggregates the core headers and defines common types and globals.
• HwIdCheck.h (or equivalent)
  • Implements the hardware ID / card-type detection logic.
• LccNodeMri.h
  • Provides standard diagnostic strings and node description text that appear in serial banners and LCC tools.
• LccNode.h and related node helpers
  • Wraps OpenMRN/OpenMRN-Lite node setup, event handling, and CDI access.
• SerialIoHelper.h (or similar)
  • Provides a common line-oriented console interface for commands and help.
• Self-test / pin-test helpers
  • Building blocks used by card firmware to validate wiring and I/O.

Refer to the generated Modules and Classes sections for complete lists of types and functions.

Usage

To use LccFusionCore in an Arduino-based ESP32 sketch:

• Install the library into your Arduino/libraries/ folder (or via the board package that bundles it).

• In your sketch, include the main header:

  #include <LccFusionCore.h>

• Create or use an LccNode (or equivalent) instance from the core library.
• Call the provided initialization methods from setup() to configure the node, card ID, I²C, and any detection hardware.
• In loop(), call the core library's update / poll functions so that events, timers, and diagnostics can run.

Individual cards (BSD, UOD, Audio, etc.) typically provide thin sketches that follow this pattern and then add card-specific configuration.

Typical Integration Pattern

A very simplified sketch using LccFusionCore might look like:

#include <LccFusionCore.h>
 
void setup() {
  // Initialize serial I/O for diagnostics.
  g_serialIO.begin(115200);
 
  // Initialize the LCC Fusion node and card-specific hardware.
  initLccFusionNode();
  initCardHardware();
}
 
void loop() {
  // Let the core library process timers, events, and self-tests.
  runLccFusionCoreLoop();
}

In real card firmware, the core library provides concrete types and functions for node setup, CDI handling, event producers/consumers, and self-test harnesses.

Relationship to Card Firmware

LccFusionCore is intended to be used alongside one or more card firmware sketches in the LCC Fusion Project. The typical relationship is:

• LccFusionCore:
  • Core node and diagnostic infrastructure.
  • Shared helpers and abstractions.
• Card firmware (e.g., BSD, UOD, Audio):
  • Card-specific wiring, configuration, and behavior.
  • Thin setup() / loop() that call into the core.

For more details on specific cards, see the card-level firmware pages (BSD Card, UOD Card, Audio Card, Node Card, etc.) in the generated documentation.

Related Resources

• LCC Fusion Project:
  • https://github.com/patfleming/LccFusionProject
• Project website and documentation:
  • https://patfleming.github.io/LccFusionProject

These resources provide assembly guides, wiring documentation, CDI configuration tools, and higher-level usage tutorials that complement this API reference.

Macro Definition Documentation

EEPROM_BASE_ADDRESS

#define EEPROM_BASE_ADDRESS   0x50

Base I²C address for on‑card 24LC01/02 EEPROM devices.

Every card (except the Node Card) includes a tiny serial EEPROM that stores its identity record. The address of each EEPROM is EEPROM_BASE_ADDRESS + offset, where offset derives from the card’s address switch (0–7). See I2cCardIdMgr for reading and writing these records.

Definition at line 88 of file CardVars.h.

HASSERT

#define HASSERT

(

x

)

Value:

       do                                                           \
       {                                                            \
              if (!(x))                                             \
              {                                                     \
                     Serial.printf("Assertion failed: %s:%d: %s\n", \
                                   __FILE__, __LINE__, #x);         \
                     assert(0);                                     \
                     abort();                                       \
              }                                                     \
       } while (0)

Hardware assertion with logging.

Evaluates the expression x and, if it is false, prints a detailed diagnostic message to the Serial console, including the file name, line number and the failed expression string. It then triggers a standard assert(0) followed by abort() to halt execution. Use this macro in code paths that must never be reached or to enforce hardware assumptions during development. When the expression evaluates to true the macro expands to a no‑op.

Parameters

x	Boolean expression to test.

Definition at line 58 of file LccMacros.h.

LCD_BASE_ADDRESS

#define LCD_BASE_ADDRESS   0x3C

Base I²C address for the 128x64 OLED display (SSD1306/SSD1309).

All displays used in the LCC Fusion project expose their controller at 7‑bit address 0x3C. Adjust this constant if your hardware uses a different address (for example, 0x3D).

Definition at line 45 of file CardVars.h.

MCP23017_BASE_ADDRESS

#define MCP23017_BASE_ADDRESS   0x20

Base I²C address for the MCP23017 port expander.

Each card that uses the 16‑bit I/O expander (MCP23017) ties the A2:A0 address lines to the 3‑bit address switch on the PCB. The effective address is computed as MCP23017_BASE_ADDRESS + offset, where offset comes from the switch setting. This constant is defined here to allow overriding the default (0x20) if needed.

Definition at line 57 of file CardVars.h.

PCA9685_BASE_ADDRESS

#define PCA9685_BASE_ADDRESS   0x40

Base I²C address for the PCA9685 16‑channel PWM driver.

Cards that drive servos or LED dimmers use the PCA9685. Similar to MCP23017, its address lines map to the card’s address switch.

Definition at line 76 of file CardVars.h.

SOUND_CARD_BASE_ADDRESS

#define SOUND_CARD_BASE_ADDRESS   0x30

Base I²C address for the Sound Card’s DFPlayer controllers.

DFPlayer modules do not expose I²C; however, the Sound Card uses this address range for its on‑board configuration EEPROM. See also I2cCardIdMgr for details on card programming.

Definition at line 67 of file CardVars.h.

Enumeration Type Documentation

CardType

enum CardType : uint8_t

Enumerates all card categories recognizable by the HW ID signature.

Each enumerator corresponds to a distinct LCC Fusion card. The detection logic in detectHwId() measures the analog voltage on HW_ID_PIN and selects one of these values based on the configured voltage ranges. The final two sentinel values are used to report absence of a card or failure to match any known signature.

Enumerator
CARD_NODE	Node Card: generic I/O lines and NeoPixel support
CARD_QUAD_NODE	Quad‑Node Card: four Node Cards on one PCB
CARD_DCC	DCC Card: drives DCC signals for model railroads
CARD_SOUND	Sound Card: DFPlayer‑based sound playback
CARD_AUDIO	Audio Card: ESP32‑native I²S and TTS playback
CARD_UOD	Ultrasonic Object Detection (UOD) card
CARD_BSD	Block Sensor (BSD) card measuring current draw
CARD_COUNT	Number of recognized cards in the lookup table
CARD_NOT_FOUND	Sentinel meaning no card present on the HW_ID_PIN
CARD_NOT_IDENTIFIED	Sentinel meaning the measured voltage did not match any signature

Definition at line 97 of file HwIdCheck.h.

Function Documentation

detectHwId()

static CardType detectHwId ( )

inlinestatic

Detect the type of LCC Fusion card attached via the HW_ID_PIN.

Reads the analog voltage on HW_ID_PIN and compares it against the voltage ranges defined in cardSignatures. If the voltage falls below roughly 0.3 V the function concludes that no card is connected (returns CARD_NOT_FOUND). If the voltage lies within one of the predefined ranges it prints the detected card name and returns the corresponding CardType. Otherwise it prints that the card is unknown and returns CARD_NOT_IDENTIFIED.

Returns

The detected card type or one of the sentinel values (CARD_NOT_FOUND or CARD_NOT_IDENTIFIED).

Definition at line 172 of file HwIdCheck.h.

Here is the caller graph for this function:

verifyCardType()

static bool verifyCardType ( CardType  expectedCard )

inlinestatic

Verify that the detected hardware matches the expected card type.

Invokes detectHwId() and compares the result with expectedCard. If the function detects CARD_NOT_FOUND (no card inserted) it returns true to allow firmware to be programmed into a bare ESP32. For any other mismatch it prints an error message and returns false.

Parameters

expectedCard

The card type required by the running firmware.

Return values

true	The detected card matches expectedCard or no card is present.
false	The detected card type does not match and a mismatch was reported.

Definition at line 209 of file HwIdCheck.h.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

cardSignatures

cardSignatures

Initial value:

= {
  { "Node Card",    2.00, 2.25 },
  { "Quad-Node Card",   2.85, 3.15 },
  { "DCC Card",     2.10, 2.35 },
  { "Sound Card",   2.45, 2.70 },
  { "Audio Card",   2.65, 2.90 },
  { "UOD Card",     1.50, 1.75 },
  { "BSD Card",     0.68, 3.15 }
}

Lookup table of expected HW_ID voltage ranges for each card type.

Each entry corresponds to a value in CardType (from CARD_NODE up to CARD_BSD). The minV and maxV fields define the acceptable ADC voltage range on HW_ID_PIN for that card. detectHwId() scans this table to decide which card is currently plugged into the ESP32.

The ranges include tolerance for component variation and ADC noise, so they should only be tightened with care and after measurement on real hardware.

Definition at line 147 of file HwIdCheck.h.