blob: 3dc98e4fd2ee8597d78742361ed9114c427617b5 [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
7Heritage
8--------
9
10libmtp is based on several ancestors:
11
12* libptp2 by Mariusz Woloszyn was the starting point used
13 by Richard A. Low for the initial starter port. You can
14 find it at http://libptp.sourceforge.net/
15
16* libgphoto2 by Mariusz Woloszyn and Marcus Meissner was
17 used at a later stage since it was (is) more actively
18 maintained. libmtp tracks the PTP implementation in
19 libgphoto2 and considers it an upstream project. We will
20 try to submit anything generally useful back to libgphoto2
21 and not make double efforts. In practice this means we
22 use ptp.c, ptp.h and ptp-pack.c verbatim from the libgphoto2
23 source code. If you need to change things in these files,
24 make sure it is so general that libgphoto2 will want to
25 merge it to their codebase too. You find libgphoto2 as part
26 of gPhoto: http://gphoto.sourceforge.net/
27
28* libnjb was a project that Richard and Linus were working
Linus Walleijfcf88912006-06-05 13:23:33 +000029 on before libmtp. When Linus took Richards initial port
Linus Walleij0dd71e92006-05-04 18:47:07 +000030 and made an generic C API he re-used the philosophy and
31 much code from libnjb. Many of the sample programs are for
32 example taken quite literally from libnjb. You find it here:
33 http://libnjb.sourceforge.net/
34
35
36Compiling programs for libmtp
37-----------------------------
38
39libmtp has support for the pkg-config script by adding a libmtp.pc
40entry in $(prefix)/lib/pkgconfig. To compile a libmtp program,
41"just" write:
42
43gcc -o foo `pkg-config --cflags --libs libmtp` foo.c
44
45This also simplifies compilation using autoconf and pkg-config: just
46write e.g.
47
48PKG_CHECK_MODULES(MTP, libmtp)
49AC_SUBST(MTP_CFLAGS)
50AC_SUBST(MTP_LIBS)
51
52To have libmtp LIBS and CFLAGS defined. Needless to say, this will
53only work if you have pkgconfig installed on your system, but most
54people have nowadays.
55
56If your library is installed in e.g. /usr/local you may have to tell
57this to pkgconfig by setting the PKG_CONFIG_PATH thus:
58
59export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
60
61
62Documentation
63-------------
64
65Read the API documentation that can be generated with doxygen.
66It will be output in doc/html if you have Doxygen properly
67installed. (It will not be created unless you have Doxygen!)
68
69For information about the Media Transfer Protocol, see:
70http://en.wikipedia.org/wiki/Media_Transfer_Protocol
71
72
73Contributing
74------------
75
76See the project page at http://libmtp.sourceforge.net/
Linus Walleijee73ef22006-08-27 19:56:00 +000077We always need your help. There is a mailinglist and a
78bug report system there.
Linus Walleij6fd2f082006-03-28 07:19:22 +000079
Linus Walleija1b66f22007-05-10 20:02:16 +000080
81New Devices
82-----------
83
Linus Walleijfcf88912006-06-05 13:23:33 +000084If you happen upon a device which libmtp claims it cannot
85autodetect, please submit the vendor ID and device ID
Linus Walleij9ee29402007-10-31 20:24:48 +000086(these can be obtained from the "lsusb" and "lsusb -n"
87commands run as root) as a bug, patch or feature request
88on the Sourceforge bug tracker at our homepage. If it
89gives a sensible output from "mtp-detect" then please attach
90the result as well as it teach us some stuff about your
91device. If you've done some additional hacking, join our
92mailinglist and post your experiences there.
Linus Walleijda558be2007-03-10 21:42:25 +000093
Linus Walleija1b66f22007-05-10 20:02:16 +000094If you want to be able to hack some more and you're not
95afraid of C hacking, add an entry for your device's
96vendor/product ID and a descriptive string to the database
Linus Walleij6dc01682007-11-15 21:23:46 +000097in the file src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +000098
99If you want to poke around to see if your device has some
100special pecularities, you can test some special device
Linus Walleij6dc01682007-11-15 21:23:46 +0000101flags (defined in src/device-flags.h) by inserting them
102together with your device entry in src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +0000103Flags can be tested in isolation or catenated with "|"
104(binary OR). If relatives to your device use a certain
105flag, chances are high that a new device will need it
106too, typically from the same manufacturer.
107
108The most common flag that needs to be set is the
109DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel
110drivers that may have attached to the device making
Linus Walleij94f23d52007-08-04 19:37:28 +0000111MTP access impossible. This is however not expected to
112really work: this is a problem being tracked as of
113now (2007-08-04). See the "last resort" solutions below
114if you really need to get your dual-mode device to work
115with MTP.
Linus Walleija1b66f22007-05-10 20:02:16 +0000116
Linus Walleijcc2cf972007-11-22 20:23:43 +0000117Another flag which is easy to identify is the
118DEVICE_FLAG_NO_ZERO_READS, which remedies connection
119timeouts when getting files, and some timeouts on e.g.
120successive "mtp-connect" calls.
121
Linus Walleij91fb0282007-09-03 21:16:08 +0000122If you are a device vendor, please consider assigning one
123of your employees as a contact person for libmtp, have them
124sign up to the libmtp development list and answer questions
125and post new device ID:s as they are released to our
126mailing list. By the way: do you have spare devices you
127can give us? Send them to Richard (Mac support) or Linus
128(Linux support). (So far nobody did that except for Microsoft
129who sent us a Zune by proxy!)
130
Linus Walleija1b66f22007-05-10 20:02:16 +0000131If your device is very problematic we are curious of how it
Linus Walleijda558be2007-03-10 21:42:25 +0000132works under Windows, so we enjoy reading USB packet sniffs
133that reveal the low-level traffic carried out between
134Windows Media Player and your device. This can be done
Linus Walleij61c25682007-09-04 14:46:21 +0000135using e.g.:
136
137* USBsnoop:
138 http://benoit.papillault.free.fr/usbsnoop/
139
140* The trial version of HHD Softwares software-only
141 USB monitor. You need to get a copy of version 2.37 since
142 the newer trial versions won't let you carry out the
143 needed packet sniffs. (As of 2007-03-10 a copy can be found
144 at: http://www.cobbleware.com/files/usb-monitor-237.exe)
145
Linus Walleijda558be2007-03-10 21:42:25 +0000146There are other USB monitors as well, some more expensive
147alternatives use hardware and even measure electronic
148characteristics of the traffic (which is far too much
149detail for us).
150
Linus Walleij91fb0282007-09-03 21:16:08 +0000151Device sniffs are an easy read since the PTP/MTP protocol
152is nicely structured. All commands will have a structure such
153as this in the log, we examplify with a object list request:
154
155PTP REQEUST:
156000120: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:25.9843750 +0.0
157Pipe Handle: 0x863ce234 (Endpoint Address: 0x2)
158Send 0x20 bytes to the device:
159 20 00 00 00 01 00 05 98 23 00 00 00 27 03 00 10 ......?#...'...
160 Length TYPE CMD Trans# Param1
161
162 00 00 00 00 02 DC 00 00 00 00 00 00 00 00 00 00 .....Ü..........
163 Param2 Param3 Param4 Param5
164
165[OPTIONAL] DATA PHASE:
166000121: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0156250
167Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
168Get 0x1a bytes from the device:
169 1A 00 00 00 02 00 05 98 23 00 00 00 01 00 00 00 .......?#.......
170 Length TYPE CMD Trans# DATA
171
172 27 03 00 10 02 DC 04 00 00 30 '....Ü...0
173
174RESPONSE:
175000122: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0
176Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
177Get 0xc bytes from the device:
178 0C 00 00 00 03 00 01 20 23 00 00 00 ....... #...
179 Length TYPE CODE Trans#
180
181* One send (OUT to the device), two reads (IN from the device).
182
183* All three byte chunks commands are
184 sent/recieved/recieeved by the function ptp_transaction()
185 in the file ptp.c.
186
187* It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata()
188 or ptp_usb_getdata() and finally ptp_usb_getresp() in the file
189 libusb-glue.c. Notice ptp_usb_sendreq() and ptp_usb_getresp()
190 are ALWAYS called. The TYPE field correspond to this, so the
191 TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002),
192 and "RESPONSE" (0x0003).
193
194* Notice that the byte order is little endian, so you need to read
195 each field from right to left.
196
197* This COMMAND has:
198 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
199 Transaction# 0x00000023.
200 REQUEST parameters 0x10000327, 0x00000000, 0x0000DC02, 0x00000000
201 0x00000000, in this case it means "get props for object 0x10000327",
202 "any format", "property 0xDC02" (PTP_OPC_ObjectFormat), then two
203 parameters that are always zero (no idea what they mean or their
204 use).
205
206* The DATA has:
207 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
208 Transaction# 0x00000023.
209 Then comes data 0x00000001, 0x10000327, 0xDC02, 0x0004, 0x3000
210 Which means in this case, (and this is the tricky part) "here
211 you have 1 property", "for object 0x10000327", "it is property
212 0xDC02" (PTP_OPC_ObjectFormat), "which is of type 0x0004"
213 (PTP_DTC_UINT16), "and set to 0x3000" (PTP_OFC_Undefined, it
214 is perfectly valid to have undefined object formats, since it
215 is a legal value defining this).
216
217* This RESPONSE has:
218 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
219 Return Code ("RC") = 0x2001, PTP_RC_OK, all went fine.
220 Transaction# 0x00000023.
Linus Walleijfcf88912006-06-05 13:23:33 +0000221
Linus Walleijd05fce62007-09-29 20:17:23 +0000222If you want to compare the Windows behaviour with a similar
Linus Walleij6dc01682007-11-15 21:23:46 +0000223operation using libmtp you can go into the src/libusb-glue.c
224file and uncomment the row that reads:
Linus Walleijd05fce62007-09-29 20:17:23 +0000225
226//#define ENABLE_USB_BULK_DEBUG
227
228(I.e. remove the two //.)
229
230This will make libmtp print out a hex dump of every bulk USB
231transaction. The bulk transactions contain all the PTP/MTP layer
232data, which is usually where the problems appear.
233
Linus Walleij6fd2f082006-03-28 07:19:22 +0000234
Linus Walleijbd7624c2007-05-28 10:48:54 +0000235Devices does not work - last resort:
236------------------------------------
237
238Some devices that are dual-mode are simply impossible to get
239to work under Linux because the usb-storage(.ko) kernel
240module hook them first, and refuse to release them, even
Linus Walleij94f23d52007-08-04 19:37:28 +0000241when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe
242it DOES release it but the device will immediately be probed
243at the USB mass storage interface AGAIN because it
244enumerates.)
Linus Walleijbd7624c2007-05-28 10:48:54 +0000245
Linus Walleije20abaf2007-12-10 11:20:34 +0000246Linux: Try this, if you have a recent 2.6.x Linux kernel,
Linus Walleij584eb8d2007-09-05 19:51:27 +0000247run (as root) something like:
248
249> rmmod usb_storage ; mtp-detect
250
251You can run most any command or a client like gnomad2 or
252Amarok immediately after the rmmod command. This works
253sometimes. Another way:
Linus Walleijbd7624c2007-05-28 10:48:54 +0000254
Linus Walleij94f23d52007-08-04 19:37:28 +0000255* Edit /etc/modprobe.d/blacklist
Linus Walleijbd7624c2007-05-28 10:48:54 +0000256
257* Add the line "blacklist usb-storage"
258
259* Reboot.
260
261Now none of you USB disks, flash memory sticks etc will be
262working (you just disabled them all). However you *can* try
263your device, and it might have started working because there
264is no longer a USB mass storage driver that tries to hook onto
265the mass storage interface of your device.
266
Linus Walleij94f23d52007-08-04 19:37:28 +0000267If not even blacklisting works (check with
268"lsmod | grep usb-storage"), there is some problem with
269something else and you may need to remove or rename the file
270/lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko
271manually.
272
Linus Walleijbd7624c2007-05-28 10:48:54 +0000273If you find the PerfectSolution(TM) to this dilemma, so you
274can properly switch for individual devices whether to use it
275as USB mass storage or not, please tell us how you did it. We
276know we cannot use udev, because udev is called after-the-fact:
277the device is already configured for USB mass storage when
278udev is called.
279
Linus Walleije20abaf2007-12-10 11:20:34 +0000280On Mac OS there is another ugly hack:
281
2821. Open up a terminal window
2832. Type:
284sudo mv /System/Library/Extensions/IOUSBMassStorageClass.kext
285/System/Library/Extensions/IOUSBMassStorageClass.kext.disabled
286
287and when prompted enter your password.
288
2893. Restart.
290
291To reverse this change, just reverse the filenames:
292
293sudo mv /System/Library/Extensions/
294IOUSBMassStorageClass.kext.disabled /System/Library/Extensions/
295IOUSBMassStorageClass.kext
296
297and restart.
298
Linus Walleijbd7624c2007-05-28 10:48:54 +0000299
Linus Walleij15def332006-09-19 14:27:02 +0000300Calendar and contact support:
301-----------------------------
Linus Walleijd3bdf762006-02-20 22:21:56 +0000302
Linus Walleij3c16fe42006-04-30 07:53:41 +0000303The Creative Zen series can read VCALENDAR2 (.ics) files
Linus Walleij15def332006-09-19 14:27:02 +0000304and VCard (.vcf) files from programs like for example
305Evolution with the following limitations/conditions:
Linus Walleijd3bdf762006-02-20 22:21:56 +0000306
Linus Walleij3c16fe42006-04-30 07:53:41 +0000307- The file must be in DOS (CR/LF) format, use the unix2dos
308 program to convert if needed
Linus Walleij15def332006-09-19 14:27:02 +0000309
310- Repeat events in calendar files do not seem to be supported,
311 entries will only appear once.
312
313- Calendar (.ics) files should be stored in the folder "My Organizer"
314 when sent to the device (this directory should be autodetected
Linus Walleij80b2c722006-06-22 17:57:17 +0000315 for use with calendar files, otherwise use the option
Linus Walleij15def332006-09-19 14:27:02 +0000316 -f "My Organizer" to sendfile for this) Apparently this file can
317 also contain tasklists.
318
319- Contact (.vcf) files should be stored in the folder "My Contacts"
320 when sent to the device. (-f "My Contacts")
321
322- Some devices are picky about the name of the calendar and
323 contact files. For example the Zen Microphoto wants:
324
Linus Walleijb1318d12006-09-25 14:59:26 +0000325 Calendar: My Organizer/6651416.ics
326 Contacts: My Organizer/6651416.vcf
327
328
329Syncing in with Evolution and Creative Devices
330----------------------------------------------
331
332Evolution can easily export .ics an .vcf files, but you currently
333need some command-line hacking to get you stuff copied over in
334one direction host -> device. The examples/ directory contains a script
335created for the Creative Zen Microphoto by Nicolas Tetreault.
336
Linus Walleij6e8cef42006-12-03 20:45:04 +0000337
338It's Not Our Bug!
339-----------------
340
341Some MTP devices have strange pecularities. We try to work around
342these whenever we can, sometimes we cannot work around it or we
343cannot test your solution.
344
345* The Zen Vision:M (possibly more Creative Zens) has a firmware bug
346 that makes it drop the last two characters off a playlist name.
347 It is fixed in later firmware.
348
Linus Walleijc41f2e82007-03-12 22:26:00 +0000349* For Creative Technology devices, there are hard limits on how
350 many files can be put onto the device. For a 30 GiB device (like
351 the Zen Xtra) the limit is 6000, for a 60 GiB device the limit
352 is 15000 files. For further Creative pecularities, see the
353 FAQ sections at www.nomadness.net.
354
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000355* Sandisk sansa c150 and probably several other Sandisk devices
356 (and possibly devices from other manufacturers) have a dual
357 mode with MTP and USB mass storage. The device will initially
358 claim to be mass storage so udev will capture is and make the
Linus Walleijda558be2007-03-10 21:42:25 +0000359 use of MTP mode impossible. One way of avoiding it could be to
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000360 be to blacklist the "usb-storage" module in
361 /etc/modprobe.c/blacklist with a row like this:
Linus Walleijda558be2007-03-10 21:42:25 +0000362 "blacklist usb-storage". Some have even removed the
363 "usb-storage.ko" (kernel module file) to avoid loading.
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000364
Linus Walleijda558be2007-03-10 21:42:25 +0000365* The iriver devices (possibly all of them) cannot handle the
Linus Walleij6e8cef42006-12-03 20:45:04 +0000366 enhanced GetObjectPropList MTP command (0x9805) properly. So
367 they have been banned from using it.
368
Linus Walleijda558be2007-03-10 21:42:25 +0000369* iriver devices have problems with older versions of libmtp and
Linus Walleij82265222007-03-04 19:47:08 +0000370 with new devices libmtp does not know of as of yet, since it
371 has an oldstyle USB device controller that cannot handle zero
Linus Walleijda558be2007-03-10 21:42:25 +0000372 writes. (Register your device with us!) All their devices are
373 likely to need a special device flag in the src/libusb-glue.c
374 database.
Linus Walleij82265222007-03-04 19:47:08 +0000375
Linus Walleij6e8cef42006-12-03 20:45:04 +0000376* The Samsung Yepp T9 has several strange characteristics, some
377 that we've managed to work around. (For example it will return
378 multiple PTP packages in a single transaction.)
379
Linus Walleijf2711b32007-02-26 20:18:40 +0000380* The early firmware for Philips HDD players is known to be
381 problematic. Please upgrade to as new firmware as you can get.
382 (Yes this requires some kind of Windows Installation I think.)
383
Linus Walleij9340aac2007-10-01 10:02:05 +0000384* Some devices that implement GetObjectPropList (0x9805) will
385 not return the entire object list if you request a list for object
386 0xffffffffu. (But they should.) So they may need the special
387 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL.
388
389* Some (smaller) subset of devices cannot even get all the
390 properties for a single object in one go, these need the
391 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST. Currently only the
392 iriver devices seem to have this bug.
393
394* The Toshiba Gigabeat S (and probably its sibling the
395 Microsoft Zune and other Toshiba devices) will only display
396 album information tags for a song in case there is also
397 an abstract album (created with the album interface) with
398 the exact same name.
Linus Walleijd132d8e2007-04-03 23:24:54 +0000399
Linus Walleij265b9d62007-11-25 20:08:15 +0000400* The Zen Vision:M has an older firmware which is very corrupt,
401 it is incompatible with the Linux USB stack altogether. The
402 kernel dmesg will look something like this, and you have to
403 upgrade the firmware using Windows:
404 usb 4-5: new high speed USB device using ehci_hcd and address 5
405 usb 4-5: configuration #1 chosen from 1 choice
406 usb 4-5: can't set config #1, error -110
Linus Walleijd132d8e2007-04-03 23:24:54 +0000407
408Lost symbols
409------------
410
411Shared libraries can be troublesome to users not experienced with
412them. The following is a condensed version of a generic question
413that has appeared on the libmtp mailing list from time to time.
414
415> PTP: Opening session
416> Queried Creative Zen Vision:M
417> gnomad2: relocation error: gnomad2: undefined symbol:
418> LIBMTP_Get_Storageinfo
419> (...)
420> Are these type of errors related to libmtp or something else?
421
422The problem is of a generic nature, and related to dynamic library
423loading. It is colloquially known as "dependency hell".
424(http://en.wikipedia.org/wiki/Dependency_hell)
425
426The gnomad2 application calls upon the dynamic linker in Linux to
427resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol
428(ELF symbol, or link point or whatever you want to call them, a
429symbol is a label on a memory address that the linker shall
430resolve from label to actual address.)
431For generic information on this subject see the INSTALL file and
432this Wikipedia page:
433
434http://en.wikipedia.org/wiki/Library_(computing)
435
436When Linux /lib/ld-linux.so.X is called to link the symbols compiled
437into gnomad2 (or any other executable using libmtp), it examines the
438ELF file for the libmtp.so.X file it finds first and cannot resolve
439the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a
440problem witj) from it, since it's probably not there. There are many
441possible causes of this symbol breakage:
442
4431) You installed precompiled libmtp and gnomad2 packages (RPMs, debs
444 whatever) that do not match up. Typical cause: your gnomad2 package was
445 built against a newer version of libmtp than what's installed on your
446 machine. Another typical cause: you installed a package you found on
447 the web, somewhere, the dependency resolution system did not protest
448 properly (as it should) or you forced it to install anyway, ignoring
449 some warnings.
450
4512) You compiled libmtp and/or gnomad2 from source, installing both or
452 either in /usr/local/lib and /usr/local/bin. This means at compile-time
453 gnomad2 finds the libmtp library in /usr/local/lib but at runtime, it
454 depends on the Linux system wide library loader (/lib/ld-linux.so.X) in
455 order to resolve the symbols. This loader will look into the file
456 /etc/ld.so.conf and/or the folder /etc/ld.so.conf.d in order to find
457 paths to libraries to be used for resolving the symbols. If you have
458 some older version of libmtp in e.g. /usr/lib (typically installed by a
459 package manager) it will take precedence over the new version you just
460 installed in /usr/local/lib and the newly compiled library in
461 /usr/local/lib will *not* be used, resulting in this error message.
462
4633) You really did install the very latest versions (as of writing libmtp
464 0.1.5 and gnomad2 2.8.11) from source and there really is no
465 pre-installed package of either on your machine. In that case I'm
466 totally lost, I have no idea what's causing this.
467
468Typical remedies:
469
4701) If you don't want to mess around with your system and risk these
471 situations, only use pre-packaged software that came with the
472 distribution or its official support channels. If it still breaks,
473 blame your distribution, they're not packaging correctly. Relying on
474 properly packaged software and not installing things yourself *is* the
475 Linux solution to the "dependency hell" problem.
476
4772) Read about dynamically linked library handling until the stuff I wrote
478 about in the previous list sounds like music to your ears, inspect
479 your /lib, /usr/lib, /usr/local/lib, /etc/ld.so.conf and the
480 /etc/ld.so.conf.d, remove all pre-packed versions using RPM, APT,
481 YaST or whatever your distribution uses, compile libmtp and gnomad2
482 (or whatever) from source only and you will be enlighted.
483
484I don't know if this helps you, it's the best answer we can give.