easylinux/DCC-Bench
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bcd88909b786aad9b7eedaed64a4890955dee699
DCC-Bench/README.md
Serge NOEL 56d8cd96c8 Initialisation depot
2025-11-30 09:58:00 +01:00

12 KiB
Raw Blame History

🚂 Locomotive Test Bench

A comprehensive testing platform for model/scale locomotives using ESP32 (D1 Mini ESP32) and LM18200 H-Bridge motor driver. This system supports both DC Analog and DCC Digital control modes with a responsive web interface.

Features

Control Modes

  • DC Analog Mode: Traditional PWM-based speed control with bidirectional operation
  • DCC Digital Mode: Full DCC protocol support for digital model locomotives
    • 128-step speed control
    • Function control (F0-F12)
    • Short and long address support (1-10239)

WiFi Capabilities

  • Access Point Mode: Create a standalone WiFi network
  • Client Mode: Connect to existing WiFi networks
  • Automatic reconnection in client mode
  • Runtime WiFi configuration via web interface

Web Interface

  • Responsive Bootstrap-based design
  • Real-time status monitoring
  • Speed control with visual slider
  • Direction control (forward/reverse)
  • Emergency stop button
  • DCC address configuration
  • Function button controls (F0-F12) for DCC mode
  • WiFi settings management
  • Mobile-friendly design

Hardware Requirements

Components

  • ESP32 D1 Mini (or compatible ESP32 board)
  • LM18200 H-Bridge Motor Driver
  • 2x WS2812 RGB LEDs (for status indication)
  • Power Supply: Suitable for your locomotive scale (typically 12-18V)
  • Model locomotive (DC or DCC compatible)

Pin Connections

LM18200 Motor Driver (DC Analog Mode)

LM18200 Pin ESP32 Pin Description
PWM GPIO 25 PWM speed control
DIR GPIO 26 Direction control
BRAKE GPIO 27 Brake control (active low)
OUT1 - Motor terminal 1
OUT2 - Motor terminal 2
Vcc 5V Logic power
GND GND Ground

DCC Signal Output

Signal ESP32 Pin Description
DCC A GPIO 32 DCC Signal A
DCC B GPIO 33 DCC Signal B (inverted)

Status LEDs (WS2812)

LED ESP32 Pin Function Colors
Data GPIO 4 LED strip data -
LED 0 - Power status Green=ON, Red=OFF
LED 1 - Mode indicator Blue=DCC, Yellow=Analog

Note: DCC signals require appropriate signal conditioning and booster circuitry for track connection.

Wiring Diagram Notes

  1. Connect LM18200 motor outputs to track or locomotive
  2. Ensure proper power supply voltage for your scale
  3. DCC mode requires additional booster circuit (not included in basic schematic)
  4. Use appropriate heat sinking for LM18200

Software Setup

Prerequisites

Installation Steps

  1. Clone or download this project

    cd /your/projects/folder
git clone <repository-url>
cd LocomotiveTestBench

  2. Open in VS Code

    • Open VS Code
    • File → Open Folder → Select LocomotiveTestBench folder

  3. Download Bootstrap files for offline use

    cd data
chmod +x download_bootstrap.sh
./download_bootstrap.sh

    Or download manually:

  4. Upload Filesystem (LittleFS)

    • Click PlatformIO icon in sidebar
    • Under PROJECT TASKS → Upload Filesystem Image
    • Wait for upload to complete

  5. Build the project

    • Select "Build" under PROJECT TASKS

  6. Upload to ESP32

    • Connect ESP32 via USB
    • Click "Upload" under PROJECT TASKS
    • Wait for upload to complete

  7. Monitor Serial Output (optional)

    • Click "Monitor" to see debug output
    • Default baud rate: 115200

Configuration

First Time Setup

  1. Power on the ESP32

    • Default mode: Access Point
    • SSID: LocoTestBench
    • Password: 12345678

  2. Connect to WiFi

    • Use phone/computer to connect to LocoTestBench network
    • Default IP: 192.168.4.1

  3. Access Web Interface

    • Open browser: http://192.168.4.1
    • You should see the Locomotive Test Bench interface

