TTC Map

TTC Map

A Toronto rail explorer and ESP32 LED display built around one transit-state API. The web map shows Lines 1, 2, 4, 5 and 6 over OpenStreetMap, with route search, station details, directional markers and a schematic view.

The project implements GTFS import and validation, bounded NTAS polling, estimated train positions, a shared web/LED state model, the browser interface and firmware for an eight-LED board revision. Contributor history is available in Git; individual ownership and asset permissions are documented in docs/ASSETS.md.

The image records a real-data session on September 12, 2026; it is not a live feed.

Toronto Open Data GTFS -> validated SQLite schedules/topology --+
TTC NTAS countdowns -> per-line snapshots and interpolation ----+-> map state
                                                               |-> web explorer
                                                               +-> ESP32 LED frame

Python/FastAPI serves the vanilla JavaScript/SVG frontend. SQLite, pandas and HTTPX handle data; ESP-IDF/PlatformIO builds the firmware. There is no frontend build step and no Node server.

What the map means

• Filled arrows are NTAS-backed estimates; outlined arrows are scheduled estimates. Neither is GPS. Routes connect station coordinates approximately, not surveyed tracks.
• Lines 1/2/4 use NTAS when healthy. Line 5 is scheduled unless explicitly enabled after coverage validation; Line 6 is schedule-only.
• Direction follows API travel order. Unknown direction uses a neutral marker.
• Departures are scheduled, within a two-minute line-wide window capped at 200 rows. Service alerts, live station arrival boards and journey planning are unavailable.
• Data health does not imply normal TTC operations. Failed state requests clear train markers; a missing street background leaves the transit overlay usable.

Run on Windows

Install uv, clone this repository, then double-click start.bat or run it from PowerShell:

.\start.bat

The launcher installs the locked dependencies and starts the server. It keeps Python packages in %LOCALAPPDATA%\TTC-Map\venv, outside OneDrive. Python 3.13 is selected by .python-version; uv can download it if needed. Do not repair or reuse an old OneDrive-managed .venv to run this launcher.

Open http://localhost:8000 for the map, /search/ for timetable search, and /docs or /redoc for the local interactive API reference. Stop with Ctrl+C. For another port: .\start.bat serve --port 8001.

Windows setup and clean-checkout verification includes manual commands, separate-checkout environments and offline rehearsal.

macOS / Linux

Install uv, then open a terminal in this repository and run:

./start.command

On macOS you can also double-click start.command. The launcher installs the locked dependencies into .venv and starts the server. Open http://localhost:8000 and stop with Ctrl+C. Use ./start.command serve --port 8001 for another port or ./start.command refresh for a feed check. If an extracted archive loses executable permissions, run bash start.command.

Equivalent manual commands:

uv sync --locked
uv run --no-sync ttcmap serve

Python 3.12+ is supported by the package; the repository pins 3.13 for development. Use one worker and a local SQLite database. Linux startup has been checked under Ubuntu 24.04 (WSL2); macOS runtime and physical hardware validation remain separate checks. See setup verification.

Commands

Run these after the platform-specific setup. On Windows, set $env:UV_PROJECT_ENVIRONMENT = "$env:LOCALAPPDATA\TTC-Map\venv" first, or use .\start.bat refresh for a feed check.

Browser tests use a pinned optional Playwright install; see SETUP.md. There is no separate JavaScript build, type-checker or linter configured.

API and structure

The local API reference reads /openapi.json and can send GET requests without external scripts. All transit routes are below /api/v1:

Refresh is CLI-only. The former POST /api/v1/gtfs/refresh is removed so a viewer cannot trigger an expensive rebuild. The web refresh button reloads read endpoints.

Run from an editable repository checkout. A standalone wheel does not include the web/shared/hardware resources and is not a supported deployment package.

Configuration and troubleshooting

Copy .env.example to .env for optional overrides; all fields are in src/ttcmap/config.py. Local paths resolve against the checkout. For OneDrive installations that also need database isolation, configure DATA_DIR and DB_PATH to local storage. Cloud synchronization is not multi-host database coordination.

• Port occupied: use another port with the launcher/CLI.
• Transit data unavailable: check /api/v1/health and refresh logs. First import, expired schedules or a failed upgrade can cause 503 responses.
• Scheduled labels: live observations may be unavailable or disabled for that line.
• Street map unavailable: use the schematic; OSM tiles are an external service.
• Firmware connection: follow ESP32_SMOKE_TEST.md. The eight-LED revision does not represent a fully wired station network.

See ARCHITECTURE.md, UI_API_AUDIT.md, validation results and asset/publication status.