1 Building and Installing
2 -----------------------
4 See the "INSTALL" file.
7 Initiator and Responder
8 -----------------------
10 libmtp implements an MTP initiator, which means it initiate
11 MTP sessions with devices. The devices responding are known
12 as MTP responders. libmtp runs on something with a USB host
13 controller interface, using libusb to access the host
16 If you're more interested in the MTP responders, gadgets like
17 MP3 players, mobile phones etc, look into MeeGo:s Buteo Sync:
18 http://wiki.meego.com/Buteo - these guys are creating a fully
19 open source MTP responder.
21 Android has an MTP responder implementation:
22 https://android.googlesource.com/platform/frameworks/base/+/master/media/jni/
27 libmtp is based on several ancestors:
29 * libptp2 by Mariusz Woloszyn was the starting point used
30 by Richard A. Low for the initial starter port. You can
31 find it at http://libptp.sourceforge.net/
33 * libgphoto2 by Mariusz Woloszyn and Marcus Meissner was
34 used at a later stage since it was (is) more actively
35 maintained. libmtp tracks the PTP implementation in
36 libgphoto2 and considers it an upstream project. We will
37 try to submit anything generally useful back to libgphoto2
38 and not make double efforts. In practice this means we
39 use ptp.c, ptp.h and ptp-pack.c verbatim from the libgphoto2
40 source code. If you need to change things in these files,
41 make sure it is so general that libgphoto2 will want to
42 merge it to their codebase too. You find libgphoto2 as part
43 of gPhoto: http://gphoto.sourceforge.net/
45 * libnjb was a project that Richard and Linus were working
46 on before libmtp. When Linus took Richards initial port
47 and made an generic C API he re-used the philosophy and
48 much code from libnjb. Many of the sample programs are for
49 example taken quite literally from libnjb. You find it here:
50 http://libnjb.sourceforge.net/
53 Contacting and Contributing
54 ---------------------------
56 See the project page at http://libmtp.sourceforge.net/
57 We always need your help. There is a mailinglist and a
58 bug report system there.
60 People who want to discuss MTP devices in fora seem to
61 hang out on the forums at AnythingbutiPod:
62 http://www.anythingbutipod.com/forum/
65 Compiling programs for libmtp
66 -----------------------------
68 libmtp has support for the pkg-config script by adding a libmtp.pc
69 entry in $(prefix)/lib/pkgconfig. To compile a libmtp program,
72 gcc -o foo `pkg-config --cflags --libs libmtp` foo.c
74 This also simplifies compilation using autoconf and pkg-config: just
77 PKG_CHECK_MODULES(MTP, libmtp)
81 To have libmtp LIBS and CFLAGS defined. Needless to say, this will
82 only work if you have pkgconfig installed on your system, but most
85 If your library is installed in e.g. /usr/local you may have to tell
86 this to pkgconfig by setting the PKG_CONFIG_PATH thus:
88 export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
94 Read the API documentation that can be generated with doxygen.
95 It will be output in doc/html if you have Doxygen properly
96 installed. (It will not be created unless you have Doxygen!)
98 For information about the Media Transfer Protocol, see:
99 http://en.wikipedia.org/wiki/Media_Transfer_Protocol
101 The official 1.0 specification for MTP was released by the
102 USB Implementers Forum in may, 2008. Prior to this, only a
103 proprietary Microsoft version was available, and quite a few
104 devices out there still use some aspects of the Microsoft
105 version, which deviates from the specified standard. You can
106 find the official specification here:
107 http://www.usb.org/developers/devclass_docs/MTP_1.0.zip
113 In the subdirectory "examples" you find a number of
114 command-line tools, illustrating the use of libmtp in very
117 Please do not complain about the usability or documentation
118 of these examples, they look like they do for two reasons:
120 1. They are examples, not tools. If they were intended for
121 day-to-day usage by commandline freaks, I would have
122 called them "tools" not "examples".
124 2. The MTP usage paradigm is that a daemon should hook
125 the device upon connection, and that it should be
126 released by unplugging. GUI tools utilizing HAL (hald)
127 and D-Bus do this much better than any commandline
128 program ever can. (See below on bugs.) Specificationwise
129 this is a bug, however it is present in many, many
132 That said, if you want to pick up and maintain the examples,
139 Some MTP devices have strange pecularities. We try to work around
140 these whenever we can, sometimes we cannot work around it or we
141 cannot test your solution.
143 * Android locked screen: some devices just report zero files
144 and no storages when the device screen is locked, it looks like
148 Device 0 (VID=04e8 and PID=6860) is a Samsung Galaxy models (MTP).
149 Attempting to connect device(s)
150 Error 1: Get Storage information failed.
152 LIBMTP_Get_Storage(): No data available
155 This is probably so as not to allow the MTP access to be used
156 as a "backdoor" into the device. Unlock the device before listing
157 files, set the autolock to some large value or disabled if it
158 disturbs you, you are causing this to yourself, or should we say
159 that your vendor is prioritizing security and privacy over
160 ease-of-use. (You may talk to your vendor about this.)
162 * mtp-* tools doesn't work because someone else is already hogging
165 This is a common problem, the most common case could be that
166 gphoto2 (which can also talk PTP/MTP) is taking over the device
167 as soon as it's plugged in. Some distributions are configured that
168 way. Counter it like this:
170 gvfs-mount -s gphoto2
172 Then re-attach the device.
174 Sometimes the "gvfs-gphoto2-volume-monitor" is running on the
175 system and hogging the device, try something like:
177 pkill gvfs-gphoto2-volume-monitor
179 Then plug in the device and issue "mtp-detect" to figure out if
180 this may be the case.
182 * Generic MTP/PTP disconnect misbehaviour: we have noticed that
183 Windows Media Player apparently never close the session to an MTP
184 device. There is a daemon in Windows that "hooks" the device
185 by opening a PTP session to any MTP device, whenever it is
186 plugged in. This daemon proxies any subsequent transactions
187 to/from the device and will never close the session, thus
188 Windows simply does not close sessions at all.
190 For example this means that a device may work the first time
191 you run some command-line example like "mtp-detect" while
192 subsequent runs fail.
194 Typical sign of this illness: broken pipes on closing sessions,
195 on the main transfer pipes(s) or the interrupt pipe:
198 usb_clear_halt() on INTERRUPT endpoint: Broken pipe
201 This means that device manufacturers doesn't notice any problems
202 with devices that do not correctly handle closing PTP/MTP
203 sessions, since Windows never do it. The proper way of closing
204 a session in Windows is to unplug the device, simply put.
206 Since libmtp actually tries to close sessions, some devices
207 may fail since the close session functionality has never been
208 properly tested, and "it works with Windows" is sort of the
209 testing criteria at some companies.
211 You can get Windows-like behaviour on Linux by running a udev-aware
212 libmtp GUI client like Rhythmbox or Gnomad2, which will "hook"
213 the device when you plug it in, and "release" it if you unplug
214 it, and you start/end you transfer sessions by plugging/unplugging
217 The "Unix way" of running small programs that open the device,
218 do something, then close the device, isn't really working with
219 such devices and you cannot expect to have command line tools
220 like the mtp examples work with them. You could implement new
221 example programs that just call to a mediating daemon like the
222 Windows MTP stack does. (And change all programs using libmtp
225 If this bug in your device annoys you, contact your device
226 manufacturer and ask them to test their product with some libmtp
229 * Samsung Android 2.3.x devices: these have a special MTP stack
230 with some specific bugs that we have maybe nailed down now.
231 It suffers from an "immediate connect" syndrome, i.e. you have
232 to connect to the device within 7 seconds of plugging in, or it
233 will go numb. This also goes for command-line activity with
234 the example programs, so this device is better used with a
235 GUI tool like Rhythmbox, gnomad2...
237 * Generic USB misbehaviour: some devices behave badly under MTP
238 and USB mass storage alike, even down to the lowest layers
239 of USB. You can always discuss such issues at the linux-usb
240 mailing list if you're using Linux:
241 http://www.linux-usb.org/mailing.html
243 If you have a problem specific to USB mass storage mode, there
244 is a list of strange behaving devices in the Linux kernel:
245 http://lxr.linux.no/linux/drivers/usb/storage/unusual_devs.h
246 You can discuss this too on the mentioned list, for understanding
248 http://www2.one-eyed-alien.net/~mdharm/linux-usb/target_offenses.txt
250 * Generic certificate misbehaviour. All devices are actually
251 required to support a device certificate to be able to
252 encrypt Windows Media (WMA/WMV) files. However there are
253 obviously a lot of devices out there which doesn't support
254 this at all but instead crash. Typical printout:
256 Error 2: PTP Layer error 02ff: get_device_unicode_property(): failed
257 to get unicode property.
259 This should only affect "mtp-detect", there is no other
260 application currently retrieveing the certificate (not that we
263 * Kernel bug on Linux. Linux 2.6.16 is generally speaking required
264 to use any MTP device under USB 2.0. This is because the EHCI
265 driver previously did not support zero-length writes to endpoints.
266 It should work in most cases however, or if you connect it
267 to an UHCI/OHCI port instead (yielding lower speed). But
268 please just use a recent kernel.
270 * Zen models AVI file seeking problem: the Zens cannot parse the
271 files for the runlength metadata. Do not transfer file with e.g.
272 mtp-sendfile, use mtp-sendtr and set the length of the track to
273 the apropriate number of seconds and it will work. In graphical
274 clients, use a "track transfer" function to send these AVI files,
275 the Zens need the metadata associated with tracks to play back
276 movies properly. Movies are considered "tracks" in the MTP world.
278 * Some devices that disregard the metadata sent with the MTP
279 commands will parse the files for e.g. ID3 metadata. Some still
280 of these devices expect only ID3v2.3 metadata and will fail with
281 a modern ID3v2,4 tag writer, like many of those found in Linux
282 applications. Windows Media Player use ID3v2.3 only, so many
283 manufacturers only test this version.
285 * The Zen Vision:M (possibly more Creative Zens) has a firmware bug
286 that makes it drop the last two characters off a playlist name.
287 It is fixed in later firmware.
289 * For Creative Technology devices, there are hard limits on how
290 many files can be put onto the device. For a 30 GiB device (like
291 the Zen Xtra) the limit is 6000, for a 60 GiB device the limit
292 is 15000 files. For further Creative pecularities, see the
293 FAQ sections at www.nomadness.net.
295 * Sandisk sansa c150 and probably several other Sandisk devices
296 (and possibly devices from other manufacturers) have a dual
297 mode with MTP and USB mass storage. The device will initially
298 claim to be mass storage so udev will capture is and make the
299 use of MTP mode impossible. One way of avoiding it could be to
300 be to blacklist the "usb-storage" module in
301 /etc/modprobe.c/blacklist with a row like this:
302 "blacklist usb-storage". Some have even removed the
303 "usb-storage.ko" (kernel module file) to avoid loading.
305 * Sandisk Sansa Fuze has three modes: auto, MTP or mass storage
306 (MSC). Please set it to MTP to avoid problems with libmtp.
308 * The iriver devices (possibly all of them) cannot handle the
309 enhanced GetObjectPropList MTP command (0x9805) properly. So
310 they have been banned from using it.
312 * iriver devices have problems with older versions of libmtp and
313 with new devices libmtp does not know of as of yet, since it
314 has an oldstyle USB device controller that cannot handle zero
315 writes. (Register your device with us!) All their devices are
316 likely to need a special device flag in the src/libusb-glue.c
319 * The Samsung Yepp T9 has several strange characteristics, some
320 that we've managed to work around. (For example it will return
321 multiple PTP packages in a single transaction.)
323 * The early firmware for Philips HDD players is known to be
324 problematic. Please upgrade to as new firmware as you can get.
325 (Yes this requires some kind of Windows Installation I think.)
327 * Philips HDD 1630/16 or 1630/17 etc may lock themselves up,
328 turning inresponsive due to internal corruption. This typically
329 gives an error in opening the PTP session. Apparently you can
330 do a "repair" with the firmware utility (Windows only) which
331 will often fix this problem and make the device responsive
334 * Some devices that implement GetObjectPropList (0x9805) will
335 not return the entire object list if you request a list for object
336 0xffffffffu. (But they should.) So they may need the special
337 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL.
339 * Some (smaller) subset of devices cannot even get all the
340 properties for a single object in one go, these need the
341 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST. Currently only the
342 iriver devices seem to have this bug.
344 * The Toshiba Gigabeat S (and probably its sibling the
345 Microsoft Zune and other Toshiba devices) will only display
346 album information tags for a song in case there is also
347 an abstract album (created with the album interface) with
350 * The Zen Vision:M has an older firmware which is very corrupt,
351 it is incompatible with the Linux USB stack altogether. The
352 kernel dmesg will look something like this, and you have to
353 upgrade the firmware using Windows:
354 usb 4-5: new high speed USB device using ehci_hcd and address 5
355 usb 4-5: configuration #1 chosen from 1 choice
356 usb 4-5: can't set config #1, error -110
358 * The Sirus Stiletto does not seem to allow you to copy any files
359 off the device. This may be someone's idea of copy protection.
361 * The Samsung P2 assigns parent folder ID 0 to all unknown file
362 types.(i.e. moves them to the root folder)
364 * The Sandisk Sansa Clip+ needs a firmware upgrade in earlier
365 versions in order to work properly.
371 If you happen upon a device which libmtp claims it cannot
372 autodetect, please submit the vendor ID and device ID
373 (these can be obtained from the "lsusb" and "lsusb -n"
374 commands run as root) as a bug, patch or feature request
375 on the Sourceforge bug tracker at our homepage. If it
376 gives a sensible output from "mtp-detect" then please attach
377 the result as well as it teach us some stuff about your
378 device. If you've done some additional hacking, join our
379 mailinglist and post your experiences there.
381 If you want to be able to hack some more and you're not
382 afraid of C hacking, add an entry for your device's
383 vendor/product ID and a descriptive string to the database
384 in the file src/music-players.h.
386 If you want to poke around to see if your device has some
387 special pecularities, you can test some special device
388 flags (defined in src/device-flags.h) by inserting them
389 together with your device entry in src/music-players.h.
390 Flags can be tested in isolation or catenated with "|"
391 (binary OR). If relatives to your device use a certain
392 flag, chances are high that a new device will need it
393 too, typically from the same manufacturer.
395 The most common flag that needs to be set is the
396 DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel
397 drivers that may have attached to the device making
398 MTP access impossible. This is however not expected to
399 really work: this is a problem being tracked as of
400 now (2007-08-04). See the "last resort" solutions below
401 if you really need to get your dual-mode device to work
404 Another flag which is easy to identify is the
405 DEVICE_FLAG_NO_ZERO_READS, which remedies connection
406 timeouts when getting files, and some timeouts on e.g.
407 successive "mtp-connect" calls.
409 If your device is very problematic we are curious of how it
410 works under Windows, so we enjoy reading USB packet sniffs
411 that reveal the low-level traffic carried out between
412 Windows Media Player and your device. This can be done
416 http://benoit.papillault.free.fr/usbsnoop/
418 * The trial version of HHD Softwares software-only
419 USB monitor. You need to get a copy of version 2.37 since
420 the newer trial versions won't let you carry out the
421 needed packet sniffs. (As of 2007-03-10 a copy can be found
422 at: http://www.cobbleware.com/files/usb-monitor-237.exe)
424 There are other USB monitors as well, some more expensive
425 alternatives use hardware and even measure electronic
426 characteristics of the traffic (which is far too much
429 Device sniffs are an easy read since the PTP/MTP protocol
430 is nicely structured. All commands will have a structure such
431 as this in the log, we examplify with a object list request:
434 000120: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:25.9843750 +0.0
435 Pipe Handle: 0x863ce234 (Endpoint Address: 0x2)
436 Send 0x20 bytes to the device:
437 20 00 00 00 01 00 05 98 23 00 00 00 27 03 00 10 ......?#...'...
438 Length TYPE CMD Trans# Param1
440 00 00 00 00 02 DC 00 00 00 00 00 00 00 00 00 00 .....Ü..........
441 Param2 Param3 Param4 Param5
443 [OPTIONAL] DATA PHASE:
444 000121: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0156250
445 Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
446 Get 0x1a bytes from the device:
447 1A 00 00 00 02 00 05 98 23 00 00 00 01 00 00 00 .......?#.......
448 Length TYPE CMD Trans# DATA
450 27 03 00 10 02 DC 04 00 00 30 '....Ü...0
453 000122: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0
454 Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
455 Get 0xc bytes from the device:
456 0C 00 00 00 03 00 01 20 23 00 00 00 ....... #...
457 Length TYPE CODE Trans#
459 * One send (OUT to the device), two reads (IN from the device).
461 * All three byte chunks commands are
462 sent/recieved/recieeved by the function ptp_transaction()
465 * It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata()
466 or ptp_usb_getdata() and finally ptp_usb_getresp() in the file
467 libusb-glue.c. Notice ptp_usb_sendreq() and ptp_usb_getresp()
468 are ALWAYS called. The TYPE field correspond to this, so the
469 TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002),
470 and "RESPONSE" (0x0003).
472 * Notice that the byte order is little endian, so you need to read
473 each field from right to left.
476 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
477 Transaction# 0x00000023.
478 REQUEST parameters 0x10000327, 0x00000000, 0x0000DC02, 0x00000000
479 0x00000000, in this case it means "get props for object 0x10000327",
480 "any format", "property 0xDC02" (PTP_OPC_ObjectFormat), then two
481 parameters that are always zero (no idea what they mean or their
485 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
486 Transaction# 0x00000023.
487 Then comes data 0x00000001, 0x10000327, 0xDC02, 0x0004, 0x3000
488 Which means in this case, (and this is the tricky part) "here
489 you have 1 property", "for object 0x10000327", "it is property
490 0xDC02" (PTP_OPC_ObjectFormat), "which is of type 0x0004"
491 (PTP_DTC_UINT16), "and set to 0x3000" (PTP_OFC_Undefined, it
492 is perfectly valid to have undefined object formats, since it
493 is a legal value defining this).
496 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
497 Return Code ("RC") = 0x2001, PTP_RC_OK, all went fine.
498 Transaction# 0x00000023.
500 If you want to compare the Windows behaviour with a similar
501 operation using libmtp you can go into the src/libusb-glue.c
502 file and uncomment the row that reads:
504 //#define ENABLE_USB_BULK_DEBUG
506 (I.e. remove the two //.)
508 This will make libmtp print out a hex dump of every bulk USB
509 transaction. The bulk transactions contain all the PTP/MTP layer
510 data, which is usually where the problems appear.
513 Notes to assist with debugging new devices:
514 -------------------------------------------
516 In debugging new hardware, we highly recommend that you only
517 use the example mtp-* applications that come with libmtp, as other
518 applications may have their own bugs that may interfere with your
519 new device working correctly. Using another application instead of
520 those that come with libmtp just adds another point of failure.
522 For debugging, there are 3 main options:
524 1. Use the env variable: LIBMTP_DEBUG to increase the
525 verboseness of the debugging output for any application using
526 libmtp. Relevant codes are:
527 * 0x00 [0000 0000] : no debug (default)
528 * 0x01 [0000 0001] : PTP debug
529 * 0x02 [0000 0010] : Playlist debug
530 * 0x04 [0000 0100] : USB debug
531 * 0x08 [0000 1000] : USB data debug
532 // Codes are hex and binary respectively. Simple add them togther
533 // to get your desired level of output.
537 $ export LIBMTP_DEBUG=12
539 // To get USB debug and USB data debug information.
541 $ export LIBMTP_DEBUG=2
543 // To get Playlist debug information.
545 Also note, an application may also use the LIBMTP_debug() API
546 function to achieve the same options as listed above.
548 2. Use "strace" on the various mtp-* commands to see where/what
549 is falling over or getting stuck at.
550 * On Solaris and FreeBSD, use "truss" or "dtrace" instead on "strace".
551 * On Mac OS X, use "ktrace" or "dtrace" instead of "strace".
552 * On OpenBSD and NetBSD, use "ktrace" instead of "strace".
554 This will at least help pinpoint where the application is failing, or
555 a device is reporting incorrect information. (This is extremely helpful
556 with devices that have odd disconnection requirements).
558 The use of these tools may also pinpoint issues with libusb as
559 implemented by each OS vendor or issues with the MTP implementation
560 on the new device as well, so please be prepared for either case.
562 3. Use "gdb" or similar debugger to step through the code as it is
563 run. This is time consuming, and not needed just to pinpoint where
566 The use of gdb or another debugger may also miss or actually cause
567 command and data timing issues with some devices, leading to false
568 information. So please consider this a last resort option.
570 Also please read the "It's Not Our Bug!" section below, as it does
571 contain some useful information that may assist with your device.
574 Dual-mode devices does not work - last resort:
575 ----------------------------------------------
577 Some devices that are dual-mode are simply impossible to get
578 to work under Linux because the usb-storage(.ko) kernel
579 module hook them first, and refuse to release them, even
580 when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe
581 it DOES release it but the device will immediately be probed
582 at the USB mass storage interface AGAIN because it
585 Here is what some people do:
587 1. Plug in the device.
588 2. USB-mass storage folder will open automatically.
589 3. Unmount the device.
590 4. Run mtp-detect. It will most likely fail the first time.
591 5. Run mtp-detect again, it might work this time, or fail. Keep running
592 till it works. 99% it works by the third try.
593 6. Once mtp-detect gives you an "Ok", open either Rhythmbox or Gnomad2,
594 everything should work.
596 Linux: Try this, if you have a recent Linux kernel,
597 add the file (as root):
599 /etc/modprobe.d/no-usb-storage.conf
603 options usb-storage quirks=1234:4321:i
605 This will tell usb-storage to ignore this device when it's inserted
606 so it is not hogged by the mass storage interfaces. Remove and re-insert
607 the device and see if it works. Usually this does the trick.
609 For older systems, or as a bigger hammer, run (as root) something
612 > rmmod usb_storage ; mtp-detect
614 You can run most any command or a client like gnomad2 or
615 Amarok immediately after the rmmod command. This works
616 sometimes. Another even more brutal approach is this:
618 * Edit /etc/modprobe.d/blacklist
619 * Add the line "blacklist usb-storage"
622 Now none of you USB disks, flash memory sticks etc will be
623 working (you just disabled them all). However you *can* try
624 your device, and it might have started working because there
625 is no longer a USB mass storage driver that tries to hook onto
626 the mass storage interface of your device.
628 If not even blacklisting works (check with
629 "lsmod | grep usb-storage"), there is some problem with
630 something else and you may need to remove or rename the file
631 /lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko
634 If you find the PerfectSolution(TM) to this dilemma, so you
635 can properly switch for individual devices whether to use it
636 as USB mass storage or not, please tell us how you did it. We
637 know we cannot use udev, because udev is called after-the-fact:
638 the device is already configured for USB mass storage when
641 On Mac OS there is another ugly hack:
643 1. Open up a terminal window
645 sudo mv /System/Library/Extensions/IOUSBMassStorageClass.kext
646 /System/Library/Extensions/IOUSBMassStorageClass.kext.disabled
648 and when prompted enter your password.
652 To reverse this change, just reverse the filenames:
654 sudo mv /System/Library/Extensions/
655 IOUSBMassStorageClass.kext.disabled /System/Library/Extensions/
656 IOUSBMassStorageClass.kext
661 Calendar and contact support:
662 -----------------------------
664 The Creative Zen series can read VCALENDAR2 (.ics) files
665 and VCard (.vcf) files from programs like for example
666 Evolution with the following limitations/conditions:
668 - The file must be in DOS (CR/LF) format, use the unix2dos
669 program to convert if needed
671 - Repeat events in calendar files do not seem to be supported,
672 entries will only appear once.
674 - Calendar (.ics) files should be stored in the folder "My Organizer"
675 when sent to the device (this directory should be autodetected
676 for use with calendar files, otherwise use the option
677 -f "My Organizer" to sendfile for this) Apparently this file can
678 also contain tasklists.
680 - Contact (.vcf) files should be stored in the folder "My Contacts"
681 when sent to the device. (-f "My Contacts")
683 - Some devices are picky about the name of the calendar and
684 contact files. For example the Zen Microphoto wants:
686 Calendar: My Organizer/6651416.ics
687 Contacts: My Organizer/6651416.vcf
690 Syncing in with Evolution and Creative Devices
691 ----------------------------------------------
693 Evolution can easily export .ics an .vcf files, but you currently
694 need some command-line hacking to get you stuff copied over in
695 one direction host -> device. The examples/ directory contains a script
696 created for the Creative Zen Microphoto by Nicolas Tetreault.
702 Shared libraries can be troublesome to users not experienced with
703 them. The following is a condensed version of a generic question
704 that has appeared on the libmtp mailing list from time to time.
706 > PTP: Opening session
707 > Queried Creative Zen Vision:M
708 > gnomad2: relocation error: gnomad2: undefined symbol:
709 > LIBMTP_Get_Storageinfo
711 > Are these type of errors related to libmtp or something else?
713 The problem is of a generic nature, and related to dynamic library
714 loading. It is colloquially known as "dependency hell".
715 (http://en.wikipedia.org/wiki/Dependency_hell)
717 The gnomad2 application calls upon the dynamic linker in Linux to
718 resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol
719 (ELF symbol, or link point or whatever you want to call them, a
720 symbol is a label on a memory address that the linker shall
721 resolve from label to actual address.)
722 For generic information on this subject see the INSTALL file and
725 http://en.wikipedia.org/wiki/Library_(computing)
727 When Linux /lib/ld-linux.so.X is called to link the symbols compiled
728 into gnomad2 (or any other executable using libmtp), it examines the
729 ELF file for the libmtp.so.X file it finds first and cannot resolve
730 the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a
731 problem witj) from it, since it's probably not there. There are many
732 possible causes of this symbol breakage:
734 1) You installed precompiled libmtp and gnomad2 packages (RPMs, debs
735 whatever) that do not match up. Typical cause: your gnomad2 package was
736 built against a newer version of libmtp than what's installed on your
737 machine. Another typical cause: you installed a package you found on
738 the web, somewhere, the dependency resolution system did not protest
739 properly (as it should) or you forced it to install anyway, ignoring
742 2) You compiled libmtp and/or gnomad2 from source, installing both or
743 either in /usr/local/lib and /usr/local/bin. This means at compile-time
744 gnomad2 finds the libmtp library in /usr/local/lib but at runtime, it
745 depends on the Linux system wide library loader (/lib/ld-linux.so.X) in
746 order to resolve the symbols. This loader will look into the file
747 /etc/ld.so.conf and/or the folder /etc/ld.so.conf.d in order to find
748 paths to libraries to be used for resolving the symbols. If you have
749 some older version of libmtp in e.g. /usr/lib (typically installed by a
750 package manager) it will take precedence over the new version you just
751 installed in /usr/local/lib and the newly compiled library in
752 /usr/local/lib will *not* be used, resulting in this error message.
754 3) You really did install the very latest versions (as of writing libmtp
755 0.1.5 and gnomad2 2.8.11) from source and there really is no
756 pre-installed package of either on your machine. In that case I'm
757 totally lost, I have no idea what's causing this.
761 1) If you don't want to mess around with your system and risk these
762 situations, only use pre-packaged software that came with the
763 distribution or its official support channels. If it still breaks,
764 blame your distribution, they're not packaging correctly. Relying on
765 properly packaged software and not installing things yourself *is* the
766 Linux solution to the "dependency hell" problem.
768 2) Read about dynamically linked library handling until the stuff I wrote
769 about in the previous list sounds like music to your ears, inspect
770 your /lib, /usr/lib, /usr/local/lib, /etc/ld.so.conf and the
771 /etc/ld.so.conf.d, remove all pre-packed versions using RPM, APT,
772 YaST or whatever your distribution uses, compile libmtp and gnomad2
773 (or whatever) from source only and you will be enlighted.
775 I don't know if this helps you, it's the best answer we can give.
778 API is obscure - I want plain files!
779 ------------------------------------
781 PTP/MTP devices does not actually contain "files", they contain
782 objects. These objects have file names, but that is actually
783 just a name tag on the object.
785 Folders/directories aren't really such entities: they are just
786 objects too, albeit objects that can act as parent to other
787 objects. They are called "associations" and are created in atomic
788 fashion and even though there is an MTP command to get all the
789 associations of a certain object, this command is optional
790 so it is perfectly possible (and most common, actually) to create
791 devices where the "folders" (which are actually associations) have
792 no idea whatsoever of what files they are associated as parents to
793 (i.e. which files they contain). This is very easy for device
794 manufacturers to implement, all the association (i.e. finding out
795 which files are in a certain folder) has to be done by the MTP
796 Initiator / host computer.
798 Moving a file to a new folder is for example very simple in a
799 "real" file system. In PTP/MTP devices it is often not even possible,
800 some devices *may* be able to do that, if they support command
801 0x1019 "Move Object", but actually the only reliable way of executing
802 file movement is to upload the file to the host, download it with
803 the new parent, then delete the old file. We have played with the
804 idea of implementing this time consuming function as a fallback
805 in case the device does not support command 0x1019, perhaps one day
806 we will do that. (Some devices also support command 0x101a
809 Then the issue that in PTP/MTP it is legal for two files to have
810 exactly the same path as long as their object IDs differ. A
811 folder/association can contain two files with the exact same name.
812 (And on the Creative devices this even works, too, though most devices
813 implicitly fail at this.) Perhaps one could add some custom hook for
814 handling that, so they become /Foo.mp3 and /Foo.mp3(1) or something
815 similar, but it's really a bit kludgy.
817 Playlists and albums aren't really files, thinking about
818 them as files like the hacks in libgphoto2 is really backwards. They are
819 called associations and are more like a symbolic link that links in a
820 star-shaped pattern to all the files that are part of the album/playlist.
821 Some devices (Samsung) thought that was too complicated and have a
822 different way of storing playlists in an UTF-16 encoded .spl-like file
823 instead! This is why playlists/albums must have their own structs and
826 Plain file access also assumes to be able to write files of an
827 undetermined size, which is simply not possible in a transactional
828 file system like PTP/MTP. (See further below.)
834 Streaming reads is easy. Just connect the output file descriptor from
835 LIBMTP_Get_File_To_File_Descriptor() (and a similar function for tracks)
838 People have connected this to TCP sockets for streaming web servers
839 etc, works like a charm. Some devices will even survive if the callback
840 functions return non-zero and cancel the download. Some devices will
841 lock up and even require a reset if you do that. Devices are poorly
842 implemented so that's life. If you want to stream off a device, the
843 best idea is always to stream the entire file and discard the stuff
844 at the end you don't want. It will incur a delay if you e.g. want to
845 skip between tracks, sadly.
847 Then we get to the complicated things: streaming WRITES...
850 LIBMTP_Send_File_From_File_Descriptor() (and similar for tracks)
851 which will write a file to a device from a file descriptor, which may
852 be a socket or whatever.
854 HOWEVER: this requires a piece of metadata with the .filesize properly
857 This is not because we think it is funny to require that, the protocol
858 requires it. The reason is that PTP/MTP is a transactional file system
859 and it wants to be able to deny file transfer if the file won't fit on
860 the device, so the transaction never even starts, it's impossible to
861 start a transaction without giving file length.
863 People really want streaming so I tried a lot of hacks to see if they
864 would work, such as setting file size to 0xffffffffU or something other
865 unnaturally big and then aborting the file transfer when the stream ends.
866 It doesn't work: either the device crashes or the file simply disappears
867 since the device rolls back all failed transactions.
869 So this is an inherent limitation of the PTP/MTP protocol.
872 I want to remote control my device!
873 -----------------------------------
875 I have both good and bad news for you.
877 The good news is that the MTP protocol has well-defined commands to play
878 back content on a device. Operation 0xD411 (PTP_DPC_MTP_PlaybackObject)
879 will start playing back a file on the device (whatever that may mean if
880 this is not a music or video file), and operation 0xD403 can set the
881 playback volume to save your ears. Then there are operations to
882 determine how far into the current file you currently are, so as to
883 support say progress bars.
885 Since these commands have been around since the dawn of the MTP protocol
886 and since it was developed in cooperation with Creative Technology, this
887 is probably a requested feature from the Creative people who already had
888 support for playback on their devices using the PDE protocol back then.
890 Anyway, here are the bad news:
892 mtp-detect-trekstor-vibez.txt: 0xd411: Playback Object
894 Aha there is only one known device in the world which actually supports
895 playback on the device. So either you go buy the Trekstor Vibez, or you
896 can forget about this. You could always try asking your hardware vendor
897 of choice to go implement this.
899 Since none of the core developers of libmtp has the Trekstor device, this
900 is not yet implemented in libmtp.
906 If you are a device vendor there is a lot you can do for libmtp:
908 * Please consider assigning one of your employees as a contact person
909 for libmtp, have them sign up to the libmtp development list and answer
910 questions and post new device ID:s as they are released to our
913 * If you want to help even more, assign someone to look deeper into
914 error reports on your specific devices, understand why your firmware
915 may require some special device flags and what can be done about it.
917 * Do you have spare devices you can give us? Send them to Richard (Mac
918 support) or Linus (Linux support). (So far nobody did that except for
919 Microsoft who sent us a Zune by proxy!)
921 Vendors do need help from libmtp too, especially we want to help
922 vendors improve their MTP stacks, because they all suffer from the
923 same problem: the lack of a proper conformance test has made many devices
924 incompliant with the MTP specification as it is published today: most
925 devices are just compliant with the Windows MTP stack, and don't work
926 out-of-the-box with libmtp. We need someone on the inside to help in
927 bug reporting vendors MTP stacks internally so these issues are raised.
928 A good way to go toward better MTP compliance is to test with an
929 alternative implementation of the stack. In e.g. IETF standardization
930 it is compulsory for an RFC to have atleast two independent implementations
931 for it to reach the status as standard.
933 Being compliant with libmtp is also more and more important for
934 vendors: libmtp is being deployed in some embedded systems like
935 set-top-boxes etc. It will be very irritating for customers if a device
936 will not dock properly with some home entertainment equipment just because
937 it is based on Linux and libmtp and not the Windows MTP stack.
939 Autodetect with gudev
940 ---------------------
942 Previously you would use HAL to detect devices being plugged in. Nowadays
943 we use udev directly, or though the GNOME libgudev library. LIBMTPs
944 default udev rules export the proper properties to detect any MTP device
945 automatically, here is a verbose example derived from gnomad2:
947 #define G_UDEV_API_IS_SUBJECT_TO_CHANGE
948 #include <gudev/gudev.h>
949 const char * const gudev_subsystems[] = { "usb", NULL };
950 GUdevClient *gudev_client;
952 guint uevent_bus_hooked = 0;
953 guint uevent_device_hooked = 0;
956 static void uevent_cb(GUdevClient *client, const char *action, GUdevDevice *device, void *data)
965 devicenum = (guint64) g_udev_device_get_device_number(device);
966 g_print("%s event for %s (%"G_GINT64_MODIFIER"x)", action,
967 g_udev_device_get_sysfs_path (device), devicenum);
969 /* get device info */
970 vendor = get_property_as_int(device, "ID_VENDOR_ID", 16);
971 model = get_property_as_int(device, "ID_MODEL_ID", 16);
972 busnum = get_property_as_int(device, "BUSNUM", 10);
973 devnum = get_property_as_int(device, "DEVNUM", 10);
974 mtpdevice = get_property_as_int(device, "ID_MTP_DEVICE", 10);
976 if (vendor == 0 || model == 0) {
977 g_print("couldn't get vendor or model ID for device at (%x:%x)\n",
981 g_print("vendor = %x, model = %x, bus = %x, device = %x\n",
982 vendor, model, busnum, devnum);
986 g_print("device is MTP compliant\n");
988 if (g_str_equal(action, "add") &&
989 uevent_bus_hooked == 0 &&
990 uevent_device_hooked == 0) {
991 g_print(MTP device plugged in!\n");
992 uevent_bus_hooked = busnum;
993 uevent_device_hooked = devnum;
995 } else if (g_str_equal (action, "remove") &&
996 uevent_bus_hooked == busnum &&
997 uevent_device_hooked == devnum) {
998 g_print("MTP device removed!\n");
999 uevent_bus_hooked = 0;
1000 uevent_device_hooked = 0;
1009 * Monitor udev device events - we're only really interested in events
1012 gudev_client = g_udev_client_new(gudev_subsystems);
1013 uevent_id = g_signal_connect_object(gudev_client,
1015 G_CALLBACK(uevent_cb),
1018 SKETCH OF AN OVERVIEW
1019 ---------------------
1021 Draft agenda for a talk on MTP devices submitted for the Android
1022 builders summit, might come to recycle this:
1025 - Transactional filesystem - no corruption due to unplugged cables!
1026 - The host and the device can access the files simultaneously, the
1027 device will always "own" the physical file system and proxy the
1028 host (MTP initiator).
1030 - relation to libgphoto2
1031 - User expectations fall short:
1032 - Not really a mountable filesystem.
1033 - Streaming does not work. (Size needs to be known beforehand due to
1034 transactional nature.)
1035 - GVFS MTP backend to the rescue.
1037 - Using the same VID/PID for several modes, some of which are not MTP.
1038 HTC Zopo, HD2, Bird (0x0bb4/0x0c02). Thanks for that, now we cannot
1039 detect the protocol from just VID+PID but have to examine the interfaces.
1041 - Samsungs special Android MTP stack
1042 - SonyEricsson Aricent stack for Xperia Androids pre 4.0, broken headers!
1043 - Flat access model vs hierarchical, how Android uses MTP as an hierachical
1044 file system while it was previously a flat database.
1045 - Old paradigm: scan the entire non-hierarchical storage for all content,
1046 build a cache to speed up the (USB 1.1!) link. Usually all files were
1047 stored in the root folder or a single folder named "/Music" or similar.
1048 - Android introduced deeply nested folder hierarchies, not seen before
1050 - Microsoft not using the complete metadata dump feature of the MTP
1051 protocol (once introduced by creative) instead they walk directories
1053 - So caching a big device will take long time and/or timeout.
1054 - Go-MTPFS (FUSE) and GVFS MTP - doing the partial directory walk rather
1055 than caching all files.
1056 - Especially Android devices nowadays assume that
1057 you want to index a folder at the time, whereas older MTP devices (such
1058 as those from Creative) would assume that you wanted to index the entire
1059 device as it was plugged in, and device firmware is now ever more tailored
1060 toward per-folder filetree walking. This makes it harder for the library
1061 to provide the right abstractions: do we provide an API for indexing the
1062 whole device which is unacceptably slow on new devices, or do we provide
1063 an API for indexing a directory at the time which will somehow work on
1064 older devices too? Shall we deprecate the older API?
1065 - Detecting from vendor extension, can fix in newer extensions!
1066 - Autoprobing on Linux
1067 - Color devices do not like autoprobing
1068 - Devices need different PIDs for every alternative interface due to
1069 the Windows USB stack.
1070 - Multimode USB - one PID for each mode due to Windows limitations not
1071 applicable to Linux, SONY devices have ~5 different PIDs for a single
1073 - Mode switch devices? Maybe we do this wrong.
1074 - MTPZ, came and went. Apparently deprecated by Microsoft with Windows