Continuous, crash-proof sensor collection for Android phones and Wear OS watches — for research apps that must record all day, every day, and say exactly when and why they did not.
Group / package: com.rahulislam.sensing.
- 25 adapters across motion, environment, location (raw GNSS, fused, activity transitions, a satellite probe, an indoor/outdoor virtual sensor) and device state (battery, screen, network, hashed Wi‑Fi / Bluetooth scans, sound level in dBFS — never audio).
- A collection engine with per-sensor contiguous
seq, recorded gaps, and a write path nothing downstream can slow. - Crash-safe storage: framed, per-frame gzip + CRC32 chunk files that recover to the last valid frame after a kill or power loss; device-protected, so collection runs before the first unlock.
- A foreground service that stays up: START_STICKY, restart alarms with backoff, a chaining crash handler, boot/package-replaced receivers, WorkManager and alarm watchdogs, a policy-driven wake lock.
- Upload with per-chunk backoff, parking instead of dropping, and deletion only after commit — over any transport you write, or the bundled HTTPS one.
- Phone ↔ watch relay over the Wearable Data Layer.
- A permission gate derived from the sensors that will actually run, and nudges when something goes missing.
AGP 9.4.1, Kotlin 2.4.20, KSP 2.3.12, Gradle 9.6+, compileSdk 37 (minor 2),
minSdk 26. As an included build the SDK shares your Gradle plugin classpath,
so these must match gradle/libs.versions.toml.
Clone it beside your app:
~/code/my-app/
~/code/sensing-sdk-android/
// settings.gradle.kts
includeBuild("../sensing-sdk-android")
// app/build.gradle.kts
dependencies {
implementation("com.rahulislam.sensing:sensing-service:0.1.0") // required
implementation("com.rahulislam.sensing:sensing-sync:0.1.0") // to upload
implementation("com.rahulislam.sensing:sensing-adapters-motion:0.1.0") // the sensor groups you need:
implementation("com.rahulislam.sensing:sensing-adapters-device:0.1.0") // motion, environment, location, device
implementation("com.rahulislam.sensing:sensing-adapters-radio:0.1.0") // cellular, joined Wi-Fi, latency, Wi-Fi RTT
}sensing-adapters-radio is opt-in because of what it asks for: READ_PHONE_STATE, INTERNET, and
NEARBY_WIFI_DEVICES without neverForLocation, since Wi-Fi RTT measures distance. Cell ids, BSSIDs and
SSIDs are hashed per device. device.network_rtt connects to connectivitycheck.gstatic.com every 5 minutes
with nothing sent, so list it in your catalog only if you want that; its host extra changes the target.
The service, receivers, workers and the permissions each adapter needs merge into your manifest automatically.
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
Sensing.init(this) {
adapters(MotionAdapters.all() + DeviceAdapters.all())
catalog(MyCatalog)
consent { MyConsent(it) }
install { SyncPlugin(it) { MyUploader() } }
}
}
}Register it in AndroidManifest.xml (<application android:name=".MyApp">).
Sensing.init must run here, not in an activity: after a crash or a reboot
Android restarts the service with no UI.
object MyCatalog : SensorCatalog {
override fun forDevice(watch: Boolean) = listOf(
CatalogEntry(SensorId("motion.accelerometer"), "Accelerometer", "50 Hz",
SensorConfig(samplingPeriodUs = 20_000, maxReportLatencyUs = 1_000_000), defaultOn = true),
CatalogEntry(SensorId("device.battery"), "Battery", "on change",
SensorConfig(samplingPeriodUs = null), defaultOn = true),
)
}A sensor that is not in the catalog never runs. Sensor ids and their configs are listed in each adapter class.
class MyConsent(context: Context) : ConsentPolicy {
override fun allows(id: SensorId): Boolean = /* what the participant agreed to */
override val changes: Flow<Unit> = /* emit when that answer changes */
override fun snapshotJson(): String = /* the answer as JSON, for your records */
override fun mirror(snapshotJson: String, nowWallMs: Long) = Unit // only used by a paired watch
}Show your consent screen before collection starts, and persist the answer yourself (device-protected storage, so it can be read before the first unlock). There is deliberately no "allow everything" default.
- Keep it on the device:
SyncPlugin(it) { NoopTransport() }. - Your own server: implement
UploadTransport, three calls:init(may the server take this chunk?),upload(send the file, resuming atfromOffset),commit(confirm it is stored). A file is deleted only aftercommitreturnsOk; failures retry with backoff; returnInitResult.Unavailablewhen offline, which does not count as a failure. - The bundled HTTPS contract: add
sensing-cloudand installCloudPluginagainst a server that implements its/v1endpoints (register, config, chunk init/commit with signed-URL upload, events).
for (r in Sensing.instance.requirements.missing()) when (r.kind) {
RequirementKind.PERMISSION -> requestPermissions(arrayOf(r.permission!!), 1)
RequirementKind.BACKGROUND_LOCATION -> /* ask after foreground location; Android sends the user to Settings */
RequirementKind.NOTIFICATIONS -> /* POST_NOTIFICATIONS on 13+, or the app's notification settings */
RequirementKind.BATTERY_EXEMPTION -> startActivity(Intent(Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS,
Uri.parse("package:$packageName")))
}The list holds only what the enabled, consented sensors need right now; each
row names the sensors it is for. Check it again in onResume. While collection
runs, the SDK also posts a notification when something goes missing.
ServiceStarter.start(context, Reason.USER_ENABLED, fromForeground = true) // after consent and permissions
ServiceStarter.stop(context)Once started, collection survives app kills, crashes, reboots and updates until
stop is called.
Sensing.instance.status.status: running, paused or degraded, and why.Sensing.instance.engine.stats: samples per second, per-sensor counts.Sensing.instance.liveBus.samples: every sample as it is stored, for live charts.
- Override the foreground-service special-use subtype to match your Play Console declaration, and strip service types you do not use (see "Making it yours").
- Override the notification strings if the defaults do not fit.
- Decide your storage names (
names(SensingNames(...))) now: renaming them on an installed app orphans its data.
./gradlew :app:installDebug # start collection from your UI, then:
adb shell run-as <your.package> ls /data/user_de/0/<your.package>/files/sensing/chunks # one folder per session
adb shell am crash <your.package> # collection resumes within seconds
adb logcat -s sensing.service sensing.collect # state transitions and adapter statussample/ is the smallest app that follows these steps (./gradlew :sample:installDebug).
example/ is a full data-collection app on the SDK, phone and Wear OS, with no server: a required activity label, Start and Stop, live rates, a list of recordings with their rates and gaps, sensor and rate settings per device, permissions, export and diagnostics. Data stays on the device until someone exports it. Exports use the same sensing-export/1 format as the iOS SDK's example app, and that SDK's sensing-decode reads them.
./gradlew :example:phone:installDebug
./gradlew :example:wear:installDebug # on the watch; the same application id and signing key as the phone's| Module | Use it for |
|---|---|
sensing-service |
the graph (Sensing), the foreground service; brings model, api, storage, collection |
sensing-adapters-* |
the sensors — pick the groups you need |
sensing-sync |
uploading chunks through your UploadTransport |
sensing-cloud |
a reference /v1 HTTPS contract: registration, fleet config, heartbeats, signed-URL upload |
sensing-wear-relay |
a paired watch relaying through the phone |
-
Consent and the catalog are yours. Implement
ConsentPolicyandSensorCatalog; a sensor absent from the catalog never runs. -
Text is yours. Override any string in
sensing-service/src/main/res/values/strings.xmlby defining the same name in your app (titles receive your app's label). -
Names are yours.
Sensing.init { names(SensingNames(...)) }andRelayNames.currentset the prefs prefix, chunk directory, database and Data Layer paths. Pick them once: renaming on an installed app orphans its data. -
Play policy is yours. Override the special-use subtype to match your Play Console declaration, and strip service types you do not use:
<service android:name="com.rahulislam.sensing.service.CollectorService"> <property tools:replace="android:value" android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE" android:value="your declared use" /> </service> <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" tools:node="remove" />
The service declares
location|microphone|specialUseand uses only the types whose permission the app holds. If you collect no location or no audio, narrow the declaration too (tools:replace="android:foregroundServiceType"on the<service>), or Play will ask you to justify types you never use.
Install sensing-wear-relay in both apps (same applicationId, same signing key):
// phone
install { CloudPlugin(it, myTokens, endpoint = { myEndpoint }) }
install { SyncPlugin(it) { s -> s.plugin<CloudPlugin>().directTransport } }
install { PhoneRelayPlugin(it, PairingStore(it.context)) }
// watch
val pairing = PairingStore(this)
install { CloudPlugin(it, MirroredTokenProvider(pairing), paired = pairing, endpoint = { myEndpoint }) }
install { WatchRelayPlugin(it, pairing) }
install { SyncPlugin(it) { s -> s.plugin<WatchRelayPlugin>().transport } }Play Services binds the relay's listener services, so each app declares its own
in its manifest. The pathPrefix must equal RelayNames.current.prefix
(/sensing unless you change it), and each app advertises its capability:
<!-- phone -->
<service android:name="com.rahulislam.sensing.relay.PhoneRelayReceiver" android:exported="true">
<intent-filter>
<action android:name="com.google.android.gms.wearable.MESSAGE_RECEIVED" />
<action android:name="com.google.android.gms.wearable.CHANNEL_EVENT" />
<action android:name="com.google.android.gms.wearable.CAPABILITY_CHANGED" />
<data android:scheme="wear" android:host="*" android:pathPrefix="/sensing" />
</intent-filter>
</service>
<!-- watch: com.rahulislam.sensing.relay.WatchListenerService with DATA_CHANGED,
MESSAGE_RECEIVED and CAPABILITY_CHANGED, same <data> element --><!-- res/values/wear.xml: phone -->
<string-array name="android_wear_capabilities" translatable="false"><item>sensing_phone</item></string-array>
<!-- watch: <item>sensing_watch</item> -->Sensing.init fails at start-up if a relay plugin's required SyncPlugin is
missing.
CloudPlugin is optional. Leave it out and the link works the same: the
watch pairs, mirrors sessions and sends its chunks to the phone, and they stay
there, with your SyncPlugin deciding what happens next (NoopTransport keeps
them). The watch waits for the phone however long that takes, because it has no
token for reaching a server itself. example/ runs this way.
A paired watch collects all the time, which suits a study. For an app that
records from Start to Stop, pass collectWhenPaired = false to
WatchRelayPlugin and start the service from sensing.sessions.active. The
phone can take a Stop from the watch's own button: set
PhoneRelayPlugin.onStopRequested, and call WatchRelayPlugin.requestStop().
The two apps keep each other running. Each side pings the other every 5
minutes (pingIntervalMs, null turns it off). Play Services delivers a ping by
starting the peer's listener service — even when the peer app was killed or
force-stopped — and the peer then restarts collection. A participant who turns
collection off in the app stays off; only an in-app stop is a stop. While the
devices cannot reach each other (no Bluetooth, no shared internet) nothing can
be woken; each side keeps collecting locally and the queue drains on reconnect.
Tell participants this in your consent material.
AGP 9.4.1, Kotlin 2.4.20, Gradle 9.6+, compileSdk 37 (minor 2), minSdk 26.
As an included build the SDK shares your plugin classpath, so your AGP / Kotlin
/ KSP versions must match gradle/libs.versions.toml.
One .pb.gz file per sensor per chunk: repeated
[varint length][uint32 CRC32][gzip(SampleBatch)] frames, SampleBatch from
sensing-model/src/main/proto/sensorlog/v1/envelope.proto. Any gzip and
protobuf decoder can read it. Details in AGENTS.md.
Not yet chosen.