B2G/USBMassStorage

This page describes the USB Mass Storage feature in B2G.

Overview

USB Mass Storage (aka UMS) allows a portion of the phone to shared on the PC, when the phone is plugged into the PC via USB cable. Since UMS is a block-based protocol, it requires "ownership" of the filesystem being shared. In technical terms, this means that only the contents of an entire partition may be shared.

Terminology

Android has the notion of internal and external SD cards. The internal SD card is really a virtual thing and typically corresponds to a directory tree named /sdcard. Android apps typically store their data in a directory tree called /data. The external SD card is optional, and not all phones have it. For the ones that do, it corresponds to a physical SD card, and can typically be found in /sdcard/external_sd.

History

Prior to Android Honey Comb (HC), UMS was the common way to share data when plugging your phone into your PC. However, requiring that the entire partition be shared lead to people running out of space in the sdcard partition while lots of space remained in /data or vice-versa. With HC and ICS, Android introduced a new way of sharing information called Media Transfer Protocol (MTP), which is a file based protocol.

With the advent of MTP, it is now possible to have /data and /sdcard both exist in the same partition.

UMS is still supported under ICS, but practically isn't usable on all phones.

Enabling Mass Storage

The current B2G builds disable UMS by default and enable MTP. So in order to use mass storage, you'll need to enable it manually. To enable UMS temporarily (until the next reboot):

adb shell setprop sys.usb.config mass_storage,adb

To enable UMS permanently (or until you do a clockworkmod restore):

adb shell setprop persist.sys.usb.config mass_storage,adb

In either case, it's VERY important that mass_storage,adb have no spaces before or after the comma, and that they be in exactly that order (i.e. adb,mass_storage won't work).

To revert to using mtp, replace mass_storage,adb above with mtp,adb

How it works

UMS will only activate once the phone is unlocked, and the Settings->Storage->USB Mass Storage Enable setting is enabled. Once activated, it will stay activated until the usb cable is unplugged or the setting is disabled.

How it manifests itself on the PC will vary depending on the OS. Under ubuntu 12.04, it will show up in Nautilus under Devices:

Under ubuntu, the phone will appear in the file system under /media/5CE7-07D3 The 5CE7-07D3 is the volume serial number which is assigned at the time that that the /sdcard volume was formatted as vfat, and will most likely be different for different phones.

If you copy files to the phone, you should eject the phone before unplugging the cable or turning off UMS.

Testing

Starting conditions:

• Mass Storage is enabled (ala setprop sys.usb.config)
• Settings->Storage->USB Mass Storage Enabled is checked
• USB cable is unplugged
• Phone is locked

1. Plug in USB cable. The phone should not show up on the PC
2. Unlock the phone. The phone should now show up on the PC
3. Go into Settings->Storage and uncheck USB Mass Storage Enabled. The phone should disappear from the PC.
4. Check USB Mass Storage Enabled. The phone should show up on the PC.
5. Lock the phone (press the power button). The phone should continue to show up on the PC.
6. Unlock the phone. Nothing should change on the PC.
7. Unplug the USB cable. The phone should disappear from the PC.
8. Plug in the USB cable. This phone should reappear on the PC.
9. Lock the phone.
10. Unplug the USB cable. The phone should disappear from the PC.
11. Plug the USB cable back in. The phone should not appear on the PC until the phone is unlocked.
12. Uncheck USB Mass Storage Enabled. The phone should disappear from the PC.
13. Unplug and replug the USB cable. The phone should NOT appear on the PC.
14. Lock phone. Repeat unplug/replug. The phone should NOT appear on the PC.

Problems

If you run into problems, look for entries in logcat from the AutoMounter category. In particular, this line:

I/AutoMounter( 1835): UpdateState: umsAvail:1 umsEnabled:1 mode:1 usbCablePluggedIn:1 tryToShare:1

gives the most useful information about the internal state.

• umsAvail determines is mass_storage support was compiled into the kernel.
• umsEnabled determines if mass_storage was enabled (ala setprop sys.usb.config)
• mode should reflect the ums.mode setting, and has the values 0=disabled, 1=enabled, 2=disable_when_unplugged
• usbCablePluggedIn should reflect the state of the usb cable
• tryToShare relects whether the automounter is trying to share the sdcard with the PC or not.