Connect your Zepp smartwatch to Home Assistant and track your health & fitness data in real-time! 📊
If you find this integration useful, please give it a star on GitHub! It really helps the project grow! ⭐
Zepp2Hass receives data from your Zepp smartwatch via a local webhook endpoint. When you configure the integration, it creates a unique webhook URL that accepts JSON payloads with all your health metrics.
Rate limiting is built-in to protect your Home Assistant instance: max 30 requests per 60 seconds per device.
Each webhook includes a minimalist web interface accessible via your browser, specifically designed for quick URL retrieval.
How to find your URL:
- Navigate to Settings → Integrations → Zepp2Hass.
- Select your Device Name.
- Under Device Info, click Visit to open the interface.
- Use the one-click copy button to grab your webhook URL.
The integration creates multiple sensor types organized by category:
| Category | Sensors |
|---|---|
| Health | Heart Rate (last, resting, max), Body Temperature, Stress, Blood Oxygen |
| Activity | Steps, Calories, Fat Burning, Stands, Distance (all with goal targets) |
| Sleep | Sleep Score, Total Duration, Deep Sleep, Sleep Start/End Time |
| Workout | Training Load, Last Workout, Workout History, VO2 Max |
| Device | Battery, Screen Status/AOD/Brightness, Device Info, User Info |
| PAI | Weekly PAI score with daily PAI as attribute |
| Binary Sensors | Is Wearing, Is Moving, Is Sleeping |
- Open HACS in Home Assistant
- Search for Zepp2Hass in HACS
- Click Download
- Restart Home Assistant
- Go to Settings → Devices & Services
- Click Add Integration
- Search for Zepp2Hass
- Enter a device name (e.g., "My Zepp Watch", "Amazfit Band 7")
- Click Submit
After adding the integration, you can get your webhook URL:
Integration Interface - Go to Settings → Integrations → Zepp2Hass → Click on device name → Under "Device Info" click "Visit". This will take you to the web interface.
The URL format is:
http://YOUR_HOME_ASSISTANT_BASE_URL/api/webhook/WEBHOOK_ID
Advanced: You can change the Base URL at any time by going to Settings → Devices & Services → Zepp2Hass → Configure. The integration will automatically reload to apply the new URL.
To send data from your Zepp smartwatch to Home Assistant, you need to install the zepp2hass app on your watch and configure it:
Prerequisites: You need the Zepp app installed on your smartphone.
-
Install the App from Zepp Store
- Open the Zepp app on your smartphone
- Navigate to the Zepp Store (internal app store within the Zepp app)
- Search for "zepp2hass" and install it on your smartwatch
-
Configure the Webhook
- In the Zepp app, go to Device Application Settings → More
- Find the zepp2hass app in the list
- Enter the webhook URL you copied from Step 2
- Optionally, adjust the update interval (default: 1 minute)
- Increasing the interval (e.g., 2-5 minutes) will save battery life
- Decreasing the interval provides more frequent updates but may drain battery faster
-
Apply Settings on Your Watch
- Open the zepp2hass app directly on your smartwatch
- Click the "Apply settings" button at the bottom
Tip: For most use cases, a 2-5 minute interval provides a good balance between data freshness and battery life.
Click to see supported devices
- Amazfit Balance
- Amazfit Balance 2
- Amazfit Balance 2 XT
- Amazfit T-Rex Ultra
- Amazfit T-Rex 3
- Amazfit T-Rex 3 Pro (44mm)
- Amazfit T-Rex 3 Pro (48mm)
- Amazfit Cheetah (Round)
- Amazfit Cheetah (Square)
- Amazfit Cheetah Pro
- Amazfit Cheetah Pro Kelvin Kiptum
- Amazfit Active
- Amazfit Active Edge
- Amazfit Active Max
- Amazfit Active 2 (Round)
- Amazfit Active 2 NFC (Round)
- Amazfit Active 2 (Square)
- Amazfit Active 2 NFC (Square)
- Amazfit GTR 4
- Amazfit GTR 4 Limited Edition
- Amazfit GTS 4
- Amazfit Bip 5 Unity
- Amazfit Bip 5 Core
- Amazfit Bip 6
- Amazfit Falcon
Battery low automation:
automation:
- alias: "Zepp Battery Low"
trigger:
- platform: numeric_state
entity_id: sensor.my_zepp_watch_battery
below: 20
action:
- service: notify.mobile_app_your_phone
data:
message: "🔋 Watch battery low: {{ states('sensor.my_zepp_watch_battery') }}%"- Check the webhook URL - Visit it in your browser to verify it's accessible
- Check Home Assistant logs - Look for errors under Settings → System → Logs
- Verify network - Ensure the device sending data can reach Home Assistant
curl -X POST http://YOUR_HA_IP:8123/api/webhook/YOUR_WEBHOOK_ID \
-H "Content-Type: application/json" \
-d '{
"battery": {"current": 80},
"steps": {"current": 5000, "target": 10000},
"heart_rate": {"last": 72, "resting": 58},
"is_wearing": 1
}'Note: Replace
YOUR_WEBHOOK_IDwith the actual webhook ID from your integration. You can find it by visiting the webhook URL in your browser (GET request) or checking Home Assistant logs.
Expected response:
{ "status": "ok" }Click to expand Debug Mode instructions
How to help with debugging:
- Uninstall the Store version of the app from your watch.
- Enable Developer Mode in the Zepp App on your phone:
- Go to Profile > Settings > About.
- Tap the Zepp icon 7 times until a "Developer Mode" message appears.
- Download the App:
- Go to to Device > General > Developer Mode.
- Click the + icon in the top right corner and select Scan to scan the QR code.
How to access and share logs:
Once the QR code is scanned, follow these steps to view the real-time logs:
- Stay within the Developer Mode menu and switch to the Mini Program tab.
- After configuring the Settings, tap on the mini app icon from the list.
- Select Device logs.
- Click Enable: now, interact with the app on your watch to reproduce the issue.
- Screenshot: Please capture and send a screenshot of the logs that appear in the console.
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
This project is licensed under the MIT License - see the LICENSE file for details.
For support, please see SUPPORT.md.
Made with ❤️ for the Home Assistant community
⭐ Star this repo if you find it useful! ⭐