Konnected's Smart Garage Door Opener is an IoT device that retrofits an existing garage door opener, adding the ability to sense if the garage door is open or close and control the garage door opener toggle switch using a built-in dry-contact relay. This API specification applies to the following models when running Konnected's current ESPHome platform firmware for the GDO. This is the default firmware that's pre-installed on new Konnected GDOs, and should work out-of-the-box with this API.

Model GDOv1-S

The first generation of Konnected's GDO, sold from May - December 2023. The GDOv1-S ships with Konnected's legacy firmware, and must be re-flashed with ESPHome firmware for this API to be applicable. Flash the device at install.konnected.io/garage-door-opener and select ESPHome firmware.

Model GDOv2-S

Konnected's second generation GDO for dry-contact triggered garage door and gate openers. Sold beginning in December 2023, this model ships with ESPHome firmware pre-loaded. Firmware can be updated or re-installed at install.konnected.io/garage-door-opener

API Implementation Guide

You're building an application, driver, or other piece of software to interact with Konnected's GDO, great! This section outlines the minimal successful implementation for the core features of the device.

The Garage Door cover

Each Konnected GDO controls and monitors a single garage door. The garage door is represented by the garage door cover component, which exposes the following endpoints:

GET /cover/garage_door
POST /cover/garage_door/open
POST /cover/garage_door/close
POST /cover/garage_door/stop

A cover is the name given by the Home Assistant / ESPHome developers to represent objects or entryways that have opening and closing controls as well as states. Konnected's GDO implements the cover interface with the device class of garage.

Garage Door State

The current state of the garage door cover can be queried using the GET endpoint above and by listening for Server-sent Events state updates with the ID cover-garage_door. The state can be either OPEN or CLOSED. The garage door also has a current_operation state attribute which can be one of: IDLE, OPENING or CLOSING.

Konnected automatically determines the state of the garage door via feedback from the optical laser sensor, wired contact sensor / limit switch, or both. This state calculation is done internally and exposed to the garage door cover component. The end-user or installer can select which sensor(s) to use when configuring the firmware. By default, only the optical laser sensor is used in computing the garage door state and the wired sensor is treated as an independently reporting sensor.

In the future we may add the ability for the end-user to change the garage door state sensor input configuration on the fly, but it currently must be done at the firmware config level. For integration developers, it doesn't really matter because the garage door cover interface should always be used as the canonical state of the garage door.

Garage Door Control

The user interaction to control the garage door should be executed by the POST request cover endpoints detailed in this documentation. Konnected considers the current state of the garage door and the desired control action to ensure that the request is valid and to perform important safety warnings. For example, if the door is open and receives a close command, it will automatically trigger the pre-close warning prior to trigging the garage door opener to close. If the garage door is already closed and the device receives a close command, it will not trigger the garage door to move.

This automatic state-awareness is only done when using the garage door cover interface. You can bypass this logic if desired by utilizing the lower-level button interface for the garage door opener trigger.

Optical Laser Sensor

Most end-users will use the device's built-in optical laser sensor to detect if the garage door is open or closed. The sensor needs to be calibrated to the known distance between the ceiling-mounted Konnected GDO and the rolled-up garage door below it.

Calibrating the Sensor

Your application may need to expose a function for the end-user to calibrate the sensor distance. This is most easily done by instructing the end user to manually open the garage door with the device mounted in position. When the garage door is open, read the current value of the distance sensor (GET /sensor/sensor_distance) and subsequently set that value to the calibration endpoint (POST /number/sensor_calibration/set). Once set, the calibrated value is stored in the device's non-volatile memory.