LCC Fusion Project 1.0
LCC Automation
Loading...
Searching...
No Matches
LCC Fusion Firmware Reference

Introduction

The LCC Fusion Project is a modular hardware and firmware ecosystem for model railroad automation built on the NMRA LCC (Layout Command Control) standard and ESP32 microcontrollers. It provides a family of plug-in cards, breakout boards, and supporting tools that work together to:

  • Detect train presence and track conditions.
  • Drive signals, turnouts, motors, audio, and other layout accessories.
  • Exchange events over an LCC/CAN network using OpenMRN/OpenMRN-Lite.

This documentation describes the firmware layer of the project: core helper libraries, card-specific sketches, and configuration mechanisms.

Firmware Architecture

At a high level, the firmware is organized into:

  • LccFusionCore library
    • Core classes and helpers shared by all cards:
      • LCC node abstraction and event handling.
      • I²C card management and ID storage.
      • Serial / Bluetooth / Web Serial console support.
      • Self-test and diagnostics helpers.
  • ESP32-based Cards (firmware sketches)
    • Each plug-in card has a dedicated firmware sketch, typically very thin, that configures hardware and delegates behavior to LccFusionCore:
      • Node Card
      • BSD Card (Block Short Detection)
      • BOD/BLVD/BRD Cards (detection variants)
      • UOD Card (Ultrasonic Occupancy Detection)
      • Audio Card (configurable sound playback)
      • Output / PWM / Sensor / DIO Cards
  • Configuration & CDI
    • Card and node configuration is stored in CDI (Configuration Description Information) and can be edited using LCC tools or custom LibreOffice sheets provided by the project.

The goal is to keep card sketches small and declarative while concentrating most logic and shared behavior in the core library.

Card-Level Documentation

Each ESP32 card has its own overview page and group in this documentation. These pages describe the role of the card, its firmware entry points (setup/loop), and any card-specific helpers and configuration.

  • Node Card Firmware
  • Audio Card Firmware
  • BSD Card Firmware (Block Short Detection)
  • DCC Card Firmware
  • Sound Card Firmware
  • UOD Card Firmware (Ultrasonic Occupancy Detection)

Use the **"Modules"** and **"Related Pages"** sections in the generated documentation to navigate between cards and core components.

Source Tree Layout

A typical repository layout for the firmware looks like:

  • LccFusionCore/
    • Shared headers and source files for core functionality.
  • firmware/Node_Card/
  • firmware/Audio_Card/
    • Audio Card sketch and configuration headers.
  • firmware/BSD_Card/
    • BSD Card sketch and configuration headers.
  • firmware/DCC_Card/
    • DCC Card sketch and configuration headers.
  • firmware/Sound_Card/
    • Sound Card sketch and configuration headers.
  • firmware/UOD_Card/
    • UOD Card sketch and configuration headers.

This Doxygen configuration is run from the repository ./firmware directory and includes both the core library and all card firmware folders.

Building & Flashing

The firmware sketches can be built and flashed using:

Each card sketch typically includes a config.h that defines the required I²C address, GPIO mapping, and options specific to that card. Refer to the card’s own Doxygen page and the project website for build options.

Testing & Diagnostics

The firmware offers multiple ways to test cards and the overall system:

  • Serial/Bluetooth/Web Serial console
    • Common command patterns: ? for help, I for installation/usage info, and card-specific test commands.
  • Self-test helpers
    • I/O pin continuity checks.
    • I²C scan and card ID verification.
    • Detection and sensor sanity checks.
  • LCC Event Monitoring
    • When connected to an LCC network, cards generate and consume events based on configuration. Existing LCC tools can be used to monitor these events during testing.

Related Documentation

The Doxygen API reference is intended to complement the main LCC Fusion documentation, which provides assembly guides, wiring diagrams, planning guides, and configuration tools.

Project & License