Formats and standards

Formats and standards · 2.0.1

Three recording containers and six conversions. Conversions select part of the data; use tar.gz to archive the full measurement with media.

Delivery protocols

Delivery determines where data goes; the format determines the contents of the file.

• HTTP over local Wi-Fi: preview, downloads and live JSON / NDJSON / CSV output.
• MQTT: publish selected live measurements to a configured broker.
• S3-compatible storage, WebDAV and SFTP: delivery of exported files.

File structure

The export is a UTF‑8 text file. Depending on the estimated size it is stored as .txt or packed into GZIP. It has three parts: a first line naming the format, a header block of key=value pairs, a blank line, and then a tab-separated table of samples.

A measurement that carries photos or voice notes is exported as a tar.gz archive instead, because gzip compresses a single stream and cannot hold a folder. The text file inside is exactly the same one, only named data.txt:

signal-collector-42/
  data.txt
  media/p7-1786439642118.jpg
  media/p9-1786439701244.m4a

SIGNAL_COLLECTOR_TXT_V6
session_id=42
session_status=COMPLETED
…
sources=accelerometer,collector_heartbeat,gnss_raw,location,wifi
mark_media_count=2
mark_media_dir=media

timestamp_iso_utc	epoch_ms	elapsed_realtime_ns	session_id	sequence_number	source	payload
2026-08-10T09:14:02.118Z	1786439642118	918273645000	42	1	location	record_type=fix;provider=gps;latitude=50.087;…

Samples are ordered by timestampEpochMs and, on a tie, by insertion order. A row never contains a raw tab or line break — see escaping.

Session header

It describes the whole measurement run: when it started, how it ended and how many samples passed through each stage. The header is written by MeasurementRepository.exportLatest from a closed session.

TSV columns

Seven tab-separated columns. The first six are the same for every source; the seventh is the payload of that particular source.

Escaping

Payloads such as raw_scan_result, NMEA sentences or exception text routinely contain characters that would break the structure of the file. Escaping is therefore always applied, even when a particular value holds no problematic character.

A parser therefore splits the row on tabs first, then the payload on unescaped semicolons, then each pair on the first unescaped equals sign — and unescapes the value last.

Shared payload suffixes

Some keys do not come from the source itself but are attached to the sample along the way. That is how even an accelerometer sample carries the last known location without knowing anything about location.

Location with every sample

Added to every sample for which the last location is known. If a source already carries a location of its own, it is not attached again. For internet_quality it is always attached — empty if need be, so the data shows that no location was available.

Network context with internet mapping

Attached only to internet_quality samples, tying the measured transfer to a specific network. The set of keys differs by transport.

Sensors

source: accelerometer · gyroscope · magnetometer · barometer · light · proximity · rotation_vector

All seven sensors share the same payload shape. Values are taken exactly as SensorEvent returns them, with no filtering and no conversion. elapsed_realtime_ns is the time of the sensor event, not the time of delivery.

temperature

source: temperature · record_type: none, the payload always has the same shape

None of these is the temperature of the air around you. Every thermometer here sits inside the phone, which heats itself — the more so the longer it measures — so all of them read above the room, and the difference between them grows during a measurement. Outdoor or room temperature comes only from an external sensor over BLE (bluetooth_ble).

The phone exposes several thermometers and the app writes every one of them, each as its own row, distinguished by probe. A phone rarely carries the standard ambient sensor; what it does carry are thermometers inside chips, put there to compensate their own drift.

noise

source: noise · record_type: none, the payload always has the same shape

Only the loudness of a block of samples is computed from the microphone. No audio is stored or sent anywhere; audio cannot be reconstructed from the stored values.

location

source: location · record_type: fix · registration

record_type=fix

record_type=registration

gnss_satellite

source: gnss_satellite · record_type: satellite · summary · event · registration · callback_error

On every change of satellite status, one row per satellite is written plus a single summary. The summary is precomputed deliberately — otherwise everyone processing the data would have to compute it.

record_type=satellite

record_type=summary

record_type=event / registration / callback_error

gnss_raw

source: gnss_raw · record_type: clock · measurement · agc · capabilities · registration · status · callback_error

Raw GNSS measurements for post-processing. One clock record plus as many measurement rows as the chip tracked satellites in that epoch.

record_type=clock

record_type=measurement

record_type=agc / capabilities / status

gnss_navigation

source: gnss_navigation · record_type: navigation_message · status · registration

gnss_nmea

source: gnss_nmea · record_type: nmea · registration

gnss_antenna

source: gnss_antenna · record_type: antenna_info · registration

wifi

source: wifi · record_type: scan · access_point · connection · mlo_link · status

