#Device and sensor hub

GeoSpaX reads location and remote-sensing data straight from connected devices: phones, GPS/GNSS receivers, sports watches, drones, cameras, sensor loggers and live IoT sensors. A plugged-in device can start a recipe by itself (AUTOMATION.md §3, device trigger), and a live sensor reading can too (sensor trigger: a threshold or a geofence). That's the lazy-mapper promise: plug it in, get a map. A sensor sees something, get a map.

#1. What GeoSpaX reads

#2. Connections by edition and OS

#3. Automatic workflows

A device recipe runs when its Auto switch is on (UI, --auto, GEOSPAX_AUTO): the device hub calls the automation engine for every new or changed device with geodata, and the matching recipe gets the device folder as source (AUTOMATION.md §3). A recipe that takes the device replaces the plain auto-import.

Drop folders are the exception (v1.0). Files put into ~/GeoSpaX/Inbox (installed desktop app) or into an --inbox DIR (server) are taken by the matching device recipe without an Auto switch, because putting them there is the consent. Plugged-in phones, cameras and loggers still wait for Auto or a click (§5). The hub also remembers the content signature it last handled (<state>/devices/seen.json): a device that stays plugged in across a restart is listed but not processed again, while new photos, tracks or appended sensor rows trigger a new run. Live readings go the same way through the sensor trigger.

#3a. Send from phone (phone link)

The lazy way to get photos and tracks off a phone: no cable, no app, any OS (Windows, macOS, Linux) and any phone (Android, iPhone).

1. In GeoSpaX, Devices → Send from phone → Turn on. A QR code appears (web edition: or start with --phone).
2. Point the phone's camera at it. The phone opens the GeoSpaX page and warns once about the certificate, which is this computer's own: choose Advanced → Continue.
3. Choose files (photos from the gallery, GPX/KML tracks, sensor CSVs), Take a photo, or Share live location. When the files are in, GeoSpaX moves them as one batch into the drop folder, the matching recipe (photos-to-map, track-to-map, sensor-log-to-map) runs, and the finished map appears on the phone too.

Where photo locations come from. Phones often strip GPS from photos picked in the browser, so GeoSpaX tries in order:

• the photo's own EXIF GPS;
• a position from the phone itself: Take a photo sends the phone's GPS position along, and GeoSpaX writes it into an XMP sidecar (IMG.jpg.xmp) only if the photo has no location of its own;
• the GPS track by time. While Share live location is on, the phone's live track goes into the batch as a timed GPX, and photos without GPS are placed on it by their capture time. The same works for any device or folder that holds a GPS track (a Garmin GPX next to camera photos, say): GeoSpaX interpolates between the two track points around the photo time, if they are at most 5 minutes apart, and snaps to the nearest point within 60 s of either end. The camera's time zone comes from EXIF OffsetTimeOriginal, else this computer's. Lightroom, darktable and digiKam sidecars (exif:GPSLatitude) are read too.

The photos layer records how each photo got its position in a placed field (exif, sidecar, track), and GET /api/devices counts them (photos_placed).

Safety.

• The phone link is off until you turn it on (remembered across restarts; Turn off closes the port).
• It listens on its own port (default 8765, or the next free one) with HTTPS. Every request needs the 128-bit pairing code from the QR code; New code changes it, and phones paired earlier must scan again.
• Apart from upload and commit it forwards only live positions, run status and finished maps; settings and data are out of reach.
• Uploads are limited to 64 MB per file (videos are not mapped). A batch the phone never finishes is committed after two quiet minutes.
• Files land in the drop folder: desktop ~/GeoSpaX/Inbox/Phone <date time>/, web edition --inbox or <state>/phone/From phone/.
• The certificate and pairing code live in <state>/phone/. On Windows the firewall asks once whether GeoSpaX may accept connections on private networks.

#4. Sensors in detail

#Sensor files on a device

A file is a sensor log when its first lines say so (no configuration):

