🏃 Zepp2Hass - Zepp Smartwatch Integration for Home Assistant

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! ⭐

---

✨ Features

📡 Real-time Data via Webhook

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.

🌐 Web Interface

Each webhook includes a minimalist web interface accessible via your browser, specifically designed for quick URL retrieval.

How to find your URL:

1. Navigate to Settings → Integrations → Zepp2Hass.
2. Select your Device Name.
3. Under Device Info, click Visit to open the interface.
4. Use the one-click copy button to grab your webhook URL.

📊 Comprehensive Sensor Suite

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

---

🚀 Installation

HACS ⭐

1. Open HACS in Home Assistant
2. Search for Zepp2Hass in HACS
3. Click Download
4. Restart Home Assistant

---

⚙️ Configuration

Step 1: Add the Integration

1. Go to Settings → Devices & Services
2. Click Add Integration
3. Search for Zepp2Hass
4. Enter a device name (e.g., "My Zepp Watch", "Amazfit Band 7")
5. Click Submit

Step 2: Get Your Webhook URL

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.

Step 3: Install and Configure the Zepp2Hass App on Your Watch

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.

1. Install the App from Zepp Store
2. Open the Zepp app on your smartphone
3. Navigate to the Zepp Store (internal app store within the Zepp app)

4. Search for "zepp2hass" and install it on your smartwatch

5. Configure the Webhook

6. In the Zepp app, go to Device Application Settings → More
7. Find the zepp2hass app in the list
8. Enter the webhook URL you copied from Step 2

9. 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

10. Apply Settings on Your Watch

11. Open the zepp2hass app directly on your smartwatch
12. 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.

---

📱 Supported Devices

Click to see supported devices

🏃 Serie Balance

• Amazfit Balance
• Amazfit Balance 2
• Amazfit Balance 2 XT

🦕 Serie T-Rex (Rugged)

• Amazfit T-Rex Ultra
• Amazfit T-Rex 3
• Amazfit T-Rex 3 Pro (44mm)
• Amazfit T-Rex 3 Pro (48mm)

🐆 Serie Cheetah (Running)

• Amazfit Cheetah (Round)
• Amazfit Cheetah (Square)
• Amazfit Cheetah Pro
• Amazfit Cheetah Pro Kelvin Kiptum

💪 Serie Active

• Amazfit Active
• Amazfit Active Edge
• Amazfit Active 2 (Round)
• Amazfit Active 2 NFC (Round)
• Amazfit Active 2 (Square)
• Amazfit Active 2 NFC (Square)

⌚ Serie GTR & GTS

• Amazfit GTR 4
• Amazfit GTR 4 Limited Edition
• Amazfit GTS 4

📟 Serie Bip

• Amazfit Bip 5 Unity
• Amazfit Bip 5 Core
• Amazfit Bip 6

🎯 Other Models

• Amazfit Falcon

---

🎯 Usage Examples

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') }}%"

---

🔧 Troubleshooting

Sensors not updating?

1. Check the webhook URL - Visit it in your browser to verify it's accessible
2. Check Home Assistant logs - Look for errors under Settings → System → Logs
3. Verify network - Ensure the device sending data can reach Home Assistant

Test the webhook with curl

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_ID with 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" }

🐞 Debug Mode & Advanced Troubleshooting

Click to expand Debug Mode instructions

How to help with debugging:

1. Uninstall the Store version of the app from your watch.
2. 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.
3. Download the App:
4. Go to to Device > General > Developer Mode.
5. 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.

🤝 Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

📞 Support

For support, please see SUPPORT.md.

---

Made with ❤️ for the Home Assistant community

⭐ Star this repo if you find it useful! ⭐