Home
Welcome to the Homey-ESPhome-Enhanced wiki!
This project aim to provide ESPhome (esphome.io) support to Homey. It was original written by Robin van Kekem (https://github.com/Inversion-NL/Homey-ESPhome) but published in Homey store by someone else ...
I was looking to connect Homey to my ESPhome device using MQQT until I found this great app, and discovered how efficient the native api is compared to MQTT ... however it was missing cover support. So I made my own fork!
Few weeks later, I end up owner of the app on the Homey store, and so I released my first version 0.3.0.
- This chapter include a lot of informations and screenshots which may not be up to date! While I will try my best to keep them relevant, open a documentation issue if you find any misleading information.
- The bearer token functionnality (constraint) is explained in its own chapter below
ESPhome application come with a "Wizard" driver, it is difficult to compare it with other "standard" drivers! It allows you to manage all your ESPhome device within a single interface.
It can be accessed through the '+' (Add a device) from any zone, go check out the User Guide
ESPhome devices are great piece of engineering, they include a CPU (ESP32, ..) and can be configured to do a lot of things. Here, the word "configured" is really outmatched, it's mostly more about "programmed". You could use a single ESPhome embeded device to handle so many things ...
And that's why I made a Wizard!
Homey device are based on capabilities, actually all "home automation" things are capability based. They expect a device to do a single thing, or at least related to the same thing. But it's far from a thruth.
For exemple, there are devices with several buttons, you could use one to control a light bubble, and another to control your heater, alarm or whatever YOU WANT!
1st conclusion:
- A real world device could be matched with many "home automation" device
- In other words: You may want to consider each button of your real world device as different devices!
You could also have a device which provide a relevant information for every other devices! For exemple, an external temperature sensor which you want to appear in several room of your home (front garden, back garden, ... whatever).
2nd conclusion:
- A real world device could be matched with many "home automation" device for the same capability
- In other words: You may want to use the same button in several rooms
You could also wants a device to summarize the temperatures of all your house.
3rd conclusion:
- A "home automation" device should not be limited to a single "real world" device
In short, who the hell in this world decided how the users should handle their own home!
Bring back freedom to peoples!
Even if this chapter means to be detailed, it's actually simple once the general concept is understood.
In Homey (like most "home automation" system), a device is:
- A virtual object => named "virtual device" in ESPhome for Homey application
- It has one or several capabilities : measure_humidity, button, switch, light, ...
- A class: this concept bring a default behaviour to the device, and is out of the bound of this user guide (have fun testing different class for your device)
In ESPhome, a device is:
- A physical object (with a CPU and a configuration) => named "physical device" in ESPhome for Homey application
- It has several entities: you can see it as different 'software'
- Each entities has one or more attributs: state (on/off, interger value, float value, ...), position, button, switch, ...
In the design of the ESPhome for Homey application, we consider a native capability to be the couple "one attribut of an entity". You decide which "capability" of a "virtual device" match with which "native capability" of a "physical device".
Each native capability has its own characteristics (defined by the ESPhome device itself), organized in the application as "configs" and "constraints". In the ESPhome for Homey application, you can overwrite some of them (but not all ... at least for now).
Have fun exploring the possibilities, and go read the User Guide to undertstand how it works!
/!\ Refer to bearer token limitations for some constraints
- Connect to a new physical device:
- Using IP address and Port
- Encryption key and password are supported (encryption key is recommended)
- Create a new virtual device
- Add, modify and delete a capability, including:
- Name, Zone and Class of a virtual device
- Which native capability is matched: you can change it, and even pick one of another physical device
- Modify characteristics of a capability
- Add, modify and delete a capability, including:
- Modify a physical device
- Name, IP address, Port, Encryption key and Password
Thanks for Athom BV consistancy in their SDK and API, some functionnalities require to retrieve and input your "bearer token". Thanks Athom BV, the bearer token expire regularly, so you need to input it whenever you want to access those functionnalities ...
The bearer token can be input in the main page (first page) of the wizard, and will be valid for the current Wizard session.
If you leave the Wizard, you will need to input it again ...
The bearer token can be retrieved using the developper tool of your prefered browser, see below.
The functionnalities concerned are:
- Modification of the name and zone of a virtual device
- Deletion of a virtual device
You can do all those from the standard Homey interface, so no big deal here.
You can retrieve your token from a web browser (you cannot from the Homey app on your phone):
- Access "My Homey" web interface through a browser: https://my.homey.app/
- Connect to your Homey
- Open the developper tool (usually F12)
- Go to the network tab
- Start the "ESPhome Wizard": It can be accessed through the '+' (Add a device) from any zone (refer to the User Guide)
- Select any "emit" calls in the network tab
- Find the bearer token (in the exemple below, it starts with 0572 and ends with 88ac)
In the ESPhome for Homey application, your bearer token is not shared with anyone, the application use it locally because Athom BV (manufacturer of Homey) is not capabable to design consistent SDK and API ...
I (Baldhor) do not have any access to your bearer token, and it is filtered off from console.re logs!
Hopefully some days, Athom BV "developpers" will understand how much time peoples (like me) building applications for Homey waste time, maybe that day they will start to be consistent ...
/rant off