'StateReport' Skill Help
This Alexa skill supports spoken commands that facilitate querying the state of doors, windows, lights, appliances, meters/counters, thermostats and timers in Domoticz.
A choice was made not to control or change anything in Domoticz via this skill, as that functionality is already adequately handled by both Controlicz and Alexicz under Amazon's Smart Home skill paradigm.
As a custom skill type, the aim of StateReport is to perform useful reporting tasks that simply cannot be handled within a Smart Home skill because of gaps in the underlying voice model. It's not a replacement for the visual Domoticz dashboard but complements it for those moments when consulting a screen is not convenient.
Whenever the skill is invoked, the first query is always /json.htm?type=plans&order=name&used=true to determine what room plans you have. Then, depending on the particular command issued, the room plans with names Lights, Appliances, Doors, Windows, Meters, Thermostats are retrieved and fuzzy-searched for named devices (for drill-down) or to create a general state-report if no target device name is specified.
The Appliances room-plan might look as follows, containing devices with an on/off state only:
The Timers command category does not require a room plan to function and always automatically queries all timers in the active timer plan.
If your intent targets a single device rather than a whole roomplan, the skill's fuzzy-matching will compensate for locale differences such as spelling color/colour but will not magically allow you to use device names that don't match your locale.
If your Domoticz is in e.g. Dutch and all your devices are named in Dutch (e.g. Eetkamer Lamp) you can place an alias in the Description field of the Domoticz UI to give the device an English name for Alexa: alias: Dining Room Light; ← semicolon
Most commands can be either generally or specifically applied, so you can ask "What windows are open? for a list of all currently-open windows, or ask "Is the Bedroom Window open?" to narrow the search down.
Rather than just giving 1:1 representations of device states as answers like a Smart Home skill does, this skill aims to provide additional useful information for certain query categories:
- If a dimmable light is ON then its current dimming-percentage is mentioned.
- If an appliance (such as a washing machine) is ON then the last seen timestamp is subtracted from the current server time to tell you how long the appliance has been on for.
- If a timer with random-switching is queried then the actual switching-time for today will be mentioned in the response.
- For Evohome thermostats, you will be told what zone(s) are calling for heat and what the current setpoint and actual temperatures are, together with the controller-mode and whether an until time was specified for any overrides. That value is translated into a time-remaining calculation. The response will also mention the name and current temperature of both the coolest and warmest zones in your house.
Because Domoticz is not accessible from outside your LAN, we need to install a so-called proxy to enable secure access to your instance from the Amazon cloud.
Our easy-setup[1] procedure deploys a proxy called ngrok to open up a persistent tunnel resulting in a password-protected URL like https://a3dd1b636afa.eu.ngrok.io for your Domoticz instance.
Since initializing the tunnel is an outward process originating in your LAN, there's no need to open any ports in your router — ngrok also takes care of a valid certificate for SSL.
Alexa ↔ [443/https] ↔ proxy ↔ [8080/http] ↔ Domoticz
The skill communicates with your proxy and it is the proxy (perched on the LAN side of your firewall on your local network at home) that actually interacts with Domoticz.
With this approach, cloud control is password-protected while local control within your LAN remains completely unrestricted.
Please note that you cannot use either a VPN or the my.domoticz.com service as your proxy.
[1] You don't have to use this procedure to link the skill. If Domoticz is reachable via https due to an existing reverse-proxy running via e.g. nginx or apache in your setup, this can be used as-is. See here and substitute your own external URL instead of an assigned ngrok URL.
Visit the ngrok.com website (no affiliation) for an explanation of how it works and what plans are available. The free plan[1] works just fine for our purposes so go ahead and Sign Up.
To subsequently authenticate you towards ngrok, you should make a note of your personal authtoken which resides at https://dashboard.ngrok.com/auth/your-authtoken. It will look something like 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p.
Please ignore any download/setup instructions at the ngrok website as they are geared towards setting up access to a web-server on 80 rather than a home automation server like Domoticz on 8080. Our installer will automatically download ngrok for you and configure it for Domoticz.
[1] The easy-setup installer ensures that the skill is updated with the changed tunnel URL whenever you restart ngrok or reboot your machine.
- The target operating system under which ngrok will run.
- Region. To minimize latency, ngrok will use a cloud server physically near you. You can choose one of us eu ap au sa jp in.
- Authtoken. Paste the personal authtoken you copied after ngrok SignUp (e.g. 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p) or else use the pink -icon button to visit your ngrok account and retrieve it.
- A username to associate with your tunnel to prevent unauthorized cloud-access to Domoticz. It must be at least 4 characters and may not contain spaces or |.
- A password to associate with your tunnel to prevent unauthorized cloud-access to Domoticz. It must be at least 8 characters and may not contain spaces or |.
- The local fixed IP address used to access Domoticz inside your LAN. For example, http://192.168.1.10:8080. You may omit the http prefix but not the 8080.
When all the entries are completed, press the large pink Download Script button and the script file will be saved by your browser.
Your browser may warn that script files sourced from the internet are potentially harmful — it does this based on the .sh or .ps1 file extension, not the actual contents. Some browsers may even change the extension of the saved file to .txt to render it 'harmless'. If that happens you will need to manually rename with the correct extension before running it.
[1] All data is transported over SSL and is AES-256 encrypted at rest. The resulting script is built in RAM on our webserver — it is never saved to our filesystem. Note, however, that the password you choose for your tunnel will be stored in plain-text in the .yml file created on your machine after you run the script. It's probably wise not to re-use a password you use elsewhere.
Follow the appropriate instructions below for the operating system under which ngrok will run — note this does not have to be the same machine as Domoticz runs on ! Then perform account-linking as explained in the bottom paragraph.
Debian Linuxes
Applies to any Debian-based distro which supports systemd services and
bash scripting. Examples include Raspberry Pi OS, Ubuntu and Debian.
- Open a terminal. Place[1] the downloaded file setup.sh in your home directory, e.g. /home/pi
- Run it using sudo bash setup.sh
Installs ngrok to /usr/local/bin/ngrok and creates a service file /etc/systemd/system/ngrok.service to run ngrok as a daemon at boot. It also builds a file called ~/.ngrok2/ngrok.yml with your configuration. Finally, it creates the ~/ngrok_updater.sh auto-updater file that refreshes your tunnel details when you reboot.
MacOS
Place the downloaded setup.sh script in your normal Downloadsfolder.
- In the Finder, open the Applications folder and then Utilities. Double-click on Terminal to pop open a terminal.
- Inside the terminal window, typecd ~/Downloads
- Run the installer using sudo /bin/bash setup.sh (you will need to type your Mac password to authorize).
Installs ngrok to /usr/local/bin/ngrok and creates a launchd file /Library/LaunchDaemons/com.ngrok.onstartup.plist to run ngrok as a daemon at boot. It also builds a file called /usr/local/bin/.ngrok2/ngrok.yml with your configuration. Finally, it creates the /usr/local/bin/ngrok_updater.sh auto-updater file that refreshes your tunnel details when you reboot.
Windows 10 / 11
This is perhaps the easiest install, so you could consider using it temporarily when evaluating the
skill.
- Right-click on the downloaded PowerShell file setup.ps1 in your downloads folder and select the option to Run with PowerShell. If that is not allowed on your PC, see the comments in the file for a simple fix.
Installs ngrok to c:\ngrok and creates a config file called c:\ngrok\ngrok_config.yml. In the same directory, you'll see ngrok_autostart.ps1 and a wrapper ngrok_autostart.cmd. A shortcut to ngrok_autostart.cmd is added to Windows' startup apps folder.
Account Linking
When the setup script finishes, you will be told[2] that ngrok is now running a tunnel through a URL like https://a3dd1b636afa.eu.ngrok.io.
- Enable/Link the skill by clicking here: [ → StateReport ]. You will be redirected to log in to your Amazon account and
authorize/allow Alexa access to the skill. The correct language version for your locale will be
automatically selected.
- If you prefer to link the skill(s) manually from the Alexa portal, in the field you will enter the assigned ngrok URL, adding your credentials in the and fields. See here.
[1] If the target system is headless, use ssh or scp via e.g. filezilla, winscp or putty to transfer the script file across.
[2] On the free plan, ngrok can only be run on a single machine in your local LAN so if it's already running for some other purpose you will receive a 108 error.
During setup: ngrok errors
If you get a 108 error during setup, it's because ngrok is already running (in the background / on some other machine?) using your authtoken — you can only run one instance on a free account. For a full list of ngrok errors, see here.
monitor ngrok
From any machine in your local network, you can watch what the background ngrok process is doing by browsing to the IP address of the ngrok host machine on port 4040, e.g. http://192.168.1.8:4040 or http://localhost:4040. The status tab there will show you the ngrok subdomain assigned to your tunnel.
Alternatively, you can login to your ngrok online dashboard and see your assigned tunnel at https://dashboard.ngrok.com/status/tunnels.
Alexa says: ngrok tunnel invalid
The golden rule is — think before you re-link! It's almost never necessary.
If Alexa tells you your ngrok tunnel no longer exists, manually running the updater script should get you back online again immediately. If it happens regularly, consider using Ethernet rather than WiFi or move the machine closer to your router. Remember, ngrok can run on any machine in your network and happily proxy to Domoticz on a different machine.
Alexa says: ngrok authorization failure
Unless you deliberately changed the username and password in your .yml file, the only plausible explanation for this is that you dropped a tunnel without running the updater script. In the meanwhile, your old URL was randomly allocated to some other ngrok user (by ngrok, not us) who of course has different credentials to you. So the previously-known tunnel 'exists' but the authorization fails (for you). The cure is to manually restart ngrok on your machine — that way, you will get a new URL without conflict. If you really did change your .yml credentials then you have no option other than to re-link the skill(s). The tunnel credentials are immutable in the Alexa cloud and not pushed as part of updating (for security reasons).
uuid reset
If for whatever reason you want to reset your uuid to start an install with a clean slate, click on the tiny symbol in the info-banner on the configuration page.
As mentioned earlier, the skill determines device categories based on room plans. When you ask "What lights are on?" your Lights room plan is queried. If you don't already have this room plan defined and populated then Alexa will tell you she cannot help you. Same for the other categories.
To get the most benefit from the skill, you will have to define and populate plans with names Lights, Appliances, Doors, Windows, Meters, and Thermostats. The characteristics of each group are:
- Lights are reported as being on/off and their current dim-level is reported (as a percentage) if they are dimmable.
- Appliances are searched for on/off state but also have their on-duration mentioned. So for e.g. a dishwasher or oven, you get an indication how much longer the cycle might take to complete. Or with a washing-machine, you can judge if it is finished and can be unloaded.
- Doors, Windows are searched for their open/closed state. Useful if it's starting to rain and you are not sure if upstairs windows are still open.
- Meters are scanned to report the CounterToday values of each device. Normally used for meters/counters such as Gas, Water, Electricity.
- Evohome Zones are scanned to report the Current Temperature, SetPoint, Override, Mode, Until-time (where relevant) parameters of each TRV/zone. The EvoTouch Controller Mode is also queried. By subtracting the setpoint from the current temperature, heat-demand is mentioned as a Boolean true/false for each zone. You can therefore easily query if any zones in your home are calling for heat. The skill also sorts your zones according to current temperature and calls out both the coolest and warmest zones in the house.
Lights*
- What lights are on?
- Is the Bedroom Light on?
- Is the Garage Light off?
- What's the Corner Light dimming level?
- What's the Reading Light level?
- Full: Alexa, ask StateReport about Lights
Appliances*
- What appliances are on?
- Is the Washing Machine on?
- Is the Dishwasher off?
- Full: Alexa, ask StateReport about Appliances
Doors*
- What doors are open?
- Is the Garage Door open?
- Is the Shed Door closed?
- Full: Alexa, ask StateReport about Doors
Windows*
- What windows are open?
- Is the Bedroom Window open?
- Is the Attic Window closed?
- Full: Ask StateReport about Windows
Meters*
- Get today's energy usage
- What's today's consumption?
- Get the Gas Meter reading
- Give me the Electricity Meter reading
- Full: Ask StateReport for today's Energy Usage
Timers*
- Get the next timer
- What's the next Bedroom Light timer?
- What's the next Sprinkler timer event?
- Full: Alexa, ask StateReport what Timer switches next?
Thermostats*
- Get the heat demand
- What's the Bathroom Zone setting?
- Full: Alexa, ask StateReport about the Central Heating
General*
- Get the house summary
- Summarize
- Help (shows example commands on Echo Show screen)
- Cancel / Stop / Home Screen
- Full: Alexa, ask StateReport to Summarize
Query RoomPlan*
- List my Thermostats
- List the Meters category
*Invoking the Skill
StateReport is a so-called custom skill, meaning it has to be invoked using the skill name in your utterance (see the 'Full:' examples above).
Some different and freely interchangeable ways of invoking the skill include:
- Alexa, ask State Report what lights are on
- Alexa, ask State Report if the Kitchen Light is on
- Alexa, tell State Report to get the Corner Light level
- Alexa, open State Report and get the Reading Light state
- Alexa, launch State Report and get Open Windows
- Alexa, next timer using State Report
- Alexa, get today's readings from State Report