opensensor.space mobile (Android and iOS)

The phone app for opensensor.space, a home for open sensors of every kind. Air quality is the first device family. Weather, water, soil, noise and energy families plug in the same way, as data rather than new screens.

The app does three things.

1. Discover. On first open, before you own anything, a map shows public sensor readings near you as H3 hexagon cells, never exact points. Tap a cell to see its devices and the average, minimum and maximum of what they measure. Tap a device to see its readings with range and metric filters. Until the public feed is live on S3 and source.coop, the map shows labelled sample data. See docs/devices-and-discovery.md.
2. Collect. Pair your own devices over Bluetooth LE, then collect their immutable Parquet files over BLE or your local Wi-Fi into a verified archive on the phone. A file counts as synced only after its size, CRC-32 and PAR1 checks pass.
3. Understand. Simple screens say what the readings mean in plain words, with the peacock as a guide. Detailed and Developer levels reveal per-file, per-metric and protocol detail only for the people who want it.

Private by design. The archive lives on the phone and works without internet. LAN connects only to devices found through _ossync._tcp mDNS, with a token obtained over bonded BLE. The only other network use is anonymous, read-only downloads of the public map feed and basemap, which a Settings switch turns off. Sharing a device's own data is off by default and is turned on per device, in that device's settings, with confirmation. No accounts, no analytics. Approximate foreground location is asked only on the Near me or Use phone location tap. Device settings can save a privacy-limited H3 area to your sensor, starting at resolution 8, with an optional declared country. Exact phone fixes are never saved or sent. See device location. Public data carries H3 cells, never coordinates.

One product on two phones. Rules that must give the same answer on Android and iOS live in shared Kotlin, and screens share one design system based on the opensensor.space website. See docs/cross-platform-guide.md.

Platform status

Platform	Current scope	Verification
Android	Multi-device BLE/LAN collection, verified local archive, offline history, and background sync	Host gate passes; phone qualification is tracked separately in docs/status.md and the CoreS3 and Waveshare records.
iOS	The same shared screens, BLE and LAN collection into a verified local archive, offline history and per-device Auto-sync	Host, simulator and native checks pass. iPhone runs are tracked in docs/status.md, see docs/ios.md

Host tests, simulator builds, and phone observations are different evidence. The app ID is space.opensensor.app on Android and iOS. Read the full status record for dated results and remaining checks.

Documentation map

The docs are split by concern so you read only what you need. Start at docs/README.md for the routing table; the rules are in AGENTS.md.

flowchart LR
  P[protocol-quickref] --> T[transports] --> S[sync-engine] --> D[data-model] --> H[history-pipeline] --> U[screens]
  S --> B[background-sync] --> U
  Q[parquet] --> S
  Q --> H

Concern	File
Product direction, device families, public H3 discover map, sharing rules	docs/devices-and-discovery.md
Keeping Android and iOS the same, adding a sensor family or transport	docs/cross-platform-guide.md
Device identity, fixed names, reset and reflash recovery	docs/device-identity.md
What is verified, where, and what is next	docs/status.md
Modules, layers, "what a change touches"	docs/architecture.md
iOS app, shared Kotlin boundaries, build and qualification	docs/ios.md, ios/AGENTS.md
Screens, navigation, detail levels	docs/screens.md
Opcodes, frames, error codes, UUIDs, LAN framing (mirror of the firmware contract)	docs/protocol-quickref.md
BLE vs LAN, pairing, the LAN token, reconnect

iOS app and current scope

The iOS app uses Kotlin Multiplatform for shared protocol and sensor rules, with a Compose Multiplatform live-reading screen and native Core Bluetooth and Bonjour adapters. The Android app retains its native Compose UI and platform data stack. Both platforms can collect over Wi-Fi after each phone saves access through BLE pairing. The shared firmware allows three Wi-Fi clients per sensor alongside one BLE connection; both apps can sync two sensors concurrently per phone. History/export UI and background collection remain Android features while iOS migration continues. Build and qualification instructions are in docs/ios.md; local iOS coding instructions are in ios/AGENTS.md. On 2026-10-08, the owner confirmed live readings, Bonjour discovery, saved Wi-Fi access and collection starting on a connected iPhone. Pairing prompts, reading accuracy, stale/background behavior and completed-file phone verification still need qualification. The iPhone card now shows average KiB/s; dated transfer evidence separates measured CoreS3 host throughput from pending phone speed checks.

Build

Android and host gate:

