Background and Overview (Why and What?)
During the transition from Vera to Ezlo, users will be faced with gaps due to missing capabilities and plugins that are not yet fully realized on Ezlo Hubs. I know this from personal experience because I am living it. The Ezlo team is busily building out their hardware, cloud platform and firmware offerings and will handily meet, exceed and surpass Vera’s capabilities in due time but today there are barrier-to-entry obstacles that will may make it difficult for users to seamlessly transition from Vera to Ezlo controllers. Examples include HomeKit, MQTT, Node-Red, House Modes triggering scenes, MyQ garage doors, etc.
@reneboer has done a bang-up job developing and supporting the bi-directional bridges Ezlo Bridge for Luup and Vera Bridge for Ezlo respectively and in that spirit, I am also developing a HomeKit bridge that leverages the Ezlo JSON RPC API to bridge HomeKit accessories to Ezlo devices.
More recently @rigpapa announced Reactor Multi System that orchestrates unified logic over federated hubs and devices (i.e. scenes triggered by a device on one hub triggers logic, akin to a scene, comprising independent devices spread across independent hubs). Reactor Multi System is similar in nature to Ezlo’s Meshene that will be native to Ezlo’s platform available later this year.
To develop the Ezlo HomeKit bridge, I wrapped many of the Ezlo’s lower-level JSON RPC API methods in higher-level Typescript, and Javascript, compatible APIs. With Patrick’s Reactor Multi-System announcement, it became clear that other developers could benefit from the off-hub API wrappers that I had already developed so I decided to repackage the API into an off-hub App SDK called Ezlo-Hub-Kit.
Specifically, Ezlo-Hub-Kit is a Node.js Package Manager module that provides a convenient, fully-typed, SDK for Ezlo Innovation’s automation hubs. The kit enables off-hub applications to discover local hubs, connect to them securely, retrieve properties such as devices and rooms, observe hub events and perform hub actions.
Examples & Demo EZ-Apps (How do I use it?)
As an example of the SDK simplicity and expressiveness, the following code snippet shows how to discover all Ezlo Hubs on the local network and log the ui_broadcast messages sent by each hub to the console.
// Discover hubs as they appear in mdns
discoverEzloHubs(new EzloCloudResolver(username, password), (hub) => {
// Securely connect to the hub and register an observer of ui_broadcast messages that logs the message to console.
hub.connect().then((hub) => {
addObserver( UIBroadcastPredicate, (msg) => {
console.log('%s %s:ui_broadcast %o\n', (new Date().toUTCString()), hub.identity, msg);
});
});
});
The snippet above, while only a few lines of code, actually does some heavy-lifting for an off-hub app. First, it starts an MDNS discovery process that calls a discovery handler every time an Ezlo hub is discovered on the local area network. The discoverEzloHubs discovery method is passed an EzloCloudResolver that retrieves the registered hubs’ credentials from the Ezlo Cloud and caches them for use until they expire (in this case, the same resolver instance provides the credentials for each discovered hub). Each time a hub is discovered, the discovery handler is called with an EzloHub instance that it uses to securely connect to the discovered hub and register an observer handler of ui_broadcast messages from that hub. From that point forward, every time the hub sends a ui_broadcast message, the observation handler is invoked with the message and it is logged to the console. In addition, Ezlo-Hub-Kit employs a keep-alive strategy to ensure that Ezlo-Hub-Kit enabled apps have a “working” connection as long as the hub is on-line and accessible. Here is sample output:
$ ./test/utils/hubMonitory.js --username blacey
Password:
Observing: 90000369, architecture: armv7l , model: h2.1 , firmware: 2.0.7.1313.16, uptime: 0d 11h 23m 28s
Observing: 90000330, architecture: armv7l , model: h2.1 , firmware: 2.0.7.1313.16, uptime: 0d 17h 57m 48s
Observing: 70060017, architecture: esp32 , model: ATOM32 , firmware: 0.8.528, uptime: 1d 17h 22m 38s
Observing: 70060095, architecture: esp32 , model: ATOM32 , firmware: 0.8.528, uptime: 0d 0h 0m 32s
Thu, 28 Jan 2021 18:33:51 GMT 70060095:ui_broadcast {
id: 'ui_broadcast',
msg_subclass: 'hub.item.updated',
msg_id: 3262983542,
result: {
_id: 'DA79ACF7',
deviceId: 'ZC5F00207',
deviceName: 'Landscape 1-4',
deviceCategory: 'dimmable_light',
deviceSubcategory: 'dimmable_colored',
serviceNotification: false,
roomName: 'Exterior',
userNotification: false,
notifications: null,
name: 'electric_meter_watt',
valueType: 'power',
value: 0,
scale: 'watt',
syncNotification: false
}
}
The hubMonitor is include with Ezlo-Hub-Kit.
Sample EZ-Apps
To further illustrate the simplicity of the Ezlo-Hub-Kit SDK, I have published a few EZ-Apps (Easy eZlo Apps) that address some of the current Vera-to-Ezlo transition pain points (I have been running these in my home for a while). In the spirit of Easy, each EZ-App is packaged as dockerized Node.JS app for Intel/AMD and ARM architectures - anyone with an RPI, Synology or other computer in their home with Docker installed can run these EZ-Apps in a few simple steps. While also performing useful functions, the EZ-Apps demonstrate how to discover hubs on the local area network, establish a secure web socket connection with each, register observers for Ezlo Hub events, change House Modes and control hub elements.
Easy HouseMode-Synchronizer propagates Vera House Mode Changes to all Ezlo hubs on the local area network. The EZ-App illustrates how to use Ezlo-Hub-Kit to discover hubs, change House Modes and how to wait for the hub to complete the mode change. Users who are transitioning from Vera to Ezlo may find this App useful because House Mode changes initiated on Vera will be propagated to every Ezlo Hub on the LAN.
Easy HouseMode-SceneRunner runs a scene on an Ezlo Hub immediately after it transitions to a new House Mode. The EZ-App illustrates how to use Ezlo-Hub-Kit to discover hubs, use observers to asynchronously act on House Mode changes and execute scenes. This EZ-App will appeal to Vera Users who have grown accustomed to employing scenes triggered by House Mode changes. As of this writing, Ezlo Hub scenes can not use House Mode changes as a trigger. EZ-HouseMode-SceneRunner bridges the this obvious gap until solutions like Ezlo’s Meshene and/or Reactor Multi System are available.
Easy MQTT-Relay publishes all ui_broadcast messages from Ezlo hubs discovered on the local area network to an MQTT broker. This EZ-App illustrates how to discover hubs, register observation handlers and publish to MQTT. This should appeal to Ezlo users who would like to push Ezlo controller/hub data to a time-series database (e.g. InfluxDB) for graphical reporting and analysis (e.g. Grafana).
Try out the apps - you will probably find them useful. The ReadMe included with each EZ-App provides the necessary installation and usage details.
Note: If you are a docker-compose user, the EZ-Apps repo contains a docker-compose.yml service definition file and unified configuration for the 3 sample EZ-Apps to make bootstrapping as easy as possible…
At this point, some of you may be asking, why aren’t these EZ-Apps Node-Red flows? They certainly could be if a Node-Red node suite existed for Ezlo hubs. However my objective is to demonstrate the simplicity of using Ezlo-Hub-Kit in hopes that it will inspire other developers to leverage Ezlo-Hub-Kit for additional applications like an Ezlo node-red node suite (any takers?)
Additional Information
The Ezlo-Hub-Kit ReadMe strives to cover the normative off-hub app usage patterns. Ezlo-Hub-Kit also includes a full suite of test cases that can serve as examples for using the API. And, its open-source, so there is always the code and comments within.
Contributors Welcome!
The Ezlo-Hub-Kit is open source to enable other developers to rapidly develop an off-hub app. I encourage other developers to leverage Ezlo-Hub-Kit for their own off-hub apps (e.g. Ezlo Node-Red node suite) to help flesh out and improve the kit (i.e. fork and submit pull requests). To facilitate contributions, I am documenting the steps required to contribute. I have also deployed a Continuous Integration workflow that will run developer’s pull requests against live Ezlo Hubs using GitHub Action Runners. You can see an example GitHub CI run here
Disclaimer
Ezlo-Hub-Kit is the first Typescript/Javascript library that I have developed so I let the stones fly where appropriate (i.e. don’t be shy about constructive code critique or helpful idioms that will improve the overall quality of the code base for everyone). Furthermore, I am releasing v1.0.0-alpha.8 now to solicit developer feedback and, depending upon the feedback, may need to iterate on some of the API call signatures until 1.0 reaches beta status hence the alpha designation at this time.