Files

Serge NOEL c3176e8d79 Initialisation depot

2026-02-10 12:12:11 +01:00

12 KiB

Raw Blame History

🚂 Locomotive Test Bench

A comprehensive testing platform for model/scale locomotives using ESP32-2432S028R (ESP32 with ILI9341 touchscreen) and motor driver circuits. This system supports both DC Analog and DCC Digital control modes with an intuitive touchscreen 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-F28 capable)
- Short and long address support (1-10239)

Track Configuration

2-Rail Mode: Standard two-rail DC/DCC operation
3-Rail Mode: Center rail configuration with relay switching

Touchscreen Interface

320x240 ILI9341 TFT Display with resistive touch
Power ON/OFF control with visual indicators
Mode switching (DCC/Analog) with automatic power-off safety
Interactive speed slider (0-100%)
Direction control (Forward/Reverse)
Rail configuration selector (2-rail/3-rail)
Real-time status display
Persistent settings (saved to ESP32 NVS)

Safety Features

Automatic power-off when switching between DCC and Analog modes
Emergency stop via power button
Configuration persistence across reboots

🔧 Hardware Requirements

Main Components

ESP32-2432S028R Module (ESP32 with built-in ILI9341 touchscreen)
Motor Driver (LM18200, L298N, or similar)
DCC Booster Circuit (for DCC mode)
Relay Module (5V single-channel for 2-rail/3-rail switching)
Power Supply: Suitable for your locomotive scale (typically 12-18V)
Model locomotive (DC or DCC compatible)

ESP32-2432S028R Module Specifications

MCU: ESP32-WROOM-32
Display: 2.8" ILI9341 TFT (320x240)
Touch: XPT2046 Resistive Touch Controller
Built-in: USB-C, MicroSD slot, RGB LED

Pin Connections

See WIRING_ESP32-2432S028R.md for complete wiring diagrams and connection details.

Quick Pin Reference

Function	ESP32 GPIO	Connected To
PWM/DCC_A	18	LM18200 PWM Input (dual purpose)
DIR/DCC_B	19	LM18200 DIR Input (dual purpose)
Motor Brake	23	LM18200 Brake Input
Relay Control	4	Relay Module Signal
TFT/Touch	2,12-15,21,22	Built-in (no wiring needed)

📦 Software Setup

Prerequisites

Installation Steps

Clone or download this project

git clone <repository-url>
cd DCC-Bench

Open in VS Code
- Open VS Code
- File → Open Folder → Select DCC-Bench folder
Install Dependencies
- PlatformIO will automatically download required libraries:
  - TFT_eSPI (Display driver)
  - XPT2046_Touchscreen (Touch controller)
  - ArduinoJson (Configuration)
  - DCCpp (DCC protocol)
Build the project
```
pio run
```
Upload to ESP32-2432S028R
```
pio run --target upload
```
Monitor Serial Output (optional)
```
pio device monitor
```
- Default baud rate: 115200

🎮 Usage

First Power-On

Connect USB-C cable to ESP32-2432S028R
Display initializes - you should see the touchscreen UI
Default state:
- Power: OFF
- Mode: DC Analog
- Rails: 2-Rail
- Speed: 0%

Basic Operation

Power Control

Tap [POWER] button to toggle power ON/OFF
Green = ON, Red = OFF
Power must be ON for motor/DCC output

Mode Selection

Tap [MODE] button to switch between DCC and DC Analog
⚠️ IMPORTANT: Power automatically turns OFF when changing modes
Cyan = DCC mode, Yellow = DC Analog mode

Rail Configuration

Tap [RAILS] button to switch between 2-Rail and 3-Rail
Relay activates in 3-Rail mode
Can be changed while power is on

Speed Control

Use the horizontal slider to adjust speed (0-100%)
Drag the white knob or tap anywhere on the slider
Real-time speed updates to motor/DCC controller

Direction Control

Tap [DIR] button to toggle Forward/Reverse
FWD = Forward, REV = Reverse
Changes immediately if power is on

Status Bar

The bottom status bar shows:

Current power state
Active mode (DCC/DC)
Rail configuration (2-Rail/3-Rail)
DCC address (if in DCC mode)
Current speed and direction

⚙️ Configuration

Settings Persistence

All settings are automatically saved to ESP32's Non-Volatile Storage (NVS):

Power state
Mode selection (DCC/Analog)
Rail configuration (2-rail/3-rail)
Speed value
Direction
DCC address
DCC functions

Settings persist across power cycles and reboots.

DCC Address Configuration

To change the DCC locomotive address:

Edit src/main.cpp or add a UI element
Default address is 3 (configurable in code)
Supports addresses 1-10239 (short and long addresses)