Every fresh scan writes one row per visible access point plus one row about the phone's own connection. Android throttles scans and scanResults then keeps returning the same last result, which is why every scan attempt has its own record_type=scan row and every AP carries its own scan_timestamp_us.

record_type=scan

Written on every scan attempt, even when no new data comes of it. Without it, an old result returned again and again would look like regular sampling at the configured interval, and a coverage map could not tell where measuring actually happened. access_point rows are written only for the FRESH state.

record_type=access_point

record_type=connection

record_type=mlo_link

record_type=status

A single state, status=SCAN_CALLBACK_REGISTRATION_FAILED with the keys error and message. It means the subscription to system scans could not be registered — the data will then hold only the scans the collector requested, that is, trigger=PERIODIC_POLL.

wifi_rtt

source: wifi_rtt · record_type: capabilities · ranging_result · status

Ranging to access points that support FTM (802.11mc / 802.11az). Such APs are rare; when none is in range, status=NO_RESPONDERS is written so that it is clear the measurement ran and simply had nothing to measure.

wifi_throughput

source: wifi_throughput · record_type: wifi_throughput · status

One scan gives the signal of every network around at once; throughput does not — the phone is only ever associated with a single AP. The source therefore visits the networks listed in advance one by one through a WifiNetworkSpecifier and measures download, upload and HTTPS RTT on each. The switch applies to this app only; the rest of the phone's traffic stays on the original network.

Measure standing still: while walking, each network in the cycle would be measured from a different place and the numbers could not be compared. On the first connection to each network Android demands consent through a modal system dialog that cannot be suppressed — a walk therefore starts by clearing those dialogs at the first point.

record_type=wifi_throughput

One row per network per cycle, even when the network was never reached — otherwise the data could not tell a network that was not there from a network that was forgotten.

record_type=status

A single state, status=NO_TARGETS with an explanatory message. The source is switched on but the list of networks is empty, so it never starts — and the export shows that instead of staying silent.

mobile_network

source: mobile_network · record_type: cell · signal_strength · event · cell_bearing_estimate

For record_type=cell the set of keys is always the same and always complete — fields a given technology does not have are left empty. The columns of the table therefore never shift about depending on whether the phone is currently on LTE or 5G.

Keys shared by every cell record

Keys by technology

record_type=signal_strength

record_type=event

record_type=cell_bearing_estimate

A rough, walk-based estimate of where the serving cell of the active data SIM lies: a weighted centroid of the phone's own positions, weighted toward the stronger readings. Written only after at least five usable fixes spread over at least 30 m since the last change of serving cell, and again only when the rounded bearing or the distance step changes. Always an estimate (method=own_walk), never a fix — terrain, buildings and multipath can throw it off by a wide margin.

sim_info

source: sim_info · record_type: summary · subscription

Which cards were in the phone while measuring. mobile_network carries the identity of the transmitter but not of whoever was looking at it — and with two cards, or in roaming, that is a crucial difference. It is written once when the measurement starts and after that only when the system reports a change of subscriptions; cards do not change as you walk.

Neither ICCID nor EID is recorded. They are permanent subscription identifiers that outlive even a change of phone, whereas the rest of this section describes the network the measurement ran in. Since Android 10 the system would not hand them to an app anyway.

record_type=summary

record_type=subscription

network_context

source: network_context · record_type: capabilities · link_properties · event

The operating system's view of the networks: what the phone claims about a network before anything is transferred over it. Written at the start, periodically, and on every change.

record_type=capabilities

record_type=link_properties

record_type=event

internet_quality

source: internet_quality · record_type: network_quality_sample · network_capacity_probe · network_capacity_probe_started · speed_test_result · speed_test_event

Real HTTPS transfers bound to a specific Android Network, not an estimate of link capacity. The one-second sample is small on purpose: the goal is a continuous map of quality while walking, not a peak rate. That is why every record also carries measurement_semantics=SMALL_TRANSFER_QUALITY_NOT_MAX_SPEED.

Every sample additionally carries the shared suffixes — the location and the network snapshot.

record_type=network_quality_sample / network_capacity_probe

record_type=network_capacity_probe_started

Written the moment a burst begins. The burst holds the transport lock for the whole transfer, so during that time rows with status=BUSY arrive instead of measured samples — this marker says from when and why. Its keys are a subset of the previous table plus transfer_deadline_ms (the latest the transfer may take).

record_type=speed_test_result

A manual test started by the button, not part of continuous mapping. It transfers megabytes, not kilobytes.

record_type=speed_test_event

bluetooth_classic

source: bluetooth_classic · record_type: discovery_result · paired_device · event · registration · status

