From fa137cc3c32b8160b96e5c1fd91c75f7ffcaaaa3 Mon Sep 17 00:00:00 2001 From: igorpecovnik <6281704+igorpecovnik@users.noreply.github.com> Date: Mon, 10 Aug 2026 06:43:54 +0000 Subject: [PATCH] docs: refresh README (AI-assisted) --- README.md | 203 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 156 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 398c3dd..7d5e9db 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,193 @@

- Armbian logo + Armbian logo

-### 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. +Armbian Imager is the official cross-platform desktop tool for downloading and flashing Armbian OS images to SD cards and USB drives, with disk safety checks, checksum validation, and post-write verification. -### Features +## About -- 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)) +Armbian Imager guides you through a four-step wizard — manufacturer, board, image, and target device — then downloads, decompresses, writes, and verifies the image. Board metadata and photos come from armbian.com, and the app runs natively on Linux, macOS, and Windows on both x64 and ARM64. -> "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/)) +## Features -> "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)) +- 300+ supported single-board computers with filtering and metadata from armbian.com +- Safe writes: pre-write disk checks, checksum validation, and post-write verification +- QDL (Qualcomm Device Loader) support for EDL-based boards such as the Arduino UNO Q +- First-boot autoconfig injected into the ext4 rootfs of the flashed image (via the in-repo `armbian-write-conf` crate) +- Native builds for Linux, macOS, and Windows on x64 and ARM64 +- Built-in application updates via Tauri updater +- Multi-language interface auto-detected from the system locale +- Small binary with few runtime dependencies ## 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 | +| Platform | Architectures | Formats | +|---|---|---| +| macOS | Intel x64, Apple Silicon | `.dmg`, `.app.zip` | +| Windows | x64, ARM64 (code-signed) | `.exe`, `.msi` | +| Linux | x64, ARM64 | `.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. +3. **Pick an image.** Select desktop or server, a kernel branch, and a 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 | +| Linux | x64 | Uses UDisks2/polkit for elevated device access | | Linux | ARM64 | Native ARM64 build | -### Supported Languages +## Supported Languages + +18 locales are shipped under `src/locales/`: + +English, Italian, German, French, Spanish, Portuguese, Portuguese (Brazil), Dutch, Polish, Russian, Chinese, Japanese, Korean, Ukrainian, Turkish, Slovenian, Swedish, Croatian. + +Missing keys in non-English locales are auto-translated daily from `en.json` by the `Data: Sync translation files` workflow, then opened as a pull request for review. + +## Tech Stack + +- **Desktop shell:** [Tauri 2](https://tauri.app) (`src-tauri/`), with the shell, dialog, updater, process, and store plugins +- **Backend:** Rust (edition 2021, MSRV 1.85.0). Async I/O with `tokio`; HTTP via `reqwest` (rustls); decompression via `xz2`, `lzma-rust2`, `bzip2`, `flate2`, `zstd`; hashing via `sha2` +- **Frontend:** React 19 + TypeScript, built with Vite 8; internationalization via `i18next` / `react-i18next`; icons from `lucide-react` +- **In-repo Rust crate:** `crates/armbian-write-conf` — writes a small first-boot config file into an ext4 rootfs of a RAW disk image in userspace and then validates it (uses `gptman`, `mbrman`, `ext4-view`) +- **QDL:** Qualcomm Device Loader integration via the `qdl` crate and `nusb` +- **Platform-specific integrations:** + - Linux: `libc`, `udisks2`, `zbus` (pinned to `5.12.0`) + - macOS: `security-framework`, `core-foundation` + - Windows: `windows-sys` (file system, IOCTL, I/O) + +## Repository Layout + +``` +. +├── src/ # React + TypeScript frontend +│ ├── App.tsx, main.tsx, i18n.ts +│ ├── components/ # flash, layout, modals, settings, shared +│ ├── config/ # constants, i18n, badges, os-info, qdlBoards, ... +│ ├── contexts/ # ThemeContext, UpdateContext +│ ├── hooks/ # useTauri, useFlashOperation, useSettings, ... +│ ├── locales/ # 18 JSON translation files +│ ├── styles/ # base, layout, components, modal, flash, theme, ... +│ ├── types/, utils/ +│ └── assets/ # icons and OS logos +│ +├── src-tauri/ # Rust backend (Tauri 2) +│ ├── src/ +│ │ ├── main.rs +│ │ ├── commands/ # Tauri IPC commands (operations, scraping, ...) +│ │ ├── config/, images/, devices/, flash/ +│ │ ├── qdl/ # Qualcomm EDL board flashing +│ │ ├── paste/, logging/, utils/ +│ │ ├── autoconfig.rs, cache.rs, decompress.rs, download.rs, picture_cache.rs +│ ├── capabilities/default.json +│ ├── tauri.conf.json +│ └── Cargo.toml +│ +├── crates/armbian-write-conf/ # In-repo crate: inject first-boot config into ext4 +│ ├── src/{lib.rs,detect.rs,validate.rs} +│ └── tests/inject_real_image.rs +│ +├── scripts/ +│ ├── locales/sync-locales.js # AI-assisted locale sync +│ └── setup/ # install-linux.sh, install-macos.sh, install-windows.ps1, install.sh +│ +├── .github/workflows/ # CI: build, release, PR checks, locale sync, labels +├── package.json, vite.config.ts, tsconfig*.json, eslint.config.js +├── DEVELOPMENT.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md +└── LICENSE # GPL-2.0 +``` -English, Italian, German, French, Spanish, Portuguese, Portuguese (Brazil), Dutch, Polish, Russian, Chinese, Japanese, Korean, Ukrainian, Turkish, Slovenian, Swedish, Croatian +## Development -## Why We Sign Our Code +Full setup, build instructions, and architecture notes are in [DEVELOPMENT.md](DEVELOPMENT.md). Quick start: -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. +```bash +git clone https://github.com/armbian/imager.git +cd imager +bash scripts/setup/install.sh +npm install +npm run tauri:dev +``` -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. +### Prerequisites -## Development +| Requirement | Minimum | +|---|---| +| Node.js | 20.19.0 | +| Rust | 1.85.0 (edition 2021) | +| npm | 10+ | + +### Common scripts + +| 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 (`tsc -b && vite build`) | +| `npm run tauri:build` | Production distributable | +| `npm run lint` | ESLint | +| `npm run clean` | Remove `node_modules`, `dist`, and `src-tauri/target` | + +### Quality checks + +Before opening a PR, run the same checks as CI (`.github/workflows/maintenance-pr-check.yml`): + +```bash +# Frontend +npm run lint +npx tsc --noEmit + +# Backend +cd src-tauri +cargo fmt --check +cargo clippy --all-targets --all-features -- -D warnings +``` + +## Continuous Integration + +GitHub Actions workflows under `.github/workflows/`: + +| Workflow | Purpose | +|---|---| +| `maintenance-pr-check.yml` | Lint, type-check, Clippy, and build Linux x64 / Windows x64 / macOS ARM on every PR | +| `maintenance-build.yml` | Manual build & artifact upload for Linux, macOS, Windows (x64 + ARM64) | +| `maintenance-release.yml` | Tagged releases: multi-arch builds, code signing, updater artifacts | +| `maintenance-delete-releases.yml` | Daily cleanup of old (pre)releases, keeping the N newest | +| `data-sync-locales.yml` | Daily AI-assisted sync of locale files against `en.json` | +| `infrastructure-sync-labels.yml` | Sync GitHub issue labels from `.github/labels.yml` | + +## Contributing + +Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, branch naming, and Conventional Commits format. Please also read the [Code of Conduct](CODE_OF_CONDUCT.md). + +Other ways to help: + +- [Become a board maintainer](https://docs.armbian.com/Board_Maintainers_Procedures_and_Guidelines/) +- [Apply for an open position](https://forum.armbian.com/staffapplications/) +- [Help cover running costs](https://forum.armbian.com/subscriptions/) +- [Help community members on the forum](https://forum.armbian.com/) + +## Code Signing + +Windows releases are cryptographically signed 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 to [SignPath.io](https://signpath.io?utm_source=foundation&utm_medium=github&utm_campaign=armbian-imager) for the signing infrastructure. + +## License -Setup, build instructions, and project layout live in [DEVELOPMENT.md](DEVELOPMENT.md). +Licensed under the GNU General Public License v2.0 — see [LICENSE](LICENSE). ---