User Guide — dashboard.surfscore.live

End-user walkthrough for the SurfScore Dashboard. Covers signing in, managing plans, running walk tests, monitoring a live fleet, reviewing session history, and reading the heatmap and timeline views.

This guide is for field engineers running walk tests, broadcast / live-ops operators monitoring a fleet during an event, and network engineers / RF planners analyzing coverage — whether they're surveying a venue before going live, reviewing what happened mid-event, or planning future deployments from past data.

Table of Contents

1. Welcome

2. Getting Started

3. Navigating the Dashboard

4. Reporting Bugs & Feedback

5. Feature Flags — What You May Not See

6. Managing Plans

7. Calibrating a Floorplan

8. Placing gNB / eNB Markers

9. Managing Devices

10. Running a Walk Test

11. Live Monitoring (Fleet Monitor)

12. Field Diagnostics

13. Reviewing Session History

14. Detail Timeline

15. Heatmap Replay

16. Reading the Heatmap

17. Understanding SurfScore / URS

18. Friendly Device Names

19. Tips & Troubleshooting

20. Glossary

Welcome

The SurfScore Dashboard supports two core workflows for cellular signal quality, both indoors (against uploaded floorplans) and outdoors (against real-world maps):

• Coverage validation — run a walk test to map cellular signal across a venue, then analyze the result as a Heatmap replay (spatial — where is coverage strong / weak?) or Detail Timeline (temporal — what changed when?). Useful before an event (survey the venue, decide where to position radios), during (verify what was promised matches reality), and after (compare today's coverage against last year's, plan the next deployment).

• Live fleet monitoring — during an active broadcast or event, watch every contributing device's RF metrics, GPS lock state, and at-a-glance health on a per-plan dashboard. Devices feed in from supported devices including SurfScan Connect on Android (indoor / outdoor phones). Monitor session telemetry is persisted, so anything you watch live is also reviewable from History when the session ends.

Both workflows share a single setup step: a plan — either an uploaded indoor floorplan (with a one-time calibration) or an outdoor map area you draw on OpenStreetMap.

Other things you can do from the dashboard:

• Configure data sources — register supported vendor devices for your organization

• Place gNB / eNB markers on indoor floorplans for visual context on radio positions

• Report bugs and feedback from anywhere in the dashboard via the floating bug button

Dashboard Plans Page

Getting Started

Logging in

1. Open the dashboard URL: https://dashboard.surfscore.live

2. Enter your email address and click Continue

3. Check your inbox for a 6-digit code (it arrives within seconds)

4. Enter the code and click Sign in

Login step | enter email

Login | Enter OTP

Note: The dashboard never asks for a password. Each sign-in uses a one-time code (OTP) sent to your registered email. If you don't receive a code within a minute, check your spam folder, or contact your administrator to confirm your account is registered.

Organizations and tenants

Your account belongs to one or more organizations (also called tenants). Each organization has its own private set of plans, devices, and session history — you only see data from organizations you're a member of. The current organization name appears next to the SurfScore wordmark in the header on every page.

If you belong to multiple organizations, switch between them from the user avatar menu in the top-right corner. The active tenant is marked with a green checkmark.

Navigating the Dashboard

Once signed in, you'll land on the Plans page (the home page). The global header runs across the top of every "document" page (Plans, History, Devices):

• SurfScore · Tenant Name — clicking the wordmark returns you home

• Plans · History · Devices — the three primary tabs

• Active Sessions menu — a green radio chip on the right appears only when at least one session in your tenant is currently active. Open it to see every running walk test or monitor session, jump straight into one with Open, or close an orphaned session with End.

• Search (placeholder) — reserved for a future global search

• User avatar — opens the user menu (tenant switcher + Sign Out)

Dashboard with active sessions menu

Active Sessions Popover

Some pages run immersive (no header) because they need every pixel for the canvas — the live session page, floorplan / outdoor-map editors, heatmap replay, and Detail Timeline. Each of those has its own toolbar with a back link.

Page map

Reporting Bugs & Feedback

A small floating 🐞 bug button sits in the bottom-right corner of every page once you're signed in. Use it to report bugs, ask for features, flag suspicious data, or send general feedback — all reports go directly to the SurfScore team in Linear.

Bug report FAB

Submitting a report

1. Click the bug button → the Report a bug or send feedback modal opens

