Skip to content

About

Android and Wear OS sensing SDK: continuous phone and watch sensor collection for research apps.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

8 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

sensing-sdk-android

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.

What you get

  • 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.

Getting started

0. Check your toolchain

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.

1. Get the SDK

Clone it beside your app:

~/code/my-app/
~/code/sensing-sdk-android/

2. Add it to your build

// 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.

3. Initialise it in your Application

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.

4. Say which sensors run

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.

5. Implement consent

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.

6. Choose where data goes

  • 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 at fromOffset), commit (confirm it is stored). A file is deleted only after commit returns Ok; failures retry with backoff; return InitResult.Unavailable when offline, which does not count as a failure.
  • The bundled HTTPS contract: add sensing-cloud and install CloudPlugin against a server that implements its /v1 endpoints (register, config, chunk init/commit with signed-URL upload, events).

7. Ask for what is missing

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.

8. Start and stop

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.

9. Show status (optional)

  • 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.

10. Before you ship

  • 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.

11. Check that it works

./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 status

sample/ 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

Modules

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

Making it yours

  • Consent and the catalog are yours. Implement ConsentPolicy and SensorCatalog; a sensor absent from the catalog never runs.

  • Text is yours. Override any string in sensing-service/src/main/res/values/strings.xml by defining the same name in your app (titles receive your app's label).

  • Names are yours. Sensing.init { names(SensingNames(...)) } and RelayNames.current set 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|specialUse and 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.

A paired watch

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.

Requirements

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.

Data format

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.

License

Not yet chosen.

About

Android and Wear OS sensing SDK: continuous phone and watch sensor collection for research apps.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages