Skip to content

Latest commit

 

History

History
82 lines (60 loc) · 8.38 KB

MQTT.md

File metadata and controls

82 lines (60 loc) · 8.38 KB
Raw

homebridge-ratgdp: Native HomeKit support for Ratgdo

Homebridge Ratgdo

Downloads Version Ratgdo@Homebridge Discord verified-by-homebridge

Ratgdo-enabled garage door opener support for Homebridge.

homebridge-ratgdo is a Homebridge plugin that makes Chamberlain, Liftmaster, and other garage door openers that utilize the Ratgdo hardware control board available to Apple's HomeKit smart home platform. You can determine if your garage door opener by checking the Ratgdo website.

MQTT Support

MQTT is a popular Internet of Things (IoT) messaging protocol that can be used to weave together different smart devices and orchestrate or instrument them in an infinite number of ways. In short - it lets things that might not normally be able to talk to each other communicate across ecosystems, provided they can support MQTT.

homebridge-ratgdo will publish MQTT events if you've configured a broker in the plugin settings. Supported MQTT capabilities include:

  • Garage open and close events.
  • Garage light switch events.
  • Garage motion sensor events.
  • Garage obstruction events.

Configuration

This documentation assumes you know what MQTT is, what an MQTT broker does, and how to configure it. Setting up an MQTT broker will not be covered here. There are plenty of guides available on how to do so just a search away.

You can configure MQTT settings in the plugin webUI. The settings are:

Configuration Setting Description
mqttUrl The URL of your MQTT broker. This must be in URL form, e.g.: mqtt://user:[email protected].
mqttTopic The base topic to publish to. The default is: ratgdo.

Important

mqttUrl must be a valid URL. Just entering a hostname will result in an error. The URL can use any of these protocols: mqtt, mqtts, tcp, tls, ws, wss.

When events are published, by default, the topics look like:

ratgdo/1234567890AB/garagedoor

In the above example, 1234567890AB is the MAC address of your garage door opener. We use MAC address as an easy way to guarantee unique identifiers that won't change. homebridge-ratgdo provides you information about your Ratgdo devices and their respective MAC addresses in the Homebridge log on startup.

Topics Published

The topics and messages that homebridge-ratgdo publishes are:

Topic Message Published
dooropenoccupancy true when the garage door open indicator occupancy is detected. false when the garage door open indicator occupancy event is reset.
garagedoor closed, closing, open, opening, when garage door state changes are detected.
light true when the light has been activated. false when the light has been turned off.
lock true when the garage door opener remote lock has been activated. false when the garage door opener remote lock has been turned off.
motion true when motion is detected. false when the motion event is reset.
obstruction true when an obstruction in the garage door opener is detected. false when the obstruction event is reset.
occupancy true when occupancy is detected. false when the occupancy event is reset.

Messages are published to MQTT when an action occurs on a device that triggers the respective event, or when an MQTT message is received for one of the topics homebridge-ratgdo subscribes to.

Topics Subscribed

The topics that homebridge-ratgdo subscribes to are:

Topic Message Expected
dooropenoccupancy/get true will trigger a publish event of the current garage door opener door open indicator occupancy status.
garagedoor/get true will trigger a publish event of the current garage door opener state.
garagedoor/set One of close or open. This will send the respective command to the garage door opener. When using the ESPHome firmware, open takes an optional parameter between 0 and 100 to set the door position appropriately: open 50 will set the garage door to the 50% open position.
light/get true will trigger a publish event of the current garage door opener light.
motion/get true will trigger a publish event of the current garage door opener motion sensor.
obstruction/get true will trigger a publish event of the current garage door opener obstruction sensor.
occupancy/get true will trigger a publish event of the current garage door opener occupancy status.

Note

  • MQTT support is disabled by default. It's enabled when an MQTT broker is specified in the configuration.
  • If connectivity to the broker is lost, it will perpetually retry to connect in one-minute intervals.
  • If a bad URL is provided, MQTT support will not be enabled.