Field Teams

Overview

Field Teams are groups that manage Participants (youth athletes, tour guests, club members) with Leads (coaches or guides) and optional Guardians (parents). Attendance and identity use offline-friendly PKI-signed QR codes, with an optional Live Map for guardians.

The primary lead surface is the Activity Hub (field session cockpit)—not a separate legacy scanner app.

Concept workflow

graph TD
    subgraph Lead [Lead device — Activity Hub]
        A[Prep field cache online] --> B[Start field session]
        B --> C{Mode}
        C -->|Scan| D[Camera / BLE reads others]
        C -->|Broadcast| E[Station QR for self check-in]
        D --> F[Roster updates immediately]
        E --> G[People scan with their phones]
        G --> F
        F --> H[Pending sync when offline]
        H --> I[Sync now / auto on reconnect]
    end

    subgraph Guardian [Guardian / adult phone]
        J[Profile identity QR or station scan] --> K[Check self or kids in/out]
    end

    E -.-> J

Identity & verification

  1. Device keys: Each signed-in device holds a key pair used to sign check-in events.
  2. Local verification: After Prep, a lead can verify many scans from cached public keys without cellular.
  3. Static / printed QR: Long-lived codes for convenience (batch export or Profile share). Lower assurance than a live rotating QR; field policy may flag them as static/unverified.

Activity Hub (for Leads)

Open the hub from a live session on Home, the activity carousel, or Admin field tools.

1. Prep (before unreliable coverage)

While online, open the hub and tap Prep. This caches roster, tokens, and keys.

  • Banner shows Field ready (N cached) · ready if connection disrupted when the cache is warm. You can hide the full banner (chevron) and restore it from the thin strip if you need more room for the roster.
  • Prep is for flaky field connectivity—not a requirement to “go airplane mode for testing.”

2. Start a field session

  1. Choose activity type / title and optional High Security Mode.
  2. Nobody is clocked in automatically—including the lead, other group leads/admins, or kids. Opening the hub on another device (for example Jimmy’s tablet while Pete starts the session) does not clock that person in.
  3. After start, choose optionally:
    • Clock me in (as Lead)
    • Clock in your kids
  4. Skip both if you only need a station or will scan others later. The Clocked In roster stays empty until someone is explicitly clocked in.

3. Scan vs Broadcast

Mode What it does
Scan Lead camera (or BLE proximity) reads someone else’s code and clocks that person in or out. Flash shows their name.
Broadcast Shows a session station QR. Anyone who scans it with their own phone checks themselves (or selected kids) into this session. Use Enter Kiosk Mode for an unattended station (not a full device lock).

Personal long-lived identity QR lives under Profile → My Identity QR (share/export static image available).

4. Roster, map, monitor

  • Header: session title, group, and start (and end when known)—not the other lead’s profile.
  • Clock in without QR: the person+ icon (not a second full-width button). The picker includes you, then your kids, then other participants.
  • Roster: Scheduled, Clocked In, and Departed (after check-out, including after offline round-trips once sync completes).
  • Sort & subgroup layout: When the group has subgroups, the default sort is Subgroup — each section is broken into subgroup headers, with leads/admins at the top and kids at the bottom of each subgroup. Toggle A–Z (name) or Role (role then name) from the sort control. Use Filter chips to show one subgroup (or Unassigned) only.
  • Search: The bottom search box filters the roster by name, role, or subgroup label.
  • Field ready banner: Collapse the offline / field-cache status strip with the chevron; tap the thin residual strip to restore it.
  • Clock: A small digital clock is shown in the Activity Hub app bar.
  • Message a person: Tap a name on the roster to open an in-app chat with that person (or a kid’s guardian when the roster row is a participant).
  • Message a cohort: Next to each section title (Scheduled / Clocked In / Departed), leads and admins get a button to message everyone in that section. From Kiosk Mode, those messages go into a separate kiosk-labeled conversation so recipients see them as from the station, not the lead’s personal chat.
  • Live Map / Activity Monitor: Available from the hub; Kiosk Mode keeps these available while Leave/End Session require Exit Kiosk (device biometrics or pattern). Not a full device security lock. On a multi-group event, the map uses the event roster name (the name entered at join, or when creating the event) — not the Google account name on the profile.