WiFi Configuration

Access Point Mode (Default)

  • Creates standalone network
  • Default SSID: LocoTestBench
  • Default Password: 12345678
  • IP Address: 192.168.4.1

Client Mode

  1. Open web interface
  2. Expand "WiFi Configuration"
  3. Select "Client (Connect to Network)"
  4. Enter your network SSID and password
  5. Click "Save & Restart"
  6. Device will restart and connect to your network
  7. Check serial monitor for assigned IP address

Usage Guide

DC Analog Mode

  1. Select Mode

    • Click "DC Analog" button in Control Mode section

  2. Set Speed

    • Use slider to adjust speed (0-100%)
    • Speed shown in large display

  3. Change Direction

    • Click "🔄 Reverse" button to toggle direction
    • Arrow indicator shows current direction (→ forward, ← reverse)

  4. Emergency Stop

    • Click "⏹ STOP" button to immediately stop locomotive

DCC Digital Mode

  1. Select Mode

    • Click "DCC Digital" button in Control Mode section
    • DCC sections will appear

  2. Set Locomotive Address

    • Enter DCC address (1-10239)
    • Click "Set" button
    • Address is saved to memory

  3. Control Speed

    • Use slider to adjust speed (0-100%)
    • Direction control works same as analog mode

  4. DCC Functions

    • Function buttons (F0-F12) appear in DCC mode
    • Click button to toggle function ON/OFF
    • Active functions shown in darker color

Pin Customization

To change pin assignments, edit these files:

Motor Controller Pins

Edit include/MotorController.h:

#define MOTOR_PWM_PIN 25      // Change as needed
#define MOTOR_DIR_PIN 26      // Change as needed
#define MOTOR_BRAKE_PIN 27    // Change as needed

DCC Output Pins

Edit include/DCCGenerator.h:

#define DCC_PIN_A 32    // Change as needed
#define DCC_PIN_B 33    // Change as needed

LED Indicator Pins

Edit include/LEDIndicator.h:

#define LED_DATA_PIN 4    // WS2812 data pin
#define NUM_LEDS 2        // Number of LEDs

API Documentation

This project includes comprehensive API documentation using Doxygen.

Generate Documentation

# Install Doxygen (if not already installed)
# Ubuntu/Debian: sudo apt-get install doxygen graphviz
# macOS: brew install doxygen graphviz

# Generate documentation
./generate_docs.sh

# View documentation
xdg-open doc/html/index.html  # Linux
open doc/html/index.html      # macOS

The documentation includes:

  • Detailed class descriptions
  • Function/method documentation
  • Parameter and return value descriptions
  • Code examples and usage notes
  • Cross-referenced source code

See doc/README.md for more information.

Project Structure

LocomotiveTestBench/
├── platformio.ini          # PlatformIO configuration
├── Doxyfile               # Doxygen configuration for API docs
├── generate_docs.sh       # Script to generate documentation
├── README.md              # This file
├── doc/                   # Generated API documentation
│   └── html/             # HTML documentation (generated)
├── data/                  # Filesystem (uploaded to LittleFS)
│   ├── index.html        # Main web interface
│   ├── css/
│   │   ├── bootstrap.min.css  # Bootstrap CSS (local)
│   │   └── style.css     # Custom styles
│   └── js/
│       ├── bootstrap.bundle.min.js  # Bootstrap JS (local)
│       └── app.js        # Application JavaScript
├── include/               # Header files
│   ├── Config.h          # Configuration management
│   ├── WiFiManager.h     # WiFi connectivity
│   ├── MotorController.h # DC motor control
│   ├── DCCGenerator.h    # DCC signal generation
│   ├── LEDIndicator.h    # WS2812 LED status indicators
│   └── WebServer.h       # Web server & API
└── src/                  # Source files
    ├── main.cpp          # Main application
    ├── Config.cpp        # Configuration implementation
    ├── WiFiManager.cpp   # WiFi implementation
    ├── MotorController.cpp # Motor control implementation
    ├── DCCGenerator.cpp  # DCC implementation
    ├── LEDIndicator.cpp  # LED indicator implementation
    └── WebServer.cpp     # Web server implementation

