Skip to content

Commit 8cfc387

Browse files
Enginex0Enginex0
committed
docs(readme): add why section, emoji headers, telegram links
Redirect issue reports and device testing results to the Telegram group instead of GitHub Issues. Add "Why" highlight section matching the project's other repos. Make Telegram badge clickable.
1 parent 2ff58e8 commit 8cfc387

1 file changed

Lines changed: 70 additions & 43 deletions

File tree

‎README.md‎

Lines changed: 70 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<p align="center">
66
<img src="https://img.shields.io/badge/version-v3.1-blue?style=for-the-badge" alt="v3.1">
77
<img src="https://img.shields.io/badge/Android-12%2B-green?style=for-the-badge&logo=android" alt="Android 12+">
8-
<img src="https://img.shields.io/badge/Telegram-community-blue?style=for-the-badge&logo=telegram" alt="Telegram">
8+
<a href="https://t.me/superpowers9"><img src="https://img.shields.io/badge/Telegram-community-blue?style=for-the-badge&logo=telegram" alt="Telegram"></a>
99
</p>
1010
</p>
1111

@@ -15,42 +15,89 @@
1515

1616
---
1717

18-
## What is USB Mass Storage?
18+
## 🧬 What is USB Mass Storage?
1919

20-
When you connect your phone to a computer via USB cable, this module makes the computer see a **real USB storage device** — as if you plugged in a USB stick or CD drive. You pick a disk image file (`.img` or `.iso`) on your phone, and the computer can read and write to it directly.
20+
When you connect your phone to a computer via USB cable, this module makes the computer see a **real USB storage device**, as if you plugged in a USB stick or CD drive. You pick a disk image file (`.img` or `.iso`) on your phone, and the computer can read and write to it directly.
2121

2222
No file transfer protocols, no MTP, no ADB. The computer sees a native block device.
2323

24+
> **This is not MTP or file transfer.** USB Mass Storage exposes raw block devices to the host computer through the kernel's USB gadget ConfigFS interface. The computer sees a real disk, not a file-sharing protocol. You can boot from it, format it, or use it exactly like a physical USB drive.
25+
2426
---
2527

26-
## Features
28+
## 🔥 Why USB Mass Storage?
29+
30+
🔌 **Native Block Device** — The computer sees a real USB disk, not a file transfer protocol. Works with any OS, any file system, any tool that reads USB storage.
31+
32+
💿 **Boot From Your Phone** — Mount a bootable `.iso` as a CD-ROM drive. Install operating systems, run live CDs, or boot recovery tools directly from your phone.
33+
34+
📱 **Material 3 Companion App** — No terminal commands needed. Tap to mount, tap to eject. Full device management through a clean Compose UI with 32 language translations.
35+
36+
🛡️ **SELinux Enforcing** — The daemon runs in its own `msd_daemon` security domain with a dedicated sepolicy. No permissive hacks, no blanket root access.
37+
38+
🔧 **Multi-ABI Support** — arm64, armv7, and x86_64 binaries bundled. The installer detects your architecture and keeps only what's needed.
2739

40+
---
41+
42+
## ✨ Features
43+
44+
**USB Gadget**
2845
- [x] **Mount `.img` files as USB drives** — read-write, read-only, or CD-ROM mode
2946
- [x] **Mount `.iso` files as CD-ROM drives** — boot from ISO, install OS, run live CDs
30-
- [x] **Create virtual disk images** — specify size, format from the computer after mounting
31-
- [x] **Multiple devices** — mount up to 8 simultaneously, each appears as a separate USB device
32-
- [x] **Companion app** — Material 3 UI to manage devices, no terminal needed
33-
- [x] **Persistent mounts** — device configuration survives app restarts
47+
- [x] **Multiple devices** — up to 8 simultaneously, each appears as a separate USB device on the computer
48+
- [x] **Clean eject** — computer sees proper device disconnection
49+
50+
**Disk Management**
51+
- [x] **Create virtual disk images** — specify size in MB/GB/GiB, created instantly
52+
- [x] **Persistent configuration** — device mounts survive app restarts
53+
- [x] **File descriptor passing** — zero-copy file access over Unix socket
54+
55+
**App & Module**
56+
- [x] **Material 3 UI** — Jetpack Compose companion app with pull-to-refresh, bottom sheets, and snackbar alerts
3457
- [x] **32 languages** — app and module installer auto-detect your device language
58+
- [x] **Accent themes** — system default, almost black, and white color schemes
59+
- [x] **In-app guide** — step-by-step usage tutorial accessible from the menu
3560
- [x] **SELinux enforcing** — daemon runs in its own `msd_daemon` domain
3661
- [x] **Multi-ABI** — arm64, armv7, x86_64 binaries included, installer picks the right one
62+
- [x] **Boot guard** — automatic daemon restart with exponential backoff
3763

3864
---
3965

40-
## Requirements
66+
## 📋 Requirements
4167

4268
> [!IMPORTANT]
4369
> Root access is required. The daemon interacts with kernel USB gadget ConfigFS, which is a privileged operation.
4470
71+
**You need:**
4572
1. Android 12 or above
4673
2. A supported root manager: **KernelSU**, **Magisk**, or **APatch**
4774
3. A USB cable connecting your phone to a computer
4875

