https://github.com/patatetom/sdcard
USB read-only access to SD card on Android system
https://github.com/patatetom/sdcard
adb android filesystems fuse fuse-filesystem fuse-python fusepy linux python sdcard
Last synced: 5 months ago
JSON representation
USB read-only access to SD card on Android system
- Host: GitHub
- URL: https://github.com/patatetom/sdcard
- Owner: patatetom
- Created: 2024-09-12T13:02:30.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-29T13:50:50.000Z (over 1 year ago)
- Last Synced: 2025-01-22T16:23:05.711Z (over 1 year ago)
- Topics: adb, android, filesystems, fuse, fuse-filesystem, fuse-python, fusepy, linux, python, sdcard
- Language: Python
- Homepage:
- Size: 83 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
🚀 [switch to fusepy](https://github.com/patatetom/sdcard/tree/fusepy)
# sdcard
**USB read-only access to SD card on Android system**
`sdcard` is a Python script that uses `adb_shell`, `fuse-python` (eg. BSD/Linux/OS-X only) and `libusb` to give fast USB read-only access to the `/sdcard/` (pseudo-)folder (eg. downloads, photos, etc...) of an Android system.
> _**the Android system accessed must have `Developer Options` [enabled](https://developer.android.com/studio/debug/dev-options), as well as `USB Debugging`.**_
> _**the key present in the script must be authorized on the Android side.**_
>
> _another key pair can be generated if [required](https://github.com/patatetom/sdcard/blob/main/sdcard/__main__.py#L12-L16)._
## installation
> _these are installation examples, other ways of doing things are possible._
>
> _Android tools (eg. `adb`) are not necessary, `adb_shell` is totally independent of them._
### system side
- Archlinux (2024.09.01)
```shell
# as root, install system dependencies if not already installed
pacman -Sy
pacman -S fuse3 python3
ln -s fusermount3 /usr/bin/fusermount
```
- Debian (12/bookworm)
```shell
# as root, install system dependencies if not already installed
apt update
apt install fuse3 libusb-1.0-0 python3 python3-venv
```
- and then, still on the system being configured...
```shell
#Â as root, install Python virtual environment
python3 -m venv /opt/android
/opt/android/bin/python3 -m pip install https://github.com/patatetom/sdcard/archive/main.zip
```
### user side
> _system dependencies (`fuse`, `libusb` and `python`) are still required_
- manually
```shell
python3 -m venv ~/venv/android
~/venv/android/bin/python3 -m pip install https://github.com/patatetom/sdcard/archive/main.zip
```
- pipx
```shell
pipx install https://github.com/patatetom/sdcard/archive/main.zip
```
## usage
> _it's important to note that, by default, `sdcard` remembers the contents (metadata) of visited folders :_
> _in other words, modifications on the Android system side of a previously visited location will not be reflected by `sdcard`, unless you use the `-n` option._
>
> _the examples below are taken from the user side installation above._
```shell
~/venv/android/bin/sdcard --help
Usage: sdcard [mountpoint] [options]
Options:
-h, --help show this help message and exit
-o opt,[opt...] mount options
-r, --root access from / (default from /sdcard)
-n, --nocache do not cache data (default cache data)
FUSE options:
…
```
```shell
mkdir -p /tmp/mountpoint
~/venv/android/bin/sdcard /tmp/mountpoint
ls /tmp/mountpoint/ #1
# Alarms Android Audiobooks DCIM Documents Download Movies Music Notifications Pictures Podcasts Recordings Ringtones storage
ls -l /tmp/mountpoint/ #2
total 0
# dr-xr-x--- 2 nobody nogroup 0 Mar 22 03:00 Alarms
# dr-xr-x--- 2 nobody nogroup 0 Mar 22 03:00 Android
# dr-xr-x--- 2 nobody nogroup 0 Mar 22 03:00 Audiobooks
# dr-xr-x--- 2 nobody nogroup 0 Jun 11 09:31 DCIM
# dr-xr-x--- 2 nobody nogroup 0 Aug 28 16:18 Documents
# dr-xr-x--- 2 nobody nogroup 0 Sep 18 05:39 Download
# dr-xr-x--- 2 nobody nogroup 0 May 19 19:14 Movies
# dr-xr-x--- 2 nobody nogroup 0 May 20 06:53 Music
# dr-xr-x--- 2 nobody nogroup 0 Mar 22 03:00 Notifications
# dr-xr-x--- 2 nobody nogroup 0 Aug 10 22:38 Pictures
# dr-xr-x--- 2 nobody nogroup 0 Mar 22 03:00 Podcasts
# dr-xr-x--- 2 nobody nogroup 0 Mar 28 16:52 Recordings
# dr-xr-x--- 2 nobody nogroup 0 Mar 22 03:00 Ringtones
# dr-xr-x--- 2 nobody nogroup 0 Sep 6 23:02 storage
tar -C /tmp/mountpoint/ -cz . > /tmp/backup.tar.gz
umount /tmp/mountpoint
```
> _the second command `ls … #2` above does not reread the contents of the root folder, but uses the data cached by the first call to the command `ls … #1` : if changes have occurred on the Android system side in the meantime, these are not reflected. use the option `--nocache` to force rereading of informations._
```shell
mkdir -p /tmp/mountpoint
~/venv/android/bin/sdcard --root /tmp/mountpoint
ls /tmp/mountpoint/
# acct apex config data debug_ramdisk dev lost+found mnt odm odm_dlkm oem proc product second_stage_resources storage sys system system_ext vendor vendor_dlkm
ls -l /tmp/mountpoint/
total 0
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 acct
# dr-xr-x--- 2 nobody nogroup 0 Jun 18 1973 apex
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 1970 config
# dr-xr-x--- 2 nobody nogroup 0 Sep 8 15:34 data
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 debug_ramdisk
# dr-xr-x--- 2 nobody nogroup 0 Sep 10 15:00 dev
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 lost+found
# dr-xr-x--- 2 nobody nogroup 0 Jun 18 1973 mnt
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 odm
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 odm_dlkm
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 oem
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 1970 proc
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 product
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 second_stage_resources
# dr-xr-x--- 2 nobody nogroup 0 Jun 18 1973 storage
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 1970 sys
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 system
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 system_ext
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 vendor
# dr-xr-x--- 2 nobody nogroup 0 Jan 1 2009 vendor_dlkm
ls -l /tmp/mountpoint/storage/emulated/0/
total 0
# dr-xr-x--- 2 nobody nogroup 0 Mar 22 03:00 Alarms
# dr-xr-x--- 2 nobody nogroup 0 Mar 22 03:00 Android
# dr-xr-x--- 2 nobody nogroup 0 Mar 22 03:00 Audiobooks
# dr-xr-x--- 2 nobody nogroup 0 Jun 11 09:31 DCIM
…
umount /tmp/mountpoint
```
> _`-r`/`--root` option gives access to the root of the Android system._
## links
- [adb_shell](https://github.com/JeffLIrion/adb_shell)
- [fuse-python](https://github.com/libfuse/python-fuse)
- [libusb](https://github.com/karpierz/libusb)
- [pipx](https://github.com/pypa/pipx)