Introduction

The UOD Card is part of the LCC Fusion Project and provides Ultrasonic Occupancy Detection for model railroads and other layouts. It uses one or more ultrasonic distance sensors to detect the presence of trains, rolling stock, or other objects and reports those states as LCC Events via a Node Card connection.

Typical uses include detecting a train in a staging track, approach section, yard track, or behind scenery where optical or current-sensing detectors are less effective.

This firmware is intended for use only with an ESP32-based module mounted on an LCC Fusion UOD Card (PCB) and, 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

Supports one or more ultrasonic distance sensors (via the UOD Breakout Board).
Measures distance and converts it to occupied / clear (or multi-zone) states.
Maps sensor states to configurable LCC Event IDs via CDI configuration.
Supports per-sensor configuration, such as:
- Minimum and maximum valid distance.
- Occupied/clear threshold distance.
- Filtering / debouncing of readings.
Reports sensor status to the LCC network via I²C → Node Card → CAN Bus.
Provides optional local diagnostics (LEDs or serial messages) for each sensor.
Integrates with LCC Fusion diagnostics:
- Built-in self-tests for I²C connectivity to the Node Card.
- Optional GPIO and sensor sanity checks.
Supports serial, Bluetooth, or Web Serial text commands for:
- Viewing current distance and occupancy state per sensor.
- Running test modes (e.g., continuous distance display).
- Viewing debug / diagnostic information.

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 Module
- ESP32 DevKitC or compatible ESP32 module supported by the LCC Fusion I/O Cards board.
- 4MB or 8MB Flash (see board options).
LCC Fusion UOD Card
- ESP32 module footprint.
- I²C interface to the LCC Fusion Node Card.
- Connectors to the UOD Breakout Board for the ultrasonic sensors.
- Refer to config.h for I²C communications, I²C address, and GPIO pin assignments.
UOD Breakout Board / Ultrasonic Sensors
- Provides screw-terminals or headers for one or more ultrasonic sensors.
- Routes echo/trigger signals and power back to the UOD Card.
- Sensors may be standard 4-pin HC-SR04-style modules or compatible equivalents, depending on the board revision.

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 UOD Card firmware sketch and use Upload to flash the ESP32.

If the firmware supports CDI-based configuration, use your preferred CDI configuration tool to:

Assign I²C address information for the card.
Configure one or more sensor channels (distance thresholds, event IDs, etc.).

Testing & Diagnostics

With the UOD Card powered and connected (either to a Node Card or as a bench unit), connect a serial monitor, Bluetooth terminal, or Web Serial console at the configured baud rate (typically 115200).
Verify that the card reports its firmware banner and I²C address at startup.
Use the help (?) or info command (if provided by the sketch) to list supported commands, such as:
- Displaying live distance readings per sensor.
- Displaying current occupied/clear state and thresholds.
- Running sensor self-tests.
Move a train, car, or hand in front of each ultrasonic sensor and confirm that:
- Reported distance changes appropriately.
- Occupied/clear state transitions occur at the configured threshold.
When connected to a Node Card and CAN-enabled LCC network:
- Trigger occupancy by placing a car or train in the monitored area.
- Confirm that the corresponding LCC Events are generated and that any dependent logic (signals, sounds, indicators, etc.) responds as expected.

System Diagram

[Train / Object]
       ↓
  Ultrasonic Sensor → UOD Breakout → UOD Card → I²C → Node Card → CAN Bus (LCC Events)

Typical Applications

Detecting a train in a staging or hidden track where track circuit detection is difficult or unreliable.
Detecting a train or object in front of a backdrop, warehouse, or industry where optical sensors are impractical.
Providing approach or arrival detection for passenger stations or engine facilities.
Supplementing block-occupancy detection in special cases where physical isolation of the rails is not available.

Related Hardware and Docs

📄 UOD Card Assembly Guide (if published on the LCC Fusion docs site).
📄 UOD Breakout Board Assembly Guide (if applicable).
📄 Node Card Assembly Guide: https://patfleming.github.io/LccFusionProject/lccfusion/Node_Card-Assembly_Guide.html

Project Info

Part of the LCC Fusion Project: https://github.com/patfleming/LccFusionProject