EzloController

EzloController integrates eZLO Plus and similar (new, post-Vera firmware) hubs with Reactor. It is currently in development status — you may use it, but please report bugs and clarify issues or ask questions via the Smart Home Community forums or, if you have an account, the Reactor Mantis Bug Tracker. The EzloController may in future not be included as a standard Reactor component (i.e. not included in the standard distribution packages), but offered separately as an extra-cost add-on.

Attention

Ezlo has not formally documented any of their login procedures for the their API, either for local or remote access. The EzloController class therefore must use well-known and commonly-used but undocumented methods to establish API connections; some of these have been communicated in informal channels by eZLO engineers, and some have been "discovered" by other means. I'm not sure why they have chosen to do a fairly detailed job of documenting their API, yet not documented the procedure necessary to gain access to that API, but so be it as of this writing. Since such documentation is, in effect, a guideline and specification that tempers future changes, there is no way to know if future updates to the eZLO cloud or hub firmware will continue to support the login method used.

Before starting:

Make sure you are using a supported hub. The following are supported: eZLO Plus; eZLO Secure; Vera Edge running eZLO firmware; generation 2 or higher eZLO Atom or PlugHub. You can use first-generation eZLO Atoms, but they must use cloud access, there is no local access to the hub (see the callout below for more details). Other eZLO hubs may work but are not explicitly supported.
Your eZLO Plus/Secure/Edge should be running firmware 2.0.14.1570 or higher; Atom/Plughub must be running 0.8.539 or higher.
Make sure your hub is registered and accessible via the VeraMobile mobile app.
Except first-generation Atom, the hub should be configured with either a static IP address or using a DHCP reservation, so that its IP address is stable and never changes.

Atom Support

First-generation Atom hubs do not offer local access to the hub API, so cloud/relay access is the only way to contact the hub. This makes your configuration vulnerable to failures of your Internet access, eZLO's cloud services, and even your local network. For this reason, the use of eZLO first-generation hubs is not recommended. It's fine for experimentation, however, and may be adequate for certain less important tasks. How do you know what generation of Atom you have? You may be able to tell by the serial number alone: according to eZLO, if the first four digits of your Atom's serial number are between 7000 and 7009 (inclusive), you have a "generation 1" atom, which does not support local access to the API, so only cloud/remote access is available for these units. Serial numbers 7500 to 7599 and 7600 to 7699 are EU and US version 3 hardware Atoms, respectively, and these support both local and remote access to the API. Serial numbers starting 7010 to 7499 are version 2 hardware, but may not be "generation 2" operationally and so may or may not support local API access — you're just going to have to try it. If you're serious about using an Atom in your home automation, it is strongly recommended you use at least version 3 hardware and use local API access. The final judgement of risk tolerance is, of course, your own.

To configure your hub in Reactor, you will add configuration with your hub serial number and account credentials (username and password) to the reactor.yaml file's controllers section. For all hubs except first-generation Atom, also include the source key, putting in the IP address of your hub where shown (omit the source key entirely for first-generation Atoms). Remember that all indenting is done with spaces, not tabs, in YAML files.

# other configuration sections not shown

controllers:
- id: ezlo
  enabled: true
  implementation: EzloController
  name: "My Ezlo Hub"
  config:
    source: "wss://192.168.1.15:17000"  # change the IP address
    serial: "12345678"    # put your hub's serial # here
    username: "somebody"  # put your username here betw quotes
    password: "????????"  # and password

Restart Reactor. If your credentials and IP address are correct, Reactor will connect to the hub and inventory its devices. Go to the Reactor UI, to the Entities list (left navigation), and you should be able to see your eZLO devices as entities in the list (make sure you clear any filters you may have previously applied). If you don't see your devices, check your settings, and examine the reactor.log file for messages. The most common error is not providing all four configuration elements: source, serial, username and password (and second most common is an error in the username or password values).

All good? Excellent, please read on...

Wait! Cloud Login First!

DO NOT perform the procedure below until you have successfully connected your eZLO hub using cloud authentication. Get that working first. Once that works, then you can follow this procedure. If you have lost your Ezlo account credentials or they are not working, you will need to recover your Ezlo cloud account and use the new credentials to connect to the hub as described above before you can follow this procedure.

Not for Atom/PlugHub (RTOS hubs)

Local anonymous access (accessing the API locally without cloud login or authentication tokens) is available only on Linux-based eZLO hubs (i.e. not any version of Atom or PlugHub, which are RTOS-based).

