ESP Partition Toolbox

A desktop GUI for managing ESP32 partition tables across ESP-IDF, PlatformIO, and Arduino projects. Load an ESP32 project folder, visually edit the partition layout, validate partition constraints in real time, and save back to CSV — all without hand-editing a text file or guessing offsets.

Screenshots

Highlights

• Project loading — auto-detects ESP-IDF, PlatformIO, or Arduino projects and reads the existing partition table
• Multi-platform config sync — updates sdkconfig.defaults (ESP-IDF) or board_build.partitions in platformio.ini (PlatformIO); for Arduino it writes partitions.csv to the sketch folder and sets PartitionScheme=custom in sketch.yaml when present.
• MCU selector — auto-detected from the project config (CONFIG_IDF_TARGET, the PlatformIO board, or the Arduino FQBN) and editable when the project doesn't declare it
• Flash-size inference — when no flash size is configured, the smallest standard size that fits the existing partition table is selected automatically
• Visual partition map — proportional, color-coded bar of flash usage with a labelled legend
• Inline editing — name, type/subtype dropdowns, size (hex / K / M, slider, fill), and the encrypted and readonly flags
• Advanced mode — pin partition offsets to fixed addresses and define custom numeric partition types
• Real-time validation — 4 KB / 64 KB alignment, flash-boundary overflow, offset overlaps, duplicate detection, and ESP32 partition rules
• Partition Preview — a live, copyable view of the exact CSV that gets written, alongside a platform-aware config snippet
• KPI dashboard — total flash, plus allocated and free as a percentage of usable space
• Comments — preserved as # lines in the partition CSV header
• Save / Close / Reset — full round-trip with snapshot-based undo and optional platform config sync
• In-app help & updater — a tabbed Help reference, a custom right-click menu on every field, and a silent auto-update check (with a manual recheck in the About dialog)
• Ships as a native desktop app for Windows, macOS, and Linux

Install

Pre-built installers for every release live on the Releases page. Pick the right one for your OS:

OS	Recommended installer	Auto-update	Notes
Windows	*-setup.exe (NSIS)	Yes	Use this for personal/desktop installs.
Windows	*.msi	No	Manual re-install only; for MDM/IT use.
macOS	*.dmg	Yes	Universal binary (Intel + Apple Silicon).
Linux	*.AppImage	Yes	Mark executable, then run.
Linux	*.deb / *.rpm	No	Manual re-install only.

First-launch warning. The binary is currently unsigned at the OS level, so the first time you run it Windows SmartScreen will show "Windows protected your PC" — click More info → Run anyway. macOS Gatekeeper will say the app cannot be opened — right-click the app and choose Open, then confirm. After this one-time approval, auto-updates inherit the trust and install silently.

How updates work

Every release after the auto-update feature shipped checks https://github.com/inowio/esp-partition-toolbox/releases/latest on startup. If a newer version exists, the app prompts you to install — you can also trigger the check manually from the About dialog (the ⓘ icon in the navbar). Updates are minisign-signed by the updater key, so a tampered download is rejected.

Getting Started

Requirements

• Node.js 18+
• Rust (stable) + target-specific build tools (VS Build Tools on Windows, Xcode CLT on macOS, build-essential + WebKitGTK on Linux)

You do not need ESP-IDF installed to run the app — it only reads and writes the project's partition CSV and config files (sdkconfig.defaults, platformio.ini).

Quick Start

git clone https://github.com/inowio/esp-partition-toolbox.git
cd esp-partition-toolbox
npm install
npm run tauri dev

Production Build

npm run tauri build
# Bundles land in src-tauri/target/release/bundle

Development

npm run dev         # Vite frontend only
npm run tauri dev   # Full-stack dev (frontend + Rust)
npm run build       # Type-check + production frontend build

Unit Testing

npm run test:run                                  # Frontend tests (Vitest)
cargo test --manifest-path src-tauri/Cargo.toml   # Rust tests

See TESTING.md for the coverage summary and conventions.

Project Structure

esp-partition-toolbox/
├── src/             # React + TypeScript UI
│   ├── api/         # Updater + external-link helpers
│   ├── components/  # Presentational components
│   ├── hooks/       # Project state hook
│   └── utils/       # Partition parsing, layout, validation
├── src-tauri/       # Rust backend, Tauri config, icons
├── scripts/         # Release tooling (version bump)
├── docs/            # Maintainer documentation
└── public/          # Static assets

Recommended IDE Setup

• VS Code + Tauri + rust-analyzer

Troubleshooting

• Project won't load — the folder must be an ESP32 project: an ESP-IDF project needs a CMakeLists.txt and at least one sdkconfig.defaults (or sdkconfig.defaults.*) file; a PlatformIO project needs platformio.ini with at least one [env:…] section; an Arduino project needs a sketch folder containing a .ino sketch.
• Partition file missing — if no partition CSV exists yet, the app generates a sensible default layout in memory; it is written to disk only when you save.
• Validation errors block saving — fix the blocking errors listed in the validation panel; warnings do not block a save.
• Build failures — reinstall dependencies (npm ci), update the Rust toolchain, and ensure the platform build tools listed under Requirements are present.

Contributing

Please read CONTRIBUTING.md before opening an issue or pull request. Conventional commits, automated tests, and linted code help us triage quickly.

Maintainers cutting a release: see docs/RELEASING.md.

License

Released under the MIT License.

Support & Contact

• Issues: https://github.com/inowio/esp-partition-toolbox/issues
• Discussions: https://github.com/inowio/esp-partition-toolbox/discussions
• Email: info@inowio.in

---

Inowio Technologies LLP – From Bits to Machines. https://inowio.in