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.
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.
USB Device Access
app-pda/usbmuxd must be explicity emerged since no other stack package will pull it in. Run the daemon to make the device available to higher layers:
root #usbmuxd -f -vThe flags are optional but make managing the daemon easy and transparent.
Pairing
Pairing functionality is provided by app-pda/libimobiledevice. Emerge it, then test it by running:
user $idevice_id -lThis should print the device serial number which appeared in your dmesg log.
If this has been successful, run:
user $ideviceinfoto verify that communications with the device are functioning correctly.
Now run:
user $idevicepair pairto pair with the device. Check this with:
user $idevicepair validateMounting
app-pda/libimobiledevice is supported by gnome-base/gvfs, so if you use GNOME, it is 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.
gnome-base/gvfs
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.
root #emerge -av x11-misc/gigoloTODO: UNTESTED. Does this require a log-out / log-in? Can gvfs be restarted some other way?
app-pda/ifuse
First, emerge ifuse, then try running it:
root #emerge -av app-pda/ifuseUsers wishing to access the idevice must be members of the plugdev group, and must have write-access to the mount point.
root #gpasswd -a USER plugdevRemember, 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:
root #chmod 4755 /usr/bin/fusermountCreate a mount-point for the Media folder on the device.
root #mkdir /media/ipad-MediaCreate some App-specific mount points (I use the AppIDs as directory names, more on finding them later)
root #mkdir /media/ipad-com.apple.iBooks /media/ipad-com.olimsoft.oplayer.hd.liteSet appropriate permissions.
root #chown root:plugdev /media/ipad*root #chmod 775 /media/ipad*Now mount the device as a user. First, the Media "partition":
user $ifuse /media/ipad-MediaNow an App's Documents folder:
user $ifuse --appid com.olimsoft.oplayer.hd.lite /media/ipad-com.olimsoft.oplayer.hd.liteIf you get error "bad mount point", try this command instead previous:
user $ifuse --documents com.olimsoft.oplayer.hd.lite /media/ipad-com.olimsoft.oplayer.hd.liteFinally, the device root (jailbroken devices only - Requires 'Apple File Conduit "2"' Tweak):
user $ifuse --root /media/ipad-rootIf 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.
Transferring Media
app-pda/gtkpod
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.
net-misc/rclone
For transfering files through file manager on iPhone - using Sambda share, another option:
net-fs/samba
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.
app-pda/ifuse
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.
root #emerge app-pda/ideviceinstallerList the AppIDs of the Apps currently installed on your device.
user $ideviceinstaller -lMount by AppID:
user $ifuse --appid com.apple.iBooks /media/ipad-com.apple.iBooksIf you get error "bad mount point", try this command instead previous:
user $ifuse --documents com.apple.iBooks /media/ipad-com.apple.iBooksNow you are free to copy files to the mounted folder, which will be accessible to that App (iBooks in this example).
Troubleshooting
imobiledevice Troubleshooting
QueryType failed, error code -256
This error either appears on its own or followed by failed XML parsing, such as:
root #ideviceinfoEntity: line 1: parser error : Start tag expected, '<' not found ��w���w�8�H 8�H .0" encoding="UTF-8"?>
^In 2011-11, this was due to an Apple update, and git versions of app-pda/libimobiledevice and app-pda/ifuse were needed
error opening socket
If your device was connected before installing imobiledevice, you might get
user $idevice_id -l
usbmuxd_get_device_list: error opening socket! No device found, is it connected?
Unplug and replug your device, and try again.
ifuse Troubleshooting
GnuTLS Error: A TLS packet with unexpected length was received
root #ifuse /media/iphoneIn 2010, this could be solved by re-merging net-libs/gnutls and dev-libs/libgcrypt. See this forum thread for more informations.
Permissions
Make sure that you are mounting as a normal user.
GVfs Troubleshooting
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.