Files

21 KiB
Raw Permalink Blame History

title, status, date, scope
title status date scope
Source-code audit: how the reference PAX counter actually counts research-note 2026-11-14 ESP32-Paxcounter / libpax reference implementation; not confirmed to be the exact firmware deployed in Heilbronn

Source-code audit: how the reference PAX counter actually counts

Purpose. The challenge brief calls the PAX counters "privacy-preserving sensors" that "estimate crowd density by passively sniffing Bluetooth signals (MAC address advertisements)" and transmit "aggregated device counts" (Schwarz Digits, The Pulse of the City, challenge brief). This note audits the widely used open-source reference implementation to separate the marketing description from the actual measurement semantics. It is a code audit, not a claim about the exact firmware or configuration used by Code for Heilbronn.

Scope and caveat. The implementation audited is:

The challenge says the data come from "LoRa-based PAX Counters" deployed by Code for Heilbronn. The upstream project is the canonical open-source design, but the deployed firmware version, build flags, sensor enclosure, antenna, and backend aggregation are not documented in the challenge package. Treat the findings below as properties of the reference design, and verify them against the deployed devices before making definitive claims.

Important update from the operator. Code for Heilbronn's own project post (18 Sep 2025) describes the deployed design:

  • Hardware: Heltec Wireless Paper board with an ESP32 (Bluetooth/WLAN), battery input, and an SX1262 LoRa transceiver.
  • Counting: the sensor receives Bluetooth advertisement packets and remembers device addresses.
  • Privacy: "Diese MAC-Adressen werden gehashed und für maximal eine Stunde gespeichert" — the MAC addresses are hashed and stored for at most one hour. "Außerdem verlassen diese MAC Adressen auch gehashed nicht die Sensoren, da nur die Anzahl der gezählten Adressen gesendet wird" — even hashed, the addresses do not leave the sensors; only the number of counted addresses is transmitted.

Source: https://codeforheilbronn.de/blog/2025/09/passantenzahlen-messen-mit-lora/

This is stronger than the upstream libpax design in one respect (a one-hour hashed dedup cache rather than a 60-second 16-bit bitmap) and different in another (the deployed firmware may be a fork). The exact hash length, cache eviction rule, and aggregation from one-hour hashed counts to 15-minute CSV rows are not documented. The paper must not assume the upstream code is the deployed firmware; it should cite both and state the uncertainty.


1. Deployed firmware audit (Code for Heilbronn lorax)

The canonical deployment repository is cfhn/lorax (mirror name: cfhn/lora-frequenzmessung), https://codeberg.org/cfhn/lorax. It contains the sensor-pax ESP32 firmware, the LoRaWAN/TTN aggregator, the Go backend, TimescaleDB, and Grafana. This is a much closer match to the challenge than the generic upstream Paxcounter.

1.1 Exact cycle

sensor-pax/src/main.cpp:

paxSetup();
unsigned long scanStart = millis();
while (!new_data_available && millis() - scanStart < 35000) {
    delay(100);
}
uint16_t paxCount = current_count;
paxStop();
...
int payloadLen = snprintf(payload, sizeof(payload), "%s,0,%.4f,1,%.4f",
         cfg.sensor_id, paxCount * cfg.factor, battPct);
...
goToSleep();  // deep sleep

sensor-pax/src/pax.h:

configuration.blecounter = 1;
configuration.blescantime = 30;       // seconds
configuration.wificounter = 0;
configuration.wifi_rssi_threshold = -80;
configuration.ble_rssi_threshold = -80;
libpax_update_config(&configuration);
libpax_counter_init(log, &count_from_libpax, 10, 1);  // 10 s report, cumulative
libpax_counter_start();

sensor-pax/src/provision.h:

cfg.factor         = p.getFloat(KEY_FACTOR, 0.7f);
cfg.sleep_time_sec = p.getInt(KEY_SLEEP_TIME, 900);

Therefore each CSV density row is:

