| Key | Value |
|---|---|
| uid | withings |
| type | binding |
| author | Nanna Agesen |
| version range | [5.0.0;6.0.0) |
| download | org.openhab.binding.withings-5.2.0-SNAPSHOT.jar |
Withings Health Binding
A comprehensive openHAB binding for Withings health devices — smart scales, blood pressure monitors, activity trackers, sleep monitors, and thermometers. Retrieves body measurements, cardiovascular data, activity metrics, and sleep analysis via the Withings Cloud API v2 with full OAuth2 authorization.
Features
- Body Composition — Weight, fat ratio, fat mass, fat-free mass, muscle mass, bone mass, hydration, wrist skin temperature (ScanWatch 2)
- Cardiovascular Monitoring — Heart rate, systolic/diastolic blood pressure, SpO2, pulse wave velocity, VO2 max, vascular age, body temperature, ECG Afib classification (ScanWatch 2)
- Activity Tracking — Steps, distance, calories, elevation, light/moderate/intense activity durations, active duration, heart rate zones (0–3)
- Sleep Analysis — Total sleep, deep/light/REM duration, wakeup count, sleep score, snoring episodes, breathing disturbances, heart rate and respiration during sleep, HRV (RMSSD, SDNN, quality) and skin temperature from sleep summary (ScanWatch 2)
- Device Status — Battery level, model name, last session timestamp — per individual physical device
- Device Auto-Discovery — Physical devices appear in the openHAB Inbox under the person bridge
- OAuth2 Web Authorization — Built-in servlet at
/withingsfor browser-based authorization (modeled after HomeConnect binding) - Automatic Token Refresh — Tokens refreshed transparently before expiry, persisted via StorageService (survives reboots — even with
.thingsfile configuration) - Multi-Person Support — Multiple person bridges per account, filtered by Withings user ID
- Configurable Polling — Separate intervals for body (15 min), activity (30 min), sleep (60 min), and device info (60 min)
Upgrading from v1.x — Breaking Changes
withings:person is now a Bridge (was a Thing). The device status channels have moved to a dedicated withings:device thing.
Required changes to your configuration:
- Change
Thing person→Bridge personin your.thingsfile - Add a nested
Thing devicefor each physical device (or discover via Inbox — see Quick Start) - Update items linking device channels:
- Old:
withings:person:home:john:device#battery - New:
withings:device:home:john:body_plus:device#battery
- Old:
- No re-authorization needed — existing OAuth2 tokens remain valid
Full step-by-step migration guide: README — Upgrading from v1.x
Supported Things
| Thing Type | Description |
|---|---|
account (Bridge) |
Withings API account — manages OAuth2 tokens |
person (Bridge) |
Individual user — polls measurements by user ID, parent of physical devices |
device |
A physical Withings device — battery, model, last sync (new in v2.0.0) |
Channels
Body Measurements
| Channel | Type | Description |
|---|---|---|
body#weight |
Number:Mass | Body weight (kg) |
body#fatRatio |
Number | Body fat percentage (%) |
body#fatMass |
Number:Mass | Fat mass (kg) |
body#fatFreeMass |
Number:Mass | Fat-free / lean body mass (kg) |
body#muscleMass |
Number:Mass | Muscle mass (kg) |
body#boneMass |
Number:Mass | Bone mass (kg) |
body#hydration |
Number:Mass | Body hydration (kg) |
body#lastMeasurement |
DateTime | Timestamp of most recent measurement |
body#skinTemperature |
Number:Temperature | Wrist skin temperature from sleep summary (°C) (ScanWatch 2, v3.0.0) |
Devices: Body, Body+, Body Comp, Body Scan
Cardiovascular
| Channel | Type | Description |
|---|---|---|
cardiovascular#heartPulse |
Number | Heart rate (bpm) |
cardiovascular#systolicBP |
Number:Pressure | Systolic blood pressure (mmHg) |
cardiovascular#diastolicBP |
Number:Pressure | Diastolic blood pressure (mmHg) |
cardiovascular#pulseWaveVelocity |
Number | Pulse wave velocity (m/s) |
cardiovascular#vo2Max |
Number | VO2 Max (ml/min/kg) |
cardiovascular#vascularAge |
Number | Estimated vascular age (years) |
cardiovascular#spo2 |
Number | Blood oxygen saturation (%) |
cardiovascular#temperature |
Number:Temperature | Body temperature (°C) |
cardiovascular#afib |
Number | ECG Afib classification: 0=sinus rhythm, 1=Afib detected, 2=inconclusive (ScanWatch 2, v3.0.0) |
Devices: BPM Connect, BPM Core, Body Scan, ScanWatch, Thermo
Activity
| Channel | Type | Description |
|---|---|---|
activity#steps |
Number | Steps taken today |
activity#distance |
Number:Length | Distance travelled (m) |
activity#calories |
Number:Energy | Active calories burned (kcal) |
activity#totalCalories |
Number:Energy | Total calories — active + passive (kcal) |
activity#elevation |
Number | Floors climbed |
activity#softActivity |
Number:Time | Light activity duration (min) |
activity#moderateActivity |
Number:Time | Moderate activity duration (min) |
activity#intenseActivity |
Number:Time | Intense activity duration (min) |
activity#activeDuration |
Number:Time | Total active duration (min) |
activity#hrAverage |
Number | Average heart rate (bpm) |
activity#hrMin |
Number | Minimum heart rate (bpm) |
activity#hrMax |
Number | Maximum heart rate (bpm) |
activity#hrZone0 |
Number:Time | Time in HR zone 0 — rest (min) |
activity#hrZone1 |
Number:Time | Time in HR zone 1 — light (min) |
activity#hrZone2 |
Number:Time | Time in HR zone 2 — moderate (min) |
activity#hrZone3 |
Number:Time | Time in HR zone 3 — intense (min) |
Devices: ScanWatch, Steel HR, Move, Go
Sleep
| Channel | Type | Description |
|---|---|---|
sleep#totalSleepTime |
Number:Time | Total time asleep (min) |
sleep#totalTimeInBed |
Number:Time | Total time in bed (min) |
sleep#deepSleepDuration |
Number:Time | Deep sleep duration (min) |
sleep#lightSleepDuration |
Number:Time | Light sleep duration (min) |
sleep#remSleepDuration |
Number:Time | REM sleep duration (min) |
sleep#nbRemEpisodes |
Number | Number of REM episodes |
sleep#wakeupCount |
Number | Wakeup count |
sleep#wakeupDuration |
Number:Time | Time awake during night (min) |
sleep#outOfBedCount |
Number | Number of out-of-bed events |
sleep#timeToSleep |
Number:Time | Time to fall asleep (min) |
sleep#sleepLatency |
Number:Time | Sleep latency (min) |
sleep#wakeupLatency |
Number:Time | Time in bed after waking (min) |
sleep#sleepScore |
Number | Sleep quality score (0–100) |
sleep#sleepEfficiency |
Number | Sleep efficiency (%) |
sleep#snoring |
Number:Time | Snoring duration (min) |
sleep#snoringEpisodes |
Number | Number of snoring episodes |
sleep#breathingDisturbances |
Number | Breathing disturbance index |
sleep#nightEvents |
Number | Total night events |
sleep#sleepHrAverage |
Number | Average HR during sleep (bpm) |
sleep#sleepHrMin |
Number | Min HR during sleep (bpm) |
sleep#sleepHrMax |
Number | Max HR during sleep (bpm) |
sleep#sleepRrAverage |
Number | Average respiration rate (brpm) |
sleep#sleepRrMin |
Number | Min respiration rate (brpm) |
sleep#sleepRrMax |
Number | Max respiration rate (brpm) |
sleep#sleepHrvRmssd |
Number | HRV RMSSD (ms) (ScanWatch 2, v3.0.0) |
sleep#sleepHrvSdnn |
Number | HRV SDNN (ms) (ScanWatch 2, v3.0.0) |
sleep#sleepHrvQuality |
Number | HRV quality score (ScanWatch 2, v3.0.0) |
sleep#sleepSkinTemperature |
Number:Temperature | Wrist skin temperature from sleep (°C) (ScanWatch 2, v3.0.0) |
Devices: Sleep Analyzer, ScanWatch, Steel HR
Device Status (new in v2.0.0)
| Channel | Type | Description |
|---|---|---|
device#battery |
String | Battery level (high / medium / low) |
device#model |
String | Device model name (e.g. Body+, ScanWatch) |
device#lastSession |
DateTime | Timestamp of last recorded session |
Multiple devices? Each physical device gets its own
withings:devicething under the person bridge. Devices are auto-discovered via the openHAB Inbox — just scan from the person bridge. (new in v2.0.0)
Devices: All Withings devices
Quick Start
withings.things
Bridge withings:account:home "Withings Account" [
clientId="YOUR_CLIENT_ID",
clientSecret="YOUR_CLIENT_SECRET",
redirectUri="https://your-openhab.example.com/callback"
] {
Bridge person nanna "Nanna" [
userId=17873009,
pollingIntervalBody=15,
pollingIntervalActivity=30,
pollingIntervalSleep=60
] {
Thing device body_plus "Withings Body+" [
deviceId="YOUR_DEVICE_ID"
]
}
}
Tip: Leave the
devicething out initially. Authorize first, then go to Settings → Things → (person bridge) → Scan to discover devices automatically. Copy thedeviceIdfrom the Inbox entry.
withings.items
Group gWithings "Withings Health" <body>
// Body
Number:Mass Withings_Weight "Weight [%.1f kg]" (gWithings) { channel="withings:person:home:nanna:body#weight" }
Number Withings_Fat_Ratio "Fat Ratio [%.1f %%]" (gWithings) { channel="withings:person:home:nanna:body#fatRatio" }
Number:Mass Withings_Muscle_Mass "Muscle Mass [%.1f kg]" (gWithings) { channel="withings:person:home:nanna:body#muscleMass" }
DateTime Withings_Last "Last Measurement [%1$td-%1$tm-%1$tY]" (gWithings) { channel="withings:person:home:nanna:body#lastMeasurement" }
// Device — note: withings:device thing, not withings:person
String Withings_Battery "Battery [%s]" (gWithings) { channel="withings:device:home:nanna:body_plus:device#battery" }
String Withings_Model "Device [%s]" (gWithings) { channel="withings:device:home:nanna:body_plus:device#model" }
DateTime Withings_Last_Sync "Last Sync [%1$td-%1$tm-%1$tY]" (gWithings) { channel="withings:device:home:nanna:body_plus:device#lastSession" }
OAuth2 Authorization
- Configure bridge with
clientId,clientSecret, andredirectUri - Open
http://your-openhab:8080/withingsin a browser - Click “Authorize with Withings” → log in → grant all permissions
- Note the User ID shown on success page → use for person bridge
userId
Upgrading from v1.x? See the migration guide in the README. No re-authorization needed — existing tokens remain valid. Change
Thing person→Bridge personin your.thingsfile and update device channel items to the newwithings:deviceUIDs.
What’s New in v3.0.1
- Fix:
sleep#sleepEfficiencynow correctly reports percentage (0–100) — previously the raw API ratio (0.0–1.0) was returned without conversion
What’s New in v3.0.0
| New Channel | Type | Device |
|---|---|---|
cardiovascular#afib |
Number | ECG Afib classification (0/1/2) — ScanWatch 2 |
sleep#sleepHrvRmssd |
Number | HRV RMSSD during sleep (ms) — ScanWatch 2 |
sleep#sleepHrvSdnn |
Number | HRV SDNN during sleep (ms) — ScanWatch 2 |
sleep#sleepHrvQuality |
Number | HRV quality score — ScanWatch 2 |
body#skinTemperature |
Number:Temperature | Wrist skin temperature from sleep summary (°C) — ScanWatch 2 |
See the full changelog on GitHub.
Prerequisites
- Withings Developer Account with registered application
- At least one Withings health device linked to your account
- Public callback URL for OAuth2 (or use pre-configured tokens)
- Required scopes:
user.metrics,user.activity,user.sleepevents,user.info
Resources
- Download JAR: org.openhab.binding.withings-5.2.0-SNAPSHOT.jar
- Source Code: github.com/Prinsessen/openhab-withings-binding
- Full Documentation: README.md
- Changelog: v3.0.1 — Sleep Efficiency Fix
- License: EPL-2.0
Note: This version isn’t on the marketplace yet — I want to validate it against a few more device types (including ScanWatch) before pushing a wider release. The JAR above is the fastest way to get it right now.
