Help & guides

If you've just been invited to beta-test the RoadEye Android app, the full step-by-step guide lives at /help/beta-tester. Covers uninstalling any prior build, installing the new APK from /install/apk, signing in with the demo access code (TRYME001), the 7-step onboarding, running a Test Survey Mode drive, trying each of the five detection providers (especially the new "On-device YOLO26n, BETA" option), cross-checking results on this web dashboard, and how to use Field diagnostics to report issues. Also lists known issues and what's deliberately not in this build so you don't waste time reporting them.

RoadEye is an open road-asset inventory and condition platform for UK local authorities. Inspectors capture road imagery and GPS routes from a phone mounted in a survey vehicle; the platform processes that data, surfaces detections to inspectors and managers, and produces PAS 2161-style reports. The simplest end-to-end flow is: install the mobile APK from /install → sign in with your access code → press Start Drive → drive a route → press Stop Drive → review detections in /admin/qa → approve or send for field check → export from /reports.

Mount the phone on the dashboard before driving — never operate the app while moving. After sign-in, tap the Drive tab, watch the pre-flight checklist (camera, GPS, network, battery) turn green, then press Start. The status strip at the top shows live GPS lock, online state, and pending sync count. The app records 30-second MP4 segments and 1 Hz GPS points; both upload automatically when on Wi-Fi. If you lose network mid-drive everything is buffered locally and drains when you reconnect. Press Pause to stop capture without ending the drive; Stop closes the drive and triggers final upload. Field test mode (Settings → Field test mode) shows live counters useful for indoor testing.

The map at / shows every captured detection clustered by location. Use the Detection filters panel to scope by class, provider, QA status, segmentation status, confidence range, severity range, and survey. Six quick presets jump to common views: Critical defects, Needs review, Field check, YOLO26 only, Low confidence, Latest survey. Click a marker to open the asset detail panel. From there you can flip its QA status, mark for field check, or open it on the QA review page. Routes recorded from mobile drives appear as polylines in the same view.

/admin/qa lists detections needing a human eye, sorted by severity (highest first) then confidence (lowest first). Each row has Approve, Reject, and Edit buttons; bulk actions appear when rows are selected. The Edit panel shows a mask preview (real EdgeSAM mask, or a placeholder rectangle if segmentation is unavailable) plus the original class and severity, both editable. Use "Field check" when an in-office decision isn't safe — the row routes to the field-check work queue for an inspector to verify on-site.

/reports generates CSV, GeoJSON, and HMDIF-subset exports of the asset inventory, filtered by class and date range. Exports happen entirely in your browser — no server round-trip. The PAS 2161 tab (/reports/pas2161) adds a readiness checklist plus a PAS-style export with explicit warnings where required fields are absent or approximated. AI-generated detections are flagged in every export so downstream consumers know which rows need QA before operational use.

PAS 2161 is the UK Publicly Available Specification for road condition monitoring data. It defines collection methods, processing rules, file formats (HMDIF), validation requirements, and consistency criteria so different authorities can compare data. RoadEye is PAS 2161-style, NOT certified compliant: the readiness checklist on /reports/pas2161 transparently shows which fields and processes are present (network sections, survey sessions, condition categories, validation marks, coverage, QA status) and which are gaps (chainage / linear referencing, road class, formal validation pipeline). Outputs are clearly labelled draft / reviewed / approved.

RoadEye uses YOLOv8 / YOLO26 family models for detection (server-side via the detect-frame Edge Function, or on-device via bundled ONNX). Optional EdgeSAM/SAM segmentation refinement adds masks for shape-relevant classes (potholes, cracks, drainage). Every detection row carries: confidence score (0-1), provider id (yolo26-ultralytics-direct / yolov8n-pothole-hf-v1 / mock-v1 / etc), confidence threshold at the time of capture, segmentation status (completed / failed / unavailable / not_requested), and QA status. Treat unreviewed AI rows as advisory, not authoritative — always pass through the QA workflow before formal use.

On the mobile app, Settings → Field test mode opens a full-screen diagnostic view: survey ID, route point count, frames captured/uploaded/pending, detection count, upload failures, GPS lock duration, plus the last 50 in-app log events. The Share button packages the snapshot as text for support requests. Test detect now POSTs a synthetic frame to the deployed detect-frame Edge Function so you can verify the mobile→server inference path without driving. Clear local test data wipes the SQLite pending buffer for a clean test re-run (does not affect already-uploaded data).

Camera prompt hangs at "Requesting…" → uninstall + reinstall the latest APK; the v15 expo-camera permission API was misnamed in earlier builds. GPS stuck at "Waiting for first GPS fix" → the watcher tries High accuracy first (satellite), downgrades to Balanced (Wi-Fi/cell) after 10s. Move outdoors for satellite-grade fix. Detections not appearing on map → check /admin/diagnostics first (DB / Auth / Storage healthcheck), then /admin/ai-monitoring for failed jobs. Sign-up creates account but app shows "you don't have access" → race condition fixed in commit f393ac7; useProfile now polls for the webhook-created profile row up to 12s. New user truly missing a profile after that → check the 30-user cap, then promote from /admin/users.

Confidence: model's self-reported certainty (0-1) for a detection. Severity: 1 (low) through 5 (urgent). QA status: auto_detected (fresh from AI) / needs_review (queued for triage) / approved / rejected / needs_field_check (requires on-site visit). Segmentation status: not_requested (bbox only) / completed (real mask) / failed / unavailable (rectangle placeholder). Fallback used: primary detection backend errored, secondary backend ran instead. PAS 2161: UK Publicly Available Specification for road condition monitoring data exchange. HMDIF: Highway Management Data Interchange Format, the file format PAS 2161 references. Coverage: kilometres of network surveyed (denominator depends on whether a baseline network is loaded — currently we report drive-distance only).

Still stuck?

Open /admin/diagnostics for live infrastructure health, or share your mobile field diagnostics export. Source code: github.com/myroadsnow/roadeye.