{"id":33897212,"url":"https://github.com/davidepalleschi/zepp2hass","last_synced_at":"2026-04-24T22:01:11.263Z","repository":{"id":323038637,"uuid":"1087326614","full_name":"davidepalleschi/zepp2hass","owner":"davidepalleschi","description":"Connect your Zepp smartwatch to Home Assistant and track your health \u0026 fitness data in real-time","archived":false,"fork":false,"pushed_at":"2026-02-02T21:30:57.000Z","size":429,"stargazers_count":23,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-03T11:20:10.494Z","etag":null,"topics":["custom-component","hacs-integration","home-assistant","home-assistant-integration","zepp","zeppos"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidepalleschi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-31T18:12:50.000Z","updated_at":"2026-02-03T07:11:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/davidepalleschi/zepp2hass","commit_stats":null,"previous_names":["davidepalleschi/zepp2hass"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/davidepalleschi/zepp2hass","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidepalleschi%2Fzepp2hass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidepalleschi%2Fzepp2hass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidepalleschi%2Fzepp2hass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidepalleschi%2Fzepp2hass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidepalleschi","download_url":"https://codeload.github.com/davidepalleschi/zepp2hass/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidepalleschi%2Fzepp2hass/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32242315,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-component","hacs-integration","home-assistant","home-assistant-integration","zepp","zeppos"],"created_at":"2025-12-11T19:05:26.435Z","updated_at":"2026-04-24T22:01:11.250Z","avatar_url":"https://github.com/davidepalleschi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🏃 Zepp2Hass - Zepp Smartwatch Integration for Home Assistant\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./images/zepp2hass.svg\" alt=\"Zepp2Hass Logo\" width=\"300\" style=\"margin-bottom: 20px;\"/\u003e\n\n![Zepp Logo](https://img.shields.io/badge/Zepp-Smartwatch-blue?style=for-the-badge\u0026logo=watch)\n![Home Assistant](https://img.shields.io/badge/Home%20Assistant-Custom%20Integration-orange?style=for-the-badge\u0026logo=home-assistant)\n![HACS](https://img.shields.io/badge/HACS-Custom%20Repository-red?style=for-the-badge)\n\n**Connect your Zepp smartwatch to Home Assistant and track your health \u0026 fitness data in real-time! 📊**\n\n\u003e **If you find this integration useful, please give it a star on GitHub! It really helps the project grow! ⭐**\n\n[![GitHub release](https://img.shields.io/github/release/davidepalleschi/zepp2hass.svg)](https://github.com/davidepalleschi/zepp2hass/releases)\n[![GitHub issues](https://img.shields.io/github/issues/davidepalleschi/zepp2hass.svg)](https://github.com/davidepalleschi/zepp2hass/issues)\n[![License](https://img.shields.io/github/license/davidepalleschi/zepp2hass.svg)](https://github.com/davidepalleschi/zepp2hass/blob/main/LICENSE)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n### 📡 Real-time Data via Webhook\n\nZepp2Hass 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.\n\n**Rate limiting** is built-in to protect your Home Assistant instance: max 30 requests per 60 seconds per device.\n\n### 🌐 Web Interface\n\nEach webhook includes a minimalist web interface accessible via your browser, specifically designed for quick URL retrieval.\n\n**How to find your URL:**\n\n1. Navigate to **Settings** → **Integrations** → **Zepp2Hass**.\n2. Select your **Device Name**.\n3. Under **Device Info**, click **Visit** to open the interface.\n4. Use the **one-click copy button** to grab your webhook URL.\n\n### 📊 Comprehensive Sensor Suite\n\nThe integration creates multiple sensor types organized by category:\n\n| Category           | Sensors                                                                 |\n| ------------------ | ----------------------------------------------------------------------- |\n| **Health**         | Heart Rate (last, resting, max), Body Temperature, Stress, Blood Oxygen |\n| **Activity**       | Steps, Calories, Fat Burning, Stands, Distance (all with goal targets)  |\n| **Sleep**          | Sleep Score, Total Duration, Deep Sleep, Sleep Start/End Time           |\n| **Workout**        | Training Load, Last Workout, Workout History, VO2 Max                   |\n| **Device**         | Battery, Screen Status/AOD/Brightness, Device Info, User Info           |\n| **PAI**            | Weekly PAI score with daily PAI as attribute                            |\n| **Binary Sensors** | Is Wearing, Is Moving, Is Sleeping                                      |\n\n---\n\n## 🚀 Installation\n\n### HACS ⭐\n\n1. Open **HACS** in Home Assistant\n2. Search for **Zepp2Hass** in HACS\n3. Click **Download**\n4. Restart Home Assistant\n\n---\n\n## ⚙️ Configuration\n\n### Step 1: Add the Integration\n\n1. Go to **Settings** → **Devices \u0026 Services**\n2. Click **Add Integration**\n3. Search for **Zepp2Hass**\n4. Enter a **device name** (e.g., \"My Zepp Watch\", \"Amazfit Band 7\")\n5. Click **Submit**\n\n### Step 2: Get Your Webhook URL\n\nAfter adding the integration, you can get your webhook URL:\n\n**Integration Interface** - Go to Settings → Integrations → Zepp2Hass → Click on device name → Under \"Device Info\" click \"Visit\". This will take you to the web interface.\n\nThe URL format is:\n\n```\nhttp://YOUR_HOME_ASSISTANT_BASE_URL/api/webhook/WEBHOOK_ID\n```\n\n\u003e **Advanced:** You can change the **Base URL** at any time by going to **Settings** → **Devices \u0026 Services** → **Zepp2Hass** → **Configure**. The integration will automatically reload to apply the new URL.\n\n### Step 3: Install and Configure the Zepp2Hass App on Your Watch\n\nTo send data from your Zepp smartwatch to Home Assistant, you need to install the **zepp2hass** app on your watch and configure it:\n\n\u003e **Prerequisites:** You need the **Zepp** app installed on your smartphone.\n\n1. **Install the App from Zepp Store**\n   - Open the **Zepp** app on your smartphone\n   - Navigate to the **Zepp Store** (internal app store within the Zepp app)\n   - Search for **\"zepp2hass\"** and install it on your smartwatch\n\n2. **Configure the Webhook**\n   - In the **Zepp** app, go to **Device Application Settings** → **More**\n   - Find the **zepp2hass** app in the list\n   - Enter the webhook URL you copied from Step 2\n   - Optionally, adjust the **update interval** (default: 1 minute)\n     - Increasing the interval (e.g., 2-5 minutes) will save battery life\n     - Decreasing the interval provides more frequent updates but may drain battery faster\n\n3. **Apply Settings on Your Watch**\n   - Open the **zepp2hass** app directly on your smartwatch\n   - Click the **\"Apply settings\"** button at the bottom\n\n\u003e **Tip:** For most use cases, a 2-5 minute interval provides a good balance between data freshness and battery life.\n\n---\n\n## 📱 Supported Devices\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to see supported devices\u003c/summary\u003e\n\n### 🏃 Serie Balance\n\n- Amazfit Balance\n- Amazfit Balance 2\n- Amazfit Balance 2 XT\n\n### 🦕 Serie T-Rex (Rugged)\n\n- Amazfit T-Rex Ultra\n- Amazfit T-Rex 3\n- Amazfit T-Rex 3 Pro (44mm)\n- Amazfit T-Rex 3 Pro (48mm)\n\n### 🐆 Serie Cheetah (Running)\n\n- Amazfit Cheetah (Round)\n- Amazfit Cheetah (Square)\n- Amazfit Cheetah Pro\n- Amazfit Cheetah Pro Kelvin Kiptum\n\n### 💪 Serie Active\n\n- Amazfit Active\n- Amazfit Active Edge\n- Amazfit Active Max\n- Amazfit Active 2 (Round)\n- Amazfit Active 2 NFC (Round)\n- Amazfit Active 2 (Square)\n- Amazfit Active 2 NFC (Square)\n\n### ⌚ Serie GTR \u0026 GTS\n\n- Amazfit GTR 4\n- Amazfit GTR 4 Limited Edition\n- Amazfit GTS 4\n\n### 📟 Serie Bip\n\n- Amazfit Bip 5 Unity\n- Amazfit Bip 5 Core\n- Amazfit Bip 6\n\n### 🎯 Other Models\n\n- Amazfit Falcon\n\n\u003c/details\u003e\n\n---\n\n## 🎯 Usage Examples\n\n**Battery low automation:**\n\n```yaml\nautomation:\n  - alias: \"Zepp Battery Low\"\n    trigger:\n      - platform: numeric_state\n        entity_id: sensor.my_zepp_watch_battery\n        below: 20\n    action:\n      - service: notify.mobile_app_your_phone\n        data:\n          message: \"🔋 Watch battery low: {{ states('sensor.my_zepp_watch_battery') }}%\"\n```\n\n---\n\n## 🔧 Troubleshooting\n\n### Sensors not updating?\n\n1. **Check the webhook URL** - Visit it in your browser to verify it's accessible\n2. **Check Home Assistant logs** - Look for errors under Settings → System → Logs\n3. **Verify network** - Ensure the device sending data can reach Home Assistant\n\n### Test the webhook with curl\n\n```bash\ncurl -X POST http://YOUR_HA_IP:8123/api/webhook/YOUR_WEBHOOK_ID \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"battery\": {\"current\": 80},\n    \"steps\": {\"current\": 5000, \"target\": 10000},\n    \"heart_rate\": {\"last\": 72, \"resting\": 58},\n    \"is_wearing\": 1\n  }'\n```\n\n\u003e **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.\n\nExpected response:\n\n```json\n{ \"status\": \"ok\" }\n```\n\n### 🐞 Debug Mode \u0026 Advanced Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand Debug Mode instructions\u003c/summary\u003e\n   \n**How to help with debugging:**\n\n1.  **Uninstall the Store version** of the app from your watch.\n2.  **Enable Developer Mode** in the Zepp App on your phone:\n    - Go to **Profile \u003e Settings \u003e About**.\n    - Tap the **Zepp icon 7 times** until a \"Developer Mode\" message appears.\n3. **Download the App:**\n   - Go to to **Device \u003e General \u003e Developer Mode**.\n   - Click the **+** icon in the top right corner and select **Scan** to scan the QR code.\n\n\n**How to access and share logs:**\n\nOnce the QR code is scanned, follow these steps to view the real-time logs:\n\n* Stay within the **Developer Mode** menu and switch to the **Mini Program** tab.\n* After configuring the **Settings**, tap on the mini app icon from the list.\n* Select **Device logs**.\n* Click **Enable**: now, interact with the app on your watch to reproduce the issue.\n* **Screenshot:** Please capture and send a screenshot of the logs that appear in the console.\n\n\u003c/details\u003e\n\n## 🤝 Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 📞 Support\n\nFor support, please see [SUPPORT.md](SUPPORT.md).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ for the Home Assistant community**\n\n⭐ **Star this repo if you find it useful!** ⭐\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidepalleschi%2Fzepp2hass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidepalleschi%2Fzepp2hass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidepalleschi%2Fzepp2hass/lists"}