By default, eZLO hubs are configued for authenticated access. That means Reactor needs to log in to the eZLO cloud services and request an access token that it can then use to log in to the hub locally. The access token has a defined lifetime, and when it expires, a new token must be requested from the cloud services, which is done automatically as needed by EzloController. If your Internet access goes down, however, Reactor will be unable to reach the cloud services, and therefore unable to access your hub. This creates a critical-path dependency on Internet access and the stability/availability of eZLO's cloud services for your home automation rules.

eZLO hubs have the ability to enable anonymous access so that they can be accessed locally (from within your own network) without the cloud service's tokens. In this mode, reconnection to the hub is immediate and reliable even when Internet access is unavailable. Enabling anonymous access on the hub is relatively easy.

Confirm that your eZLO hub is connected for local access using cloud authentication. The controller's system entity in the Entities list will have true values for both sys_system.state and x_ezlo_sys.using_cloud_auth. The x_ezlo_sys.using_cloud_relay attribute should be false. If it is true, you have not correctly configured source with the IP address of the hub. Correct this, restart Reactor, and recheck these values before proceeding.
Add the line indicated below (do not remove or modify any other config lines yet), indented the same as the password: line:
```
password: "whateverItIs"
set_anonymous_access: true   <--- add this using same indent (spaces) as "password"
```
Restart Reactor. Reactor will log in one more time using the cloud services, but when it gets into the hub, it will reconfigure the hub up for anonymous access. It takes up to two minutes for this process to complete, and your eZLO hub may reboot one or two times, so wait at least a full two minutes before continuing.
Refresh your browser, and open the Entities list again. Go to the system entity for the eZLO hub, expand it, and confirm that the attribute x_ezlo_sys.anonymous_access_enabled is now true (again, this takes several minutes, so if it's still false, wait another minute or two). You will also receive an alert on the Status view telling you that anonymous access has been enabled.

You Are Not Finished!

EzloController will continue to use cloud login unless and until you complete the step below!
Now that anonymous access is enabled on the hub, we need to tell Reactor to use anonymous access rather than cloud authorization. Reactor will always use cloud authentication when username and password are set in your configuration, so your final step in this process is to comment out the username and password entries in your config as shown below, and restart Reactor. You can also comment out the set_anonymous_access line. Then restart Reactor one more time. To comment out the lines, just insert a # at the first (non-space) character.
```
#username: "yourusername"
#password: "whateverItIs"
#set_anonymous_access: true
```

Remember to restart Reactor after making this final change. After restart, Reactor should be connected with anonymous access (no cloud auth). To confirm, go back to the Entities list and check the eZLO hub's system entity. The value of x_ezlo_sys.using_cloud_auth should now be false, indicating that Reactor is connected anonymously.

Security Risk!

Enabling anonymous access creates certain security risks that only you can assess and accept. It allows any person on your network to access and control the hub. If any host in your network is compromised or your network is otherwise accessed by an unauthorized person or device, it would be possible for them to access and control your hub as well. The risk of enabling anonymous access is yours entirely.

If you later wish to restore authenticated access to your hub (i.e. disable anonymous access), simply uncomment the username, password and set_anonymous_access lines (remove the # in front of them), and set set_anonymous_access to false. Then restart Reactor, and it will reconfigure the hub with anonymous access disabled.

Known Issues

Ezlo's firmware is currently still under development and in a constant state of flux. There are many unfinishes areas of the firmware, including device support and other critical features. Features may break between versions of firmware, and since Ezlo hubs currently apply automatic updates with no way to turn that off, updates of firmware can occur without warning. As such, we view Ezlo hub support as experimental. The following are known issues as of this writing:

Previously, Reactor could run Lua code on the hub using the hub.extensions.plugin.run API method with the Lua bas64-encoded in the code parameter; as of Ezlo firmware version 2.0.15.1570.4 this no longer works at all, and there does not appear to be any replacement API as yet. Ref: https://community.ezlo.com/t/beta-ezlo-linux-v-2-0-15-1591-2-for-ezlo-plus-ezlo-secure-controllers/217665/5?u=rigpapa
There is apparently no analogue in the Ezlo API for the ZWave send data action; on Vera hubs, for example, the ZWave Network device (#1) supported a SendData action that could be passed a byte string to send; no such action has as yet made an appearance in the Ezlo API. Ref: https://community.ezlo.com/t/whats-the-new-firmware-equivalent-of-the-zwave-senddata-action/218029?u=rigpapa
Broadlink IR devices put into learn mode return their results via a broadcast, but there's no data connecting the broadcast to either the device or the original hub.item.value.set request required to start the process. As a result, the returned data can't reliably be attached to its originating device. Ref: https://community.ezlo.com/t/broadlink-ir-what-do-these-items-mean-do/217834/7?u=rigpapa

Updated: 2023-Jan-20

EzloController

Getting Rid of the eZLO Cloud Login Requirement

Known Issues