value = (unique locally administered BLE MAC hashes seen in a ~10-second scan)
        × (per-sensor factor, default 0.7)

and the next row is produced after a 15-minute deep sleep (default SLEEP_SEC=900).

The actual scan is shorter than 30 seconds. blescantime = 30 is passed to start_BLE_scan(), but this fork never uses it to stop the scan. Instead, the main loop exits on the first new_data_available callback, and the report timer is configured for 10 seconds (libpax_counter_init(..., 10, 1)). So the effective scan is approximately 10 seconds, followed by a 15-minute sleep. That is a ~1.1% duty cycle (10 s / ~910 s), not 3.3%. The 35-second loop bound is only a safety timeout. The target is a 10-second snapshot, so a crowd that peaks between snapshots is invisible, and the forecast is predicting a sparse sample rather than an integrated footfall flow.

1.2 The factor is an undocumented calibration knob

cfg.factor is provisioned per sensor (.env requires FACTOR), defaults to 0.7, and is multiplied into the payload. The repository contains no calibration procedure, no ground-truth counts, and no explanation of what 0.7 means. It could be a device-to-person correction, a normalization to a manual count, or an arbitrary scale. The paper must not treat the CSV values as raw device counts or as people.

1.3 The hash is still 16-bit

sensor-pax/lib/paxlib/libpax.cpp:

#define LIBPAX_MAX_SIZE 0xFFFF
#define LIBPAX_MAP_SIZE (LIBPAX_MAX_SIZE / BITS_PER_WORD)
...
IRAM_ATTR int mac_add(uint8_t *paddr, snifftype_t sniff_type) {
  uint16_t *id;
  // mac addresses are 6 bytes long, we only use the last two bytes
  id = (uint16_t *)(paddr + 4);
  // if it is NOT a locally administered ("random") mac, we don't count it
  if (!(paddr[0] & 0b10)) return false;
  int added = add_to_bucket(*id);
  ...
}

This confirms the 16-bit ID and the locally-administered-only filter in the deployed firmware. Two important precision points:

  • The code does not apply a cryptographic hash. It truncates the last two bytes of the MAC address into a uint16_t (id = (uint16_t *)(paddr + 4)). The operator's blog calls this "gehashed"; the paper should call it a 16-bit truncation, which is weaker than a hash and has a small ID space.
  • The operator's blog statement that MACs are "hashed and stored for at most one hour" is not what this firmware does literally: the bitmap is reset at each wake (libpax_counter_init calls libpax_counter_reset), and the device deep-sleeps after each ~10 s scan. The blog may describe an earlier version or the intended privacy policy. The paper should report both and flag the discrepancy.

1.4 The CSV is a raw export, not an aggregate

The aggregator (backend/Aggregator/main.go) parses the payload as sensor_id,type,value,..., maps type 0 to densityData, and posts the value to the backend. The backend stores it in sensor_data(time, sensor_id, name, longitude, latitude, type, value) with no time-bucket aggregation in the schema. The challenge CSV has the same columns and ~15-minute spacing. The simplest reading is that the CSV is a direct export of these per-wake values, not a 15-minute mean. This should be verified with the data provider, but the code strongly supports it.

1.5 What this changes

The measured value is a ~10-second sample, scaled by a fixed, undocumented factor, from a sensor that sees only randomized BLE addresses, hashed into 16 bits, with an RSSI cut-off at -80 dBm, repeated every 15 minutes. That is a chain of six lossy transformations before the number reaches the CSV. The paper's reliability critique is not speculative; it is a property of the deployed design.


2. What the upstream reference code counts

2.1 BLE path

libpax/lib/libpax/blescan.cpp starts a passive BLE scan:

uint8_t scan_type = 0x00;  // passive scan, since we don't need / want answers
...
uint16_t scan_interval = BLESCANINTERVAL * 1000 / 625;
uint16_t scan_window   = BLESCANWINDOW  * 1000 / 625;
...
uint8_t filter_duplicates = 0x00;  // duplicate filtering disabled