Live Map: labels, tap, VIP star

The legend is the name list on the live map (the floating “People (…)” panel), not a map key of colors. It is built from the group’s live roster (groups/{id}/live: members, kids, leads) plus mesh VIPs that have no live doc yet. It groups by role; with 20+ names it also groups A–Z. Filter, All/None, eye (hide), follow, and star live there — you do not have to tap dots on the map.

Opening the Live Map does not clock you in and does not broadcast into an activity_only group. You appear on others’ maps only after hub clock-in (or the group is always-visible / you tap Broadcast). The top sharing pill matches that roster, not merely “map is open.”

If the map shows Loading map tiles… (gray with that text), the street pictures are still arriving — pinch-zoom-out on a drive can briefly empty the cache. It is not a crash. My location (center button) reloads tiles.

A later release (not this one) will keep satellite as aerial photos and draw vector streets (smaller downloads, smoother zoom). You will be able to download streets for this area at town zoom for offline use — not house-by-house, and not a full satellite pack.

The People panel starts closed (list icon in the app bar). Search is by name. Type chips (Kid, Lead, Member, …) filter by role. All / None / Only need a name or a chip first; otherwise a snackbar explains them:

Button Effect
All Un-hide everyone matching the filter (show their dots).
None Hide everyone matching the filter.
Only Show the filter matches; hide everyone else on the roster.

Star in the People list is the same set as Map Settings. Stars are saved on your account (users/{uid}.liveMapStarred) so they follow you to another phone, tablet, or browser, and cached on-device for offline. Pin colors match the map: kid blue, lead/VIP orange, active member red, others teal. You and your active kids paint on top of overlapping dots.

Large named pins: you; your kids who are active on the field (every accepted guardian, including shared / co-guardians — not only the account owner); leads / rank 0–2 (including CLI --vips); anyone you star. Someone else’s kid is a crowd dot unless you select them (tap) or star them. Pending guardian invites do not count until they accept. At city zoom the crowd becomes count bubbles; large pins stay individual.

Star from Map Settings (gear), not by hunting dots. Default is no stars. Soft limit 24 named extra pins — a warning appears if you star more (labels crowd and slow the map). Stars persist per group on the device.

Legend eye hides a person on the canvas. Radio frames for a roster person merge into their uid so you do not see a second ghost next to Pete/Jimmy.

Action What you get
Tap a dot Name + last GPS sheet. That one stays labeled until you tap empty map.
Long-press Same as tap.
Legend star Marks that person a VIP: always labeled, not swallowed into a cluster. Star again to clear.
Legend crosshair Follow them: the map glides with their live/predicted position. Pan to stop.
Compass track up Rotate so your heading is toward the top of the screen (smooth, not jumpy). Combine with follow-me or follow-person.

CLI stress VIPs (mesh-stress-test --vips 5) show as orange named dots (VIP Racer 0, …) and appear under their role in the legend so you can star or follow them. - End session: Closes attendance; open people are checked out as part of cleanup.

5. Check-out policy (secure vs insecure)

Mode Self clock-out Who can clock others out
Normal (insecure) Yes — from the green LIVE card on Home/Calendar, or the roster logout control Leads, admins, guardians for their kids
High Security No — must check out with a leader (scan or lead roster action) Session leaders / coaches on the session, and guardians for their kids

6. Offline & sync

  • Scans write locally to pending_checkins and apply when the network returns.
  • Banner shows pending counts; Sync now flushes the local queue after reconnect.
  • High Security Mode (group/session setting) blocks casual self check-out so out requires a leader. It works with offline after Prep—not instead of it.

