HomeAssistant Hekr Integration

HomeAssistant implementation of Hekr API communicator

💵 Donation options to support development

💬 Technical Support

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.

❗❗❗ WARNING ❗❗❗

THIS PROJECT IS HIGHLY WORK-IN-PROGRESS!!! Things are subject to change drastically until at least two to three different Hekr implementations are discovered and added to the integration as well as the parent python module. Please, read release notes carefully before installing or upgrading. I am not responsible for damaging your devices in any way!

❗❗❗ Elro Connects owners ❗❗❗

This module does not yet support Elro Connects, however work has been done to make a testing implementation. Testers with Elro K1 gateways are needed. Please, contact me via e-mail <[email protected]>.

Contribution

If you found yourself using Wisen application with any of your Smart Home devices, contact me via e-mail <[email protected]>. The process of adding new devices is not yet completely formalized, the milestone is set for a release-candidate version.

Check original repository with HekrAPI bindings: hekrapi-python: Hekr protocol bindings for Python

You can also help with translating this component. Fork this repository, make changes to preferred language files in custom_components/hekr/translations, remove the _remove_me_after_making_translations_or_everything_will_be_replaced translation key, and submit a pull request. Alternatively you can send a translation file directly through one of the communication channels listed at the end of this page.

Supported protocols

• Power meter protocol: power_meter
• Power socket protocol: power_socket

Power meter protocol: power_meter

(more screenshots available at: images/power_meter)

Supported devices

• HIKING DDS238-4W

Example configuration

hekr:
  devices:
    - host: home-power-meter.lan
      device_id: ESP_2M_AABBCCDDEEFF
      control_key: 202cb962ac59075b964b07152d234b70
      protocol: power_meter
      sensors:
        - general
        - detailed
      switches: main_power

In this state, the plugin will generate three sensors, all obtained via a single queryDev command. These sensors are:

• status - Status (whether device reports any kind of errors)
• current_consumption - Current Consumption (current power consumption in W, phase attributes in kW)
• total_consumption - Total Consumption (total energy consumption in kW/h).

Also the following sensors are available, but not enabled by default (as they increase the amount of requests required to poll the device, leading to infrequent, but possible timeouts):

• general - General Information (spews out all data available from queryDev command)
• detailed - Detailed Information (spews out all data available from queryData command)
• voltage - Voltage (voltage for every available phase, also mean voltage)
• current - Current (current for every available phase, also mean current)
• power_factor - Power Factor
• active_power - Active Power
• reactive_power - Reactive Power

Recent release added support for switches, but so far there is only one supported:

• main_power - Main Power (toggles relay power on and off)

Custom sensors, set polling interval and name

hekr:
  devices:
    - device_id: ESP_2M_AABBCCDDEEFF
      host: home-power-meter.lan
      control_key: 202cb962ac59075b964b07152d234b70
      scan_interval:
        seconds: 15
      protocol: power_meter
      sensors:
        - general
        - detailed
        - status
        - current_consumption
        - total_consumption
        - voltage
        - current
        - power_factor
        - active_power
        - reactive_power

Enable main_power switch, do not add any sensors

hekr:
  devices:
    - device_id: ESP_2M_AABBCCDDEEFF
      host: home-power-meter.lan
      control_key: 202cb962ac59075b964b07152d234b70
      scan_interval:
        seconds: 15
      protocol: power_meter
      sensors: false
      switches:
        - main_power

Power socket protocol: power_socket

Device | Board picture

Supported devices

• SK-B-03/16A/EU
• 7h sevenON elec
• Sockets that identify themselves as CZ-05

Example configuration

hekr:
  devices:
    - host: tv-power-socket.lan
      device_id: ESP_2M_AABBCCDDEEFF
      control_key: 202cb962ac59075b964b07152d234b70
      protocol: power_socket

In this state, the component will generate a single switch (main_power) obtained via a single Quary command.

Fetching device_id and control_key for local setup

The following steps (evidently) assume you already paired target device using Wisen.

Integrations menu

The easiest way to accomplish this is to begin an integration flow with account setup type.

Tick the box Create notification with device info during setup, and a persistent notification will appear containing compatible YAML config.

Wisen application (Only Android ! Doesn't work with Apple App anymore)

To obtain device_id and control_key:

• Open Wisen application
• Open sidebar menu (on the left)
• Select Management menu entry
• Select your device
• Tap device icon at the top 5 times
• A toast notification will appear

HttpCanary (packet sniffing, Android)

The following tutorial is left for educational purposes / explanation on how protocol decoding was done.

Pre-requisites:

• An android device with working Wi-Fi
• Installed HttpCanary application (Google Play Store link)
• Installed and configured Wisen application (Google Play Store link)
• Configured target device via Wisen application
• Non-isolated access point to communicate with target device

Capturing instructions:

1. Open HttpCanary application, and do the following:
   1. (required) Accept VPN configuration and (optional) install root certificate
   2. Open Target Apps from the side menu
   3. Tap + in the top right corner
   4. Search for Wisen in the search box, and select Wisen from search results
   5. Go back to the main screen; you will see Wisen's icon with Tap the floating button to start capture text under it appear in the middle of your screen. !!! DO NOT START CAPTURE YET !!!
2. Force-close and re-open Wisen application, and do the following:
   1. Open Settings from the side menu
   2. Open LAN settings submenu
   3. Flick the switch to on position
3. Go back to the HttpCanary application, and start listening by pressing button in the bottom left corner; you will now observe Capturing... as well as possibly some of cloud Wisen's requests appear on screen; should they not appear, go back to Wisen and open up your device from the grid of available devices. After than, enough requests will be made to successfully extract needed data.
4. Look for requests with of WebSocket type, or UDP type to port 10000. Once you found at least one, open it and look for messages containing ctrlKey (=control_key) and devTid (=device_id). An example response would look something like this, mind the linebreaks:

   {
     "msgId": 7,
     "action": "devSend",
     "params": {
       "devTid": "ESP_2M_AABBCCDDEEFF", // This will be your `device_id`
       "appTid": [],
       "subDevTid": null,
       "ctrlKey": "202cb962ac59075b964b07152d234b70", // This will be your `control_key`
       // more data...
     },
     // more data...
   }

5. Congratulations, you're ready! You can proceed by using any of the configuration methods described above to add your device to HomeAssistant.

Author

👤 Alexander Ryazanov (@alryaz)

• Github: @alryaz
• Telegram: @alryaz
• E-Mail: [email protected]

Give a ⭐ if this project helped you!