Node Card Firmware

Introduction

The LCC Fusion Node Card is the core ESP32-based controller in the LCC Fusion Project. It hosts the OpenMRN/OpenLCB stack, manages local I/O, and communicates with other cards over the Node Bus and CAN/LCC network.

This documentation focuses on the firmware running on the Node Card:

• How the Node integrates with the OpenLCB stack.
• How configuration data (CDI) is mapped into runtime objects.
• How producer/consumer events are registered and dispatched.
• How I2C- and GPIO-based expansion cards are discovered and used.

---

Overview

At a high level, the Node Card firmware:

• Brings up the OpenLCB node (ID, SNIP, CDI, configuration file).
• Attaches one or more configured helper classes that map CDI data into runtime behavior (e.g., I/O cards, audio cards, sensors).
• Registers producer and consumer events based on CDI configuration.
• Dispatches incoming LCC events to the appropriate handlers (GPIO, I²C devices, audio, etc.).

The main entry points are the Arduino-style:

• setup() – initializes hardware, OpenLCB stack, and configured cards.
• loop() – runs the OpenMRN executor and any periodic housekeeping.

---

Key Components

The Node Card firmware is organized into a small set of core classes and helpers:

• LccNode
  Wrapper around the OpenLCB/OpenMRN node, responsible for:
  • Node initialization and reset handling.
  • CDI access and configuration file management.
  • Utility hooks for self-test, brown-out detection, etc.
• I2cCardHelper
  Common helper for cards that are discovered/configured via I²C (e.g., MCP23017-based I/O, sensor, and audio cards). Handles:
  • Per-card I²C address offsets.
  • Pull-up checks and basic bus validation.
  • Common logging and diagnostics.
• Configured Producer/Consumer helpers (examples):
  
  • IoConfiguredPC – maps CDI I/O card entries to OpenLCB events and GPIO/pin behavior.
    
  • AudioConfiguredConsumer – maps CDI audio card entries to OpenLCB consumer events and audio playback.
    
  • Other card-specific helpers follow the same pattern: constructed with a node pointer, a CDI repeated group, and optional metadata such as device type and description.
• Event metadata helpers
  Types such as EventUserArgsUnion pack small pieces of metadata (card number, pin number, flags, etc.) into user_arg fields so the dispatcher can efficiently route events at runtime.

---

Quick Start

A typical Node Card sketch follows this pattern:

#include <LccFusionCore.h>
#include "LccNode.h"
#include "IoConfiguredPC.h"
#include "AudioConfiguredConsumer.h"
// ... other includes ...
 
// Global node wrapper
LccNode lccNode;
 
void setup() {
  // Initialize serial / diagnostics (optional).
  lccNode.begin();
 
  // Access CDI-generated configuration (example names).
  auto cfg = lccNode.config();
 
  // Configure I/O cards.
  IoConfiguredPC<NUM_IO_CARDS> ioConfigured(
      lccNode.node(),
      cfg.ioCardsSeg().ioCardConfig(),
      16,
      EventDeviceTypes::IoCard,
      "IO Card");
 
  // Configure audio cards.
  AudioConfiguredConsumer<NUM_AUDIO_CARDS> audioConfigured(
      lccNode.node(),
      cfg.audioCardsSeg().audioCardConfig(),
      EventDeviceTypes::AudioCard);
 
  // Register events and apply CDI configuration as needed...
}
 
void loop() {
  // Run the OpenMRN executor and any periodic tasks.
  lccNode.loop();
}

The actual class and segment names may differ, but the pattern is:

• Create a single LccNode instance.
• Construct one or more configured helpers for each supported card type.
• In setup(), apply CDI configuration and register events.
• In loop(), call back into LccNode (or the OpenMRN executor) regularly.

---

Self-Test and Diagnostics

Many Node Card–related classes include hooks for:

• Power-on self-test (PST) of GPIO and I²C lines.
• Optional serial / WebSerial / Bluetooth diagnostics.
• Error reporting for missing cards, invalid addresses, or duplicate I²C offsets.

Refer to the individual class documentation under Node Card Firmware for details on available self-test and diagnostic features.