Defaults in libpax_api.cpp and shared/paxcounter_orig.conf:

#define BLESCANWINDOW   80   // milliseconds
#define BLESCANINTERVAL 80   // milliseconds  (100% duty cycle)
#define SENDCYCLE       30   // payload send cycle [seconds/2] => 60 s
#define BLECOUNTER      0    // upstream default: BLE sniffer off
#define WIFICOUNTER     1    // upstream default: Wi-Fi sniffer on

The BLE scanner is passive: it listens for advertising reports and never sends scan requests. With an 80 ms window every 80 ms, it is effectively continuous. Every advertising report above the RSSI threshold is passed to mac_add().

2.2 The mac_add() filter is the key

libpax/lib/libpax/libpax.cpp:

IRAM_ATTR int mac_add(uint8_t *paddr, snifftype_t sniff_type) {
  // Check locally administered bit first (cheapest check)
  if (!(paddr[0] & 0b10)) return 0;

  // Use last 2 bytes of MAC address as ID (little-endian)
  uint16_t id = (paddr[5] << 8) | paddr[4];

  int added = add_to_bucket(id, sniff_type);
  ...
}

Interpretation:

  • Bit 1 of the first MAC octet is the locally administered bit.
  • if (!(paddr[0] & 0b10)) return 0; returns early when the bit is not set, i.e. it ignores universally administered (burned-in/static) MAC addresses and only counts locally administered (randomized) addresses.
  • The ID is not the MAC address. It is a 16-bit value made from the last two bytes of the address.
  • The ID is stored in a 65,536-bit bitmap (seen_ids_map_ble), so a device is counted at most once per bitmap epoch.
  • The bitmap is cleared every report cycle (libpax_counter_reset()), which defaults to 60 seconds.

This is a privacy choice: the code does not persist MAC addresses and does not use the full address. It is also a measurement choice with large consequences: the count is not a count of all nearby devices, and it is not a count of people.

The upstream documentation says:

"Identifiers are generated by using the last 2 bytes of universal MAC adresses. Personal MAC adresses remain untouched and are not evaluated." — https://paxcounter.org/legalnote/

The code's bit test appears to do the opposite of the documentation's wording: it counts locally administered addresses and skips universal ones. This may be a documentation lag, a byte-order subtlety, or a change in the implementation. The paper should report the code behavior and flag the discrepancy, not silently repeat the documentation.

2.3 Wi-Fi path

libpax/lib/libpax/wifiscan.cpp uses ESP32 promiscuous mode and captures management and data frames:

const wifi_ieee80211_packet_t* const ipkt =
    (wifi_ieee80211_packet_t*)ppkt->payload;
mac_add((uint8_t*)ipkt->hdr.addr2, MAC_SNIFF_WIFI);

It hops channels on a timer. Upstream default channel map is 1/3/6/9/11 (or all channels in some configs), with a 0.5 s switch interval. The default build config enables Wi-Fi counting and disables BLE counting; a deployment that follows the challenge brief ("Bluetooth signals") must have changed this. The CSV does not expose the Wi-Fi/BLE split.

Paper implication. The public description says "Bluetooth"; the reference implementation defaults to Wi-Fi and supports both. The delivered CSV has only densityData and batteryData, not separate wifi/ble counts. The unit of value is therefore ambiguous: it may be pax = wifi + ble, BLE-only, or Wi-Fi-only depending on the deployment. This is an open provenance question, not a detail to guess.


3. Failure modes visible in the code

2.1 Only randomized addresses are counted

If the deployed firmware uses the current mac_add() logic, devices that transmit a universal/static MAC are invisible. Modern phones and watches usually use resolvable private addresses (randomized) for BLE, so this may be intentional: the counter counts the privacy-preserving addresses, not the stable identity. But the consequence is that the population is not "all devices"; it is "devices currently using a locally administered address that the scanner hears." Devices with static addresses, some IoT devices, and some older hardware are excluded. The count is a sample of a particular address regime, not a device census.

