# AutoSense Firmware Flash Kit — v1.0.0

This kit lets you flash the AutoSense sensor firmware onto an ESP32 or ESP8266
(NodeMCU v2) board. Pick the guide that matches your situation:

- **Section A** — Your board is brand new / blank (never ran AutoSense before). Use a USB cable and the flash scripts in this kit.
- **Section B** — Your board is already running an older AutoSense firmware. Use the built-in web update page — no cables or tools needed.

---

## Section A — Flashing a blank board over USB

### 1. Install the flashing tool

You need Python 3 installed, then install `esptool`:

```bash
pip install esptool
```

### 2. Connect the board

Plug your ESP32 or ESP8266 into your computer via USB. Note which COM port /
serial port it shows up as:

- **Windows**: Device Manager → Ports (COM & LPT) → e.g. `COM5`
- **macOS**: `ls /dev/cu.*` → e.g. `/dev/cu.usbserial-0001`
- **Linux**: `ls /dev/ttyUSB*` → e.g. `/dev/ttyUSB0`

### 3. Run the flash script

**Windows:**
- ESP32 board → double-click `flash_esp32.bat`
- ESP8266 (NodeMCU) board → double-click `flash_esp8266.bat`
- Enter the COM port when prompted.

**macOS / Linux:**
```bash
chmod +x flash_esp32.sh flash_esp8266.sh
./flash_esp32.sh      # for ESP32 boards
./flash_esp8266.sh    # for ESP8266 / NodeMCU boards
```

If the board doesn't start flashing, hold the **BOOT** (or **FLASH**) button on
the board while it connects, until you see "Connecting..." succeed.

This writes both the firmware **and** the web UI files (`main.js`, `style.css`,
`plugins.json`) in one pass — the scripts include a `littlefs.bin` filesystem
image built from the `data/` folder, so there is nothing extra to upload on a
freshly flashed board.

### 4. First boot

After flashing completes, power-cycle the board. It will boot into
**Access Point mode**:

1. On your phone/laptop, connect to the WiFi network **`AutoSense`**
   (password: `AutoSense`).
2. Open a browser to `http://192.168.4.1:1980`.
3. Click **Setup WiFi** and enter your home/office WiFi credentials, MQTT
   broker address, and device name.
4. The device reboots and joins your network at
   `http://<device-name>.local:1980`.

---

## Section B — Updating a board that already runs AutoSense

No cables needed — this is an over-the-air (OTA) style update through the
device's own web interface.

1. Find the device on your network (`http://<device-name>.local:1980`, or its
   IP address).
2. Open the firmware upload page: `http://<device-name>.local:1981/update`
3. Upload the matching `.bin` file for your board from the `bin/` folder in
   this kit:
   - ESP32 boards → `bin/esp32/firmware.bin`
   - ESP8266 / NodeMCU boards → `bin/esp8266/firmware.bin`
4. Wait for the upload to finish — the device will reboot automatically on
   the new firmware.

> Note: only `firmware.bin` is needed for a firmware OTA update. The
> bootloader and partition table files (ESP32) are only required for
> Section A (USB flash of a blank board).

### Updating the web UI files only

If just the web interface changed (`main.js`, `style.css`, `plugins.json`)
and not the firmware itself, you don't need to reflash anything. Use the
static file upload page instead:

1. Open `http://<device-name>.local:1981/upload`.
2. Upload each file from the `data/` folder in this kit
   (`data/main.js`, `data/style.css`, `data/plugins.json`) one at a time.
3. Reboot the device (`http://<device-name>.local:1980/reboot`) to make sure
   it picks up the new files.

---

## Troubleshooting

- **"Failed to connect" during USB flash**: hold the board's BOOT button while
  the script attempts to connect, release once it says "Connecting...".
- **Wrong board type flashed**: re-run Section A with the correct script —
  ESP32 and ESP8266 images are not interchangeable.
- **Can't reach `.local` address**: use the device's IP address instead (check
  your router's device list), or reconnect to the `AutoSense` AP and revisit
  `http://192.168.4.1:1980`.
- **Settings lost after update**: this is expected only if you used
  `/reset` — a normal firmware update (Section A or B) keeps your saved
  settings.

## Package contents

```
AutoSense_Flash_Kit_1.0.0/
├── INSTRUCTIONS.md          <- this file
├── flash_esp32.bat/.sh      <- USB flash script for ESP32 (firmware + web UI files)
├── flash_esp8266.bat/.sh    <- USB flash script for ESP8266/NodeMCU (firmware + web UI files)
├── bin/
│   ├── esp32/
│   │   ├── bootloader.bin
│   │   ├── partitions.bin
│   │   ├── boot_app0.bin
│   │   ├── firmware.bin
│   │   └── littlefs.bin      <- web UI files, pre-packaged as a filesystem image
│   └── esp8266/
│       ├── firmware.bin
│       └── littlefs.bin      <- web UI files, pre-packaged as a filesystem image
└── data/                     <- same web UI files as loose files, for the /upload page
    ├── main.js
    ├── style.css
    └── plugins.json
```
