Bottom HAT

train-controller

A Raspberry Pi–based model train controller. Automatically runs a train between two platforms, handling acceleration/deceleration, platform stopping, track switching, and safety cutoffs — with a web dashboard for monitoring and manual control.

Hardware

• Raspberry Pi 2B
• Two custom PCBs for level-shifting and motor drive:
  • Bottom Hat: 3.3V → 5V level shifting (BC337 transistors), with a hardware SR-latch overcurrent safety circuit
  • Top Hat: 5V → 12V level shifting into an IRF4905 P-channel MOSFET, driving the motor directly
• Sensors for slow-zone detection and platform stop detection (Platform A / B)
• A stepper-driven (or relay-driven) track switch between the two platforms
• MCP3008 ADC for current monitoring (via SPI)
• QR code scanner for per-train identification

Software Overview

The controller runs as a single Python script, integrated_train_controller_23_debug_boost_2.py, using pigpio for hardware PWM. Key behaviors:

• Automatic operation loop: accelerate → run at full speed → slow on approach → stop at platform → switch track → repeat
• Per-train speed profiles stored in a local SQLite database (trains.db), selected via QR code scan
• Emergency stop and graceful shutdown, both with double-press detection to avoid accidental triggers
• A Flask web dashboard (served directly from the script, no separate template files) for live status, speed control, and emergency stop

See TRAIN_CONTROLLER_DOCUMENTATION.md for full details on constants, GPIO wiring, and the operational workflow.

New to Git? See GIT_WORKFLOW_GUIDE.md for the commands and workflow used to maintain this repository.

Running It

1. Install dependencies on the Raspberry Pi (pigpio, Flask, spidev, etc. — see imports at the top of the script)
2. Ensure the pigpio daemon is running: sudo pigpiod
3. Run the script: python3 integrated_train_controller_23_debug_boost_2.py
4. Open the dashboard in a browser on the same network: http://<pi-ip-address>:5000

Status

Actively developed and bench-tested incrementally. Current focus: validating max_slow_speed against the motor's conduction threshold on the rebuilt two-PCB hardware.