export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
tools/setup-hooks.sh                 # once per clone: git hooks (ktlint, gitleaks, hygiene; verify on push)
./gradlew --no-daemon clean verify   # lint + assembleDebug + every module's unit tests
adb install app/build/outputs/apk/debug/app-debug.apk

The iOS build requires macOS and Xcode. Follow docs/ios.md for simulator framework linking, the Xcode build, and real-iPhone qualification steps. GitHub Actions validates shared Kotlin iOS tests and unsigned simulator Debug/device Release builds on Apple Silicon with Xcode 27 and the iOS 27 SDK. Simulator apps and failure reports are retained as workflow artifacts; iOS signing and TestFlight setup are documented in docs/build-and-release.md.

Ready-made APKs: every push to main refreshes the rolling latest pre-release; a v* tag publishes a permanent release. Details, signing and the debug fake device: docs/build-and-release.md. The release page distributes Android APKs and links to iOS simulator artifacts in Actions. Signed iPhone/TestFlight distribution is not available yet.

Layout

core/protocol/   KMP common rules + JVM adapters · contract mirror: UUIDs, frames v1+v2, CONFIG, LAN framing, JSON, PAR1/CRC verify
core/parquet/    JVM-only · own Parquet reader + writer (GeoParquet 2.0, LZ4/Snappy/GZIP, codec SPI) · test fixtures
core/history/    KMP sensor-domain rules + JVM file adapters · Metrics registry (moving to core/model), Aggregator → tiers, TimeEstimate, Columns, AirMood, file index
app/             Android app · data/{ble,lan,sync,background,history,local,settings,export,fake} · ui/{scan,device,history,files,debug,settings}
ios/shared/      Kotlin Multiplatform presentation state and Compose Multiplatform live screen
ios/App/         Xcode app · Swift/Core Bluetooth/Bonjour platform adapters
tools/           fixture generators + PyArrow/DuckDB oracle (run in ../opensensor-space-firmware's pixi env), hooks, signing
docs/            one file per concern (see the map above)

Planned (see the production plan)
build-logic/        convention plugins for every module
core/model/         Device, DeviceFamily, Capability, ObservedProperty, Scale, family registry
core/sync/          one sync engine for both phones behind FrameLink and ArchiveStore ports
core/designsystem/  opensensor.space tokens, theme and shared components (Compose Multiplatform)
core/publicfeed/    public discover feed port, sample fixture, later Parquet over HTTP
feature/discover/   shared map, cell sheet and public device page

The Bluetooth protocol is owned by the firmware repo (../opensensor-space-firmware/docs/shared/ble-sync-protocol.md); this app mirrors it and never changes a frame, opcode, UUID or JSON key first.

License & Attribution (CC-BY-4.0)

Walkthru.Earth original code in this repository (app/, core/, feature/, ui/, ios/, tools/, build-logic/, build files and documentation) is licensed under the Creative Commons Attribution 4.0 International Public License (CC-BY-4.0). See LICENSE and NOTICE. The CC-BY-4.0 license does not cover the third-party parts listed below, which keep their own licenses.

Attribution requirement. Any application, app store build, firmware image, hardware product, dataset, or documentation that uses or incorporates opensensor-space-mobile must include clear, visible attribution to Walkthru.Earth (https://walkthru.earth), for example

"Sensor sync and air quality views powered by Walkthru.Earth (walkthru-earth/opensensor-space-mobile), licensed under CC-BY-4.0."

Third-party notices

Component	Location	License	Copyright
Android Studio architecture template, the portions this project started from	spread through the Android project, per-file headers replaced by NOTICE	Apache-2.0, see apache.org/licenses/LICENSE-2.0	Copyright (C) 2022 The Android Open Source Project
Cairo font v3.130, from google/fonts ofl/cairo at commit a2c83daed9bc723922de8d0a9512990bd3d91df4	ui/designsystem/src/commonMain/composeResources/	SIL OFL 1.1, see Cairo-OFL.txt	Copyright 2009 The Cairo Project Authors
Quicksand font, the variable TTF from google/fonts ofl/quicksand	ui/designsystem/src/commonMain/composeResources/	SIL OFL 1.1, see Quicksand-OFL.txt	Copyright 2011 The Quicksand Project Authors

Libraries pulled in by Gradle (for example AndroidX, Kotlin, Compose Multiplatform, OkHttp and zstd-jni) are not copied into this repository. Each keeps its own license, and app builds that ship them must carry their notices.