Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 1 | Building and Installing |
| 2 | ----------------------- |
Linus Walleij | 6fd2f08 | 2006-03-28 07:19:22 +0000 | [diff] [blame] | 3 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 4 | See the "INSTALL" file. |
| 5 | |
| 6 | |
| 7 | Heritage |
| 8 | -------- |
| 9 | |
| 10 | libmtp 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 Walleij | fcf8891 | 2006-06-05 13:23:33 +0000 | [diff] [blame] | 29 | on before libmtp. When Linus took Richards initial port |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 30 | 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 | |
| 36 | Compiling programs for libmtp |
| 37 | ----------------------------- |
| 38 | |
| 39 | libmtp has support for the pkg-config script by adding a libmtp.pc |
| 40 | entry in $(prefix)/lib/pkgconfig. To compile a libmtp program, |
| 41 | "just" write: |
| 42 | |
| 43 | gcc -o foo `pkg-config --cflags --libs libmtp` foo.c |
| 44 | |
| 45 | This also simplifies compilation using autoconf and pkg-config: just |
| 46 | write e.g. |
| 47 | |
| 48 | PKG_CHECK_MODULES(MTP, libmtp) |
| 49 | AC_SUBST(MTP_CFLAGS) |
| 50 | AC_SUBST(MTP_LIBS) |
| 51 | |
| 52 | To have libmtp LIBS and CFLAGS defined. Needless to say, this will |
| 53 | only work if you have pkgconfig installed on your system, but most |
| 54 | people have nowadays. |
| 55 | |
| 56 | If your library is installed in e.g. /usr/local you may have to tell |
| 57 | this to pkgconfig by setting the PKG_CONFIG_PATH thus: |
| 58 | |
| 59 | export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig |
| 60 | |
| 61 | |
| 62 | Documentation |
| 63 | ------------- |
| 64 | |
| 65 | Read the API documentation that can be generated with doxygen. |
| 66 | It will be output in doc/html if you have Doxygen properly |
| 67 | installed. (It will not be created unless you have Doxygen!) |
| 68 | |
| 69 | For information about the Media Transfer Protocol, see: |
| 70 | http://en.wikipedia.org/wiki/Media_Transfer_Protocol |
| 71 | |
| 72 | |
| 73 | Contributing |
| 74 | ------------ |
| 75 | |
| 76 | See the project page at http://libmtp.sourceforge.net/ |
Linus Walleij | ee73ef2 | 2006-08-27 19:56:00 +0000 | [diff] [blame] | 77 | We always need your help. There is a mailinglist and a |
| 78 | bug report system there. |
Linus Walleij | 6fd2f08 | 2006-03-28 07:19:22 +0000 | [diff] [blame] | 79 | |
Linus Walleij | fcf8891 | 2006-06-05 13:23:33 +0000 | [diff] [blame] | 80 | If you happen upon a device which libmtp claims it cannot |
| 81 | autodetect, please submit the vendor ID and device ID |
| 82 | as a bug, patch or feature request on the Sourceforge |
Linus Walleij | da558be | 2007-03-10 21:42:25 +0000 | [diff] [blame^] | 83 | bug tracker at our homepage. If it gives a sensible |
| 84 | output from "mtp-detect" then please attach the result as |
| 85 | well as it teach us some stuff about your device. |
| 86 | |
| 87 | If your device is problematic we are curious of how it |
| 88 | works under Windows, so we enjoy reading USB packet sniffs |
| 89 | that reveal the low-level traffic carried out between |
| 90 | Windows Media Player and your device. This can be done |
| 91 | using the trial version of HHD Softwares software-only |
| 92 | USB monitor. You need to get a copy of version 2.37 since |
| 93 | the newer trial versions won't let you carry out the |
| 94 | needed packet sniffs. (As of 2007-03-10 a copy can be found |
| 95 | at: http://www.cobbleware.com/files/usb-monitor-237.exe) |
| 96 | There are other USB monitors as well, some more expensive |
| 97 | alternatives use hardware and even measure electronic |
| 98 | characteristics of the traffic (which is far too much |
| 99 | detail for us). |
| 100 | |
| 101 | If you want to poke around to see if your device has some |
| 102 | special pecularities, you can test some special device |
| 103 | flags (defined in src/libusb-glue.h) by inserting them |
| 104 | together with your device entry in src/libusb-glue.c. |
| 105 | Flags can be tested in isolation or catenated with "|" |
| 106 | (binary OR). If relatives to your device use a certain |
| 107 | flag, chances are high that a new device will need it |
| 108 | too, typically from the same manufacturer. |
Linus Walleij | fcf8891 | 2006-06-05 13:23:33 +0000 | [diff] [blame] | 109 | |
Linus Walleij | 6fd2f08 | 2006-03-28 07:19:22 +0000 | [diff] [blame] | 110 | |
Linus Walleij | 15def33 | 2006-09-19 14:27:02 +0000 | [diff] [blame] | 111 | Calendar and contact support: |
| 112 | ----------------------------- |
Linus Walleij | d3bdf76 | 2006-02-20 22:21:56 +0000 | [diff] [blame] | 113 | |
Linus Walleij | 3c16fe4 | 2006-04-30 07:53:41 +0000 | [diff] [blame] | 114 | The Creative Zen series can read VCALENDAR2 (.ics) files |
Linus Walleij | 15def33 | 2006-09-19 14:27:02 +0000 | [diff] [blame] | 115 | and VCard (.vcf) files from programs like for example |
| 116 | Evolution with the following limitations/conditions: |
Linus Walleij | d3bdf76 | 2006-02-20 22:21:56 +0000 | [diff] [blame] | 117 | |
Linus Walleij | 3c16fe4 | 2006-04-30 07:53:41 +0000 | [diff] [blame] | 118 | - The file must be in DOS (CR/LF) format, use the unix2dos |
| 119 | program to convert if needed |
Linus Walleij | 15def33 | 2006-09-19 14:27:02 +0000 | [diff] [blame] | 120 | |
| 121 | - Repeat events in calendar files do not seem to be supported, |
| 122 | entries will only appear once. |
| 123 | |
| 124 | - Calendar (.ics) files should be stored in the folder "My Organizer" |
| 125 | when sent to the device (this directory should be autodetected |
Linus Walleij | 80b2c72 | 2006-06-22 17:57:17 +0000 | [diff] [blame] | 126 | for use with calendar files, otherwise use the option |
Linus Walleij | 15def33 | 2006-09-19 14:27:02 +0000 | [diff] [blame] | 127 | -f "My Organizer" to sendfile for this) Apparently this file can |
| 128 | also contain tasklists. |
| 129 | |
| 130 | - Contact (.vcf) files should be stored in the folder "My Contacts" |
| 131 | when sent to the device. (-f "My Contacts") |
| 132 | |
| 133 | - Some devices are picky about the name of the calendar and |
| 134 | contact files. For example the Zen Microphoto wants: |
| 135 | |
Linus Walleij | b1318d1 | 2006-09-25 14:59:26 +0000 | [diff] [blame] | 136 | Calendar: My Organizer/6651416.ics |
| 137 | Contacts: My Organizer/6651416.vcf |
| 138 | |
| 139 | |
| 140 | Syncing in with Evolution and Creative Devices |
| 141 | ---------------------------------------------- |
| 142 | |
| 143 | Evolution can easily export .ics an .vcf files, but you currently |
| 144 | need some command-line hacking to get you stuff copied over in |
| 145 | one direction host -> device. The examples/ directory contains a script |
| 146 | created for the Creative Zen Microphoto by Nicolas Tetreault. |
| 147 | |
Linus Walleij | 6e8cef4 | 2006-12-03 20:45:04 +0000 | [diff] [blame] | 148 | |
| 149 | It's Not Our Bug! |
| 150 | ----------------- |
| 151 | |
| 152 | Some MTP devices have strange pecularities. We try to work around |
| 153 | these whenever we can, sometimes we cannot work around it or we |
| 154 | cannot test your solution. |
| 155 | |
| 156 | * The Zen Vision:M (possibly more Creative Zens) has a firmware bug |
| 157 | that makes it drop the last two characters off a playlist name. |
| 158 | It is fixed in later firmware. |
| 159 | |
Linus Walleij | d24a7ab | 2007-03-07 21:48:43 +0000 | [diff] [blame] | 160 | * Sandisk sansa c150 and probably several other Sandisk devices |
| 161 | (and possibly devices from other manufacturers) have a dual |
| 162 | mode with MTP and USB mass storage. The device will initially |
| 163 | claim to be mass storage so udev will capture is and make the |
Linus Walleij | da558be | 2007-03-10 21:42:25 +0000 | [diff] [blame^] | 164 | use of MTP mode impossible. One way of avoiding it could be to |
Linus Walleij | d24a7ab | 2007-03-07 21:48:43 +0000 | [diff] [blame] | 165 | be to blacklist the "usb-storage" module in |
| 166 | /etc/modprobe.c/blacklist with a row like this: |
Linus Walleij | da558be | 2007-03-10 21:42:25 +0000 | [diff] [blame^] | 167 | "blacklist usb-storage". Some have even removed the |
| 168 | "usb-storage.ko" (kernel module file) to avoid loading. |
Linus Walleij | d24a7ab | 2007-03-07 21:48:43 +0000 | [diff] [blame] | 169 | |
Linus Walleij | da558be | 2007-03-10 21:42:25 +0000 | [diff] [blame^] | 170 | * The iriver devices (possibly all of them) cannot handle the |
Linus Walleij | 6e8cef4 | 2006-12-03 20:45:04 +0000 | [diff] [blame] | 171 | enhanced GetObjectPropList MTP command (0x9805) properly. So |
| 172 | they have been banned from using it. |
| 173 | |
Linus Walleij | da558be | 2007-03-10 21:42:25 +0000 | [diff] [blame^] | 174 | * iriver devices have problems with older versions of libmtp and |
Linus Walleij | 8226522 | 2007-03-04 19:47:08 +0000 | [diff] [blame] | 175 | with new devices libmtp does not know of as of yet, since it |
| 176 | has an oldstyle USB device controller that cannot handle zero |
Linus Walleij | da558be | 2007-03-10 21:42:25 +0000 | [diff] [blame^] | 177 | writes. (Register your device with us!) All their devices are |
| 178 | likely to need a special device flag in the src/libusb-glue.c |
| 179 | database. |
Linus Walleij | 8226522 | 2007-03-04 19:47:08 +0000 | [diff] [blame] | 180 | |
Linus Walleij | 6e8cef4 | 2006-12-03 20:45:04 +0000 | [diff] [blame] | 181 | * The Samsung Yepp T9 has several strange characteristics, some |
| 182 | that we've managed to work around. (For example it will return |
| 183 | multiple PTP packages in a single transaction.) |
| 184 | |
Linus Walleij | f2711b3 | 2007-02-26 20:18:40 +0000 | [diff] [blame] | 185 | * The early firmware for Philips HDD players is known to be |
| 186 | problematic. Please upgrade to as new firmware as you can get. |
| 187 | (Yes this requires some kind of Windows Installation I think.) |
| 188 | |
Linus Walleij | 6e8cef4 | 2006-12-03 20:45:04 +0000 | [diff] [blame] | 189 | * Very few devices that implement GetObjectPropList (0x9805) will |
| 190 | return the entire object list if you request a list for object |
| 191 | 0xffffffffu. (But they should.) So we're currently not using |
| 192 | that feature. |