status=ADAPTER_DISABLED means Bluetooth is switched off. Without that report the source would look enabled, just without a single find.

bluetooth_ble

source: bluetooth_ble · record_type: advertisement · status

The complete advertising payload, raw bytes included. The scan runs in low-latency mode and does not filter, so in a busy environment it is the most prolific source of rows.

collector_heartbeat

source: collector_heartbeat · record_type: collector_heartbeat · every 5 s

The heartbeat is not a source of data about the surroundings but about the measurement itself. It passes through the same queue and the same writer as every other sample, so a finished file shows which module was really running when, and whether writing ever stalled. Silence in the data therefore cannot be mistaken for a fault.

haptic

source: haptic · record_type: haptic

A vibration is a mechanical impulse and the phone is recording the accelerometer and the gyroscope at the same time, so every buzz writes itself into its own data as a shake that did not come from walking. This record says when it happened, so a window can be cut around it in the sensor stream. What gets written is the loss and return of the default network and the point marker; the alarm for a failed write has no record, because by then the writer is no longer alive — that one is carried by end_reason=WRITER_ERROR, and no sensor data is produced beyond that moment.

session

source: session · record_type: session_started · session_paused · session_resumed · survey_point · mark_media · export

Start resumes into the last measurement that was not reset, so one session can consist of several separate stretches. These records say where a stretch began and where it ended — without them a pause in the data could not be told from a hole in coverage or from frozen collection. A pause is deliberately two separate events rather than one record with a length: a record with a length would have to wait for the end of the pause, and if the system killed the app meanwhile, it would never be written at all.

record_type=survey_point

A marker of the place the measurement is standing at. Indoors GNSS gives no position, so this is the only thing in the data that ties measured values to a point on a floor plan: the operator stops, taps Mark point, waits a moment and walks on. The marker stands on its own in the timeline and point_index is not added to the other records — values are attributed to a point by a time window after the marker, not by a key in every row.

The tap also buzzes, so every point has a haptic row with the same timestamp — the shake in the sensors is therefore not unexplained.

record_type=mark_media

A photo or a voice note taken at a survey point. The file is not in the TXT — it travels in the same archive, under media/ next to data.txt, and this record is what ties it to a point. A measurement carrying media is therefore exported as a single tar.gz: gzip on its own compresses one stream and cannot hold a folder.

record_type=export

The export writes itself into the measurement it came from: when, in which format, which way it left and how much it carried. It is written only after the file exists, so an exported file never contains the record of its own export — only the next one does. That is the order of events, not a gap. The app reads the last of these rows before a Reset to say whether the measurement has left the phone.

A voice note is timed to its end, while the point it belongs to was written when the operator tapped — that is where they stood. The gap between the two rows is the length of the recording.

mqtt

source: mqtt · record_type: mqtt_connected · mqtt_disconnected · mqtt_failed

Breaks in the live MQTT output, written into the measurement as their own source. When the connection to the broker drops, the live stream falls silent — and without this record, whoever looks at the finished measurement cannot tell whether nothing happened out there or the broker just went quiet. A failed connection attempt is not written on its own: an hour on a route with no signal would otherwise leave the export with dozens of rows about nothing. Only a connection that had stood and then broke, and the final give-up once retries are exhausted, get a row.

Like collector_heartbeat, haptic and session, this is a record of the app's own operation, not a measured quantity — it is deliberately left out of the source picker and does not drive the live pulse on screen.

No broker address, client identity or password ever reaches the export through this source — only the name of an enum case leaves the connection layer. A rejected password shows up as reason=CONNECTION_REJECTED;reason_code=BAD_CREDENTIALS, never as the credentials themselves or the exception text that named them.

record_type=mqtt_connected

record_type=mqtt_disconnected

A connection that had stood broke. The client will retry.

record_type=mqtt_failed

Retries are exhausted. From here on the silence is no longer temporary — the response to it lives in settings, not in another attempt.

Measurement parameters

Every source can be switched on individually before the start, and for some of them the pace can be set as well. Values outside the range are pulled back to the limits — otherwise interval_s=0, say, would turn the periodic loop into a tight loop.

Storage in the phone

The data sits in a local Room / SQLite database, schema version 6. It is never sent anywhere; exporting to a file is up to the user.

Table sensor_samples

Table measurement_sessions

One row per measurement run. The columns match the fields in the export header; on top of that, acceptedSamples, writtenSamples, droppedSamples and lastPersistedAtEpochMs are updated as the run proceeds, in the same transaction as the insert of a batch of samples. If the process dies, the session stays in the RUNNING state and the next app start closes it as INTERRUPTED with end_reason=PROCESS_RECOVERY — the partial record stays exportable.