4976
---
5077

51-
## Quick Start
78+
## 📱 Compatibility
79+
80+
### Root Managers
81+
82+
| Manager | Status | Notes |
83+
|---|---|---|
84+
| KernelSU | ✅ Tested | Full support including lifecycle scripts |
85+
| Magisk | ✅ Supported | Standard module install |
86+
| APatch | ✅ Supported | Standard module install |
87+
88+
### Tested Devices
89+
90+
| Device | Android | Status |
91+
|---|---|---|
92+
| Redmi 14C (2409BRN2CA) | 14 (SDK 34) | ✅ Daily driver |
5293

53-
1. **Download** the latest ZIP from [Releases](https://github.com/Enginex0/UsbMassStorage/releases)
94+
> If you test on a different device, report your results in the [Telegram group](https://t.me/superpowers9).
95+
96+
---
97+
98+
## 🚀 Quick Start
99+
100+
1. **Download** the latest release ZIP from [Releases](https://github.com/Enginex0/UsbMassStorage/releases)
54101
2. **Flash** via your root manager and reboot
55102
3. **Open** the USB Mass Storage app
56103
4. **Grant root** when prompted
@@ -60,7 +107,7 @@ The computer detects a new USB device within seconds.
60107

61108
---
62109

63-
## Usage
110+
## ⚙️ Usage
64111

65112
### Mounting a Disk Image
66113

@@ -70,51 +117,29 @@ Choose the device type:
70117

71118
| Type | Use Case |
72119
|---|---|
73-
| **Read-Write** | Regular USB stick — computer can read and write freely |
74-
| **Read-Only** | Write-protected USB — computer can only read |
75-
| **CD-ROM** | Virtual CD/DVD drive — use for `.iso` files, OS installers, bootable media |
120+
| **Read-Write** | Regular USB stick, computer can read and write freely |
121+
| **Read-Only** | Write-protected USB, computer can only read |
122+
| **CD-ROM** | Virtual CD/DVD drive, use for `.iso` files, OS installers, bootable media |
76123

77124
Tap **Mount**. Done.
78125

79126
### Creating a New Image
80127

81128
Tap **+**, then **Create new disk image**. Set a filename and size (e.g., `512 MB`, `2 GiB`). The image is created instantly on your phone.
82129

83-
After mounting, format it from the computer — FAT32, exFAT, or NTFS.
130+
After mounting, format it from the computer (FAT32, exFAT, or NTFS).
84131

85132
### Multiple Devices
86133

87-
Mount up to 8 devices at once. Each shows as a separate USB device on the computer.
88-
89-
Tap a device card to change its type or eject it.
134+
Mount up to 8 devices at once. Each shows as a separate USB device on the computer. Tap a device card to change its type or eject it.
90135

91136
### Ejecting
92137

93138
Tap the eject icon on the device card. The computer sees the device disconnected cleanly.
94139

95140
---
96141

97-
## Compatibility
98-
99-
### Root Managers
100-
101-
| Manager | Status |
102-
|---|---|
103-
| KernelSU | ✅ Tested |
104-
| Magisk | ✅ Supported |
105-
| APatch | ✅ Supported |
106-
107-
### Tested Devices
108-
109-
| Device | Android | Status |
110-
|---|---|---|
111-
| Redmi 14C (2409BRN2CA) | 14 (SDK 34) | ✅ Daily driver |
112-
113-
> If you test on a different device, [open an issue](https://github.com/Enginex0/UsbMassStorage/issues) with your results.
114-
115-
---
116-
117-
## Architecture
142+
## 🏗️ Architecture
118143

119144
```
120145
┌──────────────┐ Unix Socket ┌──────────────┐ ConfigFS ┌──────────┐
@@ -131,7 +156,7 @@ The app is a regular user app. The daemon handles all privileged operations.
131156

132157
---
133158

134-
## Building from Source
159+
## 🔨 Building from Source
135160

136161
**Prerequisites:** JDK 17, Android SDK (compile SDK 35), Rust toolchain with Android targets.
137162

@@ -150,7 +175,7 @@ Output ZIP lands in `out/`.
150175

151176
---
152177

153-
## Common Issues
178+
## 🔧 Common Issues
154179

155180
| Problem | Fix |
156181
|---|---|
@@ -159,6 +184,8 @@ Output ZIP lands in `out/`.
159184
| Computer doesn't detect USB | Reconnect the cable. Make sure USB debugging isn't overriding gadget mode |
160185
| "AppFuse proxy" error | Your file picker is proxying the file. Use a different file manager (not Google Files) |
161186

187+
For other issues, ask in the [Telegram group](https://t.me/superpowers9).
188+
162189
---
163190

164191
## 💬 Community
@@ -171,7 +198,7 @@ Output ZIP lands in `out/`.
171198

172199
---
173200

174-
## License
201+
## 📄 License
175202

176203
This project is licensed under the [GNU General Public License v3.0](LICENSE).
177204

0 commit comments

Comments
 (0)