2.2 A 16-bit ID space collides

The bitmap has 2^16 = 65,536 slots. With n distinct IDs in one 60 s epoch, the expected number of colliding pairs is approximately:

E[collisions] ≈ n(n - 1) / (2 × 65,536)

Examples (assuming uniform hashing, which is an approximation):

Distinct IDs in 60 s Expected colliding pairs Approx. probability of at least one collision
50 0.019 ~1.9%
100 0.076 ~7.3%
200 0.304 ~26%
300 0.685 ~50%
500 1.90 ~85%

At a busy inner-city corner, hundreds of devices in a minute are plausible. Collisions cause undercounting, and the error grows quadratically with density. The 16-bit hash is a deliberate privacy/space trade-off, but it makes the counter non-linear at exactly the moments a staffing decision cares about.

2.3 The counting window is not a 15 min count

The upstream report timer resets the bitmap every SENDCYCLE (default 60 s). The operator's blog says the deployed firmware hashes MACs and stores them for at most one hour, which suggests a one-hour dedup cache rather than a 60-second bitmap. Either way, the CSV has a ~15 min cadence (median 15.3 min), and the aggregation rule is undocumented. Plausible rules:

  • mean of 15 one-minute unique counts,
  • maximum of 15 one-minute counts,
  • sum of 15 one-minute counts,
  • a count over a different window entirely.

These are not equivalent. A mean of per-minute unique counts is not the number of unique devices in 15 minutes; a sum double-counts devices that persist across minutes. The challenge's own open question asks what the unit of densityData is (see OKF_Vault/mission/data.md). The paper must state that the unit is undocumented and that this limits absolute-count claims.

2.4 Queue drops under density

blescan.cpp:

#define BLE_ADV_QUEUE_SIZE 60
...
if (xQueueSend(adv_queue, (void *)&send_data, (TickType_t)0) != pdTRUE) {
  ble_adv_dropped = ble_adv_dropped + 1;
  ESP_LOGD(TAG, "Failed to enqueue advertising report. Queue full.");
}

The code counts dropped advertising reports in ble_adv_dropped, but the variable is not part of the normal payload and is not in the CSV. Under high device density, reports can be dropped before mac_add() ever sees them. The code comments explicitly raise the queue from 30 to 60 "to give more headroom under high device density, where accurate counting matters most." The deployed data cannot tell us how many reports were dropped.

2.5 RSSI threshold and physical layer

Both BLE and Wi-Fi paths apply an RSSI filter (ble_rssi_threshold, wifi_rssi_threshold). Upstream default is 0 (disabled), but a deployment can set a threshold. Range, antenna orientation, body shielding, enclosure, mounting height, and crowding all change what is heard. A person behind a wall or in a crowd may be invisible; a person near the sensor may be counted once per 60 s. The count is a detection process, not a sample of a well-defined catchment area.

2.6 Clock and time sync

The device can sync time from LoRaWAN, GPS, or an RTC. If time sync fails, the 60 s report cycle still runs, but the timestamp attached by the backend may drift. The CSV has UTC timestamps and a 15 min cadence; the paper should not assume perfect clock alignment across sensors. The mission/data.md notes DST handling as a preprocessing requirement.

2.7 LoRaWAN delivery

The payload is sent over LoRaWAN. The CSV is the backend's view, not the device's view. Lost uplinks, network congestion, and retransmissions can remove readings. The 4–6 day gaps in the 8-sensor network are consistent with power, maintenance, or LoRaWAN coverage problems; the challenge package does not document the cause. The paper should treat gaps as missing not at random until proven otherwise.


3. Privacy reading

