Updating Over-the-Air via ESPHome Command Line

This guide explains how to update your Konnected device firmware using pre-built OTA (Over-the-Air) binary files and the ESPHome command line tool. This method is useful when you want to update your device without using the ESPHome Dashboard or Home Assistant.

Prerequisites

A computer or laptop on the same network as your Konnected device
Python 3.7 or newer installed on your computer
Your Konnected device's IP address

Overview

OTA updates allow you to wirelessly upload new firmware to your Konnected device without physically connecting it to your computer. Konnected provides pre-built OTA binary files for official "stock" firmware releases, which you can download and upload using the ESPHome command line tool. These are the same firmware binaries that we use at the factory to

Step 1: Install ESPHome Command Line Tool

The ESPHome command line tool is distributed as a Python package and can be installed using pip.

Installation

Open a terminal or command prompt and run:

pip install esphome

Verify Installation

After installation completes, verify that ESPHome is installed correctly:

esphome version

You should see the ESPHome version number displayed.

Step 2: Download Firmware Files

You'll need to download two files from the Konnected ESPHome GitHub releases:

The pre-built OTA binary file (.ota.bin)
The corresponding YAML configuration file

Download from GitHub Releases

Visit the Konnected ESPHome releases page: https://github.com/konnected-io/konnected-esphome/releases
Find the release version you want to install (typically the latest release)
Download the appropriate .ota.bin file for your device. OTA binary files are named with the pattern:
```
konnected-esphome-[device-type]-[version].ota.bin
```
For example: konnected-esphome-garage-door-GDOv2-Q-1.5.6.ota.bin
Download the corresponding YAML configuration file for your device:
```
[device-type].yaml
```
For example: garage-door-GDOv2-Q.yaml

Save Files

Save both files to a convenient location on your computer, such as your Downloads folder. Make note of the file paths as you'll need them in the next step.

Step 3: Find Your Device's IP Address

You need to know your Konnected device's IP address on your local network. You can find this by:

Checking your router's connected devices list
Using the Konnected mobile app (Device Info)
Checking your Home Assistant integrations (if applicable)
Using a network scanning tool like Fing or Advanced IP Scanner

The IP address will look something like 10.0.1.212 or 192.168.1.100.

Step 4: Upload the Firmware

Now you're ready to upload the firmware to your device using the ESPHome command line tool.

Upload Command

Open a terminal or command prompt and run the following command, replacing the file paths and IP address with your actual values:

esphome upload garage-door-GDOv2-Q.yaml --file ~/Downloads/konnected-esphome-garage-door-GDOv2-Q-1.5.6.ota.bin --device 10.0.1.212

Command Breakdown

esphome upload - The ESPHome command to upload firmware
garage-door-GDOv2-Q.yaml - The configuration file (first parameter, required)
--file ~/Downloads/konnected-esphome-garage-door-GDOv2-Q-1.5.6.ota.bin - Path to the pre-built OTA binary
--device 10.0.1.212 - The IP address of your Konnected device

Example for Different Operating Systems

macOS/Linux:

esphome upload garage-door-GDOv2-Q.yaml --file ~/Downloads/konnected-esphome-garage-door-GDOv2-Q-1.5.6.ota.bin --device 192.168.1.100

Windows (PowerShell):

esphome upload garage-door-GDOv2-Q.yaml --file C:\Users\YourName\Downloads\konnected-esphome-garage-door-GDOv2-Q-1.5.6.ota.bin --device 192.168.1.100

Windows (Command Prompt):

esphome upload garage-door-GDOv2-Q.yaml --file C:\Users\YourName\Downloads\konnected-esphome-garage-door-GDOv2-Q-1.5.6.ota.bin --device 192.168.1.100

What to Expect

When you run the upload command, you should see:

ESPHome connects to your device
Progress indicators showing the upload status
A success message when the upload completes
Your device will automatically restart with the new firmware

The entire process typically takes 1-2 minutes.

Troubleshooting

"Could not connect to device" or "Connection refused"

Possible causes and solutions:

Wrong IP address: Verify your device's current IP address hasn't changed. Check your router or use a network scanner.
Device is offline: Ensure your Konnected device has power and is connected to your WiFi network.
Firewall blocking connection: Temporarily disable your computer's firewall or add an exception for ESPHome.
Network issues: Make sure your computer and Konnected device are on the same network (not separated by VLANs or guest networks).

"File not found" error

Possible causes and solutions:

Incorrect file path: Double-check that the paths to both the .yaml and .ota.bin files are correct.
Missing tilde expansion (Windows): On Windows, use the full path instead of ~. For example, use C:\Users\YourName\Downloads\... instead of ~/Downloads/...
Files not downloaded: Ensure both files have been completely downloaded from GitHub.

"ESPHome command not found"

Possible causes and solutions:

ESPHome not installed: Run pip install esphome to install it.
Python not in PATH: Ensure Python and pip are properly installed and added to your system's PATH environment variable.
Using wrong Python version: ESPHome requires Python 3.7 or newer. Check your version with python --version or python3 --version.
Install location issue: Try python -m esphome or python3 -m esphome instead of just esphome.

Upload starts but fails partway through

Possible causes and solutions:

Weak WiFi signal: Move the Konnected device closer to your WiFi router or access point.
Network interruption: Ensure stable network connectivity during the upload process.
Insufficient space: The device may not have enough flash memory. This is rare but can happen with corrupted filesystems.
Wrong binary file: Ensure you downloaded the correct .ota.bin file for your specific device model.

Frequently Asked Questions

Do I need to compile the firmware myself?

No! Konnected provides pre-built OTA binary files for all official firmware releases. You only need to download the .ota.bin file and upload it using the command shown in this guide.

What's the difference between `.bin` and `.ota.bin` files?

.bin files are used for initial flashing via USB/serial connection
.ota.bin files are specifically formatted for over-the-air updates and are what you should use with the esphome upload command

Can I use this method to update from any version to any other version?

Yes, OTA updates work regardless of your current firmware version, as long as your device has OTA update capability enabled (which all Konnected stock firmware versions do).

Will this erase my configuration?

No, OTA updates preserve your WiFi credentials and device configuration. However, it's always good practice to back up your configuration before updating.

How do I know which firmware file to download for my device?

The firmware filenames include the device type. Match the filename to your specific Konnected device model (e.g., Alarm Panel, Garage Door Opener, etc.). Check your device documentation if you're unsure.

Can I downgrade to an older firmware version?

Yes, you can upload any firmware version using this method, including older versions if you need to downgrade.

What if I don't know my device's IP address?

Check your router's DHCP client list, use the Konnected mobile app, or use a network scanning tool. Alternatively, you can check your Home Assistant integrations if your device is connected to Home Assistant.

The YAML file seems unnecessary. Why is it required?

The ESPHome tool requires a configuration file as a parameter even when using the --file flag to specify a pre-built binary. The YAML file provides metadata about the device that ESPHome uses during the upload process.

Alternative Update Methods

If you encounter issues with the command line method, consider these alternatives:

Web Based Install Tool: You can always recover the device by physically re-flashing it with a USB cable via install.konnected.io.
Command Line (via USB cable)
Konnected App: Devices can be updated through the Konnected mobile app

Updating Over-the-Air via ESPHome Command Line

Update your Konnected device firmware using pre-built OTA (Over-the-Air) binary files and the ESPHome command line tool.