Firmware Update

You can see the current firmware version in Home Assistant. Find your Home Buttons in the device list and click it. Firmware version is displayed in the Device info card.

Firmware can be updated in a couple ways:

• Over The Air (OTA) using a web interface - recommended
• Online Flash Tool using a web browser and USB to Serial adapter
• Esptool.py via USB to Serial adapter
• Full Image Flash - repair a device that is not booting. Can be done via Esptool.py or Online Flash Tool.

OTA is the simplest way and therefore recommended.

Over The Air (OTA)

1. Find the latest firmware here. Check release notes for any special update requirements. Make sure to select the correct file ending with _mini.bin. Download it to your computer.

2. Enter Setup from the Settings Menu. Home Buttons will display instructions for connecting to a web interface. Scan the QR code or enter the local IP into a web browser.

   

3. Click Info and scroll to the bottom of the Info screen. Click Update. The update menu will load:

   

4. Click Choose file and select the previously downloaded .bin file on your computer.

5. Click Update Wait a few seconds while the firmware is downloaded to the device. When done, Update Successful message will appear in your web browser and Home Buttons will reboot.

   

Online Flash Tool

Flash your device from your web browser.

1. Connect Home Buttons to your computer using an USB to Serial adapter.

   Important: Adapter should be set to 3.3 V logic level.

   • Connect GND of adapter to GND of Home Buttons
   • Connect TX of adapter to RX of Home Buttons
   • Connect RX of adapter to TX of Home Buttons

   The batteries must stay inserted during the update process.

   Pins are located on the right edge of the PCB:

   

   Depending on your adapter, it might be possible to plugin its header directly into Home Buttons. But double check the pin order first.

2. Go to nplan.github.io/HomeButtonsFlasher and follow the instructions.

Google Chrome and Microsoft Edge are supported

Esptool.py

1. Install esptool. If you already have Python installed, the easiest way is to install it using pip:

   pip install esptool
   

   See here for more installation details.

2. Find the latest firmware here. Check release notes for any special update requirements. Make sure to select the correct file:

   1. Update image - regular update

      Select file ending with _mini.bin.

   2. Full image - to flash the entire device memory. This will erase all user data.

      Select file ending with _mini_full_image.bin.

   Download the file to your computer.

3. Open the case. See instructions here.

4. Place device into programming mode. Press and hold the BOOT button and then press the RST button. BOOT LED will light up. Release both buttons.

   

5. Connect Home Buttons to your computer using an USB to Serial adapter.

   Important: Adapter should be set to 3.3 V logic level.

   • Connect GND of adapter to GND of Home Buttons
   • Connect TX of adapter to RX of Home Buttons
   • Connect RX of adapter to TX of Home Buttons

   The batteries must stay inserted during the update process.

   Pins are located on the right edge of the PCB:

   

   Depending on your adapter, it might be possible to plugin its header directly into Home Buttons. But double check the pin order first.

6. Determine port on you computer.

   Windows

   Open Device Manager and check Ports section. If you're not sure which device is Home Buttons, disconnect it and then reconnect it. See which port disappears and then appears again. Remember the COM## name.

   ** macOS and Linux **

   Run the following command twice. First with Home Buttons connected and then disconnected. The port that is present the first time and not the second is the correct one.

   macOS

   ls /dev/cu*
   

   Linux

   ls /dev/tty*
   

   Copy the path of the correct port.

7. Flash the firmware using esptool.

   Run this commands in Terminal or Command Prompt:

   1. Update image - regular update

      python -m esptool --port PORT --after no_reset erase_region 0xe000 0x2000
      

      python -m esptool --port PORT --after no_reset write_flash 0x10000 BIN_FILE_PATH
      

      Substitute PORT with port that you determined in previous step. Substitute BIN_FILE_PATH with the path of downloaded firmware .bin file.

      The erase_region command resets the app partition boot switch. It's required to make sure the device will boot to the newly flashed firmware.

   2. Full image - to flash the entire device memory. This will erase all user data.

      python -m esptool --port PORT --after no_reset write_flash 0x0 BIN_FILE_PATH
      

      Substitute PORT with port that you determined in previous step. Substitute BIN_FILE_PATH with the path of downloaded firmware .bin file.

8. Wait a few seconds for firmware to flash. When done, you will see a confirmation in Terminal or Command Prompt window.

9. Disconnect the USB to Serial adapter and press the RST button.

Full Image Flash

This method flashes the entire device memory. It can be used to repair a device that is not booting.

Important! User data will be lost. This includes button labels, WiFi credentials, MQTT settings, etc.

You can flash your device via:

• Online Flash Tool - follow the instructions above. Select Full Image in the online tool prior to flashing.
• Esptool.py - follow the instructions above. Download the correct image when required.