THIS IS A TEST INSTANCE ONLY! REPOSITORIES CAN BE DELETED AT ANY TIME!

You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
magnus 9eff61a699
Merge pull request #261 from magnusja/qemu-tests
2 days ago
.github/workflows android ci libusb path 7 months ago
androidtests Make USB permission request token more unique 5 days ago
app Remove tests from demo app 5 days ago
gradle/wrapper use new bintray repo and change identifier 7 months ago
httpserver Fix gradle warning 5 days ago
javafs Set minimum SDK to 15 for JavaFS 5 days ago
libaums Add parameterized tests for all USB communications and move to libusbcomm 5 days ago
libusbcommunication Move androidTests to separate module 5 days ago
storageprovider change obsolete email 9 months ago
.gitignore compile libusb 7 months ago
.travis.yml once again 7 months ago
ISSUE_TEMPLATE.md Update ISSUE_TEMPLATE.md 1 year ago
LICENSE Initial commit 6 years ago
README.md Update README.md 7 months ago
bintray.gradle use new bintray repo and change identifier 7 months ago
build.gradle update dokka 7 months ago
gradle.properties migrate to android x 1 year ago
gradlew New grade module structure 4 years ago
gradlew.bat New grade module structure 4 years ago
install.gradle Refactor bintray upload to upload all modules 3 years ago
settings.gradle Move androidTests to separate module 5 days ago

README.md

libaums

Javadocs Build Status codecov Codacy Badge Download Gitter chat

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

How to use

Install

The library can be included into your project like this:

implementation 'me.jahnen:libaums:0.7.5'

If you need the HTTP or the storage provider module:

implementation 'me.jahnen:libaums-httpserver:0.5.3'
implementation 'me.jahnen:libaums-storageprovider:0.5.1'

Basics

Query available mass storage devices

Java

UsbMassStorageDevice[] devices = UsbMassStorageDevice.getMassStorageDevices(this /* Context or Activity */);

for(UsbMassStorageDevice device: devices) {
    
    // before interacting with a device you need to call init()!
    device.init();
    
    // Only uses the first partition on the device
    FileSystem currentFs = device.getPartitions().get(0).getFileSystem();
    Log.d(TAG, "Capacity: " + currentFs.getCapacity());
    Log.d(TAG, "Occupied Space: " + currentFs.getOccupiedSpace());
    Log.d(TAG, "Free Space: " + currentFs.getFreeSpace());
    Log.d(TAG, "Chunk size: " + currentFs.getChunkSize());
}

Kotlin

val devices = UsbMassStorageDevice.getMassStorageDevices(this /* Context or Activity */)

for (device in devices) {

    // before interacting with a device you need to call init()!
    device.init()

    // Only uses the first partition on the device
    val currentFs = device.partitions[0].fileSystem
    Log.d(TAG, "Capacity: " + currentFs.capacity)
    Log.d(TAG, "Occupied Space: " + currentFs.occupiedSpace)
    Log.d(TAG, "Free Space: " + currentFs.freeSpace)
    Log.d(TAG, "Chunk size: " + currentFs.chunkSize)
}

Permissions

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

Java

PendingIntent permissionIntent = PendingIntent.getBroadcast(this, 0, new Intent(ACTION_USB_PERMISSION), 0);
usbManager.requestPermission(device.getUsbDevice(), permissionIntent);

Kotlin

val permissionIntent = PendingIntent.getBroadcast(this, 0, Intent(ACTION_USB_PERMISSION), 0);
usbManager.requestPermission(device.usDevice, permissionIntent);

For more information regarding permissions please check out the Android documentation: https://developer.android.com/guide/topics/connectivity/usb/host.html#permission-d

Working with files and folders

Java
UsbFile root = currentFs.getRootDirectory();

UsbFile[] files = root.listFiles();
for(UsbFile file: files) {
    Log.d(TAG, file.getName());
    if(file.isDirectory()) {
        Log.d(TAG, file.getLength());
    }
}

UsbFile newDir = root.createDirectory("foo");
UsbFile file = newDir.createFile("bar.txt");

// write to a file
OutputStream os = new UsbFileOutputStream(file);

os.write("hello".getBytes());
os.close();

// read from a file
InputStream is = new UsbFileInputStream(file);
byte[] buffer = new byte[currentFs.getChunkSize()];
is.read(buffer);
Kotlin
val root = currentFs.rootDirectory

val files = root.listFiles()
for (file in files) {
    Log.d(TAG, file.name)
    if (file.isDirectory) {
        Log.d(TAG, file.length)
    }
}

val newDir = root.createDirectory("foo")
val file = newDir.createFile("bar.txt")

// write to a file
val os = UsbFileOutputStream(file)

os.write("hello".toByteArray())
os.close()

// read from a file
val ins = UsbFileInputStream(file)
val buffer = ByteArray(currentFs.chunkSize)
ins.read(buffer)

Using buffered streams for more efficency

OutputStream os = UsbFileStreamFactory.createBufferedOutputStream(file, currentFs);
InputStream is = UsbFileStreamFactory.createBufferedInputStream(file, currentFs);