For Guardians (Parents)

1. Identity setup

Complete identity setup in Profile so the device can sign events. Use My Identity QR to show a live code, or Share static QR for print/email.

2. Check-in at the field

  • Scan the lead’s Broadcast station QR with your phone (self check-in path), or
  • Show your (or your kid’s) QR for a lead to Scan.

Select which dependents apply when the UI offers multi-select.

3. Check-out

  • Normal sessions: Clock yourself out from the green LIVE session card on Home/Calendar, or use the logout control on the Field Session roster.
  • High Security sessions: Self clock-out is disabled. Check out with a leader (scan station / lead scan, or lead roster action). Guardians can still check out their own kids when the policy allows.

Admin prep (before field day)

  • Admin → Manage Members → Batch Export Static QRs — print badges for the whole group without anyone being clocked in.
  • High Security Mode — group setting under member/group settings.
  • Promote field leaders as needed so they can open the hub and start sessions.
  • If you use Feasycom beacons, keep firmware current and power-cycle before provisioning; Android provisioning uses the vendor Feasycom SDK. Tags are identified by the group iBeacon UUID plus Major/Minor.

Live Map & tracking

  • Hybrid Multi-Tier Meshing: Live positions propagate across four simultaneous communication layers:
    1. Direct Hardware GPS: Your own avatar position is derived directly from your device’s GPS hardware clock in real-time (0 ms lag).
    2. Local Wi-Fi Mesh (UDP): When connected to the same camp Wi-Fi, vehicle router, or mobile hotspot, devices broadcast mesh position frames directly over the local subnet (<30 ms latency, zero cloud costs).
    3. Direct Cellular P2P: Devices establish direct encrypted peer-to-peer streams across cellular LTE/5G NATs for low-latency (<90 ms) tracking without database round-trips.
    4. Bluetooth Low Energy (BLE) Mesh: Off-grid radio mesh allows direct peer-to-peer tracking and multi-hop relaying even with zero cellular reception.
    5. Cloud Presence: Periodic checkpoints are written to the cloud for remote web viewers and historical records.
  • Optional edge-relay computers: Clubhouse laptops and always-on servers can forward the mesh to web maps for the groups you belong to (and optional event logs). Helping other clubs is an explicit “public relay” opt-in, not the default. Relays keep a reconstruction log per group and per event. Most relays do not need ports 80/443 or a certificate. Those are only for machines that internet browsers will use. See Live map relays. How club vs event maps and kids work when encryption ships: Live map privacy.
  • Mesh Uplink Gateway (Field Relay): A device-level toggle allows a well-connected device (such as a vehicle tablet, camp Raspberry Pi, or coach phone with strong cell reception) to act as the cloud bridge for nearby offline nodes, fusing their sightings and uploading them automatically.
  • Collaborative iBeacon Centroid Positioning: When multiple devices detect the same participant beacon, their observations are combined using an inverse-square weighted centroid algorithm to estimate the participant’s position accurately.
  • Beacon identity: FeasyBeacons are matched on the map by programmed iBeacon UUID / Major / Minor. SwapSanity does not save or look people up by MAC address. Battery comes from Feasy’s unencrypted 0xFFF0 advertisement on that same iBeacon packet (not Eddystone-TLM). Tags are programmed iBeacon-only to save battery.
  • Attendance / proxy location: Checked-in participants can appear relative to lead activity for guardian awareness.
  • Activity tracking: When a session uses higher-resolution tracking, paths and last-known points update for the active roster with 15 Hz dead-reckoning smoothing.
  • Markers: Reflect check-in state and verification quality (e.g. live PKI vs static QR).
  • Privacy fence (polygon or radius): Multi-group / event boundaries define where live location sharing is allowed. Leaving that area stops sharing (and can check you out of the event). This is not the same as personal autostart places, which use circles only so the phone can use low-power OS geofencing.