• CSV / TSV / TXT (comma, semicolon or tab; quoted fields; decimal commas with semicolons): the header has a latitude column (lat, latitude, gps_lat, geo:lat, locationLatitude(WGS84) …) and a longitude column (lon, lng, long, longitude, geo:long …). A time column (time, timestamp, datetime, loggingTime …) is kept as text.
• JSON lines / JSON arrays (.jsonl, .ndjson, .json): records with lat/lon keys, a nested location/position object, or a GeoJSON Point geometry (values from properties).
• FIT (.fit): every record message with a position.

Every numeric column becomes a measurement (up to 32 per file, 64 per device). Names are cleaned to snake_case and units are taken from the header (PM2.5 (µg/m³) → pm2_5 in µg/m³; Temperature [°C] → temperature in °C). Bookkeeping columns (ids, accuracy, HDOP, satellites, bearing) are skipped, and rows without a fix (empty or 0/0 coordinates) are counted and skipped. A logger that moved (timed rows a few metres apart) also gets a track; a list of fixed stations does not. The device's GeoPackage gains a readings layer: time, source, device and one real field per measurement, so every tool, recipe step and R/Python code step can use it.

#Live readings over HTTP

POST /api/devices/live takes one JSON object per reading:

{ "id": "aq-01", "name": "Market street monitor", "lat": -5.8601, "lon": 144.2302,
  "values": { "pm2_5": 41.2, "pm10": 66.0, "temperature": 23.1 } }

• Flat numeric keys work too ({"id": "probe-7", "lat": …, "lon": …, "soil_moisture": 31.5}), and numeric strings count.
• A reading without lat/lon uses the sensor's last position (fixed stations send it once).
• t is optional: seconds or milliseconds since 1970, or ISO 8601 text.
• Live ids are sensor-<id> for sensors and phone-<id> for the phone page.
• The response gives the live id: {"ok": true, "device": "sensor-aq-01"}.

#Live readings over MQTT

--mqtt mqtt://[user[:password]@]host[:1883]/topic/filter/# (repeatable; desktop: GEOSPAX_MQTT=url1,url2). Each message is parsed like an HTTP push.

Brokers on the internet need TLS: mqtts://[user[:password]@]host[:8883]/topic/#. The broker's certificate must be valid for the host name and signed by a CA in Mozilla's list (the webpki-roots set, built in, so it works the same on every OS). There is no switch to skip the check. Options after ?:

Paths with spaces or & are percent-encoded (%20, %26). When TLS fails, the Devices pane says why in words: the CA is unknown (add ?ca=), the certificate is for another host name or has expired, the broker wants a client certificate, or the port speaks plain MQTT. The device id comes from the payload (id, device, sensor_id, tid) or else from the topic (sensors/aq-02 → sensors-aq-02). Supported payloads:

• the generic JSON above;
• OwnTracks location messages (_type: location; tst, acc, vel in km/h, batt). A phone running the free OwnTracks app becomes a live device, with no GeoSpaX app on the phone.

Messages that are not JSON objects are counted as ignored. The Devices pane shows each subscription's state, message count and last error, with passwords masked.

#LoRaWAN sensors (The Things Stack, ChirpStack)

LoRaWAN sensors talk to gateways, and the gateways forward to a network server. GeoSpaX subscribes to the network server's MQTT feed and recognises its uplink messages, so no adapter or mapping file is needed:

Or, without a broker: add a webhook integration in The Things Stack pointing at https://your-geospax/api/devices/live (uplink messages only). The same message format is understood over HTTP.

What one uplink becomes:

• Device: the device id (TTN) or device name (ChirpStack); the Devices pane shows LoRaWAN · TTN or LoRaWAN · ChirpStack as the source.
• Values: every number in the decoded payload (decoded_payload or object, so set up a payload formatter or codec). One level of nesting is flattened (battery.voltage → battery_voltage). It also adds rssi and snr of the strongest gateway and gateways (how many heard it), which is handy for coverage maps.
• Position, first that applies:
  1. latitude/longitude in the decoded payload (GPS trackers);
  2. the location set for the device in the network console;
  3. the strongest receiving gateway's location, with an accuracy of 2,000 m. The sensor is somewhere near that gateway, which is enough to see which area a reading belongs to but not for a street-level map.
