Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -1012,3 +1012,24 @@ because breaking it fails silently:
- **A running check ends the moment a different ring is paired** (`AccuracyRingWatcher`, started
from `PulseLoopApplication`). Ring rows carry no device id, so a later sweep could not split
the two rings' data.

## Health Connect as the data source: one app, no ring, nothing back

**Read this before touching `health/source/` or the export's exclusions.** Full design:
`docs/health-connect-source.md`.

A user without a PulseLoop ring can pick another device's app (Oura, Samsung Health, Fitbit) and
PulseLoop imports it from Health Connect into the ring's own tables. Three rules hold it together,
and each one fails silently if broken:

- **Every read carries a `DataOrigin` filter for the chosen package.** Unfiltered, PulseLoop's own
earlier exports come straight back in as "new" data, and two apps' steps sum into the same slot.
- **It goes through `EventPersistenceSubscriber.ingest`, not around it.** That path is what gives an
import deterministic ids, the user's deletions, and the waking-day sleep reconcile. Writing rows
directly would re-create every duplicate and resurrection bug the ring path already fixed.
- **While it is on, the export holds back every type, for all time** (`exportExclusions`, through
`ExportPause`). Exporting would write the source app's own data back to Health Connect under
PulseLoop's name. Don't narrow it to "the types the source writes": a type the source starts
writing next month would then echo.

It is exclusive with a paired ring: a `DeviceIdentified` turns it off.
6 changes: 6 additions & 0 deletions app/src/main/AndroidManifest.xml
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,12 @@
<uses-permission android:name="android.permission.health.READ_SLEEP" />
<uses-permission android:name="android.permission.health.READ_OXYGEN_SATURATION" />
<uses-permission android:name="android.permission.health.READ_HEART_RATE_VARIABILITY" />
<!-- Health Connect as the data source, no ring (health/source/HealthConnectSource.kt): the
accuracy check's reads above plus these. -->
<uses-permission android:name="android.permission.health.READ_TOTAL_CALORIES_BURNED" />
<uses-permission android:name="android.permission.health.READ_EXERCISE" />
<uses-permission android:name="android.permission.health.READ_RESPIRATORY_RATE" />
<uses-permission android:name="android.permission.health.READ_MENSTRUATION" />
<!-- Optional: lets the accuracy check's 6-hourly worker read without the app open. -->
<uses-permission android:name="android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND" />

