BETA
This is a beta release. There will be some bugs, issues, etc. Please bear with us and open issues in the repo.
Hilo integration for Home Assistant
This is the unofficial HACS Hilo integration for Home Assistant. Hilo is a smart home platform developed by a Hydro Quebec subsidiary. This integration has no direct tie with Hilo or Hydro Quebec. This is a community initiative. Please don't contact Hilo or Hydro-Quebec with issues with this Home Assistant integration, you can open an issue in the GitHub repository instead.
If you want to help with the development of this integration, you can always submit a feedback form from the Hilo application and requesting that they open their API publicly and that they provide a testing environment to the developers.
Big shout out to Francis Poisson who's the original author of this integration. Without the work he put into this integration, I would probably have never even considered Hilo.
Another big shout out to @ic-dev21 for his implication at multiple levels.
I decided to move the integration here because of the latest updates from Hilo broke the original one, and I took the time to completely rewrite it. Hilo is now pushing device readings via websocket from SignalR.
- Support for switches and dimmers as light devices
- Get current and set target temperature of thermostat
- Get energy usage of pretty much each device
- Generates energy meters and sensors
- Sensor for Hilo Events (challenges)
- Sensor for Hilo Gateway
- Now configuration is done via the UI
- Updates are now closer to realtime
- NEW: Authentication directly on Hilo's website
- NEW: Outdoor weather sensor with changing icon like in the Hilo App
- Add functionalities for other devices
- unit and functional tests
- Adding type hints to the code
- API calls to Hilo documentation now available here
- Map send energy meters automatically to energy dashboard
This custom component requires that Hilo has carried out the installation in your home. It will not be possible to set it up otherwise.
This custom component has been tested to work by various users on HA OS (as bare metal or VM), Docker with the official (ghcr.io) image and Podman. Other types of install may cause permission issues during the creation of a few files needed by the custom component.
Make sure you have HACS installed. Under HACS, click the '+ EXPLORE & DOWNLOAD REPOSITORIES' button on the bottom of the page, search for "Hilo", choose it, and click download in HACS.
Download and copy the custom_components/hilo
directory from the latest release to your custom_components
directory in HA.
In HA, go to Settings > Devices & Services > Integrations. In the bottom right corner, click the '+ ADD INTEGRATION' button.
If the component is properly installed, you should be able to find the 'Hilo integration' in the list. You might need to clear your browser cache for the integration to show up.
The configuration is done in the UI. When you add the integration, you will be redirected to Hilo's website login page to authenticate.
You must then accept to link your account. To do so, you must enter your Home Assistant instance's URL or IP address and click Link Account.
After this, you will be prompted to assign a room for each one of your devices.
After update, you will get an error saying you must reauthenticate for the integration to work.
After correctly linking your account like in the previous section, you should see a popup telling you the reauthentification was successful.
Energy meters are a feature of this integration. We used to manually generate them with template sensors and automation, but they now have been fully integrated into the Hilo integration.
When enabling Hilo generated energy meters, it's recommended to remove the manually generated ones to have the most accurate statistics, otherwise we might end up with duplicated data.
If you're facing an issue, and you want to collaborate, please enable debug
log level for this integration and provide a copy
of the home-assistant.log
file. Details on how to enable debug
are below.
If you want to enable the automatic generation of the energy sensors, follow these steps:
-
Make sure that the
utility_meter
platform is loaded in yourconfiguration.yaml
file from home assistant. You simply need to add a line like this in yourconfiguration.yaml
:utility_meter:
-
Click
Configure
on the integration UI and check theGenerate energy meters
box. -
Restart home assistant and wait 5 minutes until you see the
sensor.hilo_energy_total_low
entity getting created and populated with data:- The
status
should be incollecting
- The
state
should be a number higher than 0.
- The
-
All generated entities and sensors will be prefixed or suffixed with
hilo_energy_
orhilo_rate_
. -
If you see the following error in your logs, this is a bug in Home Assistant, and it's because the power meter in question has 0 W/h usage so far. This will disappear once usage has been calculated.
2021-11-29 22:03:46 ERROR (MainThread) [homeassistant] Error doing job: Task exception was never retrieved Traceback (most recent call last): [...] ValueError: could not convert string to float: 'None'
Once created, energy meters will then have to be added manually to the energy dashboard.
Other options are available under the Configure
button in Home Assistant:
-
Generate energy meters
: CheckboxAutomatically generate energy meters, see procedure above for proper setup Requires this line to be added to your configuration.yaml file:
utility_meter:
-
Generate only total meters for each devices
: CheckboxCalculate only energy total without splitting between low cost and high cost
-
Also log request data and websocket messages (requires debug log level on both the integration and pyhilo)
: CheckboxAllows higher logging level for developers/debugging
-
Lock climate entities during Hilo challenges, preventing any changes when a challenge is in progress.
Prevents modifying temperature setpoints during Hilo Challenges
-
Track unknown power sources in a separate energy sensor. This is a round approximation calculated when we get a reading from the Smart Energy Meter.
: CheckboxAll energy sources other than Hilo hardware are lumped into a single sensor. Uses the reading from the home's smart meter.
-
hq_plan_name
: StringDefine the Hydro Quebec rate plan name. Only 2 values are supported at this time:
rate d
flex d
-
appreciation phase
: Integer (hours)Add an appreciation phase of X hours before the preheat phase.
-
pre_cold phase
: Integer (hours)Add a cooldown phase of X hours to reduce temperatures before the appreciation phase
-
Scan interval (min: 60s)
: IntegerNumber of seconds between each device update. Defaults to 60 and, it's not recommended to go below 30 as it might result in a suspension from Hilo. Since 2023.11.1 the minimum has changed from 15s to 60s.
You can find multiple examples and ideas for lovelace dashboard, cards and automation here in the wiki of the project
As stated above, this is an unofficial integration. Hilo is not supporting direct API calls and might obfuscate the service or prevent us from using it.
For now, these are the swagger links we've found:
- https://wapphqcdev01-automation.azurewebsites.net/swagger/index.html
- https://wapphqcdev01-notification.azurewebsites.net/swagger/index.html
- https://wapphqcdev01-clientele.azurewebsites.net/swagger/index.html
You can find the FAQ in the wiki of the project: https://github.com/dvd-dev/hilo/wiki/FAQ
Reporting any kind of issue is a good way of contributing to the project, and it's available to anyone.
If you face any kind of problem or weird behavior, please submit an issue and ideal, attach debug logs.
To enable debug log level, you need to add this to your configuration.yaml
file:
logger:
default: info
logs:
custom_components.hilo: debug
pyhilo: debug
If you have any kind of python/home-assistant experience and want to contribute to the code, feel free to submit a pull request.
- Prepare necessary directories:
$ HASS_DEV=~/hass-dev/
$ HASS_RELEASE=2023.12.3
$ mkdir -p ${HASS_DEV}/config
$ cd $HASS_DEV
$ git clone https://github.com/dvd-dev/hilo.git
$ git clone https://github.com/dvd-dev/python-hilo.git
$ git clone https://github.com/home-assistant/core.git
$ git --git-dir core/ checkout $HASS_RELEASE
NOTE: We also clone home-assistant's core to make it easier to add logging at that level repo.
- Launch the container:
$ docker run -d -p 8123:8123 \
--name hass \
-v ${HASS_DEV}/config:/config \
-v ${HASS_DEV}/python-hilo/pyhilo:/usr/local/lib/python3.11/site-packages/pyhilo:ro \
-v ${HASS_DEV}/hilo/custom_components/hilo/:/config/custom_components/hilo:ro \
-v ${HASS_DEV}/core/homeassistant:/usr/src/homeassistant/homeassistant:ro \
homeassistant/home-assistant:$HASS_RELEASE
- Check the container is running
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
bace2264ee54 homeassistant/home-assistant:2023.12.3 "/init" 3 hours ago Up 28 minutes 0.0.0.0:8123->8123/tcp hass
- Check home-assistant logs
$ less ${HASS_DEV}/config/home-assistant.log
$ grep hilo ${HASS_DEV}/config/home-assistant.log
- Activate debug logs
$ cat << EOF >> ${HASS_DEV}/config/configuration.yaml
logger:
default: info
logs:
custom_components.hilo: debug
pyhilo: debug
EOF
$ docker restart hass
It goes without saying you must test your modifications on your local install for problems. You may modify the .py files inside the following folder. Don't forget a backup!
custom_components/hilo
If you need to modify python-hilo for your tests, you can pull your own fork into Home Assistant with the following on the CLI:
pip install -e git+https://github.com/YOUR_FORK_HERE/python-hilo.git#egg=python-hilo
You must then restart Home Assistant for your install to take effect. To go back to the original, simply type:
pip install python-hilo
And restart Home Assistant
- First you need to
fork
the repository into your own userspace. - And then, you can
clone
it on your computer. - To maintain some kind of tidiness and standard in the code, we have some linters and validators that need to be executed via
pre-commit
hooks:
pre-commit install --install-hooks
- You can now proceed with whatever code change you want.
- Once you're done with the code change, you can
stage
the files for acommit
:
git add path/to/file
- And you can create a
commit
:
git commit -m "I changed this because blabla"
- Finally, you can
push
the change in your upstream repository:
git push
- At this point, if you visit the upstream repository, GitHub should prompt you to create a Pull Request (aka PR). Just follow the instructions.