• Ignored: join, ack, downlink and status events (they carry no readings).

Sensor triggers work as for any live sensor: air-quality-alert fires when a LoRaWAN node reports pm2_5 above 35.

#OGC SensorThings services

The OGC SensorThings API is how many public sensor networks publish their data: air-quality and water-level networks, FROST servers, city IoT platforms. --sta https://host/v1.1 (desktop: GEOSPAX_STA=url1,url2) polls a service; options go after ?, joined with &:

Big city platforms list tens of thousands of Things; use bbox= for the area you map instead of raising max.

Tested against two public services (October 2026):

• One request per 100 stations asks for each Thing's location and, per datastream, only the newest observation ($expand=…Observations($orderby=phenomenonTime desc;$top=1)). Pages follow @iot.nextLink.
• Each Thing with a point location becomes a live sensor sta-<service>-<id> with the Thing's name. The service part is name= or the telling part of the host name (iot.hamburg.de → sta-hamburg-6211), so two services never mix up their stations. Values are named after the observed property and its unit: PM2.5 in µg/m³ → pm2_5, Water level in cm → water_level. Accented letters are folded (Température → temperature); two datastreams with the same name become pm2_5 and pm2_5_2. Things without a location and non-numeric results are skipped.
• A station is updated only when its newest observation is newer than at the last poll, so readings are not duplicated and triggers fire once per real observation.
• The Devices pane shows each service with its number of stations, updates and the last poll time, or the error (screenshot).

To try all of this without hardware, scripts/demo-sensor-networks.py serves a SensorThings service with stations in Port Moresby and publishes TTN and ChirpStack uplinks to a local broker:

python3 scripts/demo-sensor-networks.py --mqtt 127.0.0.1:1883 --topic sensors --sta-port 8140 &
geospax-server --mqtt "mqtt://127.0.0.1:1883/sensors/#" --sta "http://127.0.0.1:8140/v1.1?every=10&name=demo" --auto air-quality-alert

#Sensor triggers

triggers:
  - sensor: { field: pm2_5, above: 35, cooldown: 30m }          # threshold, any live sensor
  - sensor: { field: water_level, above: 2.4, device: "gauge-*" } # wildcard on the sensor id or name
  - sensor: { inside: farm.parcels }                             # geofence: a phone/GNSS/sensor enters a polygon layer
  - sensor: { field: temperature, below: 2, inside: farm.parcels, cooldown: 2h }   # frost inside the parcels

• above: / below: need a field:. A geofence alone fires on entering (outside → inside).
• With a field, a geofence restricts the threshold to readings inside the polygons.
• cooldown (default 10 min) is per recipe and per device.
• The run gets ${trigger.device}, ${trigger.value}, ${trigger.threshold}, ${trigger.lat}, ${trigger.lon}, ${trigger.text} (e.g. "AQ CI reported pm2_5 = 48 (above 35) at 08:41") and every value of the reading.
• Inputs named device, lat and lon are filled in.

#Sensor steps

• sensor.snapshot writes the last minutes of live readings to <recipe>.live_readings, each sensor's path as <recipe>.live_tracks, and its latest position (labelled with its name) as <recipe>.live_latest.
• sensor.summary computes count, mean, 95th percentile and maximum per measurement, and flags air quality against the WHO 2021 global air quality guidelines: PM2.5 15 µg/m³ and PM10 45 µg/m³ (24-hour), NO₂ 25 µg/m³ (24-hour), O₃ 100 µg/m³ (8-hour), SO₂ 40 µg/m³ (24-hour), CO 4 mg/m³ (24-hour).
  • It picks the field to map: a pollutant first, then heart rate, CO₂, noise, temperature …
  • The report says plainly that single readings only indicate exposure and are not 24-hour means.
• AutoMap classes PM2.5 and PM10 at the guideline and the WHO interim targets.
  • PM2.5: 15 / 25 / 37.5 / 50 / 75 µg/m³. PM10: 45 / 50 / 75 / 100 / 150 µg/m³.
  • Colours follow an air-quality index, from green ("guideline met") to dark red ("above IT-1").
  • This replaces statistical breaks that mean nothing to a reader.

