Initialisation depot

2025-11-30 09:58:00 +01:00
commit 56d8cd96c8
28 changed files with 3154 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,438 @@
+# 🚂 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