Description
The MonadCount companion mobile app is a scriptable wireless participant. From the experiment's standpoint, each phone running the app is a controllable agent with deterministic BLE advertising behaviour, programmable WiFi association, smartphone-side CSI and BLE fingerprinting, and a TCP/UDP control channel.
The app is the bridge between the simulation layer and the field layer of the experiment series: a JuPedSim agent in EXP-S1 maps onto a gamified app task in EXP-P1 / EXP-F* with the same trajectory + the same BLE adv timing + the same WiFi handoff pattern. This is what makes simulation→field comparison meaningful.
Capabilities
| Capability | Role in experiments |
|---|---|
| BLE adv TX (configurable rate, configurable payload) | Automated ground-truth source — each phone broadcasts a unique adv. BLE listeners (esp32-c6) count adverts → automated occupancy without manual labelling. |
| BLE adv RX (passive scan + RSSI) | Smartphone-side fingerprint of the BLE infrastructure; complements infrastructure-side counting with a participant-side view. |
| CSI fingerprinting (smartphone-side) | Captures CSI / RSSI samples of nearby APs from the participant's perspective. Useful for fingerprint-based localisation baselines. |
| BLE fingerprinting (smartphone-side) | RSSI maps per location for fingerprint-based positioning baselines. |
| TCP / UDP comms (bidirectional with collection server) | Command channel for calibration-mode toggle, walk-task assignment, WiFi handoff trigger; data uplink for the smartphone-side fingerprints. |
| WiFi switching (programmable association) | Forces the phone to associate with a chosen AP — turns AP topology into a controllable experimental covariate. |
Why this matters structurally
The old EXP-001..005 notes listed the app once in their devices section and then ignored it. That undersold three substantive uses:
- Programmable participants — a gamified task ("walk to door, hold 30 s, walk to whiteboard") gives JuPedSim-style ground truth on real RF without manual annotation. EXP-F1 ground-truth validation is defined by what the app prescribes vs what the infrastructure observes.
- Deterministic BLE adv timing — calibration-mode entry (EXP-F2) is one push notification, not an engineering problem.
- WiFi-switch as covariate — EXP-F3 cross-geometry transfer becomes a controlled experiment when AP association is scripted.
Role in the experiment series
- EXP-S1 — none directly. Simulation uses synthetic agents; the app's task schema is the interface a Layer-F agent must satisfy to be comparable.
- EXP-P1 — full gamification loop: walk-task assignment, BLE-adv toggle, WiFi-switch, telemetry uplink. End-to-end mobile-app ↔ collection-server validation.
- EXP-F1 — primary ground-truth source for BLE-anchored CSI validation.
- EXP-F2 — calibration-mode trigger; participants get a push notification, app increases BLE adv rate to 1 Hz (from background 0.1 Hz), system collects fresh labelled data for fine-tuning.
- EXP-F3 — phone-penetration scenarios S1..S5 are app-driven (selective app uninstall / disable per participant); WiFi-switch covariate runs here.
Quirks / known issues
- iOS background BLE adv restrictions. Background advertising on iOS is rate-limited and payload-truncated; field experiments must enrol participants with the app in foreground mode OR use Android-only cohorts for the calibration campaigns. Decide per-EXP.
- Permission flow friction. Android 12+ runtime permissions (NEARBY_DEVICES, FINE_LOCATION) and iOS Bluetooth always-on consent are participant-recruitment hurdles. Onboarding script ships with EXP-P1.
- Battery cost. Sustained BLE adv at 1 Hz + WiFi-CSI + TCP heartbeat drains a phone within a working day. Field experiments must either (a) provide charging, (b) cap session length, or (c) drop CSI capture and keep BLE only.
- Clock skew. Phone wall-clocks drift relative to the infrastructure NTP plane. The TCP heartbeat carries a server timestamp for re-synchronisation; field data uses the server timestamp, not the phone's.
Tooling
- The app is in-house; build matrix and capability flags live with the app project, not in this vault. Reference what the app supports here, version-by-version.
- Collection-server endpoint (TCP/UDP) is part of the EXP-P1 platform; spec lives in EXP-P1.
Related entries
- ble · bluetooth — protocol baselines
- esp32-c6 — BLE listener that counts the app's adverts
- esp32-c5 — CSI extractor whose data the app is the ground truth for
- raspberry-pi-5 — Pi 5 sensing host