Read sleep stages from Health Connect

[schklom]

Describe the feature

Only the total sleep duration is currently read from Health Connect, even when individual sleep stages (e.g. Deep Sleep, REM Sleep, etc) are available. I would like for Home-Assistant to also read individual sleep stages (their times and durations).

Use cases

I could track my sleep quality in addition to the total duration

Examples

Gadgetbridge can link to wearable devices (like a smartwatch) and push the Sleep stages and durations throughout the nights to Android Health Connect.

Garmin Connect currently does it for Garmin smartwatches, but with their cloud service. But Gadgetbridge allows to have everything done without a proprietary cloud.

Anything else?

If it helps, here is some official documentation on reading sleep stages https://developer.android.com/health-and-fitness/health-connect/features/sleep-sessions#read-sleep-sessions

val response =
    healthConnectClient.readRecords(
        ReadRecordsRequest(
            SleepSessionRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
for (sleepRecord in response.records) {
    // Retrieve relevant sleep stages from each sleep record
    val sleepStages = sleepRecord.stages
}

[KruseLuds]

I'd be interested in implementing this and submitting a PR to the Android Companion App.

I've reviewed the current Health Connect implementation, including the recent sleep-duration stage handling. Since the Companion App already reads "SleepSessionRecord.stages", I'd like to extend the existing implementation to expose the richer standardized Health Connect sleep data rather than only using the stages to calculate total sleep duration.

My proposed approach would be strictly Health Connect-based and provider-neutral. It would not contain Samsung/Fitbit/device-specific logic or attempt to combine separate "SleepSessionRecord"s.

Following the existing Companion App sensor model, independently useful measurements would be exposed as individual sensors:

• Sleep Start
• Sleep End
• Light Sleep Duration
• Deep Sleep Duration
• REM Sleep Duration
• Awake Duration
• Awake In Bed Duration
• Out Of Bed Duration
• Sleeping / Unspecified Stage Duration
• Unknown Stage Duration

The existing Sleep Duration sensor would remain unchanged for backward compatibility.

All standardized Health Connect sleep stage types would be supported. Missing data would remain unavailable/unknown rather than being converted to zero, since "not supplied" and an actual zero value are different.

I would also preserve the complete ordered "SleepSessionRecord.stages" information, including each stage's type, "startTime", and "endTime", as structured session attributes so Home Assistant does not discard the original sleep-stage timeline.

Optional/contextual Health Connect fields such as the session title, notes, zone offsets, data origin, device metadata, record ID, and recording method would likewise be preserved where appropriate as attributes rather than separate entities.

If there are no objections to this approach, I'm happy to implement it, add/update the unit tests, test it against real Health Connect data, and submit a PR.

[schklom]

Thus sounds perfect! Thanks!

[KruseLuds]

@schklom Done!

I followed up on this and added support for individual Health Connect sleep stages.

Android implementation: home-assistant/android#7356
Documentation: home-assistant/companion.home-assistant#1407

This adds sleep start/end plus stage durations for Light, Deep, REM, Awake, Awake in bed, Out of bed, Sleeping/unspecified, and Unknown.

Now assuming they will accept my request, it will be merged in and then rolled out!