{"id":13428681,"url":"https://github.com/magnusja/libaums","last_synced_at":"2025-05-14T07:08:29.486Z","repository":{"id":13252808,"uuid":"15937775","full_name":"magnusja/libaums","owner":"magnusja","description":"Open source library to access USB Mass Storage devices on Android without rooting your device","archived":false,"fork":false,"pushed_at":"2025-04-18T18:19:36.000Z","size":1999,"stargazers_count":1314,"open_issues_count":64,"forks_count":274,"subscribers_count":44,"default_branch":"develop","last_synced_at":"2025-04-19T06:54:11.856Z","etag":null,"topics":["android","android-library","android-things","android-usb-host","fat32","files","java","kotlin","kotlin-android","kotlin-library","libaums","mass-storage","mass-storage-device","on-the-go","storage","usb","usb-drive","usb-flash","usb-host","usb-otg"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magnusja.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-01-15T14:41:06.000Z","updated_at":"2025-04-18T23:43:21.000Z","dependencies_parsed_at":"2023-01-13T17:23:34.440Z","dependency_job_id":"10c772e2-256e-4ef6-ba2b-11deb50dce14","html_url":"https://github.com/magnusja/libaums","commit_stats":{"total_commits":693,"total_committers":20,"mean_commits":34.65,"dds":0.4170274170274171,"last_synced_commit":"cc71b9654ac2ea0ee713f06b26d9eb01fa88b515"},"previous_names":["mjdev/libaums"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnusja%2Flibaums","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnusja%2Flibaums/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnusja%2Flibaums/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnusja%2Flibaums/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magnusja","download_url":"https://codeload.github.com/magnusja/libaums/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254092776,"owners_count":22013290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-library","android-things","android-usb-host","fat32","files","java","kotlin","kotlin-android","kotlin-library","libaums","mass-storage","mass-storage-device","on-the-go","storage","usb","usb-drive","usb-flash","usb-host","usb-otg"],"created_at":"2024-07-31T01:01:02.783Z","updated_at":"2025-05-14T07:08:29.467Z","avatar_url":"https://github.com/magnusja.png","language":"Kotlin","funding_links":[],"categories":["Libraries","Kotlin","Utility"],"sub_categories":[],"readme":"libaums\n=======\n[![Javadocs](https://www.javadoc.io/badge/me.jahnen.libaums/core.svg)](https://www.javadoc.io/doc/me.jahnen.libaums/core)\n[ ![Build Status](https://travis-ci.org/magnusja/libaums.svg?branch=develop)](https://travis-ci.org/magnusja/libaums)[ ![codecov](https://codecov.io/gh/magnusja/libaums/branch/develop/graph/badge.svg)](https://codecov.io/gh/magnusja/libaums)[ ![Codacy Badge](https://api.codacy.com/project/badge/Grade/31124a2747de41b49c040b9f7979c2a6)](https://www.codacy.com/manual/magnusja/libaums?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=magnusja/libaums\u0026amp;utm_campaign=Badge_Grade)\n[ ![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/libaums)\n\nA library to access USB mass storage devices (pen drives, external HDDs, card readers) using the Android USB Host API. Currently it supports the SCSI command set and the FAT32 file system.\n\n## How to use\n\n### Install\n\nThe library can be included into your project like this:\n\n```ruby\nimplementation 'me.jahnen.libaums:core:0.10.0'\n```\n\nIf you need the HTTP or the storage provider module:\n\n```ruby\nimplementation 'me.jahnen.libaums:httpserver:0.6.2'\nimplementation 'me.jahnen.libaums:storageprovider:0.6.2'\n```\n\n### Basics\n#### Query available mass storage devices\n\n#### Java\n\n```java\nUsbMassStorageDevice[] devices = UsbMassStorageDevice.getMassStorageDevices(this /* Context or Activity */);\n\nfor(UsbMassStorageDevice device: devices) {\n    \n    // before interacting with a device you need to call init()!\n    device.init();\n    \n    // Only uses the first partition on the device\n    FileSystem currentFs = device.getPartitions().get(0).getFileSystem();\n    Log.d(TAG, \"Capacity: \" + currentFs.getCapacity());\n    Log.d(TAG, \"Occupied Space: \" + currentFs.getOccupiedSpace());\n    Log.d(TAG, \"Free Space: \" + currentFs.getFreeSpace());\n    Log.d(TAG, \"Chunk size: \" + currentFs.getChunkSize());\n}\n```\n\n#### Kotlin\n\n```kotlin\nval devices = UsbMassStorageDevice.getMassStorageDevices(this /* Context or Activity */)\n\nfor (device in devices) {\n\n    // before interacting with a device you need to call init()!\n    device.init()\n\n    // Only uses the first partition on the device\n    val currentFs = device.partitions[0].fileSystem\n    Log.d(TAG, \"Capacity: \" + currentFs.capacity)\n    Log.d(TAG, \"Occupied Space: \" + currentFs.occupiedSpace)\n    Log.d(TAG, \"Free Space: \" + currentFs.freeSpace)\n    Log.d(TAG, \"Chunk size: \" + currentFs.chunkSize)\n}\n```\n\n#### Permissions\n\nYour app needs to get permission from the user at run time to be able to communicate the device. From a `UsbMassStorageDevice` you can get the underlying `android.usb.UsbDevice` to do so.\n\n#### Java\n```java\nPendingIntent permissionIntent = PendingIntent.getBroadcast(this, 0, new Intent(ACTION_USB_PERMISSION), 0);\nusbManager.requestPermission(device.getUsbDevice(), permissionIntent);\n````\n\n#### Kotlin\n\n```kotlin\nval permissionIntent = PendingIntent.getBroadcast(this, 0, Intent(ACTION_USB_PERMISSION), 0);\nusbManager.requestPermission(device.usDevice, permissionIntent);\n```\n\nFor more information regarding permissions please check out the Android documentation: https://developer.android.com/guide/topics/connectivity/usb/host.html#permission-d\n\n#### Working with files and folders\n\n##### Java\n\n```java\nUsbFile root = currentFs.getRootDirectory();\n\nUsbFile[] files = root.listFiles();\nfor(UsbFile file: files) {\n    Log.d(TAG, file.getName());\n    if(!file.isDirectory()) {\n        Log.d(TAG, file.getLength());\n    }\n}\n\nUsbFile newDir = root.createDirectory(\"foo\");\nUsbFile file = newDir.createFile(\"bar.txt\");\n\n// write to a file\nOutputStream os = new UsbFileOutputStream(file);\n\nos.write(\"hello\".getBytes());\nos.close();\n\n// read from a file\nInputStream is = new UsbFileInputStream(file);\nbyte[] buffer = new byte[currentFs.getChunkSize()];\nis.read(buffer);\n```\n\n##### Kotlin\n```kotlin\nval root = currentFs.rootDirectory\n\nval files = root.listFiles()\nfor (file in files) {\n    Log.d(TAG, file.name)\n    if (file.isDirectory) {\n        Log.d(TAG, file.length)\n    }\n}\n\nval newDir = root.createDirectory(\"foo\")\nval file = newDir.createFile(\"bar.txt\")\n\n// write to a file\nval os = UsbFileOutputStream(file)\n\nos.write(\"hello\".toByteArray())\nos.close()\n\n// read from a file\nval ins = UsbFileInputStream(file)\nval buffer = ByteArray(currentFs.chunkSize)\nins.read(buffer)\n```\n\n#### Using buffered streams for more efficency\n\n```java\nOutputStream os = UsbFileStreamFactory.createBufferedOutputStream(file, currentFs);\nInputStream is = UsbFileStreamFactory.createBufferedInputStream(file, currentFs);\n```\n\n#### Cleaning up\n\n```java\n// Don't forget to call UsbMassStorageDevice.close() when you are finished\n\ndevice.close();\n```\n\n#### Troubleshooting\n\nIf you get the following error fairly often (mostly under Android 9.0 Pie):\n\n```\njava.io.IOException: Could not write to device, result == -1 errno 0 null\n```\n\nor something similar, you might want to try the [libusb module](https://github.com/magnusja/libaums/tree/develop/libusbcommunication). This uses, instead of the Android USB host API, the [libusb](https://github.com/libusb/libusb) library for low level communication with the USB mass storage device. \n\nsee discussions: https://github.com/magnusja/libaums/issues/209 https://github.com/magnusja/libaums/issues/237 https://github.com/magnusja/libaums/pull/242\n\n__Note__, that libusb is licensed under LGPL, which is different from the license this project is licensed under! This might come with some drawbacks or extra work for closed source applications, see here: https://xebia.com/blog/the-lgpl-on-android/\n\n## Provide access to external apps\n\nUsually third party apps do not have access to the files on a mass storage device if the Android system does mount (this is usually supported on newer devices, back in 2014 there was no support for that) the device or this app integrates this library itself. To solve this issue there are two additional modules to provide access to other app. One uses the Storage Access Framework feature of Android (API level \u003e= 19) and the other one spins up an HTTP server to allow downloading or streaming of videos or images for instance.\n\n\n### HTTP server\n[![Javadocs](https://www.javadoc.io/badge/me.jahnen.libaums/httpserver.svg)](https://www.javadoc.io/doc/me.jahnen.libaums/httpserver)\n\nlibaums currently supports two different HTTP server libraries.\n\n1. [NanoHTTPD](https://github.com/NanoHttpd/nanohttpd)\n2. [AsyncHttpServer](https://github.com/koush/AndroidAsync/blob/master/AndroidAsync/src/com/koushikdutta/async/http/server/AsyncHttpServer.java)\n\nYou can spin up a server pretty easy, you just have to decide for a HTTP server implementation. If you do not have special requirements, you can just go for one, it should not make much of a difference.\n\n#### Java\n\n```java\nUsbFile file = ... // can be directory or file\n\nHttpServer server = AsyncHttpServer(8000); // port 8000\n// or\nHttpServer server = NanoHttpdServer(8000); // port 8000\n\nUsbFileHttpServer fileServer = new UsbFileHttpServer(file, server);\nfileServer.start();\n```\n\n#### Kotlin\n\n```kotlin\nval file: UsbFile\n// can be directory or file\n\nval server = AsyncHttpServer(8000) // port 8000\n// or\nval server = NanoHttpdServer(8000) // port 8000\n\nval fileServer = UsbFileHttpServer(file, server)\nfileServer.start()\n```\n\nThe file you provide can either be an actual file or a directory:\n\n1. File: Accessible either via \"/\" or \"/FILE_NAME\"\n2. Directory: All files in this directory und sub directories are accessable via their names. Directory listing is not supported!\n\nIf you want to be able to access these files when your app is in background, you should implement a service for that. There is an example available in the `httpserver` module. You can use it, but should subclass it or create your own to adapt it to your needs.\n\n#### Java\n\n```java\nprivate UsbFileHttpServerService serverService;\n\nServiceConnection serviceConnection = new ServiceConnection() {\n    @Override\n    public void onServiceConnected(ComponentName name, IBinder service) {\n        Log.d(TAG, \"on service connected \" + name);\n        UsbFileHttpServerService.ServiceBinder binder = (UsbFileHttpServerService.ServiceBinder) service;\n        serverService = binder.getService();\n    }\n\n    @Override\n    public void onServiceDisconnected(ComponentName name) {\n        Log.d(TAG, \"on service disconnected \" + name);\n        serverService = null;\n    }\n};\n\n@Override\nprotected void onCreate(Bundle savedInstanceState) {\n...\n    serviceIntent = new Intent(this, UsbFileHttpServerService.class);\n...\n}\n\n @Override\nprotected void onStart() {\n    super.onStart();\n\n    startService(serviceIntent);\n    bindService(serviceIntent, serviceConnection, Context.BIND_AUTO_CREATE);\n}\n\nprivate void startHttpServer(final UsbFile file) {\n...\n    serverService.startServer(file, new AsyncHttpServer(8000));\n...\n}\n```\n\n#### Kotlin\n\n```kotlin\nprivate var serverService: UsbFileHttpServerService? = null\n\ninternal var serviceConnection: ServiceConnection = object : ServiceConnection() {\n    override fun onServiceConnected(name: ComponentName, service: IBinder) {\n        Log.d(TAG, \"on service connected $name\")\n        val binder = service as UsbFileHttpServerService.ServiceBinder\n        serverService = binder.getService()\n    }\n\n    override fun onServiceDisconnected(name: ComponentName) {\n        Log.d(TAG, \"on service disconnected $name\")\n        serverService = null\n    }\n}\n\noverride protected fun onCreate(savedInstanceState: Bundle) {\n    serviceIntent = Intent(this, UsbFileHttpServerService::class.java)\n}\n\noverride protected fun onStart() {\n    super.onStart()\n\n    startService(serviceIntent)\n    bindService(serviceIntent, serviceConnection, Context.BIND_AUTO_CREATE)\n}\n```\n\nSee the example app for additional details on that.\n\n\n### Storage Access Framework\n[![Javadocs](https://www.javadoc.io/badge/me.jahnen.libaums/storageprovider.svg)](https://www.javadoc.io/doc/me.jahnen.libaums/storageprovider)\n\nTo learn more about this visit: https://developer.android.com/guide/topics/providers/document-provider.html\n\nTo integrate this module in your app the only thing you have to do is add the definition in your AndroidManifest.xml.\n\n```xml\n\u003cprovider\n    android:name=\"me.jahnen.libaums.storageprovider.UsbDocumentProvider\"\n    android:authorities=\"me.jahnen.libaums.storageprovider.documents\"\n    android:exported=\"true\"\n    android:grantUriPermissions=\"true\"\n    android:permission=\"android.permission.MANAGE_DOCUMENTS\"\n    android:enabled=\"@bool/isAtLeastKitKat\"\u003e\n    \u003cintent-filter\u003e\n        \u003caction android:name=\"android.content.action.DOCUMENTS_PROVIDER\" /\u003e\n    \u003c/intent-filter\u003e\n\u003c/provider\u003e\n```\n\nAfter that apps using the Storage Access Framework will be able to access the files of the USB mass storage device.\n\n\n#### Hints\n\n1. In the `app/` directory you can find an example application using the library.\n2. When copying a file always set the length via `UsbFile.setLength(long)` first. Otherwise the ClusterChain has to be increased for every call to write. This is very inefficent.\n3. Always use `FileSystem.getChunkSize()` bytes as buffer size, because this alignes with the block sizes drives are using. Everything else is also most likeley a decrease in performance.\n4. A good idea is to wrap the UsbFileInputStream/UsbFileOutputStream into BufferedInputStream/BufferedOutputStream. Also see `UsbFileStreamFactory`.\n\n##### Thesis\n\nThe library was developed by Mr. Jahnen as part of his bachelor's thesis in 2014. It's a sub-topic of the research topic \"Secure Copy Protection for Mobile Apps\" by Mr. Kannengießer. The full thesis document can be downloaded [here](https://www.in.tum.de/fileadmin/w00bws/os/Lehre/Abschlussarbeiten/Jahnen-thesis.pdf).\n\n\nLibaums - Library to access USB Mass Storage Devices  \nLicense: Apache 2.0 (see license.txt for details)   \nAuthor: Magnus Jahnen, github@mgns.tech \nAdvisor: Nils Kannengießer, nils.kannengiesser at tum.de  \nSupervisor: Prof. Uwe Baumgarten, baumgaru at in.tum.de  \n\nTechnische Universität München (TUM)  \nLehrstuhl/Fachgebiet für Betriebssysteme  \nwww.os.in.tum.de  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagnusja%2Flibaums","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagnusja%2Flibaums","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagnusja%2Flibaums/lists"}