{"id":24621487,"url":"https://github.com/alryaz/hass-hekr-component","last_synced_at":"2025-05-07T12:20:21.782Z","repository":{"id":42424315,"uuid":"215825339","full_name":"alryaz/hass-hekr-component","owner":"alryaz","description":"Hekr integration using python-hekr","archived":false,"fork":false,"pushed_at":"2025-01-19T14:23:28.000Z","size":542,"stargazers_count":35,"open_issues_count":9,"forks_count":12,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-31T09:51:15.289Z","etag":null,"topics":["consumption","hekr","homeassistant-components","python","wisen-application"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alryaz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["alryaz"],"patreon":"alryaz","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["http://paypal.me/alryaz"]}},"created_at":"2019-10-17T15:25:01.000Z","updated_at":"2025-01-19T14:22:04.000Z","dependencies_parsed_at":"2025-01-19T15:24:09.190Z","dependency_job_id":"c4a795e5-c8d9-4dc8-8350-8374ee7bd53f","html_url":"https://github.com/alryaz/hass-hekr-component","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alryaz%2Fhass-hekr-component","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alryaz%2Fhass-hekr-component/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alryaz%2Fhass-hekr-component/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alryaz%2Fhass-hekr-component/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alryaz","download_url":"https://codeload.github.com/alryaz/hass-hekr-component/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252874108,"owners_count":21817757,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["consumption","hekr","homeassistant-components","python","wisen-application"],"created_at":"2025-01-25T02:22:10.798Z","updated_at":"2025-05-07T12:20:21.759Z","avatar_url":"https://github.com/alryaz.png","language":"Python","funding_links":["https://github.com/sponsors/alryaz","https://patreon.com/alryaz","http://paypal.me/alryaz"],"categories":[],"sub_categories":[],"readme":"\n# HomeAssistant Hekr Integration \n\u003e HomeAssistant implementation of Hekr API communicator\n\u003e\n\u003e [![hacs_badge](https://img.shields.io/badge/HACS-Default-green.svg?style=for-the-badge)](https://github.com/custom-components/hacs)\n\u003e [![License](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)\n\u003e [![Maintenance](https://img.shields.io/badge/Maintained%3F-bugfixes%20only-yellow.svg?style=for-the-badge)](https://github.com/alryaz/hass-hekr-component/graphs/commit-activity)\n\n\u003e 💵 **Donation options to support development**  \n\u003e [![Donate using YooMoney](https://img.shields.io/badge/YooMoney-8B3FFD.svg?style=for-the-badge)](https://yoomoney.ru/to/410012369233217)\n\u003e [![Donate using Tinkoff](https://img.shields.io/badge/Tinkoff-F8D81C.svg?style=for-the-badge)](https://www.tinkoff.ru/cf/3g8f1RTkf5G)\n\u003e [![Donate using Sberbank](https://img.shields.io/badge/Сбербанк-green.svg?style=for-the-badge)](https://www.sberbank.com/ru/person/dl/jc?linkname=3pDgknI7FY3z7tJnN)\n\u003e [![Donate using DonationAlerts](https://img.shields.io/badge/DonationAlerts-fbaf2b.svg?style=for-the-badge)](https://www.donationalerts.com/r/alryaz)\n\u003e\n\u003e 💬 **Technical Support**  \n\u003e [![Telegram Group](https://img.shields.io/endpoint?url=https%3A%2F%2Ftg.sumanjay.workers.dev%2Falryaz_ha_addons\u0026style=for-the-badge)](https://telegram.dog/alryaz_ha_addons)  \n\u003e **Warning:** The group is primarily oriented toward Russian users, however do not hesitate to join and ask questions in English, to which I usually reply in a timely manner.\n\n## ❗❗❗ WARNING ❗❗❗\n**THIS PROJECT IS HIGHLY _WORK-IN-PROGRESS_!!!**\nThings are subject to change drastically until at least two to three different Hekr implementations are discovered and\nadded to the integration as well as the parent python module. Please, read release notes carefully before installing\nor upgrading. __I am not responsible for damaging your devices in any way!__\n\n## ❗❗❗ _Elro Connects_ owners ❗❗❗\nThis module **does not** yet support _Elro Connects_, however work has been done to make a testing implementation.\nTesters with _Elro K1_ gateways are needed. Please, contact me via e-mail \n\u003c[alryaz@xavux.com](mailto:alryaz@xavux.com?subject=Elro%20Connects%20Integration)\u003e.\n\n\n## Contribution\nIf you found yourself using Wisen application with any of your Smart Home devices, contact me via\ne-mail \u003c[alryaz@xavux.com](mailto:alryaz@xavux.com?subject=Hekr%20for%20HomeAssistant%20Contribution)\u003e.\nThe process of adding new devices is not yet completely formalized, the milestone is set for a release-candidate version.\n\nCheck original repository with HekrAPI bindings: [hekrapi-python: Hekr protocol bindings for Python](https://github.com/alryaz/hekrapi-python)\n\nYou can also help with translating this component. Fork this repository, make changes to preferred language files in\n`custom_components/hekr/translations`, remove the `_remove_me_after_making_translations_or_everything_will_be_replaced`\ntranslation key, and submit a pull request. Alternatively you can send a translation file directly through one of the\ncommunication channels listed at the end of this page.\n\n## Supported protocols\n\n- [Power meter protocol](#power_meter_protocol): `power_meter`\n- [Power socket protocol](#power_socket_protocol): `power_socket`\n\n## Power meter protocol: `power_meter`\n\u003ca name=\"power_meter_protocol\"\u003e\n\n![Loaded badges for power meter protocol](https://raw.githubusercontent.com/alryaz/hass-hekr-component/master/images/power_meter/badges.png)\n\n_(more screenshots available at: [images/power_meter](images/power_meter))_\n\n### Supported devices\n- HIKING DDS238-4W\n\n### Example configuration\n```yaml\nhekr:\n  devices:\n    - host: home-power-meter.lan\n      device_id: ESP_2M_AABBCCDDEEFF\n      control_key: 202cb962ac59075b964b07152d234b70\n      protocol: power_meter\n      sensors:\n        - general\n        - detailed\n      switches: main_power\n```\n\nIn this state, the plugin will generate three sensors, all obtained via a single `queryDev` command.\nThese sensors are:\n- `status` - **Status** (whether device reports any kind of errors)\n- `current_consumption` - **Current Consumption** (current power consumption in *W*, phase attributes in *kW*)\n- `total_consumption` - **Total Consumption** (total energy consumption in *kW/h*).\n\nAlso the following sensors are available, but not enabled by default (as they increase the amount of requests required\nto poll the device, leading to infrequent, but possible timeouts):\n- `general` - **General Information** (spews out all data available from `queryDev` command)\n- `detailed` - **Detailed Information** (spews out all data available from `queryData` command)\n- `voltage` - **Voltage** (voltage for every available phase, also mean voltage)\n- `current` - **Current** (current for every available phase, also mean current)\n- `power_factor` - **Power Factor**\n- `active_power` - **Active Power**\n- `reactive_power` - **Reactive Power**\n\nRecent release added support for switches, but so far there is only one supported:\n- `main_power` - **Main Power** (toggles relay power on and off) \n\n#### Custom sensors, set polling interval and name\n```yaml\nhekr:\n  devices:\n    - device_id: ESP_2M_AABBCCDDEEFF\n      host: home-power-meter.lan\n      control_key: 202cb962ac59075b964b07152d234b70\n      scan_interval:\n        seconds: 15\n      protocol: power_meter\n      sensors:\n        - general\n        - detailed\n        - status\n        - current_consumption\n        - total_consumption\n        - voltage\n        - current\n        - power_factor\n        - active_power\n        - reactive_power\n```\n\n#### Enable `main_power` switch, do not add any sensors\n```yaml\nhekr:\n  devices:\n    - device_id: ESP_2M_AABBCCDDEEFF\n      host: home-power-meter.lan\n      control_key: 202cb962ac59075b964b07152d234b70\n      scan_interval:\n        seconds: 15\n      protocol: power_meter\n      sensors: false\n      switches:\n        - main_power\n```\n\n## Power socket protocol: `power_socket`\n\u003ca name=\"power_socket_protocol\"\u003e\n\n![Loaded switches for power socket protocol](https://raw.githubusercontent.com/alryaz/hass-hekr-component/master/images/power_socket/switches.png)\n\n**[Device](https://raw.githubusercontent.com/alryaz/hass-hekr-component/master/images/power_socket/device.jpg) | [Board picture](https://raw.githubusercontent.com/alryaz/hass-hekr-component/master/images/power_socket/board.jpg)**\n\u003c!--_(more screenshots available at: [images/power_socket](images/power_socket))_--\u003e\n\n### Supported devices\n- SK-B-03/16A/EU\n- 7h sevenON elec\n- Sockets that identify themselves as CZ-05\n\n### Example configuration\n```yaml\nhekr:\n  devices:\n    - host: tv-power-socket.lan\n      device_id: ESP_2M_AABBCCDDEEFF\n      control_key: 202cb962ac59075b964b07152d234b70\n      protocol: power_socket\n```\n\nIn this state, the component will generate a single switch (`main_power`) obtained via a\nsingle `Quary` command.\n\n\u003c!-- Unfortunately, they named it Quary, not Query, and I'm equally irked by this --\u003e\n\n## Fetching `device_id` and `control_key` for local setup\nThe following steps (evidently) assume you already paired target device using Wisen.\n\n### _Integrations_ menu\nThe easiest way to accomplish this is to begin an integration flow with `account` setup type.\n\nTick the box `Create notification with device info` during setup, and a persistent notification\nwill appear containing compatible YAML config.\n\n### _Wisen_ application   (Only Android ! Doesn't work with Apple App anymore)\nTo obtain `device_id` and `control_key`:\n- Open _Wisen_ application\n- Open sidebar menu (on the left)\n- Select _Management_ menu entry\n- Select your device\n- Tap device icon at the top 5 times\n- A toast notification will appear\n\n### HttpCanary (packet sniffing, Android)\nThe following tutorial is left for educational purposes / explanation on how protocol decoding was done.\n\n##### Pre-requisites:\n- An android device with working Wi-Fi\n- Installed _HttpCanary_ application ([Google Play Store link](https://play.google.com/store/apps/details?id=com.guoshi.httpcanary\u0026hl=ru))\n- Installed and configured _Wisen_ application ([Google Play Store link](https://play.google.com/store/apps/details?id=me.hekr.hummingbird))\n- Configured target device via Wisen application\n- Non-isolated access point to communicate with target device\n\n##### Capturing instructions:\n1. Open _HttpCanary_ application, and do the following:\n   1. ___(required)___ Accept VPN configuration and ___(optional)___ install root certificate\n   1. Open `Target Apps` from the side menu\n   1. Tap `+` in the top right corner\n   1. Search for `Wisen` in the search box, and select _Wisen_ from search results \n   1. Go back to the main screen; you will see _Wisen_'s icon with `Tap the floating button to start capture` text under\n      it appear in the middle of your screen. __!!! DO NOT START CAPTURE YET !!!__\n1. Force-close and re-open _Wisen_ application, and do the following:\n   1. Open `Settings` from the side menu\n   1. Open `LAN settings` submenu\n   1. Flick the switch to ___on___ position\n1. Go back to the _HttpCanary_ application, and start listening by pressing button in the bottom left corner; you will\n   now observe `Capturing...` as well as possibly some of cloud Wisen's requests appear on screen; should they not\n   appear, go back to _Wisen_ and open up your device from the grid of available devices. After than, enough requests\n   will be made to successfully extract needed data.\n1. Look for requests with of `WebSocket` type, or `UDP` type to port `10000`. Once you found at least one, open it and\n   look for messages containing `ctrlKey` (=`control_key`) and `devTid` (=`device_id`).\n   An example response would look something like this, mind the linebreaks:\n   ```js\n   {\n     \"msgId\": 7,\n     \"action\": \"devSend\",\n     \"params\": {\n       \"devTid\": \"ESP_2M_AABBCCDDEEFF\", // This will be your `device_id`\n       \"appTid\": [],\n       \"subDevTid\": null,\n       \"ctrlKey\": \"202cb962ac59075b964b07152d234b70\", // This will be your `control_key`\n       // more data...\n     },\n     // more data...\n   }\n   ```\n1. __Congratulations, you're ready!__ You can proceed by using any of the configuration methods described above to add\n   your device to HomeAssistant.\n \n## Author\n\n👤 **Alexander Ryazanov (@alryaz)**\n\n* Github: [@alryaz](https://github.com/alryaz)\n* Telegram: [@alryaz](https://t.me/alryaz)\n* E-Mail: [alryaz@xavux.com](mailto:alryaz@xavux.com?subject=Hekr%20Component)\n\nGive a ⭐ if this project helped you!\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falryaz%2Fhass-hekr-component","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falryaz%2Fhass-hekr-component","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falryaz%2Fhass-hekr-component/lists"}