Apple iPod, iPad, iPhone
This is a placeholder for a more comprehensive article on how to manage an Apple device on a Gentoo system. The goal is to mount the iPod/iPhone/iPad somewhere so that it can be interfaced with by other tools, such as app-pda/gtkpod or media-sound/banshee or others. It also shows how to copy files to the iDevice using a file manager, without the need of syncing via iTunes.
- 1 The idevice Software Stack
- 2 Pairing
- 3 Mounting
- 4 Transferring Media
- 5 Troubleshooting
- 6 External resources
The idevice Software Stack
This is the idevice software stack. The dependencies will be pulled in automatically, but this is useful as a reference when trying to figure out which layers are or are not working.
Pairing functionality is provided by app-pda/libimobiledevice. Emerge it, then test it by running:
This should print the device serial number which appeared in your dmesg log.
If this has been successful, run:
to verify that communications with the device are functioning correctly.
to pair with the device. Check this with:
app-pda/libimobiledevice is supported by gnome-base/gvfs, so if you use GNOME, it's easy for you. If not, you will need app-pda/ifuse. Both of these will mount /var/root/Media from the idevice to a target directory. If your device is 'jailbroken', you may use the --root flag to gain access to the root of the device.
Note that media files must be in /var/mobile/Applications//.data/Movies/ to be accessible by applications running on the device. More on this later.
Simply emerge gvfs with USE="ios", and it should auto-mount it for you. You can also mount the device manually using a frontend to GIO/GVfs such as x11-misc/gigolo, xfce-base/thunar (>=1.6.x) or gnome-base/nautilus.
emerge -av gigolo
TODO: UNTESTED. Does this require a log-out / log-in? Can gvfs be restarted some other way?
First, emerge ifuse, then try running it:
emerge -av ifuse
Users wishing to access the idevice must be members of the plugdev group, and must have write-access to the mount point.
gpasswd -a USER plugdev
Remember, you need to start a new user session after doing this for it to take effect. Most users quit their window manager and re-enter it to do this.
Also you need to change fusermount permissions:
chmod 4755 /usr/bin/fusermount
Create a mount-point for the Media folder on the device.
Create some App-specific mount points (I use the AppIDs as directory names, more on finding them later)
mkdir /media/ipad-com.apple.iBooks /media/ipad-com.olimsoft.oplayer.hd.lite
Set appropriate permissions.
chown root:plugdev /media/ipad*
chmod 775 /media/ipad*
Now mount the device as a user. First, the Media "partition":
Now an App's Documents folder:
ifuse --appid com.olimsoft.oplayer.hd.lite /media/ipad-com.olimsoft.oplayer.hd.lite
Finally, the device root (jailbroken devices only): (UNTESTED)
ifuse --root /media/ipad-root
If the preceding steps worked, this should be enough to mount the device. This can be automated using udev rules.
You should note that the author's experience is that throughput is slow, and is seriously affected by multiple copies in parallel - iotop reports transfer rates of approximately 1200 KiB/s for a single transfer, but a total of 600 KiB/s for two in parallel.
For transferring audio files to the idevice, mount the Media partition, make sure that your user can read and write files there and point gtkpod at it.
To Apps on the iDevice
Frontends to gnome-base/gvfs
Once you've "connected" to the 'Documents on My iPad' device using Gigolo, you can access the device via a file manager such as Thunar (>=1.6.x) or Nautilus and access the 'Documents' folder of the apps that support the iTunes Document Sharing feature (also called the "House Arrest" protocol). Copying files to this 'Documents' folder will make some apps pick up the files and allow you to view/edit/delete them on the iPad.
Following is a non-exhaustive list of free apps that support file transfers as described above:
- Videos: 'OPlayerHD Lite', 'HD Player'
- Audio: 'OPlayerHD Lite'
- Photos: 'Another Photo Viewer'
- PDFs or E-books: 'Documents 2', 'ciando Reader'
Sometimes it may be necessary to restart the app to make it aware of the transferred file, or possibly even reboot the iPad.
ifuse can also mount areas of the ipad by AppID, which allows the user to transfer files, which may then be used by the particular application. The AppID is a kind of namespace, particular to each application.
To find these AppIDs, you must install app-pda/ideviceinstaller.
List the AppIDs of the Apps currently installed on your device.
Mount by AppID:
ifuse --appid com.apple.iBooks /media/ipad-com.apple.iBooks
Now you are free to copy files to the mounted folder, which will be accessible to that App (iBooks in this example).
QueryType failed, error code -256
This error either appears on its own or followed by failed XML parsing, such as:
Entity: line 1: parser error : Start tag expected, '<' not found ��w���w�8�H 8�H .0" encoding="UTF-8"?>^
error opening socket
If your device was connected before installing imobiledevice, you can might get
usbmuxd_get_device_list: error opening socket! No device found, is it connected?
Unplug and replug your device, and try again.
GnuTLS Error: A TLS packet with unexpected length was received
Make sure that you are mounting as a normal user.
Unhandled Apple File Control error
If you're getting a: "Failed to open directory "ggImageViewer". Unhandled Apple File Control error (7).", then it is possible that the relevant app doesn't properly support the Apple file sharing protocol. Sometimes though it helps if you simply disconnect the 'Documents on My iPad' device, unplug the iPad, then plug it back and reconnect the device. Then you might be able to normally access an app's sandboxed 'Documents' folder.