Introduction

The BSD Card is part of the LCC Fusion Project and provides Block Short Detection for model railroad power districts and track blocks. It continuously monitors the track supply for short-circuit conditions and reports those faults as LCC Events via a Node Card connection.

This firmware is intended for use only with an ESP32 DevKitC Module (or equivalent ESP32 module) mounted on an LCC Fusion BSD Card (PCB) and, when used in production, is normally controlled by an LCC Fusion Node Card over the Node Bus I²C connection.

The firmware can be compiled using one of the following: 1) Arduino IDE (or CLI) using the 'ESP32 Dev Module' board packaged with the Espressif ESP32-core. 2) Arduino IDE (or CLI) using the 'I/O Cards' board packaged with the LCC Fusion Boards - https://github.com/patfleming/LccFusionProject/blob/main/assets/downloads/package_lcc_fusion_esp32_index.json

NOTE: the LCC Fusion 'I/O Cards' board provides firmware support for: 1) an ESP32 with 4MB or 8MB flash 2) Bluetooth serial terminal apps running on either a phone or tablet. Connection information is provided at startup via a cabled serial monitor. 3) Web Serial console running within a browser connected via WiFi to the ESP32 access point. Connection information is provided at startup via a cabled serial monitor.

Key Firmware Features

Monitors one or more DCC/DC track blocks for short-circuit events.
Uses on‑board comparator circuitry to detect over‑current / low‑voltage conditions.
Reports fault/clear status to the LCC network via I²C → Node Card → CAN Bus.
Maps block state to configurable LCC Event IDs (short detected / short cleared).
Supports local visual indicators (LEDs) and optional audible alerts (buzzer).
Supports serial, Bluetooth, or Web Serial text commands for:
- Viewing current block status.
- Running built‑in self‑tests.
- Viewing debug / diagnostic information.
Includes built‑in I²C address setting and verification logic.

Dependencies

Software
- Arduino IDE 2.x
- Libraries included with the LCC Fusion board package: https://github.com/patfleming/LccFusionProject/blob/main/assets/downloads/package_lcc_fusion_esp32_index.json
ESP32 DevKitC-V4 Board (38‑pin) or compatible
- ESP32 WROOM‑32D/32 module
- 4MB or 8MB Flash
LCC Fusion BSD Card
- On‑board short‑detection comparator(s) and sense resistors.
- I²C interface to the LCC Fusion Node Card.
- Optional LED indicators and buzzer.
- Refer to config.h for I²C communications, I²C address, and GPIO pin assignments.
BSD Breakout / Track Interface (if used)
- Connects one or more protected track sections / power districts to the BSD Card.

Build & Flash Instructions

Install Arduino IDE 2.x.
Download the LCC Fusion board package using Arduino IDE preferences 'Additional boards URLs' pointing to: https://github.com/patfleming/LccFusionProject/blob/main/assets/downloads/package_lcc_fusion_esp32_index.json
Install the LccFusion Board via Arduino IDE Boards Manager.
Select the board: LCC Fusion → I/O Cards.
Configure board options (flash size, serial options, etc.) as required.
Open the BSD Card firmware sketch and use Upload to flash the ESP32.

Testing & Diagnostics

Attach the BSD Card to a Node Card (or to a bench supply/test jig) and:
- Use a serial monitor, Bluetooth, or Web Serial console at 115200 baud.
- Verify that the card reports its firmware banner and I²C address at startup.
- Use the provided test commands (see sketch help text) to:
  - Simulate short / clear events.
  - Display current block status and raw comparator readings.
  - Run self‑tests on the I²C interface and GPIOs.
When connected to a Node Card and CAN‑enabled LCC network:
- Confirm that the expected LCC Events are generated when a block short is detected and when it clears.