Homebridge myQ

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

homebridge-myq is officially retired, for now. For those interested in an alternative solution, I would highly recommend looking into Ratgdo and my homebridge-ratgdo plugin that provides all the capabilities of homebridge-myq and more capabilities that were never possible due to the myQ API constraints. Thank you for all the support and to the members of the community I've gotten to know over the years.

homebridge-myq ~~is~~was 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~~were two ways to control a myQ-compatible garage door opener through HomeKit:

1. 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.

2. 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. 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 myQ devices. 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 and gate 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 Started

  • 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 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.

Things To Be Aware Of

• The myQ API has largely stabilized in recent years, particularly with the advent of the v6 version of the API. However, the myQ cloud can (and does) have occasional reliability challenges that can manifest through connectivity issues that you will see in the Homebridge logs related to this plugin. These are not bugs in homebridge-myq and there's not much we can do it aside from attempt to gracefully handle the errors when they occur. The myQ cloud is quite reliable the large majority (~93-95% by my estimate) of the time. Please do not open bug reports related to API issues - they'll be closed summarily unless it's a new API-specific issue that's emerged as a result of changes to the undocumented myQ API. These issues are largely harmless and resolve themselves on their own, usually in minutes, and occasionally in hours or days.

• 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 cloud infrastructure from Liftmaster / Chamberlain is not completely reliable and occasionally errors out due to infrastructure maintenance, network issues, or other infrastructure hiccups that occur on the myQ end of things. This plugin has no control over this. The logging is informative and not a cause for significant concern unless it is constant and ongoing for multiple days, 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.

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 protected]",
    "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.

Plugin Development Dashboard

This is mostly of interest to the true developer nerds amongst us.