#5. Privacy and safety

• Location history and photo locations are personal data. Auto-import is off by default: the first time a device appears, GeoSpaX asks. Drop folders (§3) are the only exception, because you put the files there yourself.
• Live sharing from a phone needs an explicit Start on that phone and stops when the page closes. OwnTracks shares only what you configure in the app.
• The phone link (§3a) is off until you turn it on, needs the pairing code from the QR code on every request, uses HTTPS, and stays on your network.
• Everything stays on the machine (desktop) or your own server (web). Nothing goes to third parties; the MQTT broker is one you run or choose.
• MQTT credentials are never shown in the UI or logs. Use mqtts:// for any broker outside your LAN: certificates are always verified, and there is no "insecure" switch. API keys belong in the URL's password part, which is masked everywhere.
• Exports strip EXIF location unless you choose to keep it. Imports can be forgotten per device.

#6. Architecture

 device roots (mounts, gvfs, --watch dirs)        live sources
        │  poll every 5 s                          phone page / sensors: POST /api/devices/live
        ▼                                          MQTT/TLS subscriber (OwnTracks, sensor JSON, LoRaWAN)
                                                   SensorThings poller
  DeviceWatcher ──► scan (bounded walk, classifiers)  NMEA serial/TCP/file · gpsd
        │            photos: EXIF GPS + DJI XMP                 │
        │            tracks: GPX/KML (GDAL), NMEA, SRT          ▼
        │            sensor logs: CSV/TSV/JSON, FIT       LiveStore (fixes + readings per device)
        ▼                                                    │            │
  import job (job registry) ──► <state>/devices/<id>.gpkg    │            └─► sensor hook ──► sensor triggers
        │                photos · tracks · waypoints · readings              (threshold, geofence, cooldown)
        ▼                                                    ▼
  layers hot-registered in the engine ──► map, symbology,   GET /api/devices/live · /api/devices/readings
                                          recipes, triggers

• Code:
  • crates/engine/src/devices.rs: discovery, scan, import, live store, NMEA/gpsd/SRT parsers.
  • crates/engine/src/sensors.rs: sensor CSV/JSON/FIT readers, live message parsing (including LoRaWAN uplinks), the MQTT client with TLS, WHO guideline levels.
  • crates/engine/src/sta.rs: OGC SensorThings polling.
  • automation/mod.rs (on_sensor): sensor triggers.
• Device trigger:
  • With a device recipe on Auto, a new device runs that recipe: import → AutoMap → finished map → report.
  • Without one, --auto-import (desktop: GEOSPAX_AUTO_IMPORT=1) still imports new devices without a click.
  • Several devices at once queue one run per device (measured: phone, drone card and two GPS folders were mapped in 0.3 s after the first scan).
• geospax run photos-to-map --input source=/media/$USER/PHONE does the same from the command line. source: auto picks the connected device (phones and cameras first, sensor loggers last).

#7. What is built (v1)

API

Options (server flags; desktop environment variables)

Imported devices persist: their GeoPackages are re-registered at startup. A device with point clouds imports a point_clouds layer: one footprint per LAS/LAZ file with its points, coordinate system, LAS version and height range (a tile index). Measured results: bench/RESULTS.md §10 (devices), §13 (sensors), §17 (sensor networks) and §18 (LiDAR).

The UI has a Devices section in Contents. It lists detected devices with photo, track, reading and point-cloud counts (and the measurements), live devices with their tracks, live sensors with their latest values, MQTT status and SensorThings services. Import & map styles the new layers with AutoMap (GET /api/layers/{id}/autostyle), the same choice a recipe makes: readings come out coloured by their main measurement, PM in WHO classes. Send from phone (§3a) shows the QR code for the phone link; the phone page it opens sends files, geotagged camera photos and live location. scripts/demo-sensor-feed.py simulates two walking air-quality sensors (HTTP or MQTT) for demos.

Next: BLE sensors, GoPro GPMF, thermal and multispectral frames, SensorThings MQTT extension (push instead of polling).