RailwayController

RailwayController is an educational research project for a locally hosted ESP32 railway controller with a Progressive Web App interface.

The current design direction is now a custom PWA-controlled DC-only railway controller. DCC planning has been removed because reliable DCC packet generation, booster behaviour, programming support, and Wi-Fi-hosted control add too much complexity for the intended ESP32 educational build.

This revised architecture deliberately retains only:

• the AC toroidal transformer;
• the ESP32 WROOM DevKit 1 board;
• the buck-converter approach for logic power.

Everything else is open to redesign around a reliable analogue DC controller.

Current Goal

The goal is to make a locally hosted, installable PWA that controls a conventional two-rail DC model railway through an ESP32 and a protected H-bridge output stage.

The controller should provide:

• variable speed and direction for analogue DC locomotives;
• an 18-20 V unloaded motor bus for headroom, with normal track output capped to about 12 V effective by measured-bus PWM limiting;
• safe stop, ramping, current limiting, and short-circuit handling;
• visible power, Wi-Fi, track enabled, and fault status;
• a local web app that works on phone, tablet, and desktop without cloud services;
• hardware behaviour that remains safe during Wi-Fi loss, browser reload, ESP32 reset, brownout, and firmware faults.

This repository is still in research and architecture. The documents are not build instructions and should not be treated as certified electronics guidance.

Key Documents

• PWA-controlled DC components list
• PWA-controlled DC circuit and logic flow
• Existing KiCad schematic scaffold notes
• Previous KiCad schematic specification

The KiCad material still reflects the older four-channel analogue scaffold and should be considered historical until it is deliberately redesigned for the new simplified DC architecture.

DCC Decision

DCC is explicitly out of scope for this hardware planning pass.

Reasoning:

• DCC waveform timing is protocol-critical and would need deterministic peripheral scheduling while the ESP32 is also serving Wi-Fi and a PWA.
• DCC track power is continuous and raises the consequences of shorts, wrong-mode use, and decoder/analogue-locomotive mistakes.
• DCC programming mode needs a separate current-limited service path and acknowledgement-current detection.
• A robust DCC command station is a different project from a safe educational DC controller.

The project may still leave mechanical and software room for a future external DCC system, but this controller should not attempt to generate DCC packets or claim DCC compatibility.

Deep-Dive Design Analysis

What The Device Must Do

The controller needs three firm operating states:

• Off/safe: no track energy, driver disabled, re-enable requires checks.
• DC enabled: H-bridge output provides controlled polarity and PWM duty for analogue speed/direction.
• Fault latched: output disabled after over-current, driver fault, brownout, watchdog failure, or emergency stop until deliberate user acknowledgement.

Unlike the previous switchable idea, there is no DC/DCC mode transition to manage. That simplification is important: every software path can be optimised for one output behaviour, one locomotive compatibility model, and one safety envelope.

Recommended First Hardware Shape

The most credible first prototype is:

• one protected DC track output;
• one ESP32-hosted PWA throttle;
• optional physical emergency stop and track-enable switch;
• one H-bridge driver with current sense and fault reporting;
• one hardware enable gate that defaults off;
• voltage and current telemetry for diagnostics;
• fusing, TVS protection, inrush control, proper terminals, and a safe enclosure.

Additional outputs can be added after one channel is proven with dummy loads and real locomotives.

Proposed Hardware Blocks

AC toroidal transformer
    -> secondary fuse
    -> low-voltage power switch
    -> inrush limiter / pre-charge
    -> bridge rectifier
    -> ripple-rated DC bus capacitor bank
    -> TVS clamp and bleed resistor
    -> protected H-bridge
    -> track output

DC bus
    -> buck converters
    -> ESP32 WROOM DevKit 1
    -> PWA host, command API, DC state machine, telemetry

Track current
    -> H-bridge current sense / comparator
    -> hardware gate or driver disable
    -> ESP32 telemetry
    -> PWA and panel fault indication

The H-bridge is the central engineering choice. It should be a protected brushed-DC motor driver or carrier with current feedback, fault output, thermal shutdown, and enough current margin for the intended OO-gauge locomotives.

The motor-power design target is an unloaded rectified bus of about 18-20 V DC, not an uncontrolled 18-20 V track output. Firmware should measure the bus and cap PWM so the normal profile delivers about 12 V effective at full throttle. A separate old-locomotive profile may permit a modest higher effective cap only with stricter current, thermal, and ramp limits.

