deployed-sign-map/README.md

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:

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.

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.