From 776779a2ce5c89211d2cde9d240076f695a8f7f3 Mon Sep 17 00:00:00 2001
From: Igor <igor@armbian.com>
Date: Fri, 18 Jul 2025 12:27:01 +0200
Subject: [PATCH] Improve Armbian firmware README

---
 README.md | 34 ++++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 8841438..cdbb5f7 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,32 @@
-# firmware
-Armbian specific firmware
+<h2 align="center">
+  <img src="https://raw.githubusercontent.com/armbian/.github/master/profile/logo.png" alt="Armbian logo" width="25%">
+  <br><br>
+</h2>
+
+### Purpose of This Repository
+
+The **Armbian firmware** repository provides a curated set of binary firmware files required by various hardware components on ARM-based single board computers (SBCs) supported by Armbian.
+
+### Purpose
+
+- Distribute essential **proprietary firmware blobs**.
+- Enable **Wi-Fi**, **Bluetooth**, **GPU**, **VPU**, and other peripherals.
+- Ensure **hardware compatibility** out-of-the-box.
+- Provide a **leaner alternative** to full upstream `linux-firmware` packages by including only relevant firmware for supported boards.
+
+### Usage in Armbian
+
+- Packaged as `armbian-firmware` and installed automatically during OS setup or upgrades.
+- Used by Armbian's custom kernels and U-Boot bootloaders to support board-specific features.
+
+### Includes Firmware for
+
+- Realtek and Broadcom Wi-Fi/Bluetooth chips
+- Mali and other ARM GPU/VPU components
+- Various embedded controllers, USB devices, and more
+
+### Structure
+
+The layout generally follows upstream `linux-firmware` standards, with additional Armbian-specific filtering and optimizations.
+
+> ⚠️ Note: Some firmware files are proprietary and distributed under their respective licenses. Redistribution is limited to non-commercial or usage-only contexts.