User Guide
All screen captures are based on a web browser, but it apply to your phone Homey application too.
The Wizard session can sometimes abruptly 'break', that's because Homey handle a 'timeout' ...
Everytime the configuration is loaded / reloaded, it can take a few seconds (usually 5).
All pages including forms (group of fields the user can input into) work out the same way.
The principles are described in the page Edit physical device.
All input fields include constraints (format, required or not, ...).
Only the unusual constraints are listed here.
I'm not going to teach you the format of an IP address!
- Physical device NAME:
- Start by a letter
- Can include upper case, lower case, number and space
- No special characters like '-', '/', '_', ...
- Virtual device NAME:
- same as physical device name
- Encryption key:
- Refer to ESPhome documentation: https://esphome.io/components/api.html
Yes, that's 5 clicks just to open it ... I'm not responsible for Athom BV user experience
This is the main page which open when you start the Wizard.
- It loads all your configuration, so it can takes a few seconds to appear
- The first time, it also loads all the HTML, javascript and so on, so it can be long ... (up to 10/15 seconds)
- Those advices only appear after migration from the old Wizard to the new one
- New users will not experience them
- Old users need to rename all their physical devices to get ride of it
They have been named 'migrated<n>' during the migration from the old Wizard ...
- Link to this Wiki
- You are there, keep reading :)
- Go to page Manage your virtual devices
- Hint: manage!
- Go to page Manage your physical devices
- Hint: manage!
- Simple shortcut to page New physical device
- It allow you to quickly connect to a new physical device
- Simple shortcut to page New virtual device
- It allow you to quickly add a new virtual device
- Got to page Console Re
- See bearer token limitations chapter
This page summarize your physical devices and virtual devices.
It's where you really start to manage your configuration and all your virtual devices.
Yes I know, the 'available' are not aligned ... I'm not a CSS expert sorry :)
- Go back to page Main
- It will force reload your configuration, but the 'new' physical devices will not be lost
- Go to page New physical device
- It allow you to quickly connect to a new physical device
- Current list and state of your ESPhome physical devices
- If a physical device is unavailable, you should go repair it through the page Manage your virtual devices
- If a physical device is 'new' (unused), the Wizard will forget about it when you close the Wizard
- Go to page New virtual device
- It allow you to quickly add a new virtual device
- Current list and state of your virtual devices
- Only show a limited amount of information to keep the list 'small'
- Go to page Edit virtual device
- The starting point to check the details of a virtual device, modify or delete it!
- hide/show the used physical devices
Usefull if you have a long list of physical devices
Unused(new) physical devices are never hidden
it will hide automatically if you have (at least one) unused physical devices
it will hide automatically if you have more than 3 physical devices
- Filter on a specific zone
By default, it will show all zones (sorted by home structure, not alphabetically!)
You can choose a zone to filter
Very handy when you have a big house
This page help you manage your physical devices.
- Go back to page Main
- It will force reload your configuration, but the 'new' physical devices will not be lost
- The name of your physical device
- It makes it easier once you have a long list to recognize them
- The state of your physical device
- Only show a limited amount of information to keep the list 'small'
- Go to page Edit physical device
- Hint: edit!
- Collect debug info for further investigation
- It will collect lot of information and make them appear in a text area (see point 6)
Passwords and Encryption key are filtered, so don't be worried!
- The collected debug info
- You can copy the whole field and join it in an issue so I can "fix it" :)
It will appear only after you clicked a link as described in step 5
No, it cannot be copied directly to the clipboard, Athom BV made it forbidden (or at least didn't authorize it)
So you need to select and copy the value yourself
This page help you connect to a new physical device.
Newly added physical device will be available for use in one (or many) virtual device(s).
If you end your Wizard session before using them, the application will 'forget' them
Refer to page Edit physical device
It's actually the same page, but with a different title and processing when you click the apply button
This page help you modify your physical device: name, ip address, port, encryption key and password can all be modified!
- Go back to page Manage your physical devices
- If there are unapplied modification(s), a popup will ask you to confirm
- The details of the physical devices, with the fields you can modify
- Grey bounded fields are editable
- Red bounded fields are invalid
- The error and warning messages
- Red message(s) means there are an invalid field (red bounded), you need to fix the issue
- Orange message(s) are a warning: in this capture, it's a security advice, you can ignore it or not (it's YOUR responsability)
- Apply your modification(s)
- Actually, this link will not appear if there are an error message (ie. a red bounded field!), I modified manually the capture to make it appear
- Your modification(s) will be applied, the configuration reloaded, and go back to page Manage your physical devices
If there are an error, a popup will warn you, and the page will not move ... try again?
Wonder about field format? Refer to Field format validation
New virtual device page ... I think you got the point, right?
As a first step, you need to give it a name, a zone and a class!
- back ... I need to explain once more?
- Choose a zone/class for your device
- Zone
- By default, it use the zone from which you started the Wizard
- If you input your bearer token in the Main page, you will be able to pick a zone from a list
- Class
- All I can say is that my 'cover' were not recognized correctly by Google Home until I set the class 'blinds'
- The documentation from Athom BV is very limited: https://apps-sdk-v3.developer.homey.app/tutorial-device-classes.html
- If you understand all the hidden secrets of each class, please write a wiki ... and send me the link!
- Otherwise, be logical and/or test them all one by one => the Wizard make it easy, enjoy!
- Just an overview of the possible class to choose from
- Apply the modification(s)
- It will reload the configuration and go to page Edit virtual device
It starts all the same as the page New virtual device
You can modify the name, zone (if bearer token is set ..) and class of the virtual device! But you can also add and modify capabilities!
Hint: the edit capability page allows to delete a capability!
- back ... I need to explain once more?
- Choose a zone/class for your device
- Zone
- By default, it use the zone from which you started the Wizard
- If you input your bearer token in the Main page, you will be able to pick a zone from a list
- Class
- All I can say is that my 'cover' were not recognized correctly by Google Home until I set the class 'blinds'
- The documentation from Athom BV is very limited: https://apps-sdk-v3.developer.homey.app/tutorial-device-classes.html
- If you understand all the hidden secrets of each class, please write a wiki ... and send me the link!
- Otherwise, be logical and/or test them all one by one => the Wizard make it easy, enjoy!
- Just an overview of the possible class to choose from
- Apply the modification(s)
- It will reload the configuration and go to page Edit virtual device
- Go to page New capability
- Allows to add a new capability
- Details of an existing capability
- Go to page Edit capability
- Allows to edit the capability
This one is going to be complicated to explain, sit down, breath, ... :)
In the first place you need to select a native capability from a physical device, then you will be able to match it to a capability from Homey (either standard or custom).
- back ... I need to explain once more?
- Choose a physical device
Refer to Manage your physical devices page to change their names!
- Choose a native capability
The list of native capabilities is based on the announcement published by your physical device
The ESPhome application for Homey use thise annoucement to recognize the supported native capabilities
Based on the implementation progress, more native capabilities may be support later, do not hesitate to create an enhancement request: Open an issue
Once a physical device and a native capability is selected, the page will be updated:
- You can modify the selected physical device and native capability anytime
It will update dynamically the page based on the new selection
- Some basic informations are shown regarding the native capability
Number usage: it indicates if this native capability of this physical device is already used!
You may want or not to use the same native capability several times!
- The show/hide link will show you even more informations
The Configuration and Constraints additional informations are used as default values for the capibility itself (see below)
- You can select a compatible capability (standard or custom)
The compatible critereas are complicated to explain, there are many (type, readOnly, writeOnly, ...)
If something looks wrong: Open an issue
Standard capabilities are designed by Athom BV (manufacturer of Homey): Homey Capabilities
Custom capabilities are designed (by me) specifically for ESPhome application for homey to enhance the supported use cases: Custom Capabilities
Once a capability is selected, the page will update once more:
- You can modify the selected capability anytime
It will update dynamically the page based on the new selection
The title and others options will not be lost
- Title: the name of the capability as it will appear in the flows and device
It's currently not mandatory, as the title will be decided by default by Homey itself
However, I advice you to define one yourself
Worst case, you can set it later Edit capability page)
- Index: refer to Custom capabilities
- Other options: refer to Capability options
Don't forget to press the apply link at the end :)
Refer to New capability page It's mostly all the same, but the physical device, native capability, capability and all the options are already initialized :)
- Allows to delete a capability!
Don't forget to press the apply link at the end :)
ConsoleRe is a web application available for free which allows to collect and watch logs as they go.
By default, the only way to access the logs of a Homey application is to run it in "developper mode" using "homey app run" command from the cli.
Usage of console.re is for private and occasionnal use, do not keep the functionnality enabled if you do not need it!
console.re will de disabled automatically after 6 hours of continious use
Yes, logs can contains personnal data (ip address, and so on, ...) so it should not be activated constantly, but only for investigations!
When you activate the console.re functionnality, the application will publish ALL your logs to console.re on a channel you configured!
console.re is a "public" web site, anyone can access your logs, if them find your channel!
Try to make YOUR channel unique and not obvious => avoid console.re/Baldhor :)
That said, the following informations are filtered out from te logs BEFORE sending them to console.re:
- password
- encryptionKey
- bearerToken
In my opinion, those are the most important to protect, nobody care about your IP address and port, or whatever
Do not hesitate to open an issue to argue if you think something else should be filtered out!
- Go back to main page
- Validate your modification
This link will appear only if you made any modification AND if they are valid
- Your channel name
Try to make YOUR channel unique and not obvious => avoid console.re/Baldhor :)
- Enable or Disable console.re
It will disable itself after 6 continuious hours
If you restart the application every 5 hours, it will never stop :)
- A link to your channel
Just open it in a large enough screen (computer :))
You can share it with us/me (in a github issue for exemple), your confidential datas are filtered
- A link to this wiki!
