439 lines
12 KiB
Markdown
439 lines
12 KiB
Markdown
# 🚂 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
|
|
- [Visual Studio Code](https://code.visualstudio.com/)
|
|
- [PlatformIO IDE Extension](https://platformio.org/install/ide?install=vscode)
|
|
|
|
### Installation Steps
|
|
|
|
1. **Clone or download this project**
|
|
```bash
|
|
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**
|
|
```bash
|
|
cd data
|
|
chmod +x download_bootstrap.sh
|
|
./download_bootstrap.sh
|
|
```
|
|
|
|
Or download manually:
|
|
- [Bootstrap CSS](https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css) → `data/css/bootstrap.min.css`
|
|
- [Bootstrap JS](https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js) → `data/js/bootstrap.bundle.min.js`
|
|
|
|
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`:
|
|
```cpp
|
|
#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`:
|
|
```cpp
|
|
#define DCC_PIN_A 32 // Change as needed
|
|
#define DCC_PIN_B 33 // Change as needed
|
|
```
|
|
|
|
### LED Indicator Pins
|
|
Edit `include/LEDIndicator.h`:
|
|
```cpp
|
|
#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
|
|
|
|
```bash
|
|
# 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
|
|
```json
|
|
{
|
|
"mode": "dcc",
|
|
"speed": 50,
|
|
"direction": 1,
|
|
"dccAddress": 3,
|
|
"ip": "192.168.4.1",
|
|
"wifiMode": "ap"
|
|
}
|
|
```
|
|
|
|
#### POST /api/mode
|
|
Set control mode
|
|
```json
|
|
{"mode": "dcc"} // or "analog"
|
|
```
|
|
|
|
#### POST /api/speed
|
|
Set speed and direction
|
|
```json
|
|
{"speed": 75, "direction": 1}
|
|
```
|
|
|
|
#### POST /api/dcc/address
|
|
Set DCC locomotive address
|
|
```json
|
|
{"address": 1234}
|
|
```
|
|
|
|
#### POST /api/dcc/function
|
|
Control DCC function
|
|
```json
|
|
{"function": 0, "state": true}
|
|
```
|
|
|
|
#### POST /api/wifi
|
|
Configure WiFi (triggers restart)
|
|
```json
|
|
{
|
|
"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
|