Skip to content

FIRMWARE_UPDATE.md

Latest commit

 

History

History
63 lines (40 loc) · 3.77 KB

FIRMWARE_UPDATE.md

File metadata and controls

63 lines (40 loc) · 3.77 KB
Raw

AirCube Firmware Update Guide

Update your AirCube from the browser with AirCube Web. It talks to the cube over USB using the Web Serial API, so there is nothing to install -- and once you are connected you also get live readings, the LED brightness control and your history, the same as the desktop app.

Prerequisites

  • Browser: Google Chrome or Microsoft Edge (Safari and Firefox do not support Web Serial)
  • OS: Windows, macOS, Linux, or ChromeOS
  • Cable: A data-capable USB-C cable (charge-only cables won't work)

Step-by-Step

1) Open AirCube Web

Go to stuckatprototype.github.io/AirCube.

2) Connect your AirCube

  1. Plug the USB-C cable into your AirCube and your computer.
  2. Close anything else that might be holding the serial port (AirCube Tray, Arduino Serial Monitor, idf.py monitor).
  3. Click + Connect and pick your AirCube from the browser's device prompt. It appears as "USB JTAG/serial debug unit" or similar.

With one cube connected the app opens straight to its page and starts showing live readings.

3) Flash the firmware

  1. Open the ⋯ menu on the device page and choose Flash firmware. (You can also reach it from Settings → Firmware.)
  2. Pick the version you want. The newest release is marked (latest).
  3. Leave the flash offset at 0x0 (merged release image).
  4. Click Flash and watch the log. It takes about 30 seconds.

The cube reboots itself when the write finishes and reconnects automatically. The LED should light up green after a few seconds.

Your settings -- brightness level and Zigbee pairing -- are preserved across firmware updates.

Flashing a development build

If you built the firmware yourself with idf.py build, you have two options:

  • Flash build/AirCube.bin (the app only) at offset 0x10000.
  • Or run esptool merge-bin first and flash the merged image at 0x0.

Use the Local .bin button in the flash dialog to pick the file, then choose the matching offset.

Troubleshooting

  • No device in the connect dialog: Make sure another app isn't using the serial port. Try a different USB port or cable. On some USB-C cables, flipping the connector helps.
  • Browser not supported: Use Chrome or Edge on a desktop OS. Safari and Firefox do not implement Web Serial, and iOS browsers cannot access USB devices at all.
  • "Failed to open serial port": Another tab or application already has it. Close AirCube Tray and any serial monitors, then click Refresh in the dialog.
  • Flashing fails partway: Unplug the AirCube, plug it back in, and try again. The bootloader is only reached at reset, so a fresh power cycle usually clears it.
  • Charge-only cable: Some USB-C cables carry power but no data. Use the same cable that works with the desktop app.
  • Linux: If the device never appears, your user may need permission for the ESP USB device. Add a udev rule for 303a:1001 or add yourself to the dialout group, then replug.
  • The cube doesn't reconnect after flashing: Unplug and replug the USB-C cable, then click Connect again.

Alternatives

  • AirCube Tray -- the Windows desktop app, which can also flash over USB.
  • ESP Launchpad -- Espressif's generic web flasher. Use the DIY tab, add the .bin from Releases, and set the flash address to 0x0.
  • esptool -- esptool --chip esp32h2 -p PORT write-flash 0x0 AirCube_firmware_vX.Y.Z.bin

Success

After it reboots, the AirCube LED lights up and begins showing air quality colors within a few seconds. The gas sensor needs about 3 minutes to warm up before readings stabilize.