Touch Calibration

If touch response is inaccurate, adjust calibration in include/TouchscreenUI.h:

#define TS_MIN_X 200    // Adjust if needed
#define TS_MAX_X 3700   // Adjust if needed
#define TS_MIN_Y 200    // Adjust if needed
#define TS_MAX_Y 3750   // Adjust if needed

📝 Pin Customization

To change pin assignments, edit these files:

Motor Controller Pins

Edit include/MotorController.h:

#define MOTOR_PWM_PIN 18      // PWM speed control
#define MOTOR_DIR_PIN 19      // Direction control
#define MOTOR_BRAKE_PIN 23    // Brake control

DCC Output Pins

Edit include/DCCGenerator.h:

#define DCC_PIN_A 17    // DCC Signal A
#define DCC_PIN_B 16    // DCC Signal B (inverted)

Relay Control Pin

Edit include/RelayController.h:

#define RELAY_PIN 4    // 2-rail/3-rail relay control

📚 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/
## 📂 Project Structure

DCC-Bench/ ├── platformio.ini # PlatformIO configuration (ESP32-2432S028R) ├── README.md # This file ├── ESP32-2432S028R_MIGRATION.md # Migration details ├── WIRING_ESP32-2432S028R.md # Wiring guide ├── include/ # Header files │ ├── Config.h # Configuration management (NVS) │ ├── MotorController.h # DC motor control │ ├── DCCGenerator.h # DCC signal generation │ ├── RelayController.h # 2-rail/3-rail relay control │ └── TouchscreenUI.h # Touchscreen interface └── src/ # Source files ├── main.cpp # Main application ├── Config.cpp # Configuration implementation ├── MotorController.cpp # Motor control implementation ├── DCCGenerator.cpp # DCC implementation ├── RelayController.cpp # Relay control implementation └── TouchscreenUI.cpp # UI implementation


## 🔧 Troubleshooting

### Display Issues
- **Blank screen**: Check USB power connection, verify 5V supply
- **Touch not responding**: Adjust touch calibration values in `TouchscreenUI.h`
- **Inverted display**: Change rotation in `TouchscreenUI::begin()`
- **Wrong colors**: Verify ILI9341 driver configuration in `platformio.ini`

### Motor Not Running (DC Mode)
- Verify mode is set to "DC Analog" (yellow button)
- Check power is ON (green button)
- Verify motor controller connections
- Check pin assignments match your wiring
- Use serial monitor to verify commands

### DCC Not Working
- Verify mode is set to "DCC" (cyan button)
- Check power is ON
- Verify DCC booster is connected and powered
- Check DCC signal with oscilloscope (GPIO 17, 16)
- Verify DCC address matches your locomotive
- 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


### Relay Not Switching
- Check relay module power (5V and GND)
- Verify GPIO 4 connection to relay signal pin
- Listen for relay click when toggling 2-rail/3-rail
- Test relay with multimeter (continuity test)

### Settings Not Saving
- Check serial monitor for NVS errors
- Try factory reset (clear NVS partition)
- Verify ESP32 flash has NVS partition

### Serial Monitor Shows Errors
- Check all #include statements resolved
- Verify all libraries installed via PlatformIO
- Check for pin conflicts
- Review error messages for specific issues

## 📋 Technical Specifications

### Software
- **Platform**: PlatformIO with Arduino framework
- **Libraries**:
  - TFT_eSPI (Display driver)
  - XPT2046_Touchscreen (Touch controller)
  - ArduinoJson (Configuration)
  - DCCpp (DCC protocol from Locoduino)
- **Storage**: ESP32 NVS (Non-Volatile Storage)

### Hardware Limits
- **PWM Frequency**: 20kHz (motor control)
- **DCC Timing**: NMRA standard compliant
- **Touch**: Resistive (pressure-sensitive)
- **Display**: 320x240 pixels, 65K colors

## 🤝 Support & Contributing

For issues, questions, or contributions:
- Check serial monitor output for debugging (115200 baud)
- Verify hardware connections match pin assignments
- Review **[WIRING_ESP32-2432S028R.md](WIRING_ESP32-2432S028R.md)**
- Check **[ESP32-2432S028R_MIGRATION.md](ESP32-2432S028R_MIGRATION.md)** for migration details
- Test with known-good locomotive

## 📄 License

This project is open source. Check repository for license details.

---

**Version**: 2.0 (ESP32-2432S028R Edition)  
**Last Updated**: December 2025  
**Compatible Hardware**: ESP32-2432S028R (ESP32 with ILI9341 touchscreen)  
**Framework**: Arduino for ESP32 via PlatformIO

12 KiB Raw Blame History