Skip to content

Automatic refresh repository README #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

Automatic refresh repository README #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
146 changes: 101 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,90 +3,146 @@
<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.
## 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).

| <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> |
| `.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

Armbian Imager is distributed under the GNU General Public License, either version 2 or (at your option) any later version. Version 2 is the floor, so the terms stay compatible with the [Armbian build framework](https://github.com/armbian/build).

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

---

Expand Down