Skip to content

docs: refresh README (AI-assisted) #167

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
igorpecovnik wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: refresh README (AI-assisted) #167

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 156 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,84 +1,193 @@
<h2 align="center">
<a href=#><img src="https://raw.githubusercontent.com/armbian/.github/master/profile/logosmall.png" alt="Armbian logo"></a>
<a href="#"><img src="https://raw.githubusercontent.com/armbian/.github/master/profile/logosmall.png" alt="Armbian logo"></a>
<br><br>
</h2>

### 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).

| <a href="https://github.com/armbian/imager/releases"><img src="https://cdn.jsdelivr.net/npm/simple-icons@v11/icons/apple.svg" width="24"><br><strong>macOS</strong></a> | <a href="https://github.com/armbian/imager/releases"><img src="https://cdn.jsdelivr.net/npm/simple-icons@v11/icons/windows11.svg" width="24"><br><strong>Windows</strong></a> | <a href="https://github.com/armbian/imager/releases"><img src="https://cdn.jsdelivr.net/npm/simple-icons@v11/icons/linux.svg" width="24"><br><strong>Linux</strong></a> |
|:---:|:---:|:---:|
| Intel & Apple Silicon | x64 & ARM64 (code-signed) | x64 & ARM64 |
| <code>.dmg</code> / <code>.app.zip</code> | <code>.exe</code> / <code>.msi</code> | <code>.deb</code> / <code>.AppImage</code> |
| 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).

---

Expand Down