2. Pick a Severity — Low (cosmetic), Medium (annoying but workable), High (feature broken), Blocker (you can't continue)

3. Pick a Category — Bug, Feature request, Data issue, or Other

4. Describe what you did, what you expected, and what actually happened (minimum 10 characters, maximum 5000)

5. Review the Context sent with this report block at the bottom — this is text, not a screenshot, and includes:

   • Your email and organization

   • The page path you were on

   • Your viewport size (window width × height)

   • The session ID if you were on /session/<id> or /history/<id>

6. Click Submit

Reviewing your own reports

Switch to the My reports tab inside the modal to see the last 10 reports you've filed, each with a severity / category / status pill and a link to the Linear issue once triaged.

Bug report — my reports tab

Attaching a diagnostics snapshot

When the Field Diagnostics drawer is available (see Field Diagnostics below), its Open bug report with snapshot button pre-fills a plain-text dump of current device health, last-seen times, and recent events. That makes diagnostic-grade reports a one-click affair — no need to retype RF metrics into the description box.

Managing Plans

A plan is the canvas your walk test or monitor data lands on. Two kinds:

• Indoor floorplan — a PNG / JPEG image of a building, calibrated to a real-world scale

• Outdoor map — a real-world area defined by an Area of Operations (AO) polygon you draw on OpenStreetMap

The Plans page (/floorplans) shows both kinds in a single grid, sorted by most recently updated. Each card shows a type badge ("Floorplan" or "Outdoor Map"), the plan name, and a row of icon-button actions.

Plans Page

Card icon actions

Each card has a tight icon row (left to right):

Adding a plan

Click + Add Plan in the top right. A modal asks you to pick the kind:

• 📐 Indoor Floorplan → upload form (image + name)

• 🌍 Outdoor Map → a 3-step flow Enter address to locate the area → Frame on the map → confirm area → add a Name → Save.

Uploading an indoor floorplan

A floorplan is a PNG or JPEG image of the building you'll walk through. Higher resolution gives more accurate heatmap placement — aim for at least 1500 × 1500 pixels.

1. From Plans, click + Add Plan → choose Indoor Floorplan

2. Type a name (e.g. "Building A — Floor 2")

3. Click Choose File and pick your image

4. Click Upload

5. The new floorplan appears in the grid with a thumbnail preview

Floorplan upload form

The "Not Calibrated" badge

Newly uploaded floorplans show a grey Not Calibrated badge. The + New Session icon and Live Monitor icon are both disabled (tooltip: "Calibrate floorplan first") until you calibrate.

Why? The dashboard needs to know how many pixels equal one meter on this floorplan. Without calibration, the Android app can't accurately place your walk path on the floorplan and the monitor view can't size the rendered pin radius.

Indoor plan calibration page

Creating an outdoor map

An outdoor map is a real-world area defined on OpenStreetMap. It's used for outdoor walk tests where the position source is GPS (either from a device or from SurfScan Connect on a phone).

1. From Plans, click + Add Plan → choose Outdoor Map

2. Locate — search for an address or place name (e.g. "Madison Square Garden") or pan / zoom OSM to the right spot

   1. 
      
      

3. Frame — The Area of Operations (AO) is defined by the square highlighted area, zoom in/out and pan until you have an area highlighted slightly larger than the AO. If contributing walk test or monitored devices send data while outside of the AO, it is still captured and displayed but a clear AO quickly defines the specific areas of interest for teams on the ground.

   1. 

      Outdoor plan: Defining the Area of Operations

      
      

4. Name — type a name (e.g. "PGA Bethpage 18th Hole") and (optional) description

5. Click Save

The new outdoor map appears on the Plans page with an "Outdoor Map" type badge. There's no calibration step (GPS is already in absolute coordinates) — the + New Session icon is enabled immediately.

Updated dashboard with new Indoor and Outdoor Plans

Deleting a plan

1. Click the red 🗑️ Trash icon on the plan card

2. Click the green ✓ Check that appears to confirm (the red ✗ cancels)

3. The plan and all its sessions, markers, and snapshots are removed

Warning: Deletion cascades. Removing a floorplan or outdoor map deletes all its calibration, markers, sessions, and recorded telemetry. There's no undo.

Calibrating a Floorplan

Calibration is a one-time task per floorplan. Once done, every walk test or monitor session on this floorplan uses the same scale.

How it works

You pick two points on the floorplan that you can measure in the real world (e.g. corners of a room, doorway widths, wall lengths). You enter the distance in meters between them. The dashboard computes a pixels-per-meter scale factor and saves it.

Steps

1. From the Plans list, click ✏️ Edit on the floorplan card

2. Click the green Calibrate button in the toolbar

3. The toolbar hint changes to "Click first calibration point" — click anywhere on the floorplan to mark the first point. A green dot appears.

4. The hint changes to "Click second calibration point" — click the second point. A dashed green line appears between the two dots.

5. A dialog opens asking for the Distance (meters) between the two points. Enter the real-world distance (e.g. 10.0 for 10 meters).

6. Click Save Calibration

Calibration Mode

Calibration distance dialog

After calibration

• The dashed green line stays visible with a distance label (e.g. "10m")

• The button changes to Recalibrate — click it to redo with new points

• Back on the Plans page, the badge turns green to Calibrated

• The + New Session and Live Monitor icons become enabled

Floorplan calibrated

Tips for accurate calibration

• Pick points that are far apart. Two points 10 meters apart give a more accurate scale than two points 1 meter apart, because small clicking errors are diluted.

• Pick points along a known dimension. Wall lengths from architectural drawings, hallway lengths, or known ceiling tile counts work well.

• Use the largest dimension you can verify. A 30 m hallway with a tape measure or laser distance reading is ideal.

• Recalibrate if scale ever feels off. It's quick and only affects future sessions.

Placing gNB / eNB Markers

gNB (5G) and eNB (4G/LTE) markers show where your radios physically are on the floorplan. They're useful for correlating coverage drop-offs with distance from radios.

Markers are optional but recommended — they don't affect calibration or telemetry, just visual context.

Steps

1. From Plans, click ✏️ Edit

2. Double-click anywhere on the floorplan to place a new marker

3. In the dialog:

   • Type — choose gNB (5G NR) or eNB (LTE)

   • PCI — enter the Physical Cell Identity (a number, e.g. 100)

   • Label (optional) — a friendly name like "Main Hall gNB"

4. Click Place

Placing a node marker

Editing markers

• Click and drag a marker to reposition it. The new position saves automatically.

• Click a marker to select it (it gets a white outline). Click Delete Selected in the toolbar to remove it.

Pan and zoom

• Mouse wheel — zoom in/out (centered on cursor)

• Click and drag empty space — pan the view

Managing Devices

The Devices page (/settings/devices) is where your organization registers data sources that feed telemetry into walk tests and monitor sessions. Future versions will support SurfScan RPI and OpenWRT routers in the same UI.

A device registered here doesn't poll automatically — it only polls while at least one active session has it bound (via the Data Sources panel on the live session or monitor page). When you bind a deviceto a session, the dashboard's collector worker starts hitting that vendor’s API at the configured cadence.

Adding a Device

1. From any page, click Devices in the top nav

2. Click + Add Device

3. Fill in:

   • Name — friendly label (e.g. "Bethpage Compound")

   • API URL — official endpoint

   • API Key — an API key with appropriate read permissions

   • Polling cadence — see below

4. Click Test Credentials to verify the URL and the API authentication before saving.

5. Click Save

Polling cadence

Three preset chips above the custom seconds input:

You can also type any custom value between 5 and 3600 seconds. The chips are just shortcuts for common values.

Note: The cadence you set here is the floor — the dashboard will not poll faster than this value. Actual poll frequency is also constrained by the Vendor API response time (each cycle waits for the previous one to complete or to hit a per-cycle deadline).

Dual-API traffic light (field_diagnostics)

When your tenant has the field_diagnostics flag enabled, each Devicecard displays a small API traffic light under the URL summary. The dot reflects the worker's last poll-cycle outcome:

• 🟢 Green — recent polls returned data on time

• 🟡 Yellow — recent polls degraded (slow or partial response)

• 🔴 Red — recent polls failing

• ⚪ Grey — no recent poll activity yet (idle, or hasn't been bound to a session)

Hover the dot for a tooltip with the most recent poll's status code, latency, and sample count. The traffic light is read-only — to change polling behavior, edit the Device.

Editing or deleting

Each Device has Edit and Delete buttons. Editing opens the same form pre-filled. Changes apply within ~60 seconds of saving (the next reconciliation cycle picks up the new config).

Multi-device support (future)

The Devices page is generically named for a reason — future vendor types (SurfScan RPI, OpenWRT routers, additional broadcast encoder families) will add new "+ Add" entry points here.

Running a Walk Test

A walk test captures live signal measurements as a field engineer covers an area, then renders them as a colored heatmap. There are two paths depending on what you're testing:

• Indoor walk test — an Android mobile phone (Supported Devices) running SurfScan Connect walks through a building and streams telemetry over IMU-tracked position. Source plan: an indoor floorplan.

• Outdoor walk test — an Android mobile phone and/or API backend collects telemetry from connected devices with GPS in the field. The dashboard polls the API at the cadence configured on the Devices page. Source plan: an outdoor map.

Both produce the same telemetry shape and land on the same History page; only the position source and live-view canvas differ.

Indoor walk test (SurfScan Connect)

Pre-flight checklist

Creating a session

1. From Plans, click the green ➕ New Session icon on the calibrated floorplan card

2. The setup page shows the floorplan name and current scale (e.g. "20.5 px/m (10 m reference)")

   1. 
      
      

3. Click Create Session

4. You're redirected to the live session page with a yellow CALIBRATING badge in the toolbar

Session Setup

Live session in calibrating state

On the Android device

(Brief overview — see the SurfScan Connect app docs for full instructions.)

1. Open SurfScan Connect on the PDT-FP1

2. Sign in with the same email used for the dashboard

3. Select the floorplan you just created the session for

4. The app reads the calibration data and floorplan image

5. Tap your physical starting position on the floorplan — this anchors the IMU dead-reckoning

6. Tap Start when ready

Starting the session from the dashboard

When the field engineer is ready, click the green Start Session button in the dashboard toolbar.

• The badge changes from yellow CALIBRATING to green ACTIVE

• The Android app begins streaming telemetry at 1 Hz

• Colored dots appear on the floorplan as the engineer walks

Active session with live dots

Outdoor walk test

The outdoor flow doesn't need a calibration step — GPS coordinates are already in absolute units. Instead, you bind one or more devices to the session, and the dashboard polls them at the cadence you configured on the Devices page. Android devices can also be used to contribute telemetry using the SurfScan Connect app.

Pre-flight checklist

Creating an outdoor session

1. From Plans, click the green ➕ New Session icon on the outdoor map card

2. A Mode dialog appears with two choices:

   • Walk Test — accumulating heatmap (every dot stays on the map)

   • Monitor — live tail with a vanishing window (older dots fade out as new ones arrive). Use this for ongoing live-ops monitoring of a fixed deployment. The dialog also surfaces any session already active on this plan, with quick Open / End actions, to prevent duplicate sessions.

3. Pick a mode → you're redirected. Walk Test goes to the legacy live session page (/session/<id>); Monitor goes to the per-plan Live Monitor view (/outdoor-maps/<id>/monitor) — see Live Monitoring below.

Binding a Device

Whether you're on the legacy live session page or the new Monitor view, both surface a Data Sources panel (sidebar or slide-over) listing every Device registered to your organization. Each entry has a status pill and a toggle:

• Idle (grey) — Device registered but not bound to this session

• Polling (green) — currently bound; the worker is hitting it at the configured cadence

• Stopped (yellow) — was bound earlier but you toggled it off; can be re-enabled

Click Enable to start polling, Stop to pause. Multiple devices and Android phones can feed the same session at the same time.

The Test Credentials link on each card runs a live probe of both URLs and reports the result inline.

Watching live telemetry

While active, you'll see:

• Heatmap dots appearing on the map at the configured cadence (5 s – 60 s+ depending on your device setting, SurfScan Connect app streams at <1s intervals)

• Per-modem sidebar cards on the right showing each (encoder × modem) or Android phone with latest RSRP / RSRQ / SINR / carrier / band — see Per-modem cards below

• Metric selector at the top right (RSRP / SINR / SurfScore) — switch the dot coloring at any time

The first dots appear within roughly one polling interval of session start (so a 60-s cadence device will be silent for up to a minute, a 5-s cadence almost immediate), Android devices send streaming telemetry as soon as ‘Start Walk Test’ is clicked in the app.

No GPS, no dots. If a device or phone loses GPS lock, the dashboard doesn't write a row for that poll cycle (it can't place the dot). The session stays active and resumes painting as soon as GPS returns. When field_diagnostics is on, the GPS lock icon on each device card surfaces this state at a glance.

Per-modem cards

For devices with multiple cellular modems (typical for video encoders and bonding routers), the sidebar / panel shows one card per (device, modem) pair instead of per encoder. Each card shows:

• A device color dot for visual disambiguation

• The modem label (e.g. MODEM 1, MODEM 2)

• Latest RSRP / RSRQ / SINR (or the current hero metric on the Monitor page)

• Carrier name (Verizon, T-Mobile, etc.)

• Band (e.g. B13, n77)

• An Updated N s ago indicator with a recency color: green = fresh (<10 s), yellow = stale (10–60 s), red = lost (>60 s) — useful for spotting modems that have dropped off the air

A Hide / Show toggle on each card removes / restores its dots from the heatmap without affecting other modems on the same encoder.

For indoor walk tests with single-modem Android devices, each device gets one card — no modem grouping.

Multiple devices and modems

The dashboard cycles through 8 colors keyed on the stream — (device_id, modem_id) for multi-modem devices, or device_id alone for single-stream sources. The 9th stream reuses the first color. For typical events (1–3 PDT-FP1 phones, or 1 encoder × 6 modems = 6 streams) this is plenty.

Ending the session

1. When the walk is complete, click the red End Session button in the toolbar

2. The badge changes to grey COMPLETED

3. The Android app (if used) stops streaming; bound devices (if any) are unbound automatically

4. The session moves to the History view for permanent review

Note: Live dots are ephemeral. They live in your browser's memory while the session is active. Telemetry is also persisted to the database in real time, which is what powers the History view. You can close the browser tab — the persistent data stays.

Orphaned sessions. If you navigate away from the live session page without clicking End, the session stays open and continues consuming polling capacity. The Active Sessions menu in the header surfaces every running session in your tenant — open the menu and click End on the row to close anything orphaned. (Any tenant member can end any tenant session, not just the creator.)

Live Monitoring (Fleet Monitor)

Live Monitor is a per-plan dashboard tuned for ongoing, multi-device operations — broadcast events with several encoders, long-running fleet monitoring, anything where you want at-a-glance fleet health rather than an accumulating heatmap.

Unlike a walk test, monitor sessions:

• Auto-activate on open — opening either resumes an existing monitor session for the plan or starts a fresh one. No "Create Session" click required.

• Are long-running — they stay open while operators come and go. The same shared session collects telemetry across every device that joins.

• Auto-end never — they keep running until someone clicks End Monitor in the toolbar, or until an admin closes them via the Active Sessions menu.

Opening the Monitor

From the Plans page, click the 📡 Radio icon on a card:

• Ghost-grey icon → no session yet — clicking starts one

• Bright-green icon with pulse → a session is already running — clicking jumps you straight in (tooltip shows the device count)

You can also reach it via the Active Sessions menu or the per-plan + → Monitor mode dialog (outdoor maps).

The Monitor toolbar

Panel view

The panel view is a grid of device cards, one per (session, device, modem) stream. Cards include:

• A bold device label (operator-supplied or a truncated id — see Friendly Device Names)

• The hero metric value, colored by quality threshold

• Optional sparkline of the last ~5 minutes

• Last-seen timestamp with recency color

• GPS lock icon (when field_diagnostics is on and the session is outdoor)

• Carrier · band · PCI footer

Cards arrive in the panel as soon as a device contributes its first sample. Sessions that are active but haven't received any telemetry yet show a pending placeholder card.

AlertStrip

A thin strip below the toolbar rolls up the fleet's current health — total active devices, count of degraded modems, count of critical, count by carrier. Useful for an at-a-glance ops read without scanning every card.

Map view

Click the Map toggle to switch to a spatial view: each device renders as a pin on the floorplan image (indoor) or MapLibre / OSM basemap (outdoor), colored by the hero metric. Click a pin to open the DevicePopup with the same per-modem detail as the card view.

Monitor - Map View

Ending a Monitor session

Click End Monitor in the toolbar. The session is closed, bound devicesare unbound, and you're returned to the Plans page. The session moves into History where it can be replayed like any walk test.

Re-opening creates a new session. If you click End Monitor and immediately re-open the plan's Monitor view, you're starting a fresh session — the old one stays in History as a separate row.

Field Diagnostics

Field Diagnostics is a set of surfaces aimed at the engineer in the field debugging "why isn't my coverage data showing up?" mid-event. When the flag is on for your tenant, three extra affordances light up:

1. Dual-API traffic light (Devices page)

Already covered under Managing Devices. One dot per API per device, reflecting the worker's recent poll-cycle outcomes.

2. GPS lock icon (Monitor / live session device cards)

Three-state satellite icon on each device card in an outdoor session:

• 🟢 Green satellite + check — encoder has a GPS fix and lat/lng is being logged

• 🟡 Yellow satellite + slash — polling fine, but encoder has no GPS fix (no position written this cycle)

• ⚪ Grey dim satellite — no samples in the last 60 s, GPS state is unknown

This closes the most common "I'm polling but not seeing dots" mystery — the encoder is reachable but not fixed.

3. Field Diagnostics drawer

A right-side slide-over you open from the Monitor or live session toolbar (the Diagnostics button). Two tabs:

• Devices — one row per (device, modem) with a contribution-state pill: healthy, polling-no-gps, suspect-stale-cache, session-pending, etc. Each row shows last-seen, carrier, band, RSRP, SINR.

• Events — chronological log of state transitions since you opened the drawer (e.g. "MODEM 2 → polling-no-gps at 14:32:18"). Useful for correlating a "this stopped working at 14:32" complaint with the actual cause.

Diagnostics drawer — Devices tab

Diagnostics drawer — Events tab

Two footer buttons:

• 📋 Copy snapshot — drops a plain-text dump (devices + recent events) onto the clipboard, ready to paste into Slack / Teams / email

• 📄 Open bug report with snapshot — opens the bug-report modal with the snapshot pre-filled into the description, so support gets the engineer's account plus the device state in a single ticket

Reviewing Session History

The history page

Click History in the top nav to see every completed session in your tenant.

History Page

Stat strip

Across the top, a 30-day rollup shows Sessions / Avg URS / Snapshots / Device-sessions, each with a mini sparkline of the daily distribution. Live recomputes when filters change.

Mode tabs

Filter by what the session was for:

• All — every completed session

• Monitor — long-running monitor sessions only

• Walk — discrete walk-test sessions only

• Flagged — sessions with at least one critical or warn alert (requires the monitoring_incidents flag for the alert counts to populate)

Facet filters

Below the tabs:

• Plan — multi-select dropdown of every plan that has a session in history

• Carrier — multi-select of carriers present in the data

• Band — multi-select of cellular bands present

• URS range — twin sliders to constrain to a min/max average URS

All filter state is reflected in the URL — you can copy/paste a filtered link to share with a teammate.

A Clear filters button appears whenever any facet is active.

The dense table

Click anywhere on a row (outside the Timeline button) to open the Heatmap replay.

Walk Test Session History - Heatmap Replay

Click the Timeline icon to open the Detail Timeline view.

Detail Timeline

The Detail Timeline is a temporal post-session view: every metric on its own track, scrubbable, with the original raw snapshots visible at the cursor. Best for answering "what was happening at 14:32?" rather than "where did coverage drop?" (use Heatmap Replay for spatial questions).

Open it from the Timeline icon button on any History table row.

Detail Timeline

Layout

• Top header — Back link to History, plan name + status pill + start time, single-device chrome OR device picker (when 2+ devices contributed), preset chips (30s · 2m · 5m · 15m — Incident chip is disabled until the incidents pipeline ships), and a Live button on sessions that haven't been completed.

• Scrubber strip — a session-wide SVG of the SurfScore curve. Click anywhere to position the cursor; drag the edges to set a window. The cursor is one vertical line that lines up across all tracks below.

• Metric tracks — six tracks: SurfScore, URS, RSRP, SINR, RTT, Loss. Each is a self-contained sparkline against its own y-axis. Tracks with no data for the selected device are shown greyed out with a "NO DATA" label.

• Modem lane — at the bottom, a Gantt-style row showing which carrier / band each modem was on through the session. Useful for spotting carrier handoffs. Green segments = modem online, red = offline.

• Snapshot rail — the right sidebar shows the raw snapshot rows at the cursor position — every field, in a scrollable table. The "AT CURSOR" column on each metric track mirrors the value.

• Incident Log (requires monitoring_incidents flag) — a chronological list of degraded / critical events for the session, with click-to-jump.

• Footer actions — bottom-right corner of the page: Export CSV (download the loaded window as a CSV) and Share link (copy the deep-link to this exact view, including scrub position).

Device picker

The Timeline shows one device at a time — averaging RSRP across different encoders or carriers is misleading, so we don't. If a session has 2+ contributing devices, the header surfaces a dropdown to switch between them; each entry shows the operator-supplied label, snapshot count, and modem count where applicable. Single-device sessions skip the picker and show the device inline as informational chrome.

Detail Timeline — device picker

Long sessions (window picker)

Sessions with more than 50 000 telemetry rows can't fit comfortably in browser memory. Those open with a yellow Long session · N rows banner and a date-time window picker: pick a start and end (up to 6 hours apart), click Apply window, and only that slice loads. The rest of the page works identically. A small Open heatmap replay link in the picker bar takes you to the spatial view of the full session.

Detail Timeline — long-session window picker

Heatmap View

Heatmap View is the spatial post-session view — every recorded telemetry dot painted onto the original plan, color-coded by metric.

There are two entry points to this view:

• From the Plans page, click the 🔥 Flame icon on any plan with at least one completed session → opens the per-plan multi-session heatmap with a session picker

• From the History page, click any row → opens the single-session heatmap.

Multi-Session Heatmap View

The Heatmap view loads:

• The original plan (indoor floorplan image, or outdoor map basemap with AO polygon outline)

• All gNB / eNB markers from when an indoor session ran

• All saved telemetry points as a static heatmap

• A sidebar with per-device or per-modem stats and a session picker (per-plan view only)

For indoor replays the canvas is the floorplan image. You pan (drag) and zoom (mouse wheel) just like in the live view.

For outdoor replays the canvas is a MapLibre map. Pan and zoom work via standard map gestures (drag, scroll, pinch). The AO polygon is drawn as a green dashed outline.

Session picker (per-plan heatmap)

When you open the heatmap from a plan card, the sidebar shows every completed session for that plan grouped by date, with the local time. Toggle multiple sessions on to stack their dots; useful for comparing day-over-day coverage or before/after radio adjustments.

Reading the Heatmap

Indoor vs. outdoor visual

• Indoor sessions render dots on the floorplan image. Adjacent dots overlap and blend, creating a continuous "heat field" across the walked area. Pan/zoom is canvas-style (drag empty space + mouse wheel).

• Outdoor sessions render dots on a MapLibre OpenStreetMap basemap with the AO polygon outlined. Each dot has a white stroke for contrast against street labels and building polygons. Pan/zoom uses standard map gestures.

Color coding

Each dot is colored by signal quality. The colors mean different things depending on which metric you've selected.

The metric selector

In the top-right of the replay view, a dropdown lets you choose:

• RSRP — raw signal strength (dBm)

• SINR — signal-to-noise ratio (dB) — most important for video uplink

• SurfScore — composite quality score (0–100)

Metric selector dropdown

When you switch metrics, all dots re-color instantly. The sidebar's "average" stat also updates to match.

Color thresholds

Green = better, red = worse, in all metrics.

What the metrics mean (in plain English)

RSRP (Reference Signal Received Power) — How strong the radio signal is when it reaches the phone. Measured in dBm. Closer to zero is stronger; -80 dBm is excellent indoor coverage, -110 dBm is barely usable.

SINR (Signal-to-Interference-plus-Noise Ratio) — How clean the signal is relative to background interference. Measured in dB. Critical for video uplink because the phone's modem can only encode at higher data rates (which are needed for HEVC 4K) when SINR is high. SINR > 20 dB enables the highest modulation (64QAM); below 10 dB the modem falls back to slower encodings and your video bitrate adapts down.

SurfScore / URS — A composite score (0–100) we compute from RSRP, SINR, RSRQ, and channel bandwidth. Tuned specifically for HEVC video uplink reliability. See Understanding SurfScore / URS below.

Tap-to-inspect (single session heatmap view only)

In a single session heatmap view, click any dot on the heatmap to see all the metrics for that exact moment. Works on both indoor canvas and outdoor map dots.

A Point Detail panel appears at the top of the sidebar showing:

• SurfScore, RSRP, RSRQ, SINR

• PCI (which cell was serving)

• Band, bandwidth, protocol (e.g. "B48", "20 MHz", "LTE")

• RTT, jitter, packet loss

• Device temperature, fan RPM

• Device ID (and modem ID for multi-modem encoders)

• Exact timestamp

Click Close or click empty space to dismiss.

Note: Tap-to-inspect is only available in the heatmap replay. The live session view doesn't show per-point details — its purpose is real-time monitoring, not analysis. For temporal analysis (what changed when), use the Detail Timeline instead — its snapshot rail surfaces every field at every tick.

Hiding streams

Each card in the sidebar has a Hide / Show toggle. For indoor sessions this hides a whole device's dots; for multi-modem outdoor encoders it hides a single modem's dots without affecting other modems on the same encoder. Useful for analyzing one stream's path at a time.

Understanding SurfScore / URS

SurfScore (sometimes called URS — Uplink Reliability Score — in the History page and Timeline) is a 0–100 composite that summarizes RF quality into a single number. It's tuned for professional HEVC video uplink on private 5G — the use case the dashboard was built for. SurfScore and URS are computed the same way; the two names are used interchangeably across surfaces.

Why a composite?

Looking at RSRP alone tells you "the signal is strong" but not whether it's clean enough to support 4K video. Looking at SINR alone tells you the channel is clean but not whether you have enough of it. SurfScore blends them with the right weighting for video uplink.

The formula

SurfScore = (SINR × 40%) + (RSRP × 40%) + (RSRQ × 10%) + (BW × 10%)

Each component is mapped to a 0–100 sub-score, then weighted.

Why these weights

• SINR is weighted heavy (40%) because it determines what modulation the phone can use. 64QAM (needed for high-bitrate uplink to support 4K HEVC) requires SINR > 20 dB. Below 10 dB the phone is forced into QPSK and your bitrate drops sharply.

• RSRP is also weighted heavy (40%) because if the signal is too weak, the phone falls back to lower modulation regardless of SINR.

• RSRQ (10%) correlates with RSRP and adds a quality nuance.

• Bandwidth (10%) matters but on a private network you typically know it in advance and it doesn't vary much across the floorplan.

Component thresholds

Color thresholds

Friendly Device Names

By default, devices show up by their raw device id (a hash, sometimes a serial-shaped string). On Device-driven sessions you can give a device a friendly label — typed in once on the live session or monitor surface and stored against walk_test_sessions.device_label — and it then surfaces everywhere that device appears:

• The Monitor view's device cards and map popups

• The Detail Timeline's device picker

• The Heatmap replay sidebar and point-detail panel

• The History page filter facets

The lookup falls through gracefully: if no label has been set for a device id, the raw id (truncated) is shown instead. Labels persist across sessions — once set, future sessions involving the same device id inherit the label.

Tip: A consistent labeling scheme (e.g. Truck 1 / Truck 2 / Roof Cam) pays off most when reviewing history across multiple sessions, where raw device ids quickly become indistinguishable.

Tips & Troubleshooting

"Floorplan shows Not Calibrated"

You haven't calibrated the floorplan yet. Click ✏️ Edit, then Calibrate, and follow the Calibrating a Floorplan steps.

"+ New Session and Live icons are disabled"

Same cause — calibrate the floorplan first.

"I started a session but no telemetry is showing"

For indoor sessions:

1. Session is still in CALIBRATING — click Start Session to move it to ACTIVE

2. Android app isn't connected — confirm the engineer has selected the same session on their phone

3. Engineer hasn't started walking — the Android app waits for the engineer to tap Start on the device too

For outdoor sessions:

1. No device bound to the session — open the Data Sources panel and click Enable on the device you want polling

2. Cadence hasn't fired yet — at 60 s polling, the first dots take up to a minute. Drop the cadence to Fast (15 s) or Max (5 s) on the Devices page if you need faster feedback

3. Encoders have no GPS lock — the dashboard skips telemetry from inputs without a fix. When field_diagnostics is on, the GPS lock icon on each card shows this directly (yellow satellite + slash). Telemetry resumes automatically when GPS returns.

4. Device credentials are wrong — open the Devices page, click Edit on the device, click Test Credentials. Both URLs should report green ✓. With field_diagnostics on, the dual-API traffic light tells you which side is failing without re-running the test.

"The Active Sessions menu shows a session I don't recognize"

If you walk away from a live session without clicking End, the session stays open. Use the menu's End button on the row to close it — any tenant member can end any tenant session.

"The path on the dashboard looks shifted compared to where I actually walked"

This is usually IMU dead-reckoning drift on the Android side. The phone tracks your steps via accelerometer and gyroscope, and small errors accumulate over time. Possible causes:

• The starting marker on the phone wasn't placed exactly where the engineer was standing

• The engineer walked slowly or paused (IMU is more accurate at consistent walking speed)

• Magnetic interference (rebar, large metal objects) affected the compass

If the offset is severe and consistent across the whole walk, the calibration scale may be slightly off. Try recalibrating with a longer reference distance.

"I'm on the Timeline view and it says 'Long session'"

The session is over 50 000 telemetry rows. Pick a start / end window in the picker bar and click Apply window to load up to 6 hours of that span at a time. If you really want everything in one view, the Open heatmap replay link in the picker bar opens the spatial view instead — it can handle the full session.

"Multi-modem colors look the same"

The dashboard cycles through 8 colors keyed on each unique stream. With 9+ streams the 9th reuses the first color. For typical events (1–3 PDT-FP1 phones, or 1 encoder × 6 modems) this is plenty.

"I changed the polling cadence but nothing seems faster"

Cadence changes apply within ~60 seconds — that's how often the dashboard reconciles its polling state with what's configured. If after a minute or two the dots still aren't arriving faster, check the API traffic light on the device card (green = polling on time) or contact your administrator.

"I want to file a bug with full device state attached"

On the Monitor or live session page, click Diagnostics in the toolbar (only visible with field_diagnostics on), then click Open bug report with snapshot in the drawer footer. The bug-report modal opens with a pre-filled text dump of every device's contribution state, last-seen, and recent state transitions.

Glossary

Need help?

Open the bug button in the bottom-right corner of any page to file a report or request directly to the SurfScore team.