blob: f7c86be52f599c8e2928cd3d0ffbe45b43187a51 [file] [log] [blame]
Linus Walleij0dd71e92006-05-04 18:47:07 +00001Building and Installing
2-----------------------
Linus Walleij6fd2f082006-03-28 07:19:22 +00003
Linus Walleij0dd71e92006-05-04 18:47:07 +00004See the "INSTALL" file.
5
6
Linus Walleij3f7529c2010-07-24 20:33:41 +00007Initiator and Responder
8-----------------------
9
10libmtp implements an MTP initiator, which means it initiate
11MTP sessions with devices. The devices responding are known
12as MTP responders. libmtp runs on something with a USB host
13controller interface, using libusb to access the host
14controller.
15
16If you're more interested in the MTP responders, gadgets like
17MP3 players, mobile phones etc, look into MeeGo:s Buteo Sync:
18http://wiki.meego.com/Buteo - these guys are creating a fully
19open source MTP responder.
20
21
Linus Walleij0dd71e92006-05-04 18:47:07 +000022Heritage
23--------
24
25libmtp is based on several ancestors:
26
27* libptp2 by Mariusz Woloszyn was the starting point used
28 by Richard A. Low for the initial starter port. You can
29 find it at http://libptp.sourceforge.net/
30
31* libgphoto2 by Mariusz Woloszyn and Marcus Meissner was
32 used at a later stage since it was (is) more actively
33 maintained. libmtp tracks the PTP implementation in
34 libgphoto2 and considers it an upstream project. We will
35 try to submit anything generally useful back to libgphoto2
36 and not make double efforts. In practice this means we
37 use ptp.c, ptp.h and ptp-pack.c verbatim from the libgphoto2
38 source code. If you need to change things in these files,
39 make sure it is so general that libgphoto2 will want to
40 merge it to their codebase too. You find libgphoto2 as part
41 of gPhoto: http://gphoto.sourceforge.net/
42
43* libnjb was a project that Richard and Linus were working
Linus Walleijfcf88912006-06-05 13:23:33 +000044 on before libmtp. When Linus took Richards initial port
Linus Walleij0dd71e92006-05-04 18:47:07 +000045 and made an generic C API he re-used the philosophy and
46 much code from libnjb. Many of the sample programs are for
47 example taken quite literally from libnjb. You find it here:
48 http://libnjb.sourceforge.net/
49
50
Linus Walleijea7d45b2009-02-23 22:26:09 +000051Contacting and Contributing
52---------------------------
53
54See the project page at http://libmtp.sourceforge.net/
55We always need your help. There is a mailinglist and a
56bug report system there.
57
58People who want to discuss MTP devices in fora seem to
59hang out on the forums at AnythingbutiPod:
60http://www.anythingbutipod.com/forum/
61
62
Linus Walleij0dd71e92006-05-04 18:47:07 +000063Compiling programs for libmtp
64-----------------------------
65
66libmtp has support for the pkg-config script by adding a libmtp.pc
67entry in $(prefix)/lib/pkgconfig. To compile a libmtp program,
68"just" write:
69
70gcc -o foo `pkg-config --cflags --libs libmtp` foo.c
71
72This also simplifies compilation using autoconf and pkg-config: just
73write e.g.
74
75PKG_CHECK_MODULES(MTP, libmtp)
76AC_SUBST(MTP_CFLAGS)
77AC_SUBST(MTP_LIBS)
78
79To have libmtp LIBS and CFLAGS defined. Needless to say, this will
80only work if you have pkgconfig installed on your system, but most
81people have nowadays.
82
83If your library is installed in e.g. /usr/local you may have to tell
84this to pkgconfig by setting the PKG_CONFIG_PATH thus:
85
86export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
87
88
89Documentation
90-------------
91
92Read the API documentation that can be generated with doxygen.
93It will be output in doc/html if you have Doxygen properly
94installed. (It will not be created unless you have Doxygen!)
95
96For information about the Media Transfer Protocol, see:
97http://en.wikipedia.org/wiki/Media_Transfer_Protocol
98
Linus Walleij7a83e552008-07-29 21:30:43 +000099The official 1.0 specification for MTP was released by the
100USB Implementers Forum in may, 2008. Prior to this, only a
101proprietary Microsoft version was available, and quite a few
102devices out there still use some aspects of the Microsoft
103version, which deviates from the specified standard. You can
104find the official specification here:
105http://www.usb.org/developers/devclass_docs/MTP_1.0.zip
Linus Walleij0dd71e92006-05-04 18:47:07 +0000106
Linus Walleij1b91ca62008-10-17 07:07:56 +0000107
108The Examples
109------------
110
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000111In the subdirectory "examples" you find a number of
Linus Walleij1b91ca62008-10-17 07:07:56 +0000112command-line tools, illustrating the use of libmtp in very
113simple terms.
114
115Please do not complain about the usability or documentation
116of these examples, they look like they do for two reasons:
117
1181. They are examples, not tools. If they were intended for
119 day-to-day usage by commandline freaks, I would have
120 called them "tools" not "examples".
121
1222. The MTP usage paradigm is that a daemon should hook
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000123 the device upon connection, and that it should be
Linus Walleij1b91ca62008-10-17 07:07:56 +0000124 released by unplugging. GUI tools utilizing HAL (hald)
125 and D-Bus do this much better than any commandline
126 program ever can. (See below on bugs.) Specificationwise
127 this is a bug, however it is present in many, many
128 devices.
129
130That said, if you want to pick up and maintain the examples,
131please volunteer.
132
133
Linus Walleijc36e2a62011-12-29 21:31:49 +0100134FAQ: Common Problems
135--------------------
136
137Some MTP devices have strange pecularities. We try to work around
138these whenever we can, sometimes we cannot work around it or we
139cannot test your solution.
140
141* mtp-* tools doesn't work because someone else is already hogging
142 the device
143
144 This is a common problem, the most common case could be that
145 gphoto2 (which can also talk PTP/MTP) is taking over the device
146 as soon as it's plugged in. Some distributions are configured that
147 way. Counter it like this:
148
149 gvfs-mount -s gphoto2
150
151 Then re-attach the device.
152
153* Generic MTP/PTP disconnect misbehaviour: we have noticed that
154 Windows Media Player apparently never close the session to an MTP
155 device. There is a daemon in Windows that "hooks" the device
156 by opening a PTP session to any MTP device, whenever it is
157 plugged in. This daemon proxies any subsequent transactions
158 to/from the device and will never close the session, thus
159 Windows simply does not close sessions at all.
160
Linus Walleije962add2012-01-13 20:22:22 +0100161 For example this means that a device may work the first time
162 you run some command-line example like "mtp-detect" while
163 subsequent runs fail.
164
Linus Walleijc36e2a62011-12-29 21:31:49 +0100165 Typical sign of this illness: broken pipes on closing sessions,
166 on the main transfer pipes(s) or the interrupt pipe:
167
168 Closing session
169 usb_clear_halt() on INTERRUPT endpoint: Broken pipe
170 OK.
171
172 This means that device manufacturers doesn't notice any problems
173 with devices that do not correctly handle closing PTP/MTP
174 sessions, since Windows never do it. The proper way of closing
175 a session in Windows is to unplug the device, simply put.
176
177 Since libmtp actually tries to close sessions, some devices
178 may fail since the close session functionality has never been
179 properly tested, and "it works with Windows" is sort of the
180 testing criteria at some companies.
181
Linus Walleije962add2012-01-13 20:22:22 +0100182 You can get Windows-like behaviour on Linux by running a udev-aware
Linus Walleijc36e2a62011-12-29 21:31:49 +0100183 libmtp GUI client like Rhythmbox or Gnomad2, which will "hook"
184 the device when you plug it in, and "release" it if you unplug
Linus Walleije962add2012-01-13 20:22:22 +0100185 it, and you start/end you transfer sessions by plugging/unplugging
186 the USB cable.
187
188 The "Unix way" of running small programs that open the device,
189 do something, then close the device, isn't really working with
190 such devices and you cannot expect to have command line tools
191 like the mtp examples work with them. You could implement new
192 example programs that just call to a mediating daemon like the
193 Windows MTP stack does. (And change all programs using libmtp
194 directly today.)
Linus Walleijc36e2a62011-12-29 21:31:49 +0100195
196 If this bug in your device annoys you, contact your device
197 manufacturer and ask them to test their product with some libmtp
198 program.
199
200* Generic USB misbehaviour: some devices behave badly under MTP
201 and USB mass storage alike, even down to the lowest layers
202 of USB. You can always discuss such issues at the linux-usb
203 mailing list if you're using Linux:
204 http://www.linux-usb.org/mailing.html
205
206 If you have a problem specific to USB mass storage mode, there
207 is a list of strange behaving devices in the Linux kernel:
208 http://lxr.linux.no/linux/drivers/usb/storage/unusual_devs.h
209 You can discuss this too on the mentioned list, for understanding
210 the quirks, see:
211 http://www2.one-eyed-alien.net/~mdharm/linux-usb/target_offenses.txt
212
213* Generic certificate misbehaviour. All devices are actually
214 required to support a device certificate to be able to
215 encrypt Windows Media (WMA/WMV) files. However there are
216 obviously a lot of devices out there which doesn't support
217 this at all but instead crash. Typical printout:
218
219 Error 2: PTP Layer error 02ff: get_device_unicode_property(): failed
220 to get unicode property.
221
222 This should only affect "mtp-detect", there is no other
223 application currently retrieveing the certificate (not that we
224 know anyway).
225
226* Kernel bug on Linux. Linux 2.6.16 is generally speaking required
227 to use any MTP device under USB 2.0. This is because the EHCI
228 driver previously did not support zero-length writes to endpoints.
229 It should work in most cases however, or if you connect it
230 to an UHCI/OHCI port instead (yielding lower speed). But
231 please just use a recent kernel.
232
233* Zen models AVI file seeking problem: the Zens cannot parse the
234 files for the runlength metadata. Do not transfer file with e.g.
235 mtp-sendfile, use mtp-sendtr and set the length of the track to
236 the apropriate number of seconds and it will work. In graphical
237 clients, use a "track transfer" function to send these AVI files,
238 the Zens need the metadata associated with tracks to play back
239 movies properly. Movies are considered "tracks" in the MTP world.
240
241* Some devices that disregard the metadata sent with the MTP
242 commands will parse the files for e.g. ID3 metadata. Some still
243 of these devices expect only ID3v2.3 metadata and will fail with
244 a modern ID3v2,4 tag writer, like many of those found in Linux
245 applications. Windows Media Player use ID3v2.3 only, so many
246 manufacturers only test this version.
247
248* The Zen Vision:M (possibly more Creative Zens) has a firmware bug
249 that makes it drop the last two characters off a playlist name.
250 It is fixed in later firmware.
251
252* For Creative Technology devices, there are hard limits on how
253 many files can be put onto the device. For a 30 GiB device (like
254 the Zen Xtra) the limit is 6000, for a 60 GiB device the limit
255 is 15000 files. For further Creative pecularities, see the
256 FAQ sections at www.nomadness.net.
257
258* Sandisk sansa c150 and probably several other Sandisk devices
259 (and possibly devices from other manufacturers) have a dual
260 mode with MTP and USB mass storage. The device will initially
261 claim to be mass storage so udev will capture is and make the
262 use of MTP mode impossible. One way of avoiding it could be to
263 be to blacklist the "usb-storage" module in
264 /etc/modprobe.c/blacklist with a row like this:
265 "blacklist usb-storage". Some have even removed the
266 "usb-storage.ko" (kernel module file) to avoid loading.
267
268* Sandisk Sansa Fuze has three modes: auto, MTP or mass storage
269 (MSC). Please set it to MTP to avoid problems with libmtp.
270
271* The iriver devices (possibly all of them) cannot handle the
272 enhanced GetObjectPropList MTP command (0x9805) properly. So
273 they have been banned from using it.
274
275* iriver devices have problems with older versions of libmtp and
276 with new devices libmtp does not know of as of yet, since it
277 has an oldstyle USB device controller that cannot handle zero
278 writes. (Register your device with us!) All their devices are
279 likely to need a special device flag in the src/libusb-glue.c
280 database.
281
282* The Samsung Yepp T9 has several strange characteristics, some
283 that we've managed to work around. (For example it will return
284 multiple PTP packages in a single transaction.)
285
286* The early firmware for Philips HDD players is known to be
287 problematic. Please upgrade to as new firmware as you can get.
288 (Yes this requires some kind of Windows Installation I think.)
289
290* Philips HDD 1630/16 or 1630/17 etc may lock themselves up,
291 turning inresponsive due to internal corruption. This typically
292 gives an error in opening the PTP session. Apparently you can
293 do a "repair" with the firmware utility (Windows only) which
294 will often fix this problem and make the device responsive
295 again.
296
297* Some devices that implement GetObjectPropList (0x9805) will
298 not return the entire object list if you request a list for object
299 0xffffffffu. (But they should.) So they may need the special
300 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL.
301
302* Some (smaller) subset of devices cannot even get all the
303 properties for a single object in one go, these need the
304 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST. Currently only the
305 iriver devices seem to have this bug.
306
307* The Toshiba Gigabeat S (and probably its sibling the
308 Microsoft Zune and other Toshiba devices) will only display
309 album information tags for a song in case there is also
310 an abstract album (created with the album interface) with
311 the exact same name.
312
313* The Zen Vision:M has an older firmware which is very corrupt,
314 it is incompatible with the Linux USB stack altogether. The
315 kernel dmesg will look something like this, and you have to
316 upgrade the firmware using Windows:
317 usb 4-5: new high speed USB device using ehci_hcd and address 5
318 usb 4-5: configuration #1 chosen from 1 choice
319 usb 4-5: can't set config #1, error -110
320
321* The Sirus Stiletto does not seem to allow you to copy any files
322 off the device. This may be someone's idea of copy protection.
323
324* The Samsung P2 assigns parent folder ID 0 to all unknown file
325 types.(i.e. moves them to the root folder)
326
327* The Sandisk Sansa Clip+ needs a firmware upgrade in earlier
328 versions in order to work properly.
329
330
Linus Walleija1b66f22007-05-10 20:02:16 +0000331New Devices
332-----------
333
Linus Walleijfcf88912006-06-05 13:23:33 +0000334If you happen upon a device which libmtp claims it cannot
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000335autodetect, please submit the vendor ID and device ID
Linus Walleij9ee29402007-10-31 20:24:48 +0000336(these can be obtained from the "lsusb" and "lsusb -n"
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000337commands run as root) as a bug, patch or feature request
338on the Sourceforge bug tracker at our homepage. If it
339gives a sensible output from "mtp-detect" then please attach
340the result as well as it teach us some stuff about your
341device. If you've done some additional hacking, join our
Linus Walleij9ee29402007-10-31 20:24:48 +0000342mailinglist and post your experiences there.
Linus Walleijda558be2007-03-10 21:42:25 +0000343
Linus Walleija1b66f22007-05-10 20:02:16 +0000344If you want to be able to hack some more and you're not
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000345afraid of C hacking, add an entry for your device's
346vendor/product ID and a descriptive string to the database
Linus Walleij6dc01682007-11-15 21:23:46 +0000347in the file src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +0000348
349If you want to poke around to see if your device has some
350special pecularities, you can test some special device
Linus Walleij6dc01682007-11-15 21:23:46 +0000351flags (defined in src/device-flags.h) by inserting them
352together with your device entry in src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +0000353Flags can be tested in isolation or catenated with "|"
354(binary OR). If relatives to your device use a certain
355flag, chances are high that a new device will need it
356too, typically from the same manufacturer.
357
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000358The most common flag that needs to be set is the
Linus Walleija1b66f22007-05-10 20:02:16 +0000359DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel
360drivers that may have attached to the device making
Linus Walleij94f23d52007-08-04 19:37:28 +0000361MTP access impossible. This is however not expected to
362really work: this is a problem being tracked as of
363now (2007-08-04). See the "last resort" solutions below
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000364if you really need to get your dual-mode device to work
Linus Walleij94f23d52007-08-04 19:37:28 +0000365with MTP.
Linus Walleija1b66f22007-05-10 20:02:16 +0000366
Linus Walleijcc2cf972007-11-22 20:23:43 +0000367Another flag which is easy to identify is the
368DEVICE_FLAG_NO_ZERO_READS, which remedies connection
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000369timeouts when getting files, and some timeouts on e.g.
Linus Walleijcc2cf972007-11-22 20:23:43 +0000370successive "mtp-connect" calls.
371
Linus Walleija1b66f22007-05-10 20:02:16 +0000372If your device is very problematic we are curious of how it
Linus Walleijda558be2007-03-10 21:42:25 +0000373works under Windows, so we enjoy reading USB packet sniffs
374that reveal the low-level traffic carried out between
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000375Windows Media Player and your device. This can be done
Linus Walleij61c25682007-09-04 14:46:21 +0000376using e.g.:
377
378* USBsnoop:
379 http://benoit.papillault.free.fr/usbsnoop/
380
381* The trial version of HHD Softwares software-only
382 USB monitor. You need to get a copy of version 2.37 since
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000383 the newer trial versions won't let you carry out the
Linus Walleij61c25682007-09-04 14:46:21 +0000384 needed packet sniffs. (As of 2007-03-10 a copy can be found
385 at: http://www.cobbleware.com/files/usb-monitor-237.exe)
386
Linus Walleijda558be2007-03-10 21:42:25 +0000387There are other USB monitors as well, some more expensive
388alternatives use hardware and even measure electronic
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000389characteristics of the traffic (which is far too much
Linus Walleijda558be2007-03-10 21:42:25 +0000390detail for us).
391
Linus Walleij91fb0282007-09-03 21:16:08 +0000392Device sniffs are an easy read since the PTP/MTP protocol
393is nicely structured. All commands will have a structure such
394as this in the log, we examplify with a object list request:
395
396PTP REQEUST:
397000120: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:25.9843750 +0.0
398Pipe Handle: 0x863ce234 (Endpoint Address: 0x2)
399Send 0x20 bytes to the device:
400 20 00 00 00 01 00 05 98 23 00 00 00 27 03 00 10 ......?#...'...
401 Length TYPE CMD Trans# Param1
402
403 00 00 00 00 02 DC 00 00 00 00 00 00 00 00 00 00 .....Ü..........
404 Param2 Param3 Param4 Param5
405
406[OPTIONAL] DATA PHASE:
407000121: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0156250
408Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
409Get 0x1a bytes from the device:
410 1A 00 00 00 02 00 05 98 23 00 00 00 01 00 00 00 .......?#.......
411 Length TYPE CMD Trans# DATA
412
413 27 03 00 10 02 DC 04 00 00 30 '....Ü...0
414
415RESPONSE:
416000122: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0
417Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
418Get 0xc bytes from the device:
419 0C 00 00 00 03 00 01 20 23 00 00 00 ....... #...
420 Length TYPE CODE Trans#
421
422* One send (OUT to the device), two reads (IN from the device).
423
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000424* All three byte chunks commands are
425 sent/recieved/recieeved by the function ptp_transaction()
Linus Walleij91fb0282007-09-03 21:16:08 +0000426 in the file ptp.c.
427
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000428* It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata()
429 or ptp_usb_getdata() and finally ptp_usb_getresp() in the file
Linus Walleij91fb0282007-09-03 21:16:08 +0000430 libusb-glue.c. Notice ptp_usb_sendreq() and ptp_usb_getresp()
431 are ALWAYS called. The TYPE field correspond to this, so the
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000432 TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002),
Linus Walleij91fb0282007-09-03 21:16:08 +0000433 and "RESPONSE" (0x0003).
434
435* Notice that the byte order is little endian, so you need to read
436 each field from right to left.
437
438* This COMMAND has:
439 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
440 Transaction# 0x00000023.
441 REQUEST parameters 0x10000327, 0x00000000, 0x0000DC02, 0x00000000
442 0x00000000, in this case it means "get props for object 0x10000327",
443 "any format", "property 0xDC02" (PTP_OPC_ObjectFormat), then two
444 parameters that are always zero (no idea what they mean or their
445 use).
446
447* The DATA has:
448 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
449 Transaction# 0x00000023.
450 Then comes data 0x00000001, 0x10000327, 0xDC02, 0x0004, 0x3000
451 Which means in this case, (and this is the tricky part) "here
452 you have 1 property", "for object 0x10000327", "it is property
453 0xDC02" (PTP_OPC_ObjectFormat), "which is of type 0x0004"
454 (PTP_DTC_UINT16), "and set to 0x3000" (PTP_OFC_Undefined, it
455 is perfectly valid to have undefined object formats, since it
456 is a legal value defining this).
457
458* This RESPONSE has:
459 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
460 Return Code ("RC") = 0x2001, PTP_RC_OK, all went fine.
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000461 Transaction# 0x00000023.
Linus Walleijfcf88912006-06-05 13:23:33 +0000462
Linus Walleijd05fce62007-09-29 20:17:23 +0000463If you want to compare the Windows behaviour with a similar
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000464operation using libmtp you can go into the src/libusb-glue.c
Linus Walleij6dc01682007-11-15 21:23:46 +0000465file and uncomment the row that reads:
Linus Walleijd05fce62007-09-29 20:17:23 +0000466
467//#define ENABLE_USB_BULK_DEBUG
468
469(I.e. remove the two //.)
470
471This will make libmtp print out a hex dump of every bulk USB
472transaction. The bulk transactions contain all the PTP/MTP layer
473data, which is usually where the problems appear.
474
Linus Walleij6fd2f082006-03-28 07:19:22 +0000475
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200476Notes to assist with debugging new devices:
477-------------------------------------------
478
Linus Walleijc36e2a62011-12-29 21:31:49 +0100479In debugging new hardware, we highly recommend that you only
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200480use the example mtp-* applications that come with libmtp, as other
481applications may have their own bugs that may interfere with your
482new device working correctly. Using another application instead of
483those that come with libmtp just adds another point of failure.
484
485For debugging, there are 3 main options:
486
Linus Walleijc36e2a62011-12-29 21:31:49 +01004871. Use the env variable: LIBMTP_DEBUG to increase the
488verboseness of the debugging output for any application using
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200489libmtp. Relevant codes are:
490* 0x00 [0000 0000] : no debug (default)
491* 0x01 [0000 0001] : PTP debug
492* 0x02 [0000 0010] : Playlist debug
493* 0x04 [0000 0100] : USB debug
494* 0x08 [0000 1000] : USB data debug
495// Codes are hex and binary respectively. Simple add them togther
496// to get your desired level of output.
497
498(Assuming bash)
Linus Walleijc36e2a62011-12-29 21:31:49 +0100499eg:
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200500$ export LIBMTP_DEBUG=12
501$ mtp-detect
502 // To get USB debug and USB data debug information.
503
504$ export LIBMTP_DEBUG=2
505$ mtp-detect
506 // To get Playlist debug information.
Linus Walleijc36e2a62011-12-29 21:31:49 +0100507
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200508Also note, an application may also use the LIBMTP_debug() API
509function to achieve the same options as listed above.
510
Linus Walleijc36e2a62011-12-29 21:31:49 +01005112. Use "strace" on the various mtp-* commands to see where/what
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200512is falling over or getting stuck at.
513* On Solaris and FreeBSD, use "truss" or "dtrace" instead on "strace".
514* On Mac OS X, use "ktrace" or "dtrace" instead of "strace".
515* On OpenBSD and NetBSD, use "ktrace" instead of "strace".
516
517This will at least help pinpoint where the application is failing, or
Linus Walleijc36e2a62011-12-29 21:31:49 +0100518a device is reporting incorrect information. (This is extremely helpful
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200519with devices that have odd disconnection requirements).
520
Linus Walleijc36e2a62011-12-29 21:31:49 +0100521The use of these tools may also pinpoint issues with libusb as
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200522implemented by each OS vendor or issues with the MTP implementation
523on the new device as well, so please be prepared for either case.
524
5253. Use "gdb" or similar debugger to step through the code as it is
526run. This is time consuming, and not needed just to pinpoint where
Linus Walleijc36e2a62011-12-29 21:31:49 +0100527the fault is.
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200528
Linus Walleijc36e2a62011-12-29 21:31:49 +0100529The use of gdb or another debugger may also miss or actually cause
530command and data timing issues with some devices, leading to false
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200531information. So please consider this a last resort option.
532
533Also please read the "It's Not Our Bug!" section below, as it does
534contain some useful information that may assist with your device.
535
536
Linus Walleij8d799eb2009-07-23 22:58:06 +0000537Dual-mode devices does not work - last resort:
538----------------------------------------------
Linus Walleijbd7624c2007-05-28 10:48:54 +0000539
540Some devices that are dual-mode are simply impossible to get
541to work under Linux because the usb-storage(.ko) kernel
542module hook them first, and refuse to release them, even
Linus Walleij94f23d52007-08-04 19:37:28 +0000543when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe
544it DOES release it but the device will immediately be probed
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000545at the USB mass storage interface AGAIN because it
Linus Walleij94f23d52007-08-04 19:37:28 +0000546enumerates.)
Linus Walleijbd7624c2007-05-28 10:48:54 +0000547
Linus Walleij8d799eb2009-07-23 22:58:06 +0000548Here is what some people do:
549
550 1. Plug in the device.
551 2. USB-mass storage folder will open automatically.
552 3. Unmount the device.
553 4. Run mtp-detect. It will most likely fail the first time.
554 5. Run mtp-detect again, it might work this time, or fail. Keep running
555 till it works. 99% it works by the third try.
556 6. Once mtp-detect gives you an "Ok", open either Rhythmbox or Gnomad2,
557 everything should work.
558
Linus Walleije20abaf2007-12-10 11:20:34 +0000559Linux: Try this, if you have a recent 2.6.x Linux kernel,
Linus Walleij584eb8d2007-09-05 19:51:27 +0000560run (as root) something like:
561
562> rmmod usb_storage ; mtp-detect
563
564You can run most any command or a client like gnomad2 or
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000565Amarok immediately after the rmmod command. This works
Linus Walleij584eb8d2007-09-05 19:51:27 +0000566sometimes. Another way:
Linus Walleijbd7624c2007-05-28 10:48:54 +0000567
Linus Walleij94f23d52007-08-04 19:37:28 +0000568* Edit /etc/modprobe.d/blacklist
Linus Walleijbd7624c2007-05-28 10:48:54 +0000569
570* Add the line "blacklist usb-storage"
571
572* Reboot.
573
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000574Now none of you USB disks, flash memory sticks etc will be
Linus Walleijbd7624c2007-05-28 10:48:54 +0000575working (you just disabled them all). However you *can* try
576your device, and it might have started working because there
577is no longer a USB mass storage driver that tries to hook onto
578the mass storage interface of your device.
579
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000580If not even blacklisting works (check with
Linus Walleij94f23d52007-08-04 19:37:28 +0000581"lsmod | grep usb-storage"), there is some problem with
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000582something else and you may need to remove or rename the file
Linus Walleij94f23d52007-08-04 19:37:28 +0000583/lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko
584manually.
585
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000586If you find the PerfectSolution(TM) to this dilemma, so you
Linus Walleijbd7624c2007-05-28 10:48:54 +0000587can properly switch for individual devices whether to use it
588as USB mass storage or not, please tell us how you did it. We
589know we cannot use udev, because udev is called after-the-fact:
590the device is already configured for USB mass storage when
591udev is called.
592
Linus Walleije20abaf2007-12-10 11:20:34 +0000593On Mac OS there is another ugly hack:
594
5951. Open up a terminal window
5962. Type:
597sudo mv /System/Library/Extensions/IOUSBMassStorageClass.kext
598/System/Library/Extensions/IOUSBMassStorageClass.kext.disabled
599
600and when prompted enter your password.
601
6023. Restart.
603
604To reverse this change, just reverse the filenames:
605
606sudo mv /System/Library/Extensions/
607IOUSBMassStorageClass.kext.disabled /System/Library/Extensions/
608IOUSBMassStorageClass.kext
609
610and restart.
611
Linus Walleijbd7624c2007-05-28 10:48:54 +0000612
Linus Walleij15def332006-09-19 14:27:02 +0000613Calendar and contact support:
614-----------------------------
Linus Walleijd3bdf762006-02-20 22:21:56 +0000615
Linus Walleij3c16fe42006-04-30 07:53:41 +0000616The Creative Zen series can read VCALENDAR2 (.ics) files
Linus Walleij15def332006-09-19 14:27:02 +0000617and VCard (.vcf) files from programs like for example
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000618Evolution with the following limitations/conditions:
Linus Walleijd3bdf762006-02-20 22:21:56 +0000619
Linus Walleij3c16fe42006-04-30 07:53:41 +0000620- The file must be in DOS (CR/LF) format, use the unix2dos
621 program to convert if needed
Linus Walleij15def332006-09-19 14:27:02 +0000622
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000623- Repeat events in calendar files do not seem to be supported,
Linus Walleij15def332006-09-19 14:27:02 +0000624 entries will only appear once.
625
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000626- Calendar (.ics) files should be stored in the folder "My Organizer"
Linus Walleij15def332006-09-19 14:27:02 +0000627 when sent to the device (this directory should be autodetected
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000628 for use with calendar files, otherwise use the option
Linus Walleij15def332006-09-19 14:27:02 +0000629 -f "My Organizer" to sendfile for this) Apparently this file can
630 also contain tasklists.
631
632- Contact (.vcf) files should be stored in the folder "My Contacts"
633 when sent to the device. (-f "My Contacts")
634
635- Some devices are picky about the name of the calendar and
636 contact files. For example the Zen Microphoto wants:
637
Linus Walleijb1318d12006-09-25 14:59:26 +0000638 Calendar: My Organizer/6651416.ics
639 Contacts: My Organizer/6651416.vcf
640
641
642Syncing in with Evolution and Creative Devices
643----------------------------------------------
644
645Evolution can easily export .ics an .vcf files, but you currently
646need some command-line hacking to get you stuff copied over in
647one direction host -> device. The examples/ directory contains a script
648created for the Creative Zen Microphoto by Nicolas Tetreault.
649
Linus Walleij6e8cef42006-12-03 20:45:04 +0000650
Linus Walleijd132d8e2007-04-03 23:24:54 +0000651Lost symbols
652------------
653
654Shared libraries can be troublesome to users not experienced with
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000655them. The following is a condensed version of a generic question
Linus Walleijd132d8e2007-04-03 23:24:54 +0000656that has appeared on the libmtp mailing list from time to time.
657
658> PTP: Opening session
659> Queried Creative Zen Vision:M
660> gnomad2: relocation error: gnomad2: undefined symbol:
661> LIBMTP_Get_Storageinfo
662> (...)
663> Are these type of errors related to libmtp or something else?
664
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000665The problem is of a generic nature, and related to dynamic library
Linus Walleijd132d8e2007-04-03 23:24:54 +0000666loading. It is colloquially known as "dependency hell".
667(http://en.wikipedia.org/wiki/Dependency_hell)
668
669The gnomad2 application calls upon the dynamic linker in Linux to
670resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol
671(ELF symbol, or link point or whatever you want to call them, a
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000672symbol is a label on a memory address that the linker shall
Linus Walleijd132d8e2007-04-03 23:24:54 +0000673resolve from label to actual address.)
674For generic information on this subject see the INSTALL file and
675this Wikipedia page:
676
677http://en.wikipedia.org/wiki/Library_(computing)
678
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000679When Linux /lib/ld-linux.so.X is called to link the symbols compiled
680into gnomad2 (or any other executable using libmtp), it examines the
681ELF file for the libmtp.so.X file it finds first and cannot resolve
Linus Walleijd132d8e2007-04-03 23:24:54 +0000682the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000683problem witj) from it, since it's probably not there. There are many
Linus Walleijd132d8e2007-04-03 23:24:54 +0000684possible causes of this symbol breakage:
685
6861) You installed precompiled libmtp and gnomad2 packages (RPMs, debs
687 whatever) that do not match up. Typical cause: your gnomad2 package was
688 built against a newer version of libmtp than what's installed on your
689 machine. Another typical cause: you installed a package you found on
690 the web, somewhere, the dependency resolution system did not protest
691 properly (as it should) or you forced it to install anyway, ignoring
692 some warnings.
693
6942) You compiled libmtp and/or gnomad2 from source, installing both or
695 either in /usr/local/lib and /usr/local/bin. This means at compile-time
696 gnomad2 finds the libmtp library in /usr/local/lib but at runtime, it
697 depends on the Linux system wide library loader (/lib/ld-linux.so.X) in
698 order to resolve the symbols. This loader will look into the file
699 /etc/ld.so.conf and/or the folder /etc/ld.so.conf.d in order to find
700 paths to libraries to be used for resolving the symbols. If you have
701 some older version of libmtp in e.g. /usr/lib (typically installed by a
702 package manager) it will take precedence over the new version you just
703 installed in /usr/local/lib and the newly compiled library in
704 /usr/local/lib will *not* be used, resulting in this error message.
705
7063) You really did install the very latest versions (as of writing libmtp
707 0.1.5 and gnomad2 2.8.11) from source and there really is no
708 pre-installed package of either on your machine. In that case I'm
709 totally lost, I have no idea what's causing this.
710
711Typical remedies:
712
7131) If you don't want to mess around with your system and risk these
714 situations, only use pre-packaged software that came with the
715 distribution or its official support channels. If it still breaks,
716 blame your distribution, they're not packaging correctly. Relying on
717 properly packaged software and not installing things yourself *is* the
718 Linux solution to the "dependency hell" problem.
719
7202) Read about dynamically linked library handling until the stuff I wrote
721 about in the previous list sounds like music to your ears, inspect
722 your /lib, /usr/lib, /usr/local/lib, /etc/ld.so.conf and the
723 /etc/ld.so.conf.d, remove all pre-packed versions using RPM, APT,
724 YaST or whatever your distribution uses, compile libmtp and gnomad2
725 (or whatever) from source only and you will be enlighted.
726
727I don't know if this helps you, it's the best answer we can give.
Linus Walleij387e37a2008-10-29 17:22:22 +0000728
729
730API is obscure - I want plain files!
731------------------------------------
732
733PTP/MTP devices does not actually contain "files", they contain
734objects. These objects have file names, but that is actually
735just a name tag on the object.
736
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000737Folders/directories aren't really such entities: they are just
Linus Walleij387e37a2008-10-29 17:22:22 +0000738objects too, albeit objects that can act as parent to other
Linus Walleij8aba06d2008-12-28 08:26:57 +0000739objects. They are called "associations" and are created in atomic
Linus Walleij387e37a2008-10-29 17:22:22 +0000740fashion and even though there is an MTP command to get all the
Linus Walleij8aba06d2008-12-28 08:26:57 +0000741associations of a certain association, this command is optional
742so it is perfectly possible (and most common, actually) to create
743devices where the "folders" (which are actually associations) have
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000744no idea whatsoever of what files they are associated as parents to
Linus Walleij387e37a2008-10-29 17:22:22 +0000745(i.e. which files they contain). This is very easy for device
Linus Walleij8aba06d2008-12-28 08:26:57 +0000746manufacturers to implement, all the association (i.e. finding out
747which files are in a certain folder) has to be done by the MTP
748Initiator / host computer.
Linus Walleij387e37a2008-10-29 17:22:22 +0000749
750Moving a file to a new folder is for example very simple in a
751"real" file system. In PTP/MTP devices it is often not even possible,
752some devices *may* be able to do that. But actually the only
753reliable way of doing that is to upload the file to the host,
Linus Walleij8aba06d2008-12-28 08:26:57 +0000754download it with the new parent, then delete the old file.
Linus Walleij387e37a2008-10-29 17:22:22 +0000755We have played with the idea of implementing this time consuming
756function, perhaps we will.
757
Linus Walleij8aba06d2008-12-28 08:26:57 +0000758Then the issue that in PTP/MTP it is legal for two files to have
759exactly the same path as long as their object IDs differ. A
760folder/association can contain two files with the exact same name.
761(And on the Creative devices this even works, too, though most devices
762implicitly fail at this.) Perhaps one could add some custom hook for
763handling that, so they become /Foo.mp3 and /Foo.mp3(1) or something
764similar, but it's really a bit kludgy.
765
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000766Playlists and albums aren't really files, thinking about
Linus Walleij387e37a2008-10-29 17:22:22 +0000767them as files like the hacks in libgphoto2 is really backwards. They are
768called associations and are more like a symbolic link that links in a
769star-shaped pattern to all the files that are part of the album/playlist.
770Some devices (Samsung) thought that was too complicated and have a
771different way of storing playlists in an UTF-16 encoded .spl-like file
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000772instead! This is why playlists/albums must have their own structs and
Linus Walleij387e37a2008-10-29 17:22:22 +0000773functions.
774
Linus Walleij8aba06d2008-12-28 08:26:57 +0000775Plain file access also assumes to be able to write files of an
776undetermined size, which is simply not possible in a transactional
777file system like PTP/MTP. (See further below.)
778
Linus Walleij387e37a2008-10-29 17:22:22 +0000779
780I Want Streaming!
781-----------------
782
783Streaming reads is easy. Just connect the output file descriptor from
784LIBMTP_Get_File_To_File_Descriptor() (and a similar function for tracks)
785wherever you want.
786
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000787People have connected this to TCP sockets for streaming web servers
788etc, works like a charm. Some devices will even survive if the callback
Linus Walleij387e37a2008-10-29 17:22:22 +0000789functions return non-zero and cancel the download. Some devices will
790lock up and even require a reset if you do that. Devices are poorly
791implemented so that's life. If you want to stream off a device, the
792best idea is always to stream the entire file and discard the stuff
793at the end you don't want. It will incur a delay if you e.g. want to
794skip between tracks, sadly.
795
796Then we get to the complicated things: streaming WRITES...
797
798There is a function:
799LIBMTP_Send_File_From_File_Descriptor() (and similar for tracks)
800which will write a file to a device from a file descriptor, which may
801be a socket or whatever.
802
803HOWEVER: this requires a piece of metadata with the .filesize properly
804set first.
805
806This is not because we think it is funny to require that, the protocol
807requires it. The reason is that PTP/MTP is a transactional file system
808and it wants to be able to deny file transfer if the file won't fit on
809the device, so the transaction never even starts, it's impossible to
810start a transaction without giving file length.
811
812People really want streaming so I tried a lot of hacks to see if they
813would work, such as setting file size to 0xffffffffU or something other
814unnaturally big and then aborting the file transfer when the stream ends.
815It doesn't work: either the device crashes or the file simply disappears
816since the device rolls back all failed transactions.
817
818So this is an inherent limitation of the PTP/MTP protocol.
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000819
820
Linus Walleijae890212012-02-16 01:56:19 +0100821I want to remote control my device!
822-----------------------------------
823
824I have both good and bad news for you.
825
826The good news is that the MTP protocol has well-defined commands to play
827back content on a device. Operation 0xD411 (PTP_DPC_MTP_PlaybackObject)
828will start playing back a file on the device (whatever that may mean if
829this is not a music or video file), and operation 0xD403 can set the
830playback volume to save your ears. Then there are operations to
831determine how far into the current file you currently are, so as to
832support say progress bars.
833
834Since these commands have been around since the dawn of the MTP protocol
835and since it was developed in cooperation with Creative Technology, this
836is probably a requested feature from the Creative people who already had
837support for playback on their devices using the PDE protocol back then.
838
839Anyway, here are the bad news:
840[logs]$ grep d411 *
841mtp-detect-trekstor-vibez.txt: 0xd411: Playback Object
842
843Aha there is only one known device in the world which actually supports
844playback on the device. So either you go buy the Trekstor Vibez, or you
845can forget about this. You could always try asking your hardware vendor
846of choice to go implement this.
847
848Since none of the core developers of libmtp has the Trekstor device, this
849is not yet implemented in libmtp.
850
851
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000852I make MTP devices!
853-------------------
854
855If you are a device vendor there is a lot you can do for libmtp:
856
857* Please consider assigning one of your employees as a contact person
858 for libmtp, have them sign up to the libmtp development list and answer
859 questions and post new device ID:s as they are released to our
860 mailing list.
861
862* If you want to help even more, assign someone to look deeper into
863 error reports on your specific devices, understand why your firmware
864 may require some special device flags and what can be done about it.
865
866* Do you have spare devices you can give us? Send them to Richard (Mac
867 support) or Linus (Linux support). (So far nobody did that except for
868 Microsoft who sent us a Zune by proxy!)
869
870Vendors do need help from libmtp too, especially we want to help
871vendors improve their MTP stacks, because they all suffer from the
872same problem: the lack of a proper conformance test has made many devices
873incompliant with the MTP specification as it is published today: most
874devices are just compliant with the Windows MTP stack, and don't work
875out-of-the-box with libmtp. We need someone on the inside to help in
876bug reporting vendors MTP stacks internally so these issues are raised.
877A good way to go toward better MTP compliance is to test with an
878alternative implementation of the stack. In e.g. IETF standardization
879it is compulsory for an RFC to have atleast two independent implementations
880for it to reach the status as standard.
881
882Being compliant with libmtp is also more and more important for
883vendors: libmtp is being deployed in some embedded systems like
884set-top-boxes etc. It will be very irritating for customers if a device
885will not dock properly with some home entertainment equipment just because
886it is based on Linux and libmtp and not the Windows MTP stack.
Linus Walleij5f5c69f2011-06-26 14:34:13 +0200887
888Autodetect with gudev
889---------------------
890
891Previously you would use HAL to detect devices being plugged in. Nowadays
892we use udev directly, or though the GNOME libgudev library. LIBMTPs
893default udev rules export the proper properties to detect any MTP device
894automatically, here is a verbose example derived from gnomad2:
895
896#define G_UDEV_API_IS_SUBJECT_TO_CHANGE
897#include <gudev/gudev.h>
898const char * const gudev_subsystems[] = { "usb", NULL };
899GUdevClient *gudev_client;
900guint uevent_id;
901guint uevent_bus_hooked = 0;
902guint uevent_device_hooked = 0;
903
904
905static void uevent_cb(GUdevClient *client, const char *action, GUdevDevice *device, void *data)
906{
907 guint64 devicenum;
908 guint vendor;
909 guint model;
910 guint busnum;
911 guint devnum;
912 guint mtpdevice;
913
914 devicenum = (guint64) g_udev_device_get_device_number(device);
915 g_print("%s event for %s (%"G_GINT64_MODIFIER"x)", action,
916 g_udev_device_get_sysfs_path (device), devicenum);
917
918 /* get device info */
919 vendor = get_property_as_int(device, "ID_VENDOR_ID", 16);
920 model = get_property_as_int(device, "ID_MODEL_ID", 16);
921 busnum = get_property_as_int(device, "BUSNUM", 10);
922 devnum = get_property_as_int(device, "DEVNUM", 10);
923 mtpdevice = get_property_as_int(device, "ID_MTP_DEVICE", 10);
924
925 if (vendor == 0 || model == 0) {
926 g_print("couldn't get vendor or model ID for device at (%x:%x)\n",
927 busnum, devnum);
928 return;
929 } else {
930 g_print("vendor = %x, model = %x, bus = %x, device = %x\n",
931 vendor, model, busnum, devnum);
932 }
933
934 if (mtpdevice) {
935 g_print("device is MTP compliant\n");
936
937 if (g_str_equal(action, "add") &&
938 uevent_bus_hooked == 0 &&
939 uevent_device_hooked == 0) {
940 g_print(MTP device plugged in!\n");
941 uevent_bus_hooked = busnum;
942 uevent_device_hooked = devnum;
943 scan_jukebox(NULL);
944 } else if (g_str_equal (action, "remove") &&
945 uevent_bus_hooked == busnum &&
946 uevent_device_hooked == devnum) {
947 g_print("MTP device removed!\n");
948 uevent_bus_hooked = 0;
949 uevent_device_hooked = 0;
950 }
951 }
952}
953
954
955
956(...)
957 /*
958 * Monitor udev device events - we're only really interested in events
959 * for USB devices.
960 */
961 gudev_client = g_udev_client_new(gudev_subsystems);
962 uevent_id = g_signal_connect_object(gudev_client,
963 "uevent",
964 G_CALLBACK(uevent_cb),
965 NULL, 0);