137 lines
9.2 KiB
Markdown
137 lines
9.2 KiB
Markdown
# Deployed Sign Map
|
||
|
||
Map deployed transit signs and kiosks against verified GTFS stops and routes, with player health and phone navigation.
|
||
|
||
**CoWork project:** CW-033 — Deployed Sign Map
|
||
**Version:** 0.1.0
|
||
**Type / status:** Tool / Beta prototype
|
||
**Owner:** Bryan Gilliom
|
||
**Contributor:** Codex
|
||
**Updated:** October 28, 2026
|
||
**Git repository:** https://git2.mpm.to/mpm/deployed-sign-map
|
||
|
||
## Overview
|
||
|
||
This working prototype combines a read-only OnSign player snapshot, an official public GTFS feed, and a native CAD/AVL stop-ID crosswalk. It supports service technicians, salespeople, and implementation teams who need to see deployed devices alongside their stops and scheduled routes. It preserves the difference between a bus-stop coordinate and the surveyed location of a physical sign. It does not modify OnSign or the CAD/AVL system.
|
||
|
||
The captured RTC Washoe pilot is complete as a snapshot. Conversion into an installable skill or plugin, live refresh, and other-agency support remain future work. There is no SKILL.md, plugin manifest, or new MCP server in this package.
|
||
|
||
## Capabilities and planned skill entry points
|
||
|
||
| Capability | Current behavior | Potential trigger |
|
||
|---|---|---|
|
||
| Deployment map | Shows field signs and kiosks with online/offline icons and excluded test/showroom records | “Map the deployed signs for this agency” |
|
||
| Native stop crosswalk | Resolves each OnSign `-S` ID through native `SrcStopID` to GTFS `stop_id`; retains comma-separated kiosk IDs individually | “Crosswalk the player stop IDs to GTFS” |
|
||
| Route geometry | Joins resolved stops to active GTFS trips; renders ordered shapes using `route_color` | “Show the routes serving these signs” |
|
||
| Service navigation | Provides Apple Maps and Google Maps driving links using GTFS coordinates | “Navigate to this stop” |
|
||
| Quiet basemaps | CARTO Positron vector, labels or no labels; hidden POIs; Esri gray, original streets, and plain background | “Use a quieter basemap” |
|
||
| Predeployment planning | Not built; planned spreadsheet/list intake with the same reconciliation rules | “Map these planned stop installations” |
|
||
|
||
These are prototype capabilities and proposed skill triggers, not already installed tools.
|
||
|
||
## Contents
|
||
|
||
- `source/`: Python preparation, read-only native API fetch, renderer, integrity checks, HTML template, and pinned third-party map libraries.
|
||
- `sample-work/rtc-washoe/`: credential-free HTML map, source snapshots, public GTFS ZIP, resolved crosswalk, verification results, and PNG previews. Keep operational sample data in Coordination Drive, not in the public Git repository.
|
||
- `HANDOFF-BRIEF.md`: accepted decisions, evidence, open work, and exact continuation steps.
|
||
- `Wiki V2.md`: source for the native Google Docs wiki.
|
||
- `file-manifest.json`: file sizes and SHA-256 values for the archived package.
|
||
|
||
## Tools and interfaces used
|
||
|
||
| System | Read operations used in this work |
|
||
|---|---|
|
||
| Existing OnSign MCP (CW-032) | `find_players`, `account_summary`, `get_player`; investigation also used `get_data_feed` and `whats_playing` |
|
||
| Native Vontas traveler API | `GetStop`; `GetStopRouteTrip` was used to establish stop/trip identifier evidence; `?WSDL` exposed the read operation schema |
|
||
| Public GTFS | `feed_info`, `calendar`, `calendar_dates`, `stops`, `stop_times`, `trips`, `routes`, `shapes` |
|
||
| Browser map | Leaflet 1.9.4, MapLibre GL JS 5.6.2, MapLibre–Leaflet integration 0.1.3 |
|
||
|
||
## Reproduce the captured snapshot
|
||
|
||
Python 3 is sufficient for the data scripts. Third-party map libraries and their license notices are included under `source/vendor/`.
|
||
|
||
From the package root, with the source and sample-work archives extracted into sibling directories:
|
||
|
||
```bash
|
||
python3 source/scripts/prepare_data.py \
|
||
--players sample-work/rtc-washoe/onsign-players.json \
|
||
--native sample-work/rtc-washoe/native-stops.json \
|
||
--gtfs sample-work/rtc-washoe/rtc-gtfs.zip \
|
||
--service-date 2026-10-28 \
|
||
--output-dir dist
|
||
|
||
python3 source/scripts/verify_snapshot.py \
|
||
--data dist/rtc-map-data.json \
|
||
--native sample-work/rtc-washoe/native-stops.json \
|
||
--gtfs sample-work/rtc-washoe/rtc-gtfs.zip
|
||
|
||
python3 source/scripts/render_map.py \
|
||
--data dist/rtc-map-data.json \
|
||
--output dist/rtc-washoe-sign-map.html
|
||
|
||
python3 -m http.server 8765 --bind 127.0.0.1
|
||
```
|
||
|
||
Open `http://127.0.0.1:8765/dist/rtc-washoe-sign-map.html`. The archive contains no API key. It defaults to Esri Gray Canvas; selecting a CARTO style asks for a basemap key held in that tab only. Rendering with `--include-carto-key` explicitly embeds `RTC_CARTO_BASEMAP_KEY`; use that only for an approved browser-key distribution.
|
||
|
||
The snapshot feed covers September 5, 2026–January 1, 2027. Replaying the captured date is intentional. A live rebuild requires a newly downloaded official feed, a fresh OnSign snapshot, and fresh native responses; do not present this capture as current health.
|
||
|
||
### Read native stops for a new snapshot
|
||
|
||
Set `RTC_NATIVE_API_BASE` to the approved HTTPS ASMX service URL and `RTC_NATIVE_API_KEY` through a secure local environment. Do not put credentials in a command, Git file, report, or handoff.
|
||
|
||
```bash
|
||
python3 source/scripts/fetch_native_stops.py \
|
||
--players input/onsign-players.json \
|
||
--output input/native-stops.json
|
||
```
|
||
|
||
The script calls only `GetStop`, validates the returned `StopID`, stores credential-free responses, throttles requests, and exits with an error if any requested ID fails. It does not fetch player records itself; the host must supply the existing OnSign MCP export.
|
||
|
||
### Setup checklist
|
||
|
||
- [ ] Extract source and private sample-work packages into the expected directory structure.
|
||
- [ ] Use Python 3 and a browser with WebGL for vector basemaps.
|
||
- [ ] Run preparation and integrity verification before rendering.
|
||
- [ ] Choose an approved CARTO basemap key or a key-free alternative.
|
||
- [ ] Preserve attribution for CARTO/OpenStreetMap or Esri and the bundled library notices.
|
||
- [ ] For live work, refresh inputs and label the OnSign/native/feed timestamps separately.
|
||
|
||
## Connection and credential model
|
||
|
||
| Field | Behavior |
|
||
|---|---|
|
||
| OnSign | Existing account-scoped, read-only MCP; no new direct OnSign API key is required by this tool |
|
||
| Native stop API | HTTPS GET; key stays in the acquisition process; authenticated URLs are not printed |
|
||
| Basemaps | Online CARTO vector service uses a browser basemap key; Esri/OSM raster and plain alternatives are available |
|
||
| Map data | Stops, routes, shapes, crosswalk, and player health are embedded as a captured snapshot |
|
||
| Remote writes | None to OnSign or native CAD/AVL |
|
||
|
||
## Workflow rules
|
||
|
||
1. Verify the agency's current official feed and service-date coverage before matching stops.
|
||
2. Extract native `-S` IDs, including each comma-separated kiosk ID. Preserve excluded records without inventing positions.
|
||
3. Use the native API's explicit `SrcStopID` crosswalk. Never assume a numeric native stop ID equals GTFS `stop_id`.
|
||
4. Use GTFS latitude/longitude for all markers and navigation. OnSign GPS, manually placed positions, and IP geolocation are not coordinate authority.
|
||
5. Derive route associations from resolved stop IDs, `stop_times`, and active `trips`; derive line geometry from ordered `shapes`. Never infer a route from a nearby line or equate native and GTFS route IDs.
|
||
6. For kiosks, use a clearly labeled parent-station anchor; derive routes from the resolved bay list, not every bay at the station.
|
||
7. Report ID failures, name conflicts, and native-versus-GTFS coordinate differences separately. The current 25 m flag is a review threshold, not a measured GPS accuracy claim.
|
||
8. Preserve keys outside published maps by default. Maintain private customer snapshots separately from public code.
|
||
|
||
## Known limits and troubleshooting
|
||
|
||
| Symptom / limit | Action |
|
||
|---|---|
|
||
| Source-stop ID is missing from current GTFS | Stop the build and obtain an agency crosswalk; do not guess coordinates |
|
||
| Kiosk bays do not share one GTFS parent station | Require explicit review; the current prototype stops rather than selecting an arbitrary anchor |
|
||
| CARTO background is missing | Check basemap key, connectivity, WebGL, and attribution; choose Esri or plain background |
|
||
| Feed has expired | Download the official current feed for a live rebuild; use the captured service date only to replay this sample |
|
||
| Source template has RTC-specific dates and copy | Generalize these before using another agency; current data scripts expose a service-date argument but the UI is still a pilot template |
|
||
| Rapid basemap switching logs an abort | A removed vector map can cancel an outstanding request; verify the selected basemap finishes loading |
|
||
| Phone navigation | Links and destinations were verified in the browser; physical iPhone/Android launch was not tested |
|
||
| Live device health / detours / arrivals | Not implemented; captured health and static scheduled service only |
|
||
|
||
## Requirements and licenses
|
||
|
||
Python 3 standard library; Leaflet 1.9.4; MapLibre GL JS 5.6.2; MapLibre–Leaflet integration 0.1.3; optional CARTO basemap access; authorized existing OnSign MCP and native API access for acquisition. Bundled upstream licenses are in `source/vendor/`. No redistribution license has been selected for MPM-authored source; creating a public repository does not by itself grant an open-source license.
|