Introduction

Konnected is Embracing ESPHome as our preferred firmware platform for our devices going forward, and this latest-generation API specification leverages the capabilities of ESPHome to provide rich integration capabilities for developers of automation and monitoring software. Read more: Konnected is Made for ESPHome

When to Use This API

This API is made for developers of automation and monitoring software and platforms, as well as individuals wanting to build custom tools, to quickly and easily integrate Konnected products into their environment. It exposes a simple REST-based API for interacting with the device, and a server-sent events framework for receiving state updates from the device.

When to use ESPHome's Native API instead

Konnected devices automatically talk via the ESPHome Native API, an optimized custom protocol that tightly integrates ESPHome with clients. Home Assistant has built-in support (via aioesphomeapi), and Hubitat now supports it (via bradsjm/hubitat-public. ESPHome's native API is feature-rich, fast and flexible, but a lot of effort to implement the protocol if there's not a library readily available. Use ESPHome's native API instead of this API if you can leverage an existing library or platform.

Prerequistes

To use this API you need a Konnected device running an ESPHome firmware build and the web_server component must be enabled (this is enabled by default).

Connecting to Wi-Fi

When the Konnected device is not connected to a Wi-Fi network, it will broadcast its own setup Wi-Fi network soon after booting. The network will be named alarm-panel-xxxxxx or garage-door-xxxxxx. Connect to this network on a phone or computer. If the captive portal Wi-Fi connection screen doesn't automatically pop up, go to http://192.168.4.1 in the browser to select your Wi-Fi network and enter the password.

Bluetooth-capable Konnected devices, including the Alarm Panel Pro and GDOv2, also support the Improv Wi-Fi standard.

Discovery via mDNS

Konnected devices running ESPHome-based firmware are discoverable on the local network via mDNS (also referred to as Zeroconf).

Konnected devices now advertise a _konnected mDNS service. (new in 2024.3 release).

ESPHome devices advertise themselves with the esphomelib and http service types depending on which services are enabled. Devices publish several TXT records on the konnected and esphomelib services which can be used to identify the device:

Konnected devices will always have a project_name attribute that begins with konnected.

Example discovery via dns-sd on Mac OS

% dns-sd -B  _http local.

Browsing for _http._tcp.local.
DATE: ---Sat 16 Dec 2023---
14:48:43.705  ...STARTING...
Timestamp     A/R    Flags  if Domain               Service Type         Instance Name
14:48:43.705  Add        3  15 local.               _http._tcp.          garage-door-c124d0

% dns-sd -B _esphomelib local.

Browsing for _esphomelib._tcp.local.
DATE: ---Sat 16 Dec 2023---
14:48:53.809  ...STARTING...
Timestamp     A/R    Flags  if Domain               Service Type         Instance Name
14:48:53.810  Add        3  15 local.               _esphomelib._tcp.    garage-door-c124d0

% dns-sd -L garage-door-c124d0 _esphomelib local.

Lookup garage-door-c124d0._esphomelib._tcp.local.
DATE: ---Sat 16 Dec 2023---
14:49:14.427  ...STARTING...
14:49:14.428  garage-door-c124d0._esphomelib._tcp.local. can be reached at garage-door-c124d0.local.:6053 (interface 15)
 package_import_url=github://konnected-io/konnected-esphome/garage-door-esp32.yaml@master project_version=0.4.2 project_name=konnected.garage-door-esp32 network=wifi board=esp32-s3-devkitc-1 platform=ESP32 mac=dc5475c124d0 version=2023.12.0-dev friendly_name=Garage\ Door\ Opener

Example discovery via avahi-browse on Linux

avahi-browse --resolve _esphomelib

Authentication

Authentication is not enabled by default. ESPHome's web server component supports digest authentication which can be enabled by customizing and rebuilding the firmware with the following config:

web_server:
  auth:
    username: !secret digest_user
    password: !secret digest_pass