Expand Down
1 change: 1 addition & 0 deletions app/src/main/java/com/pulseloop/PulseLoopApplication.kt
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ class PulseLoopApplication : Application() {
super.onCreate()
CrashLogger.install(this)
com.pulseloop.service.DrinkPrefs.init(this)
com.pulseloop.health.source.HealthConnectSource.isEnabled(this) // warms [HealthConnectSource.enabledNow]
// Application-scoped so capture runs whether or not the Debug screen is open.
DiagnosticsSubscriber(PulseLoopDatabase.getInstance(this)).start(appScope)
// Accuracy check: a different ring ends a running check at once (it can't be told apart later).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ class HealthConnectExportWorker(
client = client,
db = PulseLoopDatabase.getInstance(applicationContext),
store = store,
extraExclusions = com.pulseloop.health.source.HealthConnectSource.exportExclusions(applicationContext),
)
// The pass and "Remove PulseLoop data" must never interleave (review pass 5): a pass
// still inserting while the removal deletes would re-write records the user asked to
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,8 @@ class HealthConnectExporter(
private val db: PulseLoopDatabase,
private val store: HealthConnectPrefsStore,
private val now: () -> Long = { System.currentTimeMillis() },
/** Held back on top of the accuracy check's, for all time: the Health Connect source mode's. */
private val extraExclusions: List<com.pulseloop.health.accuracy.ExportExclusion> = emptyList(),
) {

/**
Expand Down Expand Up @@ -306,7 +308,9 @@ class HealthConnectExporter(
// advance past them (see [ExportPause]). Read once per pass; the pass runs under
// HealthConnectExportWorker.passMutex, which the resume choice also takes, so a choice can't
// land halfway through a pass.
val exclusions = ExportPause.exclusions(db.accuracyDao().all(), db.accuracyDao().allPausedUnits())
// While Health Connect is the data source ([extraExclusions]), nothing it wrote goes back to it.
val exclusions = ExportPause.exclusions(db.accuracyDao().all(), db.accuracyDao().allPausedUnits()) +
extraExclusions
fun noteHeldBack(label: String, f: ExportPause.Filtered) {
if (f.heldBack > 0) skipped += "$label: ${f.heldBack} record(s) held back by the accuracy check"
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,8 @@ class WorkoutExporter(private val db: PulseLoopDatabase) {
): PendingWorkouts {
val wm = watermark ?: 0L
val sessions = db.activitySessionDao().finishedUpdatedSince(wm)
// A workout imported from Health Connect is already there, under its own app.
.filterNot { com.pulseloop.health.source.HealthConnectSource.isImportedWorkout(it.id) }
if (sessions.isEmpty()) return PendingWorkouts(emptyList(), emptyList())

// All GPS fixes for the pending sessions in one query — a first-enable backfill can
Expand Down
226 changes: 226 additions & 0 deletions app/src/main/java/com/pulseloop/health/source/HealthConnectSource.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,226 @@
package com.pulseloop.health.source

import android.content.Context
import androidx.health.connect.client.permission.HealthPermission
import androidx.health.connect.client.records.ExerciseSessionRecord
import androidx.health.connect.client.records.MenstruationPeriodRecord
import androidx.health.connect.client.records.RespiratoryRateRecord
import androidx.health.connect.client.records.SleepSessionRecord
import androidx.health.connect.client.records.TotalCaloriesBurnedRecord
import androidx.work.Constraints
import androidx.work.ExistingPeriodicWorkPolicy
import androidx.work.ExistingWorkPolicy
import androidx.work.OneTimeWorkRequestBuilder
import androidx.work.PeriodicWorkRequestBuilder
import androidx.work.WorkManager
import com.pulseloop.health.accuracy.AccuracyCheckPermissions
import com.pulseloop.health.accuracy.ExportExclusion
import com.pulseloop.health.accuracy.ExportUnit
import com.pulseloop.health.accuracy.ReferenceAppLabels
import com.pulseloop.ring.SleepStage
import com.pulseloop.ring.WearableCapability
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import java.util.concurrent.TimeUnit

/**
* "No ring, Health Connect instead" (docs/health-connect-source.md): the user wears another
* device — an Oura, a Galaxy Ring, a Fitbit — whose app writes to Health Connect, and PulseLoop
* reads that one app's records into the same tables a paired ring fills, so every screen works.
*
* Three rules hold the feature together:
* - **One source app, by package.** Every read carries a `DataOrigin` filter. Reading "everything
* in Health Connect" would pull PulseLoop's own earlier exports back in, and mix two devices'
* steps into one day.
* - **Exclusive with a paired ring.** Both would write the same 15-minute activity slots and the
* same nights; the screen refuses to switch on while a ring is paired.
* - **Nothing goes back.** While this is on, every exported type the source writes is held back
* from the Health Connect export ([exportExclusions]), or the app would echo the source's own
* data to it under PulseLoop's name. Meals and workouts recorded in PulseLoop still export.
*/
object HealthConnectSource {

/** How far back the first import reads. Health Connect itself only serves 30 days before the first grant. */
const val FIRST_IMPORT_DAYS = 30L
/** Later passes re-read this much, because source apps write late (a night lands in the morning). */
const val OVERLAP_DAYS = 3L

/** Source rows' marker in `activity_daily.source`, so the device's own calorie figure is used. */
const val ACTIVITY_SOURCE = "health_connect"
/** Prefix of a workout imported from Health Connect; the workout export skips these. */
const val WORKOUT_ID_PREFIX = "hc-"

fun isImportedWorkout(id: String): Boolean = id.startsWith(WORKOUT_ID_PREFIX)

// ── Settings ─────────────────────────────────────────────────────────────────────────────

private fun prefs(c: Context) = c.applicationContext.getSharedPreferences("hc_source", Context.MODE_PRIVATE)

@Volatile private var cachedEnabled: Boolean? = null
@Volatile private var active: MutableStateFlow<String?>? = null

/** The source app's package while the mode is on, null while off; for the header and settings. */
fun activeSource(c: Context): StateFlow<String?> = active ?: synchronized(this) {
active ?: MutableStateFlow(if (isEnabled(c)) sourcePackage(c) else null).also { active = it }
}

/** [isEnabled] for code with no Context (view models); warmed from the Application. */
val enabledNow: Boolean get() = cachedEnabled == true

/** What the cards can show while the mode is on: what Oura and its peers write to Health Connect. */
val CAPABILITIES: Set<WearableCapability> = setOf(
WearableCapability.HEART_RATE, WearableCapability.SPO2, WearableCapability.STEPS,
WearableCapability.SLEEP, WearableCapability.REM_SLEEP, WearableCapability.HRV,
)

fun isEnabled(c: Context): Boolean = cachedEnabled ?: prefs(c).getBoolean("enabled", false).also { cachedEnabled = it }
fun sourcePackage(c: Context): String? = prefs(c).getString("package", null)
fun lastImportAt(c: Context): Long? = prefs(c).getLong("lastImportAt", 0L).takeIf { it > 0 }
fun lastImportCount(c: Context): Int = prefs(c).getInt("lastImportCount", 0)
fun lastError(c: Context): String? = prefs(c).getString("lastError", null)

fun enable(c: Context, packageName: String) {
val changed = sourcePackage(c) != packageName
prefs(c).edit().putBoolean("enabled", true).putString("package", packageName).apply {
// A different source starts from a full window, not the old one's watermark.
if (changed) remove("lastImportAt").remove("seenWorkouts")
}.apply()
cachedEnabled = true
activeSource(c); active?.value = packageName
schedule(c)
runNow(c)
}

fun disable(c: Context) {
prefs(c).edit().putBoolean("enabled", false).apply()
cachedEnabled = false
activeSource(c); active?.value = null
WorkManager.getInstance(c).cancelUniqueWork(PERIODIC)
}

internal fun recordPass(c: Context, at: Long, count: Int, error: String?) {
prefs(c).edit().apply {
if (error == null) putLong("lastImportAt", at).putInt("lastImportCount", count).remove("lastError")
else putString("lastError", error)
}.apply()
}

/** Workouts already imported once; the user deleting one must not bring it back. */
internal fun seenWorkouts(c: Context): Set<String> = prefs(c).getStringSet("seenWorkouts", emptySet()).orEmpty()

internal fun markWorkoutsSeen(c: Context, ids: Collection<String>) {
if (ids.isEmpty()) return
val keep = (seenWorkouts(c) + ids).toList().takeLast(500).toSet()
prefs(c).edit().putStringSet("seenWorkouts", keep).apply()
}

fun label(c: Context, packageName: String): String = ReferenceAppLabels.label(c, packageName)

// ── Permissions ──────────────────────────────────────────────────────────────────────────

/** The accuracy check's reads plus what only this feature uses. Declared in the manifest too. */
val readPermissions: Set<String> = AccuracyCheckPermissions.all + setOf(
HealthPermission.getReadPermission(TotalCaloriesBurnedRecord::class),
HealthPermission.getReadPermission(ExerciseSessionRecord::class),
HealthPermission.getReadPermission(RespiratoryRateRecord::class),
HealthPermission.getReadPermission(MenstruationPeriodRecord::class),
)

/** What the screen asks for: the reads, plus background reading so imports run with the app closed. */
val request: Set<String> = readPermissions + HealthPermission.PERMISSION_READ_HEALTH_DATA_IN_BACKGROUND

fun canReadInBackground(granted: Set<String>): Boolean =
HealthPermission.PERMISSION_READ_HEALTH_DATA_IN_BACKGROUND in granted

// ── Export ───────────────────────────────────────────────────────────────────────────────

/** While this is on, every unit the export could echo is held back, for all time. */
fun exportExclusions(c: Context): List<ExportExclusion> =
if (isEnabled(c)) exportExclusions() else emptyList()

fun exportExclusions(): List<ExportExclusion> = ExportUnit.entries.map { ExportExclusion(it, Long.MIN_VALUE, null) }

// ── Scheduling ───────────────────────────────────────────────────────────────────────────

private const val PERIODIC = "hc_source_import"
private const val ONE_SHOT = "hc_source_import_now"

fun schedule(c: Context) {
if (!isEnabled(c)) return
val request = PeriodicWorkRequestBuilder<HealthConnectSourceWorker>(1, TimeUnit.HOURS)
.setConstraints(Constraints.Builder().setRequiresBatteryNotLow(true).build())
.build()
WorkManager.getInstance(c).enqueueUniquePeriodicWork(PERIODIC, ExistingPeriodicWorkPolicy.KEEP, request)
}

fun runNow(c: Context) {
if (!isEnabled(c)) return
WorkManager.getInstance(c).enqueueUniqueWork(
ONE_SHOT, ExistingWorkPolicy.KEEP,
OneTimeWorkRequestBuilder<HealthConnectSourceWorker>().build(),
)
}

// ── Pure conversions (tested) ────────────────────────────────────────────────────────────

/** Health Connect's stage constant as the app's stage. "Sleeping" with no stage is asleep, stage unknown. */
fun stage(hc: Int): SleepStage = when (hc) {
SleepSessionRecord.STAGE_TYPE_LIGHT -> SleepStage.LIGHT
SleepSessionRecord.STAGE_TYPE_DEEP -> SleepStage.DEEP
SleepSessionRecord.STAGE_TYPE_REM -> SleepStage.REM
SleepSessionRecord.STAGE_TYPE_AWAKE,
SleepSessionRecord.STAGE_TYPE_AWAKE_IN_BED,
SleepSessionRecord.STAGE_TYPE_OUT_OF_BED -> SleepStage.AWAKE
else -> SleepStage.UNKNOWN
}

data class Stage(val startMs: Long, val endMs: Long, val type: Int)

/**
* A night as one stage per minute from its start, the shape a ring's sleep record has. A night
* with no stages at all is asleep throughout (stage unknown); with stages, a minute none of them
* covers is awake. Each minute takes the stage covering most of it. Null for an empty or
* over-long session.
*/
fun minuteStages(startMs: Long, endMs: Long, stages: List<Stage>, maxMinutes: Int = 24 * 60): List<SleepStage>? {
val minutes = ((endMs - startMs) / 60_000L).toInt()
if (minutes <= 0 || minutes > maxMinutes) return null
if (stages.isEmpty()) return List(minutes) { SleepStage.UNKNOWN }
val sorted = stages.sortedBy { it.startMs }
return List(minutes) { i ->
val a = startMs + i * 60_000L
val b = a + 60_000L
var best: Stage? = null
var bestOverlap = 0L
for (s in sorted) {
if (s.startMs >= b) break
val o = minOf(b, s.endMs) - maxOf(a, s.startMs)
if (o > bestOverlap) { bestOverlap = o; best = s }
}
best?.let { stage(it.type) } ?: SleepStage.AWAKE
}
}

/** The app's workout type for a Health Connect exercise type; the inverse of the export's mapping. */
fun workoutType(exerciseType: Int): String = when (exerciseType) {
ExerciseSessionRecord.EXERCISE_TYPE_WALKING -> "walk"
ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
ExerciseSessionRecord.EXERCISE_TYPE_RUNNING_TREADMILL -> "run"
ExerciseSessionRecord.EXERCISE_TYPE_BIKING,
ExerciseSessionRecord.EXERCISE_TYPE_BIKING_STATIONARY -> "cycle"
ExerciseSessionRecord.EXERCISE_TYPE_STRENGTH_TRAINING,
ExerciseSessionRecord.EXERCISE_TYPE_WEIGHTLIFTING -> "gym"
ExerciseSessionRecord.EXERCISE_TYPE_SQUASH -> "squash"
ExerciseSessionRecord.EXERCISE_TYPE_YOGA -> "yoga"
ExerciseSessionRecord.EXERCISE_TYPE_DANCING -> "dance"
ExerciseSessionRecord.EXERCISE_TYPE_HIKING -> "hike"
else -> "sport"
}

/** The window a pass reads: the first one goes back [FIRST_IMPORT_DAYS], later ones overlap the last. */
fun window(lastImportAt: Long?, now: Long): LongRange {
val from = if (lastImportAt == null) now - FIRST_IMPORT_DAYS * 86_400_000L
else maxOf(now - FIRST_IMPORT_DAYS * 86_400_000L, lastImportAt - OVERLAP_DAYS * 86_400_000L)
return from..now
}
}
Loading
Loading