| name | zepp-os-sensors |
| description | Use when the primary Zepp OS task is directly reading, subscribing to, configuring, or stopping @zos/sensor sensor/health data on a device app - heart rate, steps, calories, blood oxygen, accelerometer, gyroscope, GPS/geolocation, sleep, stress, battery, compass, workout, weather, wear/screen state. Use for permission details only when paired with implementing sensor reads. Do not use only because a query mentions sensor data if the task is persisting or aggregating values across app restarts, sending data to phone, displaying it in UI, declaring app.json permission strings, requesting permissions, scheduling background work, or building a watchface complication. |
| compatibility | Zepp OS Device App (Mini Program); requires @zos/sensor. API_LEVEL varies per sensor (HeartRate 2.0; Accelerometer/Gyroscope 3.0). Declare sensor permissions in app.json. Not for watchfaces (use hmSensor). |
Zepp OS Sensors
Context: Device App (Mini Program). Watchfaces use the separate legacy hmSensor surface; see zepp-os-watchface for watchface scope.
API_LEVEL: varies per sensor (HeartRate 2.0; Accelerometer/Gyroscope 3.0; check each).
Prereq: permissions live in app.json — see zepp-os-fundamentals.
Overview
Each sensor is a class in @zos/sensor. The shape is always: instantiate → subscribe → read → stop. But the exact method names and permission codes differ per sensor — don't assume; check references/sensor.md.
import { Accelerometer, FREQ_MODE_NORMAL } from '@zos/sensor'
const acc = new Accelerometer()
const onAccel = () => console.log(acc.getCurrent())
acc.onChange(onAccel)
acc.setFreqMode(FREQ_MODE_NORMAL)
acc.start()
acc.offChange(onAccel)
acc.stop()
Quick Reference: pattern names differ
| Sensor | Subscribe | Read | Permission |
|---|
Accelerometer [≥3.0] | onChange / offChange | getCurrent() | device:os.accelerometer |
HeartRate [≥2.0] | onCurrentChange / offCurrentChange | getCurrent(), getLast() | data:user.hd.heart_rate |
Calorie | onChange / offChange | getCurrent() | data:user.hd.calorie |
Step / Distance / Stress / BloodOxygen … | per-sensor | getCurrent() | data:user.hd.* |
Two takeaways:
- Hardware sensors use
device:os.* permissions; health/user data uses data:user.hd.*. Declare them in app.json → permissions[] (and request dynamically via @zos/app if needed — see zepp-os-fundamentals).
- Subscription method names vary (
onChange vs onCurrentChange). Always confirm in the reference.
Available classes: Accelerometer, Barometer, Battery, BloodOxygen, BodyTemperature, Buzzer, Calorie, Compass, Distance, FatBurning, Geolocation, Gyroscope, HeartRate, Pai, Screen, Sleep, Stand, Step, Stress, SystemSounds, Time, Vibrator, Wear, Weather, Workout, WorldClock.
Freq mode [≥3.0]
Continuous sensors take setFreqMode(FREQ_MODE_LOW | FREQ_MODE_NORMAL | FREQ_MODE_HIGH) — higher frequency = more data, more battery.
Common Mistakes
- Forgetting the permission in
app.json → the sensor returns nothing/throws. Many sensors require a permission; however, some status/system sensors (Battery, Screen, Wear, WorldClock) do not list a permission. Check references/sensor.md for each sensor's requirements.
- Assuming every sensor has
onChange → some use onCurrentChange, some are read-only (getCurrent one-shot). Check references/sensor.md.
- Never calling
stop() / offChange() → continuous sensors keep draining battery; always release in onDestroy.
- Using
device:os.* for health data (or vice-versa) → wrong permission family; heart rate/steps/calories are data:user.hd.*.
- Reading sensors in the side service → sensors are on the watch (device app), not the phone.
Sensor workflow checklist
Progress (instantiate → subscribe → read → stop):
Reference