Cleaning up

// Don't forget to call UsbMassStorageDevice.close() when you are finished

device.close();

Troubleshooting

If you get the following error fairly often (mostly under Android 9.0 Pie):

java.io.IOException: Could not write to device, result == -1 errno 0 null

or something similar, you might want to try the libusb module. This uses, instead of the Android USB host API, the libusb library for low level communication with the USB mass storage device.

see discussions: https://github.com/magnusja/libaums/issues/209 https://github.com/magnusja/libaums/issues/237 https://github.com/magnusja/libaums/pull/242

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/

Provide access to external apps

Usually 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 >= 19) and the other one spins up an HTTP server to allow downloading or streaming of videos or images for instance.

HTTP server

Javadocs

libaums currently supports two different HTTP server libraries.

  1. NanoHTTPD
  2. AsyncHttpServer

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

Java

UsbFile file = ... // can be directory or file

HttpServer server = AsyncHttpServer(8000); // port 8000
// or
HttpServer server = NanoHttpdServer(8000); // port 8000

UsbFileHttpServer fileServer = new UsbFileHttpServer(file, server);
fileServer.start();

Kotlin

val file: UsbFile
// can be directory or file

val server = AsyncHttpServer(8000) // port 8000
// or
val server = NanoHttpdServer(8000) // port 8000

val fileServer = UsbFileHttpServer(file, server)
fileServer.start()

The file you provide can either be an actual file or a directory:

  1. File: Accessible either via "/" or "/FILE_NAME"
  2. Directory: All files in this directory und sub directories are accessable via their names. Directory listing is not supported!

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

Java

private UsbFileHttpServerService serverService;

ServiceConnection serviceConnection = new ServiceConnection() {
    @Override
    public void onServiceConnected(ComponentName name, IBinder service) {
        Log.d(TAG, "on service connected " + name);
        UsbFileHttpServerService.ServiceBinder binder = (UsbFileHttpServerService.ServiceBinder) service;
        serverService = binder.getService();
    }

    @Override
    public void onServiceDisconnected(ComponentName name) {
        Log.d(TAG, "on service disconnected " + name);
        serverService = null;
    }
};

@Override
protected void onCreate(Bundle savedInstanceState) {
...
    serviceIntent = new Intent(this, UsbFileHttpServerService.class);
...
}

 @Override
protected void onStart() {
    super.onStart();

    startService(serviceIntent);
    bindService(serviceIntent, serviceConnection, Context.BIND_AUTO_CREATE);
}

private void startHttpServer(final UsbFile file) {
...
    serverService.startServer(file, new AsyncHttpServer(8000));
...
}

Kotlin

private var serverService: UsbFileHttpServerService? = null

internal var serviceConnection: ServiceConnection = object : ServiceConnection() {
    override fun onServiceConnected(name: ComponentName, service: IBinder) {
        Log.d(TAG, "on service connected $name")
        val binder = service as UsbFileHttpServerService.ServiceBinder
        serverService = binder.getService()
    }

    override fun onServiceDisconnected(name: ComponentName) {
        Log.d(TAG, "on service disconnected $name")
        serverService = null
    }
}

override protected fun onCreate(savedInstanceState: Bundle) {
    serviceIntent = Intent(this, UsbFileHttpServerService::class.java)
}

override protected fun onStart() {
    super.onStart()

    startService(serviceIntent)
    bindService(serviceIntent, serviceConnection, Context.BIND_AUTO_CREATE)
}

See the example app for additional details on that.

Storage Access Framework

Javadocs

To learn more about this visit: https://developer.android.com/guide/topics/providers/document-provider.html

To integrate this module in your app the only thing you have to do is add the definition in your AndroidManifest.xml.

<provider
    android:name="com.github.mjdev.libaums.storageprovider.UsbDocumentProvider"
    android:authorities="com.github.mjdev.libaums.storageprovider.documents"
    android:exported="true"
    android:grantUriPermissions="true"
    android:permission="android.permission.MANAGE_DOCUMENTS"
    android:enabled="@bool/isAtLeastKitKat">
    <intent-filter>
        <action android:name="android.content.action.DOCUMENTS_PROVIDER" />
    </intent-filter>
</provider>

After that apps using the Storage Access Framework will be able to access the files of the USB mass storage device.

Hints

  1. In the app/ directory you can find an example application using the library.
  2. 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.
  3. 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.
  4. A good idea is to wrap the UsbFileInputStream/UsbFileOutputStream into BufferedInputStream/BufferedOutputStream. Also see UsbFileStreamFactory.
Thesis

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

Libaums - Library to access USB Mass Storage Devices
License: Apache 2.0 (see license.txt for details)
Author: Magnus Jahnen, github@mgns.tech Advisor: Nils Kannengießer, nils.kannengiesser at tum.de
Supervisor: Prof. Uwe Baumgarten, baumgaru at in.tum.de

Technische Universität München (TUM)
Lehrstuhl/Fachgebiet für Betriebssysteme
www.os.in.tum.de