Skip to content

Setup

Jump to bottom
White Red edited this page Oct 7, 2024 · 15 revisions

1. Flashing

Firmware binaries are available on the releases page and come in three files as follows:

  • firmware_merged.bin - this is to be flashed with esptool.py
  • firmware.bin - this is meant for OTA update but can also be flashed with esptool.py
  • littlefs.bin - this includes the HTML files for the Web Interface

When updating, it's recommended to do it via OTA as some checks are done to assure it's at least a somewhat valid firmware.

To flash the firmware, it is recommended to use the esptool. This can be acquired from here or through Python's PIP with the command pip install esptool

If you are flashing a new device use the command: python esptool.py write_flash 0x0 <firmware_merged.bin>

If you are encountering issues with the firmware at start e.g. reset loops, try erasing the flash with esptool.py erase_flash and flash again the firmware, if it still doesn't work, open an issue or reach out on the Discord server

3. WIFI

From version 0.3, the firmware is configured to autostart an Access Point which allows for effortless WiFi configuration.

Steps are as follows:

  • Connect to the Wifi network "HomeSpan-Setup" with the password homespan
  • Wait a couple of seconds and a page should automatically open (Captive Portal)
  • Configure the Wifi credentials
  • (Optionally) Configure the HomeKit Setup Code

Note

If the page does not appear once connected to the AP, it can also be accessed manually on http://192.168.4.1/hotspot-detect.html

4. HomeKit

The pairing code is the default 466-37-726 from the HomeSpan library that can be found in their documentation here.

This can be changed when configuring WiFi through the Access Point, from the Web UI accessible on port 80 or from the serial terminal using command S <setup code>.

Modifying config.h won't change the setup code.

4.1 Sharing the HomeKey

HomeKey does not implement any sharing functionality and the only option for anyone else to have access to the same key is to invite them into your Apple Home, you can find more information about this on Apple's support page.

Note

If you don't have a homehub and are missing the invite button, follow the steps in this issue comment, thanks @yannik2480

Clone this wiki locally