Documentation

Flashie is a browser-based firmware flashing platform that uses the Web Serial API to flash firmware directly to microcontrollers. No desktop software installation is required — just a compatible browser and a USB connection.

Requirements

• Google Chrome or Microsoft Edge (version 89 or later)
• A supported microcontroller board (ESP32, ESP8266, STM32, Arduino)
• A USB data cable (not charge-only)
• An internet connection to download firmware files

Firmware flashing relies on the Web Serial API, which is only available in certain browsers.

Supported Browsers

• Google Chrome (v89+) — Fully supported
• Microsoft Edge (v89+) — Fully supported
• Opera (v76+) — Supported
• Samsung Internet (v15+) — Limited support

Unsupported Browsers

• Mozilla Firefox — No Web Serial API support
• Safari — No Web Serial API support
• Mobile browsers generally do not support Web Serial

If you see “Browser not supported” on the flash button, please switch to Chrome or Edge.

To add a new firmware project to Flashie, follow these steps:

1. Create the folder structure

public/
  projects/
    your-project-name/
      manifest.json
      firmware/
        bootloader.bin
        partitions.bin
        firmware.bin

2. Create a manifest.json

The manifest file defines the firmware files and their memory offsets for each chip family.

{
  "name": "Your Project",
  "version": "1.0.0",
  "new_install_prompt_erase": true,
  "builds": [
    {
      "chipFamily": "ESP32",
      "parts": [
        { "path": "firmware/bootloader.bin", "offset": "0x1000" },
        { "path": "firmware/partitions.bin", "offset": "0x8000" },
        { "path": "firmware/firmware.bin", "offset": "0x10000" }
      ]
    }
  ]
}

3. Add firmware files

Place your compiled firmware binaries in the firmware/ folder. The paths in manifest.json are relative to the manifest file location.

4. Register the project

Add a new entry to src/data/projects.json or use the Manage page to generate the configuration.

The manifest.json follows the ESP Web Tools manifest format.

Top-level fields

• name — Human-readable project name
• version — Firmware version string
• builds — Array of build configurations (one per chip family)
• new_install_prompt_erase — Set to true to prompt for erase before flashing
• funding_url — Optional funding link

Build object fields

• chipFamily — Target chip (ESP32, ESP32-S3, ESP32-C3, ESP8266, etc.)
• parts — Array of firmware files with paths and offsets

Part object fields

• path — Relative path from manifest to firmware file
• offset — Memory offset as string (e.g., “0x1000”)

Firmware paths in the manifest.json are relative to the manifest file itself.

Example

If your manifest is at /projects/my-project/manifest.json:

// Correct (relative path):
{ "path": "firmware/firmware.bin", "offset": "0x10000" }

// Wrong (absolute path will 404 on GitHub Pages):
{ "path": "/projects/my-project/firmware/firmware.bin", "offset": "0x10000" }

On GitHub Pages, files in the public/ folder are served at the root URL. A file at public/projects/my-project/firmware/firmware.bin is accessible at https://your-site.com/projects/my-project/firmware/firmware.bin.

You can test your manifest files directly in the browser before deploying:

1. Open the manifest URL

Navigate to your manifest file URL (e.g., https://your-site.com/projects/my-project/manifest.json).

2. Verify the JSON

The browser should display the parsed JSON. Check that all paths and offsets are correct.

3. Test firmware paths

Navigate to each firmware file URL to ensure it downloads correctly. A 404 means the path is wrong.

4. Use the Manage page

The Manage page lets you edit project metadata and generate updated configuration.

5. Run the verification checklist

After deploying, use the Verification Checklist to confirm everything is working correctly.

To update firmware or add new projects:

Updating firmware

1. Replace the firmware binary files in public/projects/<project>/firmware/
2. Update the version number in the manifest.json
3. Commit and push to GitHub
4. GitHub Pages will deploy automatically

Adding new projects

1. Create a new folder under public/projects/
2. Add a manifest.json and firmware files
3. Add the project entry to src/data/projects.json
4. Rebuild and deploy

Flashie is configured for GitHub Pages static hosting. Follow these steps to deploy:

1. Push to GitHub

Create a repository and push your code.

2. Configure GitHub Pages

Go to Settings → Pages and select “GitHub Actions” as the source.

3. Add a GitHub Actions workflow

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{secrets.GITHUB_TOKEN }}
          publish_dir: ./out

4. Configure basePath (if needed)

If deploying to a sub-path like https://user.github.io/repo-name/, update basePath in next.config.ts to /repo-name.

Most boards need to be in bootloader mode before flashing. Here's how for each type:

ESP32

1. Press and hold the BOOT button (usually labeled GPIO0)
2. Press and release the EN (reset) button
3. Release the BOOT button
4. The board is now in download mode

ESP8266

Connect GPIO0 to GND and power cycle the board. Some development boards have a dedicated FLASH button.

STM32 (DFU mode)

1. Set BOOT0 pin to HIGH (connect to 3.3V)
2. Set BOOT1 pin to LOW (connect to GND)
3. Press and release the RESET button
4. The board appears as a DFU device

Arduino

Arduino boards typically enter bootloader mode automatically when a new sketch is uploaded via serial. No manual steps are usually required.