API Reference

REST API Endpoints

GET /api/status

Returns current system status

{
  "mode": "dcc",
  "speed": 50,
  "direction": 1,
  "dccAddress": 3,
  "ip": "192.168.4.1",
  "wifiMode": "ap"
}

POST /api/mode

Set control mode

{"mode": "dcc"}  // or "analog"

POST /api/speed

Set speed and direction

{"speed": 75, "direction": 1}

POST /api/dcc/address

Set DCC locomotive address

{"address": 1234}

POST /api/dcc/function

Control DCC function

{"function": 0, "state": true}

POST /api/wifi

Configure WiFi (triggers restart)

{
  "isAPMode": false,
  "ssid": "YourNetwork",
  "password": "YourPassword"
}

Troubleshooting

Cannot Connect to WiFi AP

  • Verify ESP32 has power
  • Check default SSID: LocoTestBench
  • Default password: 12345678
  • Try restarting ESP32

Web Interface Not Loading

  • Verify correct IP address (check serial monitor)
  • Try http://192.168.4.1 in AP mode
  • Check if LittleFS mounted successfully (serial output)
  • Ensure filesystem was uploaded (Upload Filesystem Image)
  • Clear browser cache and reload
  • Try different browser

Bootstrap/CSS Not Loading

  • Verify Bootstrap files are downloaded to data/css/ and data/js/
  • Re-run data/download_bootstrap.sh script
  • Upload filesystem image again
  • Check browser console for 404 errors

Motor Not Running (DC Mode)

  • Check LM18200 connections
  • Verify power supply is connected
  • Check pin definitions match your wiring
  • Use serial monitor to verify commands are received

DCC Not Working

  • Verify DCC pins are correctly connected
  • DCC requires proper signal conditioning/booster
  • Check locomotive is DCC-compatible
  • Verify correct address is programmed in locomotive

Upload Failed

  • Check USB cable connection
  • Try different USB port
  • Press BOOT button on ESP32 during upload
  • Check correct board selected in platformio.ini

Technical Details

DCC Protocol Implementation

  • NMRA DCC Standard compliant
  • 128-step speed control
  • Function groups support (F0-F12 currently implemented)
  • Configurable preamble (14 bits)
  • Error detection with XOR checksum

PWM Specifications (DC Mode)

  • Frequency: 20 kHz
  • Resolution: 8-bit (0-255)
  • Duty cycle: 0-100% (mapped from speed)

WiFi Specifications

  • AP Mode: 802.11 b/g/n
  • Client Mode: Auto-reconnect enabled
  • Default reconnect interval: 30 seconds

Safety Notes

⚠️ Important Safety Information

  • Always disconnect power before wiring changes
  • Use appropriate fuses for your scale
  • Never exceed voltage ratings of your locomotives
  • LM18200 requires adequate heat sinking
  • Test with low voltage before full power
  • Emergency stop should be easily accessible

Future Enhancements

Potential features for future versions:

  • PWM frequency adjustment
  • Current monitoring and overload protection
  • Multiple locomotive support
  • Consist/multi-unit control
  • Extended DCC functions (F13-F28)
  • MQTT integration
  • Locomotive profile storage
  • Mobile app

License

This project is provided as-is for educational and hobbyist purposes.

Credits

  • ESP32 Arduino Core
  • ESPAsyncWebServer library
  • Bootstrap CSS framework
  • ArduinoJson library

Support

For issues, questions, or contributions:

  • Check serial monitor output for debugging
  • Verify hardware connections
  • Review pin configurations
  • Test with known-good locomotive

Version: 1.0
Last Updated: November 2025
Compatible Boards: ESP32 D1 Mini, ESP32 DevKit, other ESP32 variants
Framework: Arduino for ESP32

Reference in New Issue View Git Blame Copy Permalink