diff --git a/README.md b/README.md index 0eb253a..75f56a7 100644 --- a/README.md +++ b/README.md @@ -3,82 +3,138 @@

-### About +# Armbian Imager -Armbian Imager is the official tool for downloading and flashing Armbian OS images to single-board computers. It checks the target disk before writing, validates the checksum, and verifies the image after the write, so a bad download or the wrong disk doesn't turn into a broken card. +## Purpose of This Repository -### Features +Armbian Imager is the official cross-platform desktop tool for downloading and flashing Armbian OS images to SD cards, USB drives, and EDL-mode boards. It handles disk safety checks, checksum validation, decompression, writing, and post-write verification, so a bad download or the wrong disk doesn't turn into a broken card. + +## Features - Works with 300+ boards, with filtering and board metadata from armbian.com - Disk safety checks, checksum validation, and post-write verification -- Native builds for Linux, Windows, and macOS, on x64 and ARM64 -- Multi-language interface that follows your system language by default -- Built-in application updates -- Small binary with few runtime dependencies - -### Testimonials - -> "What a fantastic tool for getting people started with a non Raspberry PI" -> *Interfacing Linux*, hardware and software guides for Linux creatives ([source](https://www.youtube.com/watch?v=RAxQebKsnuc)) - -> "A proper multi-platform desktop app that actually works, which is rarer than you'd think." -> *Bruno Verachten*, Senior Developer Relations Engineer ([source](https://www.linkedin.com/pulse/adding-risc-v-support-armbian-imager-tale-qemu-tauri-deja-verachten-86fxe)) - -> "The Upcoming Armbian Imager Tool is a Godsend for Non-Raspberry Pi SBC Owners" -> *Sourav Rudra*, It's FOSS ([source](https://itsfoss.com/news/armbian-imager-quietly-debuts/)) - -> "According to Armbian, this results in less RAM and storage usage and a faster experience." -> *Jordan Gloor*, HowtoGeek.com ([source](https://www.howtogeek.com/armbians-raspberry-pi-imager-alternative-is-here/)) - -> "It's super easy to write an operating system... I'm always happy when an Armbian version comes out because you've got more stability and much more compatibility." -> *leepspvideo*, Simple Linux install for 300+ Arm devices ([source](https://www.youtube.com/watch?v=vUvGD2GSALI)) +- Native builds for Linux, Windows, and macOS on x64 and ARM64 +- QDL (Qualcomm Device Loader) support for EDL-based boards (e.g. Arduino UNO Q) +- Multi-threaded decompression (xz, bzip2, gzip, zstd) +- First-boot autoconfig injected into the image's ext4 rootfs in userspace +- Multi-language interface that follows the system language by default +- Built-in application updater +- Signed Windows binaries ## Download -Prebuilt binaries are available for every supported platform. +Prebuilt binaries are published on the [Releases page](https://github.com/armbian/imager/releases). |
macOS |
Windows |
Linux | |:---:|:---:|:---:| | Intel & Apple Silicon | x64 & ARM64 (code-signed) | x64 & ARM64 | -| .dmg / .app.zip | .exe / .msi | .deb / .AppImage | +| `.dmg` / `.app.zip` | `.exe` / `.msi` | `.deb` / `.AppImage` | ## How It Works 1. **Pick a manufacturer.** Choose one of the supported SBC vendors, or load your own image file. -2. **Pick a board.** Boards show real photos and metadata from armbian.com. -3. **Pick an image.** Desktop or server, a kernel branch, and a stable, nightly, or rolling release build. +2. **Pick a board.** Boards show photos and metadata sourced from armbian.com. +3. **Pick an image.** Desktop or server, kernel branch, and stable / nightly / rolling build. 4. **Flash.** The app downloads, decompresses, writes, and verifies for you. -## Customization - -- Theme: light, dark, or follow the system setting -- Developer mode: turn on detailed logging and open the log viewer -- Language: 18 languages, auto-detected from your system - ## Platform Support | Platform | Architecture | Notes | -|----------|-------------|-------| +|----------|--------------|-------| | macOS | Intel x64 | Full support | -| macOS | Apple Silicon | Native ARM64 build, Touch ID support | +| macOS | Apple Silicon | Native ARM64 build | | Windows | x64 | Requires Administrator privileges | -| Windows | ARM64 | Native ARM64 build, requires Administrator privileges | -| Linux | x64 | Uses lsblk for detection and UDisks2/polkit for elevated device access | +| Windows | ARM64 | Native ARM64 build, requires Administrator | +| Linux | x64 | Uses `lsblk` and UDisks2/polkit for elevated device access | | Linux | ARM64 | Native ARM64 build | ### Supported Languages -English, Italian, German, French, Spanish, Portuguese, Portuguese (Brazil), Dutch, Polish, Russian, Chinese, Japanese, Korean, Ukrainian, Turkish, Slovenian, Swedish, Croatian +English, Italian, German, French, Spanish, Portuguese, Portuguese (Brazil), Dutch, Polish, Russian, Chinese, Japanese, Korean, Ukrainian, Turkish, Slovenian, Swedish, Croatian (18 total). + +## Built With + +- **Frontend:** TypeScript, React 19, Vite 8, i18next +- **Backend:** Rust (edition 2021, MSRV 1.85), Tauri 2 +- **In-repo crate:** `armbian-write-conf` — writes the first-boot autoconfig file into an image's ext4 rootfs (MIT-licensed) +- **Tooling:** ESLint, `cargo fmt`, `cargo clippy` +- **Setup scripts:** Bash (`scripts/setup/install.sh`, `install-linux.sh`, `install-macos.sh`) and PowerShell (`install-windows.ps1`) + +## Repository Layout + +``` +imager/ +├── src/ # React + TypeScript frontend +│ ├── components/ # UI: flash, layout, modals, settings, shared +│ ├── config/ # Constants, i18n, badges, OS info, QDL boards +│ ├── contexts/ # Motion, Theme, Update contexts +│ ├── hooks/ # useTauri, useFlashOperation, useSettings, … +│ ├── locales/ # 18 translation files (en.json is source of truth) +│ ├── styles/ # CSS with design tokens +│ └── utils/ # Color, device, distro theme, error helpers +├── src-tauri/ # Rust backend (Tauri app) +│ ├── src/ +│ │ ├── commands/ # Tauri IPC commands +│ │ ├── devices/ # Linux / macOS / Windows device detection +│ │ ├── flash/ # Per-OS writers, verify, privilege handling +│ │ ├── qdl/ # Qualcomm Device Loader (EDL) support +│ │ ├── images/ # Image models, filters +│ │ └── ... # download, decompress, cache, paste, logging +│ ├── icons/ # App icons (desktop + Android + iOS) +│ ├── capabilities/ # Tauri capability manifests +│ └── tauri.conf.json +├── crates/ +│ └── armbian-write-conf/ # In-repo crate + vendored armbian-ext4fs +├── scripts/ +│ ├── locales/sync-locales.js # AI-assisted locale sync from en.json +│ └── setup/ # Dev environment installers (Linux/macOS/Windows) +├── .github/ # Issue templates, labels, workflows +├── DEVELOPMENT.md +├── CONTRIBUTING.md +└── LICENSE +``` -## Why We Sign Our Code +## Development -Downloading software shouldn't take a leap of faith. Every Windows release is cryptographically signed, so you can confirm the binary is exactly what we built and hasn't been tampered with on the way to you. +Environment setup, build commands, and architecture notes live in [DEVELOPMENT.md](DEVELOPMENT.md). Quick start: -This is possible thanks to [SignPath Foundation](https://signpath.org?utm_source=foundation&utm_medium=github&utm_campaign=armbian-imager), which gives free code signing certificates to open source projects, and [SignPath.io](https://signpath.io?utm_source=foundation&utm_medium=github&utm_campaign=armbian-imager) for the signing infrastructure. +```bash +git clone https://github.com/armbian/imager.git && cd imager +bash scripts/setup/install.sh +npm install +npm run tauri:dev +``` -## Development +Prerequisites: Node.js ≥ 20.19.0 and Rust (see `src-tauri/Cargo.toml` for MSRV). + +Common scripts (from `package.json`): + +| Command | Description | +|---------|-------------| +| `npm run dev` | Vite dev server (frontend only) | +| `npm run tauri:dev` | Full app with hot reload | +| `npm run build` | Production frontend build | +| `npm run tauri:build` | Production distributable | +| `npm run lint` | Run ESLint | +| `npm run clean` | Clean `node_modules`, `dist`, `src-tauri/target` | + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, branch naming, Conventional Commits, and required quality checks. Please also read the [Code of Conduct](CODE_OF_CONDUCT.md). + +Translation contributions are especially welcome — edit files in `src/locales/` and keep all 18 locales in sync with `en.json`. + +## Continuous Integration + +CI builds, lint runs, and release automation for this repository are visible at: + +**[https://actions.armbian.com/?repo=imager](https://actions.armbian.com/?repo=imager)** + +## Why We Sign Our Code + +Downloading software shouldn't take a leap of faith. Every Windows release is cryptographically signed so you can confirm the binary is exactly what we built and hasn't been tampered with on the way to you. -Setup, build instructions, and project layout live in [DEVELOPMENT.md](DEVELOPMENT.md). +This is possible thanks to [SignPath Foundation](https://signpath.org?utm_source=foundation&utm_medium=github&utm_campaign=armbian-imager), which provides free code-signing certificates to open source projects, and [SignPath.io](https://signpath.io?utm_source=foundation&utm_medium=github&utm_campaign=armbian-imager) for the signing infrastructure. ## License @@ -86,7 +142,7 @@ Armbian Imager is distributed under the GNU General Public License, either versi SPDX-License-Identifier: `GPL-2.0-or-later` -The full text is in [LICENSE](LICENSE). A few bundled components keep their own terms: the `armbian-write-conf` crate and its vendored `armbian-ext4fs` fork are `MIT`, and the language flag graphics from [Twemoji](https://github.com/jdecked/twemoji) are `CC-BY-4.0`. Per-file details are in [`src-tauri/packaging/copyright`](src-tauri/packaging/copyright). +The full text is in [LICENSE](LICENSE). A few bundled components keep their own terms: the `armbian-write-conf` crate and its vendored `armbian-ext4fs` fork are `MIT`. Per-file details are in [`src-tauri/packaging/copyright`](src-tauri/packaging/copyright). ---