README

Homebridge myQ

myQ garage door and other myQ-enabled device support for Homebridge.

homebridge-myq is a Homebridge plugin that makes myQ-enabled devices available to Apple's HomeKit smart home platform. myQ-enabled devices include many smart garage door openers made primarily by Liftmaster, Chamberlain, and Craftsman, but includes other brands as well. You can determine if your garage door or other device is myQ-enabled by checking the myQ compatibility check tool on the myQ website.

There are two ways to control a myQ-compatible garage door opener through HomeKit:

Liftmaster and Chamberlain make a hardware HomeKit bridge also called Home Bridge (not to be confused with the open source Homebridge project). Unfortunately, some of us have encountered significant issues with the hardware bridge in a real world setting, where it either stops working or hangs for extended periods of time. That said, other users have encountered no issues and this hardware solution works well.
A plugin for Homebridge like this one that emulates the capabilities of a myQ HomeKit bridge device.

Either solution will provide you with robust HomeKit integration, and you'll soon be automating your myQ smart garage with the richness of Apple's HomeKit ecosystem!

Why use this plugin for myQ support in HomeKit?

In a nutshell, the aim of this plugin for things to just work with minimal required configuration by users. The goal is to provide as close to a streamlined experience as you would expect from a first-party or native HomeKit solution. For the adventurous, those additional granular options are, of course, available to support more esoteric use cases or other unique needs.

What does just work mean in practice? It means that this plugin will discover all your myQ devices and poll at regular, reasonable intervals for changes in state of a garage door opener, lamp, or other myQ devices and inform HomeKit of those changes. By default. Without additional configuration beyond the login information required for myQ services.

homebridge-myq has been around a long time and is trusted by thousands of users. It's the first myQ Homebridge plugin to provide comprehensive support for various myQ features such as obstruction detection, and the first to provide support for multiple myQ device types (currently, garage door openers and lamps). As more of the API can be decoded, my aim is to support as many device types as possible. I rely on this plugin every day and actively maintain and support it.

Features

Easy configuration - all you need is your myQ username and password to get started. The defaults work for the vast majority of users. When you want more, there are advanced options you can play with, if you choose.
Automatic detection and configuration of all lamps, garage door and gate openers. By default - all of your supported myQ devices are made available in HomeKit.
Obstruction detection on supported myQ garage door and gate openers. When a garage door or gate is obstructed, and the myQ API provides that information, you'll see an alert raised in the Home app.
Battery status detection on supported myQ door position sensor devices. If you have a myQ supported door position sensor, you'll see an alert raised in the Home app to inform you when the battery is running low.
The ability to selectively hide and show specific gateways (useful when you have multiple homes) or openers. For those who only want to show particular devices in HomeKit, or particular homes, a flexible and intuitive way to configure device availability at a granular level is available.
Full MQTT support. For those who use MQTT, this plugin provides full MQTT support with a rich set of options. Read the MQTT documentation for more details.

How you can contribute and make this plugin even better

The myQ API is undocumented and implementing a plugin like this one is the result of many hours of reverse engineering, trial and error, and community support. This work stands on the shoulders of other myQ API projects out there and this project attempts to contribute back to that community base of knowledge to further improve myQ support for everyone.

I would love to support more types of myQ devices. Currently homebridge-myq supports the following device types:

Garage door openers
Lamps and myQ switches

Additional device types will be added as time allows. It's unlikely I will add support for myQ locks due to their deprecated protocol support. myQ cameras may be added at some point, but there are additional non-technical considerations related to the paid myQ product that I want to be mindful of.

Documentation

Getting going
- Installation: installing this plugin, including system requirements.
- Plugin Configuration: how to quickly get up and running.
- Additional Notes: some things you should be aware of, including myQ-specific quirks.
Advanced Topics
- Feature Options: granular options to allow you to show or hide specific garage door openers, gateways, and more.
- MQTT: how to configure MQTT support.
- Advanced Configuration: complete list of configuration options available in this plugin.
- Changelog: changes and release history of this plugin, starting with v2.0.

Installation

If you are new to Homebridge, please first read the Homebridge documentation and installation instructions before proceeding.

If you have installed the Homebridge Config UI, you can intall this plugin by going to the Plugins tab and searching for homebridge-myq and installing it.

If you prefer to install homebridge-myq from the command line, you can do so by executing:

sudo npm install -g homebridge-myq

Things To Be Aware Of

The myQ API gets regularly updated and unfortunately this results in regularly breaking this and other myQ-related plugins. I've refactored this plugin in part to make it easier to maintain with future API changes that may come. Unfortunately, it's an ongoing challenge since API changes can be sudden and unpredictable.
As a result of the above you will see errors similar to this on an occasional basis in the Homebridge logs:
```
myQ API: Unable to update device status from the myQ API. Acquiring a new access token.
```
These messages can be safely ignored. myQ API errors will inevtiably happen. The myQ server-side infrastructure from Liftmaster / Chamberlain is not completely reliable and occasionally errors out due to server maintenance, network issues, or other infrastructure hiccups that occur on the myQ end of things. This plugin has no control over this, unfortunately, and all we can do is handle those errors gracefully, which is what I've attempted to do. The logging is informative and not a cause for significant concern unless it is constant and ongoing, which would be indicative of the larger API issues referenced above. When one of these errors is detected, we log back into the myQ infrastructure, obtain new API security credentials, and attempt refresh our status in the next scheduled update, which by is roughly every 12 seconds by default.
Obstruction detection in myQ is more nuanced than one might think at first glance. When myQ detects an obstruction, that obstruction is only visible in the API for a very small amount of time, typically no more than a few seconds. This presents a user experience problem - if you remain completely faithful to the myQ API and only show the user the obstruction for the very short amount of time that it actually occurs, the user might never notice it because the alert is not visible for more than a few seconds. Instead, the design decision I've chosen to make is to ensure that any detected obstruction is alerted in HomeKit for 30 seconds from the last time myQ detected that obstruction. This ensures that the user has a reasonable chance of noticing there was an obstruction at some point in the very recent past, without having to have the user stare at the Home app constantly to happen to catch an ephemeral state.
If your myQ device has support for battery status, homebridge-myq will automatically detect and add support for it in HomeKit. However, you will see a warning message in the Homebridge logs along the lines of:
```
HAP Warning: Characteristic 00000079-0000-1000-8000-0026BB765291 not in required or optional characteristics for service 00000041-0000-1000-8000-0026BB765291. Adding anyway.
```
This can be safely ignored. It's an error message indicating that, in HomeKit, the garage door opener accessory service doesn't normally support battery status. HomeKit will still report it correctly, and alert you accordingly.

Plugin Configuration

If you choose to configure this plugin directly instead of using the Homebridge Configuration web UI, you'll need to add the platform to your config.json in your home directory inside .homebridge.

"platforms": [{
    "platform": "myQ",
    "email": "email@email.com",
    "password": "password"
}]

For most people, I recommend using Homebridge Configuration web UI to configure this plugin rather than doing so directly. It's easier to use for most users, especially newer users, and less prone to typos, leading to other problems.