The reference implementation's privacy disclosure is real but narrow:

  • It does not persistently store MAC addresses.
  • It does not transfer MAC addresses over LoRaWAN.
  • It stores a 16-bit ID derived from the last two bytes of the address, in RAM, for one report cycle.
  • It does no fingerprinting beyond the address hash.

This is better than storing raw MACs. It is not a formal anonymization guarantee:

  • The raw MAC is observable at the sensor before hashing.
  • A 16-bit ID space is small; collisions are both a counting error and a privacy ambiguity.
  • If an adversary can observe the same device at the sensor and correlate the 16-bit ID with another source, the "anonymous" count can become linkable.
  • The code's legal note warns that sniffing MAC addresses may be illegal depending on jurisdiction and cites the Dutch DPA's Wi-Fi tracking enforcement (see the legal research note).
  • The challenge's "privacy-preserving" label describes the aggregation architecture, not a legal or mathematical guarantee. The paper should say exactly that.

4. What this means for the paper

4.1 Claims the code supports

  • The reference design counts unique locally administered MAC hashes per scan cycle, not people.
  • The upstream implementation uses a 16-bit hash, so collisions are expected at high density; the deployed hash length is unknown.
  • It does not persist raw MACs, which is a meaningful privacy-by-design choice; the operator says the deployed cache is capped at one hour.
  • It has no exposed drop counter in the delivered data, so undercount from queue overflow cannot be quantified.
  • The upstream default config is Wi-Fi on, BLE off; the challenge's "Bluetooth" description implies a deployment-specific configuration.

4.2 Claims the code does not support

  • "The sensor counts all nearby smartphones."
  • "The count is a census of people."
  • "The count is anonymous in a formal sense."
  • "The count is linear in crowd density."
  • "The count is comparable across sensors without calibration."

4.3 A useful paper table

Property Reference implementation Consequence
Radio BLE passive scan; Wi-Fi promiscuous mode Detection depends on address type and channel
Address filter Locally administered bit only Static/universal devices excluded
ID Last 2 bytes, 16-bit Collisions grow with density
Dedup window Upstream: 60 s bitmap reset; operator: hashed cache up to 1 h Count is not a 15 min count; exact window undocumented
Hash length Upstream: 16-bit ID; deployed: unknown hash Collision rate depends on the deployed hash
Aggregation to CSV Undocumented Unit ambiguity; mean/max/sum differ
Drop visibility Internal counter, not in payload Undercount cannot be corrected
Raw MAC storage None persistent; RAM only Privacy-by-design, not formal anonymity
Legal status Upstream warns may be illegal Requires jurisdiction-specific analysis

4.4 Wording for the paper

The reference PAX counter is a privacy-by-design device: it hashes the last two bytes of locally administered MAC addresses into a 16-bit bitmap and clears the bitmap every 60 seconds. That design avoids persistent MAC storage, but it also means the published count is not a device census. It excludes universally administered addresses, collides at high density, and depends on an undocumented aggregation from 60-second scan cycles to 15-minute CSV rows. The challenge's "privacy-preserving" label is therefore an architectural claim, not a measurement guarantee.


5. Open questions to resolve before submission

  1. Which firmware version and build flags did Code for Heilbronn deploy? BLE only, Wi-Fi only, or both?
  2. What is the exact SENDCYCLE, BLESCANWINDOW, BLESCANINTERVAL, RSSI threshold, and channel map?
  3. How does the backend aggregate 60 s counts into the 15 min value? Mean, max, sum, or something else?
  4. Is value pax, ble, or wifi? The CSV does not say.
  5. What is the sensor mounting height, antenna, enclosure, and catchment area?
  6. Were the 4–6 day gaps caused by power, LoRaWAN, maintenance, or something else?
  7. Can the deployment expose ble_adv_dropped or a health metric to estimate undercount?
  8. Is there any ground-truth count (manual, camera, POS) for even a few hours?

Until these are answered, the paper should present the code audit as evidence of structural limitations, and the empirical data analysis as evidence of observed instability, not as a calibrated error rate.


6. Sources