Proposed Software Flow

boot
    -> keep track output disabled
    -> configure GPIO safe/inactive
    -> validate stored configuration
    -> start Wi-Fi or setup AP
    -> serve PWA and local API
    -> wait for deliberate track enable

PWA command
    -> validate requested speed/direction
    -> apply locomotive profile limits
    -> apply measured-bus duty cap, normally 12 V effective maximum
    -> update authoritative ESP32 state
    -> ramp actual PWM toward target
    -> confirm state back to browser

fault
    -> hardware/driver disables output first
    -> ESP32 records and latches fault
    -> PWA/panel shows fault
    -> user clears cause and acknowledges
    -> controller returns to off/safe before re-arm

The ESP32 owns the controller state. The PWA is a control surface, not the safety authority.

Similarities And Differences

Area	Previous four-channel design	New simplified DC design
Reused parts	ESP32, transformer, buck regulators, four analogue channels, physical throttles	Only ESP32 WROOM DevKit 1, AC toroidal transformer, and buck converters are guaranteed retained
Main output	Four independent analogue DC/PWM channels	Start with one robust DC output, then scale only after validation
User model	Physical centre-biased throttles plus PWA arbitration	PWA-first throttle with physical safety controls
Track signal	Variable effective DC voltage and polarity	Same fundamental DC/PWM behaviour, but simplified to one validated architecture
Timing difficulty	Moderate	Moderate; no DCC packet timing burden
Safety emphasis	Per-channel short/stall protection	One carefully validated protection chain before replication
Locomotive support	Analogue DC locomotives	Analogue DC locomotives only
Scaling strategy	Four channels from the start	Prove one output first; repeat the proven channel later

Feasibility Analysis

The DC-only controller is much more feasible than the switchable DC/DCC concept.

The realistic verdict:

• A single-output ESP32/PWA DC controller is feasible.
• A reliable educational build is feasible after bench validation of current limits, thermal behaviour, short-circuit shutdown, and Wi-Fi fault handling.
• A four-output DC controller is feasible later if the single-channel design is repeated with proper per-channel protection and power budgeting.
• DCC generation, programming, and booster behaviour are out of scope for this project phase.

The highest-risk areas are now manageable: motor-driver selection, current limiting, transformer bus voltage, heat, noisy motor wiring, ADC/current telemetry quality, and safe firmware boot states.

Development Phases

Phase 1: Research And Architecture

• Define the one-output DC architecture.
• Select protected H-bridge candidates.
• Confirm all power-path parts tolerate the 18-20 V unloaded bus plus motor transients.
• Define current-trip and output-enable hardware.
• Define PWA command/state model.
• Build a software state-machine model before committing to hardware.

Phase 2: PWA Prototype

• Create installable local PWA shell.
• Add DC throttle screen, stop control, track enable state, fault panel, and telemetry.
• Use simulated controller telemetry before hardware.
• Ensure disconnect/reconnect does not create ambiguous control state.

Phase 3: Firmware Prototype

• Generate DC PWM from ESP32 peripherals.
• Implement direction-change ramp-to-zero behaviour.
• Add watchdog, brownout, and safe boot output states.
• Implement local API/WebSocket state sync.

Phase 4: Bench Electronics

• Measure transformer and rectified bus.
• Validate buck converters.
• Test H-bridge with dummy loads.
• Verify current limiting and short-circuit shutdown.
• Scope PWM output and verify the 12 V effective duty cap before connecting locomotives.

Phase 5: Railway Testing

• Test DC mode with known analogue locomotives.
• Measure running, startup, and stall current.
• Tune PWM frequency, duty caps, ramps, current limits, and any old-locomotive profile.
• Validate derailment, short, Wi-Fi dropout, restart, and emergency-stop behaviour.

Phase 6: Documentation And Release

• Replace provisional values with measured values.
• Publish schematic, BOM, firmware, PWA assets, validation evidence, and safe build notes.
• Keep historical and rejected DCC material clearly separated from the DC build.

References

• Espressif ESP32 Technical Reference Manual
• MDN Progressive Web Apps
• Texas Instruments DRV8876 datasheet
• Texas Instruments DRV8251A product page
• Littelfuse TVS diode guidance
• Littelfuse PolySwitch resettable PPTC devices

Licence

This repository is licensed under the GNU General Public License v3.0. See LICENSE.

Copyright Dr James Rowson, 2026.