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 | |
Linus Walleij | 3f7529c | 2010-07-24 20:33:41 +0000 | [diff] [blame] | 7 | Initiator and Responder |
| 8 | ----------------------- |
| 9 | |
| 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 |
| 14 | controller. |
| 15 | |
| 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. |
| 20 | |
| 21 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 22 | Heritage |
| 23 | -------- |
| 24 | |
| 25 | libmtp 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 Walleij | fcf8891 | 2006-06-05 13:23:33 +0000 | [diff] [blame] | 44 | on before libmtp. When Linus took Richards initial port |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 45 | 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 Walleij | ea7d45b | 2009-02-23 22:26:09 +0000 | [diff] [blame] | 51 | Contacting and Contributing |
| 52 | --------------------------- |
| 53 | |
| 54 | See the project page at http://libmtp.sourceforge.net/ |
| 55 | We always need your help. There is a mailinglist and a |
| 56 | bug report system there. |
| 57 | |
| 58 | People who want to discuss MTP devices in fora seem to |
| 59 | hang out on the forums at AnythingbutiPod: |
| 60 | http://www.anythingbutipod.com/forum/ |
| 61 | |
| 62 | |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 63 | Compiling programs for libmtp |
| 64 | ----------------------------- |
| 65 | |
| 66 | libmtp has support for the pkg-config script by adding a libmtp.pc |
| 67 | entry in $(prefix)/lib/pkgconfig. To compile a libmtp program, |
| 68 | "just" write: |
| 69 | |
| 70 | gcc -o foo `pkg-config --cflags --libs libmtp` foo.c |
| 71 | |
| 72 | This also simplifies compilation using autoconf and pkg-config: just |
| 73 | write e.g. |
| 74 | |
| 75 | PKG_CHECK_MODULES(MTP, libmtp) |
| 76 | AC_SUBST(MTP_CFLAGS) |
| 77 | AC_SUBST(MTP_LIBS) |
| 78 | |
| 79 | To have libmtp LIBS and CFLAGS defined. Needless to say, this will |
| 80 | only work if you have pkgconfig installed on your system, but most |
| 81 | people have nowadays. |
| 82 | |
| 83 | If your library is installed in e.g. /usr/local you may have to tell |
| 84 | this to pkgconfig by setting the PKG_CONFIG_PATH thus: |
| 85 | |
| 86 | export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig |
| 87 | |
| 88 | |
| 89 | Documentation |
| 90 | ------------- |
| 91 | |
| 92 | Read the API documentation that can be generated with doxygen. |
| 93 | It will be output in doc/html if you have Doxygen properly |
| 94 | installed. (It will not be created unless you have Doxygen!) |
| 95 | |
| 96 | For information about the Media Transfer Protocol, see: |
| 97 | http://en.wikipedia.org/wiki/Media_Transfer_Protocol |
| 98 | |
Linus Walleij | 7a83e55 | 2008-07-29 21:30:43 +0000 | [diff] [blame] | 99 | The official 1.0 specification for MTP was released by the |
| 100 | USB Implementers Forum in may, 2008. Prior to this, only a |
| 101 | proprietary Microsoft version was available, and quite a few |
| 102 | devices out there still use some aspects of the Microsoft |
| 103 | version, which deviates from the specified standard. You can |
| 104 | find the official specification here: |
| 105 | http://www.usb.org/developers/devclass_docs/MTP_1.0.zip |
Linus Walleij | 0dd71e9 | 2006-05-04 18:47:07 +0000 | [diff] [blame] | 106 | |
Linus Walleij | 1b91ca6 | 2008-10-17 07:07:56 +0000 | [diff] [blame] | 107 | |
| 108 | The Examples |
| 109 | ------------ |
| 110 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 111 | In the subdirectory "examples" you find a number of |
Linus Walleij | 1b91ca6 | 2008-10-17 07:07:56 +0000 | [diff] [blame] | 112 | command-line tools, illustrating the use of libmtp in very |
| 113 | simple terms. |
| 114 | |
| 115 | Please do not complain about the usability or documentation |
| 116 | of these examples, they look like they do for two reasons: |
| 117 | |
| 118 | 1. 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 | |
| 122 | 2. The MTP usage paradigm is that a daemon should hook |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 123 | the device upon connection, and that it should be |
Linus Walleij | 1b91ca6 | 2008-10-17 07:07:56 +0000 | [diff] [blame] | 124 | 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 | |
| 130 | That said, if you want to pick up and maintain the examples, |
| 131 | please volunteer. |
| 132 | |
| 133 | |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 134 | FAQ: Common Problems |
| 135 | -------------------- |
| 136 | |
| 137 | Some MTP devices have strange pecularities. We try to work around |
| 138 | these whenever we can, sometimes we cannot work around it or we |
| 139 | cannot 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 Walleij | e962add | 2012-01-13 20:22:22 +0100 | [diff] [blame] | 161 | 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 Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 165 | 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 Walleij | e962add | 2012-01-13 20:22:22 +0100 | [diff] [blame] | 182 | You can get Windows-like behaviour on Linux by running a udev-aware |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 183 | 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 Walleij | e962add | 2012-01-13 20:22:22 +0100 | [diff] [blame] | 185 | 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 Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 195 | |
| 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 | |
Linus Walleij | f776f7b | 2012-06-06 10:14:05 +0200 | [diff] [blame^] | 200 | * Samsung Android 2.3.x devices: these have a special MTP stack |
| 201 | with some specific bugs that we have maybe nailed down now. |
| 202 | It suffers from an "immediate connect" syndrome, i.e. you have |
| 203 | to connect to the device within 7 seconds of plugging in, or it |
| 204 | will go numb. This also goes for command-line activity with |
| 205 | the example programs, so this device is better used with a |
| 206 | GUI tool like Rhythmbox, gnomad2... |
| 207 | |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 208 | * Generic USB misbehaviour: some devices behave badly under MTP |
| 209 | and USB mass storage alike, even down to the lowest layers |
| 210 | of USB. You can always discuss such issues at the linux-usb |
| 211 | mailing list if you're using Linux: |
| 212 | http://www.linux-usb.org/mailing.html |
| 213 | |
| 214 | If you have a problem specific to USB mass storage mode, there |
| 215 | is a list of strange behaving devices in the Linux kernel: |
| 216 | http://lxr.linux.no/linux/drivers/usb/storage/unusual_devs.h |
| 217 | You can discuss this too on the mentioned list, for understanding |
| 218 | the quirks, see: |
| 219 | http://www2.one-eyed-alien.net/~mdharm/linux-usb/target_offenses.txt |
| 220 | |
| 221 | * Generic certificate misbehaviour. All devices are actually |
| 222 | required to support a device certificate to be able to |
| 223 | encrypt Windows Media (WMA/WMV) files. However there are |
| 224 | obviously a lot of devices out there which doesn't support |
| 225 | this at all but instead crash. Typical printout: |
| 226 | |
| 227 | Error 2: PTP Layer error 02ff: get_device_unicode_property(): failed |
| 228 | to get unicode property. |
| 229 | |
| 230 | This should only affect "mtp-detect", there is no other |
| 231 | application currently retrieveing the certificate (not that we |
| 232 | know anyway). |
| 233 | |
| 234 | * Kernel bug on Linux. Linux 2.6.16 is generally speaking required |
| 235 | to use any MTP device under USB 2.0. This is because the EHCI |
| 236 | driver previously did not support zero-length writes to endpoints. |
| 237 | It should work in most cases however, or if you connect it |
| 238 | to an UHCI/OHCI port instead (yielding lower speed). But |
| 239 | please just use a recent kernel. |
| 240 | |
| 241 | * Zen models AVI file seeking problem: the Zens cannot parse the |
| 242 | files for the runlength metadata. Do not transfer file with e.g. |
| 243 | mtp-sendfile, use mtp-sendtr and set the length of the track to |
| 244 | the apropriate number of seconds and it will work. In graphical |
| 245 | clients, use a "track transfer" function to send these AVI files, |
| 246 | the Zens need the metadata associated with tracks to play back |
| 247 | movies properly. Movies are considered "tracks" in the MTP world. |
| 248 | |
| 249 | * Some devices that disregard the metadata sent with the MTP |
| 250 | commands will parse the files for e.g. ID3 metadata. Some still |
| 251 | of these devices expect only ID3v2.3 metadata and will fail with |
| 252 | a modern ID3v2,4 tag writer, like many of those found in Linux |
| 253 | applications. Windows Media Player use ID3v2.3 only, so many |
| 254 | manufacturers only test this version. |
| 255 | |
| 256 | * The Zen Vision:M (possibly more Creative Zens) has a firmware bug |
| 257 | that makes it drop the last two characters off a playlist name. |
| 258 | It is fixed in later firmware. |
| 259 | |
| 260 | * For Creative Technology devices, there are hard limits on how |
| 261 | many files can be put onto the device. For a 30 GiB device (like |
| 262 | the Zen Xtra) the limit is 6000, for a 60 GiB device the limit |
| 263 | is 15000 files. For further Creative pecularities, see the |
| 264 | FAQ sections at www.nomadness.net. |
| 265 | |
| 266 | * Sandisk sansa c150 and probably several other Sandisk devices |
| 267 | (and possibly devices from other manufacturers) have a dual |
| 268 | mode with MTP and USB mass storage. The device will initially |
| 269 | claim to be mass storage so udev will capture is and make the |
| 270 | use of MTP mode impossible. One way of avoiding it could be to |
| 271 | be to blacklist the "usb-storage" module in |
| 272 | /etc/modprobe.c/blacklist with a row like this: |
| 273 | "blacklist usb-storage". Some have even removed the |
| 274 | "usb-storage.ko" (kernel module file) to avoid loading. |
| 275 | |
| 276 | * Sandisk Sansa Fuze has three modes: auto, MTP or mass storage |
| 277 | (MSC). Please set it to MTP to avoid problems with libmtp. |
| 278 | |
| 279 | * The iriver devices (possibly all of them) cannot handle the |
| 280 | enhanced GetObjectPropList MTP command (0x9805) properly. So |
| 281 | they have been banned from using it. |
| 282 | |
| 283 | * iriver devices have problems with older versions of libmtp and |
| 284 | with new devices libmtp does not know of as of yet, since it |
| 285 | has an oldstyle USB device controller that cannot handle zero |
| 286 | writes. (Register your device with us!) All their devices are |
| 287 | likely to need a special device flag in the src/libusb-glue.c |
| 288 | database. |
| 289 | |
| 290 | * The Samsung Yepp T9 has several strange characteristics, some |
| 291 | that we've managed to work around. (For example it will return |
| 292 | multiple PTP packages in a single transaction.) |
| 293 | |
| 294 | * The early firmware for Philips HDD players is known to be |
| 295 | problematic. Please upgrade to as new firmware as you can get. |
| 296 | (Yes this requires some kind of Windows Installation I think.) |
| 297 | |
| 298 | * Philips HDD 1630/16 or 1630/17 etc may lock themselves up, |
| 299 | turning inresponsive due to internal corruption. This typically |
| 300 | gives an error in opening the PTP session. Apparently you can |
| 301 | do a "repair" with the firmware utility (Windows only) which |
| 302 | will often fix this problem and make the device responsive |
| 303 | again. |
| 304 | |
| 305 | * Some devices that implement GetObjectPropList (0x9805) will |
| 306 | not return the entire object list if you request a list for object |
| 307 | 0xffffffffu. (But they should.) So they may need the special |
| 308 | DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL. |
| 309 | |
| 310 | * Some (smaller) subset of devices cannot even get all the |
| 311 | properties for a single object in one go, these need the |
| 312 | DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST. Currently only the |
| 313 | iriver devices seem to have this bug. |
| 314 | |
| 315 | * The Toshiba Gigabeat S (and probably its sibling the |
| 316 | Microsoft Zune and other Toshiba devices) will only display |
| 317 | album information tags for a song in case there is also |
| 318 | an abstract album (created with the album interface) with |
| 319 | the exact same name. |
| 320 | |
| 321 | * The Zen Vision:M has an older firmware which is very corrupt, |
| 322 | it is incompatible with the Linux USB stack altogether. The |
| 323 | kernel dmesg will look something like this, and you have to |
| 324 | upgrade the firmware using Windows: |
| 325 | usb 4-5: new high speed USB device using ehci_hcd and address 5 |
| 326 | usb 4-5: configuration #1 chosen from 1 choice |
| 327 | usb 4-5: can't set config #1, error -110 |
| 328 | |
| 329 | * The Sirus Stiletto does not seem to allow you to copy any files |
| 330 | off the device. This may be someone's idea of copy protection. |
| 331 | |
| 332 | * The Samsung P2 assigns parent folder ID 0 to all unknown file |
| 333 | types.(i.e. moves them to the root folder) |
| 334 | |
| 335 | * The Sandisk Sansa Clip+ needs a firmware upgrade in earlier |
| 336 | versions in order to work properly. |
| 337 | |
| 338 | |
Linus Walleij | a1b66f2 | 2007-05-10 20:02:16 +0000 | [diff] [blame] | 339 | New Devices |
| 340 | ----------- |
| 341 | |
Linus Walleij | fcf8891 | 2006-06-05 13:23:33 +0000 | [diff] [blame] | 342 | If you happen upon a device which libmtp claims it cannot |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 343 | autodetect, please submit the vendor ID and device ID |
Linus Walleij | 9ee2940 | 2007-10-31 20:24:48 +0000 | [diff] [blame] | 344 | (these can be obtained from the "lsusb" and "lsusb -n" |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 345 | commands run as root) as a bug, patch or feature request |
| 346 | on the Sourceforge bug tracker at our homepage. If it |
| 347 | gives a sensible output from "mtp-detect" then please attach |
| 348 | the result as well as it teach us some stuff about your |
| 349 | device. If you've done some additional hacking, join our |
Linus Walleij | 9ee2940 | 2007-10-31 20:24:48 +0000 | [diff] [blame] | 350 | mailinglist and post your experiences there. |
Linus Walleij | da558be | 2007-03-10 21:42:25 +0000 | [diff] [blame] | 351 | |
Linus Walleij | a1b66f2 | 2007-05-10 20:02:16 +0000 | [diff] [blame] | 352 | If you want to be able to hack some more and you're not |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 353 | afraid of C hacking, add an entry for your device's |
| 354 | vendor/product ID and a descriptive string to the database |
Linus Walleij | 6dc0168 | 2007-11-15 21:23:46 +0000 | [diff] [blame] | 355 | in the file src/music-players.h. |
Linus Walleij | a1b66f2 | 2007-05-10 20:02:16 +0000 | [diff] [blame] | 356 | |
| 357 | If you want to poke around to see if your device has some |
| 358 | special pecularities, you can test some special device |
Linus Walleij | 6dc0168 | 2007-11-15 21:23:46 +0000 | [diff] [blame] | 359 | flags (defined in src/device-flags.h) by inserting them |
| 360 | together with your device entry in src/music-players.h. |
Linus Walleij | a1b66f2 | 2007-05-10 20:02:16 +0000 | [diff] [blame] | 361 | Flags can be tested in isolation or catenated with "|" |
| 362 | (binary OR). If relatives to your device use a certain |
| 363 | flag, chances are high that a new device will need it |
| 364 | too, typically from the same manufacturer. |
| 365 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 366 | The most common flag that needs to be set is the |
Linus Walleij | a1b66f2 | 2007-05-10 20:02:16 +0000 | [diff] [blame] | 367 | DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel |
| 368 | drivers that may have attached to the device making |
Linus Walleij | 94f23d5 | 2007-08-04 19:37:28 +0000 | [diff] [blame] | 369 | MTP access impossible. This is however not expected to |
| 370 | really work: this is a problem being tracked as of |
| 371 | now (2007-08-04). See the "last resort" solutions below |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 372 | if you really need to get your dual-mode device to work |
Linus Walleij | 94f23d5 | 2007-08-04 19:37:28 +0000 | [diff] [blame] | 373 | with MTP. |
Linus Walleij | a1b66f2 | 2007-05-10 20:02:16 +0000 | [diff] [blame] | 374 | |
Linus Walleij | cc2cf97 | 2007-11-22 20:23:43 +0000 | [diff] [blame] | 375 | Another flag which is easy to identify is the |
| 376 | DEVICE_FLAG_NO_ZERO_READS, which remedies connection |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 377 | timeouts when getting files, and some timeouts on e.g. |
Linus Walleij | cc2cf97 | 2007-11-22 20:23:43 +0000 | [diff] [blame] | 378 | successive "mtp-connect" calls. |
| 379 | |
Linus Walleij | a1b66f2 | 2007-05-10 20:02:16 +0000 | [diff] [blame] | 380 | If your device is very problematic we are curious of how it |
Linus Walleij | da558be | 2007-03-10 21:42:25 +0000 | [diff] [blame] | 381 | works under Windows, so we enjoy reading USB packet sniffs |
| 382 | that reveal the low-level traffic carried out between |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 383 | Windows Media Player and your device. This can be done |
Linus Walleij | 61c2568 | 2007-09-04 14:46:21 +0000 | [diff] [blame] | 384 | using e.g.: |
| 385 | |
| 386 | * USBsnoop: |
| 387 | http://benoit.papillault.free.fr/usbsnoop/ |
| 388 | |
| 389 | * The trial version of HHD Softwares software-only |
| 390 | USB monitor. You need to get a copy of version 2.37 since |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 391 | the newer trial versions won't let you carry out the |
Linus Walleij | 61c2568 | 2007-09-04 14:46:21 +0000 | [diff] [blame] | 392 | needed packet sniffs. (As of 2007-03-10 a copy can be found |
| 393 | at: http://www.cobbleware.com/files/usb-monitor-237.exe) |
| 394 | |
Linus Walleij | da558be | 2007-03-10 21:42:25 +0000 | [diff] [blame] | 395 | There are other USB monitors as well, some more expensive |
| 396 | alternatives use hardware and even measure electronic |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 397 | characteristics of the traffic (which is far too much |
Linus Walleij | da558be | 2007-03-10 21:42:25 +0000 | [diff] [blame] | 398 | detail for us). |
| 399 | |
Linus Walleij | 91fb028 | 2007-09-03 21:16:08 +0000 | [diff] [blame] | 400 | Device sniffs are an easy read since the PTP/MTP protocol |
| 401 | is nicely structured. All commands will have a structure such |
| 402 | as this in the log, we examplify with a object list request: |
| 403 | |
| 404 | PTP REQEUST: |
| 405 | 000120: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:25.9843750 +0.0 |
| 406 | Pipe Handle: 0x863ce234 (Endpoint Address: 0x2) |
| 407 | Send 0x20 bytes to the device: |
| 408 | 20 00 00 00 01 00 05 98 23 00 00 00 27 03 00 10 ......?#...'... |
| 409 | Length TYPE CMD Trans# Param1 |
| 410 | |
| 411 | 00 00 00 00 02 DC 00 00 00 00 00 00 00 00 00 00 .....Ü.......... |
| 412 | Param2 Param3 Param4 Param5 |
| 413 | |
| 414 | [OPTIONAL] DATA PHASE: |
| 415 | 000121: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0156250 |
| 416 | Pipe Handle: 0x863ce214 (Endpoint Address: 0x81) |
| 417 | Get 0x1a bytes from the device: |
| 418 | 1A 00 00 00 02 00 05 98 23 00 00 00 01 00 00 00 .......?#....... |
| 419 | Length TYPE CMD Trans# DATA |
| 420 | |
| 421 | 27 03 00 10 02 DC 04 00 00 30 '....Ü...0 |
| 422 | |
| 423 | RESPONSE: |
| 424 | 000122: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0 |
| 425 | Pipe Handle: 0x863ce214 (Endpoint Address: 0x81) |
| 426 | Get 0xc bytes from the device: |
| 427 | 0C 00 00 00 03 00 01 20 23 00 00 00 ....... #... |
| 428 | Length TYPE CODE Trans# |
| 429 | |
| 430 | * One send (OUT to the device), two reads (IN from the device). |
| 431 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 432 | * All three byte chunks commands are |
| 433 | sent/recieved/recieeved by the function ptp_transaction() |
Linus Walleij | 91fb028 | 2007-09-03 21:16:08 +0000 | [diff] [blame] | 434 | in the file ptp.c. |
| 435 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 436 | * It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata() |
| 437 | or ptp_usb_getdata() and finally ptp_usb_getresp() in the file |
Linus Walleij | 91fb028 | 2007-09-03 21:16:08 +0000 | [diff] [blame] | 438 | libusb-glue.c. Notice ptp_usb_sendreq() and ptp_usb_getresp() |
| 439 | are ALWAYS called. The TYPE field correspond to this, so the |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 440 | TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002), |
Linus Walleij | 91fb028 | 2007-09-03 21:16:08 +0000 | [diff] [blame] | 441 | and "RESPONSE" (0x0003). |
| 442 | |
| 443 | * Notice that the byte order is little endian, so you need to read |
| 444 | each field from right to left. |
| 445 | |
| 446 | * This COMMAND has: |
| 447 | CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList. |
| 448 | Transaction# 0x00000023. |
| 449 | REQUEST parameters 0x10000327, 0x00000000, 0x0000DC02, 0x00000000 |
| 450 | 0x00000000, in this case it means "get props for object 0x10000327", |
| 451 | "any format", "property 0xDC02" (PTP_OPC_ObjectFormat), then two |
| 452 | parameters that are always zero (no idea what they mean or their |
| 453 | use). |
| 454 | |
| 455 | * The DATA has: |
| 456 | CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList. |
| 457 | Transaction# 0x00000023. |
| 458 | Then comes data 0x00000001, 0x10000327, 0xDC02, 0x0004, 0x3000 |
| 459 | Which means in this case, (and this is the tricky part) "here |
| 460 | you have 1 property", "for object 0x10000327", "it is property |
| 461 | 0xDC02" (PTP_OPC_ObjectFormat), "which is of type 0x0004" |
| 462 | (PTP_DTC_UINT16), "and set to 0x3000" (PTP_OFC_Undefined, it |
| 463 | is perfectly valid to have undefined object formats, since it |
| 464 | is a legal value defining this). |
| 465 | |
| 466 | * This RESPONSE has: |
| 467 | CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList. |
| 468 | Return Code ("RC") = 0x2001, PTP_RC_OK, all went fine. |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 469 | Transaction# 0x00000023. |
Linus Walleij | fcf8891 | 2006-06-05 13:23:33 +0000 | [diff] [blame] | 470 | |
Linus Walleij | d05fce6 | 2007-09-29 20:17:23 +0000 | [diff] [blame] | 471 | If you want to compare the Windows behaviour with a similar |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 472 | operation using libmtp you can go into the src/libusb-glue.c |
Linus Walleij | 6dc0168 | 2007-11-15 21:23:46 +0000 | [diff] [blame] | 473 | file and uncomment the row that reads: |
Linus Walleij | d05fce6 | 2007-09-29 20:17:23 +0000 | [diff] [blame] | 474 | |
| 475 | //#define ENABLE_USB_BULK_DEBUG |
| 476 | |
| 477 | (I.e. remove the two //.) |
| 478 | |
| 479 | This will make libmtp print out a hex dump of every bulk USB |
| 480 | transaction. The bulk transactions contain all the PTP/MTP layer |
| 481 | data, which is usually where the problems appear. |
| 482 | |
Linus Walleij | 6fd2f08 | 2006-03-28 07:19:22 +0000 | [diff] [blame] | 483 | |
Darran Kartaschew | a476ae9 | 2011-08-08 09:07:30 +0200 | [diff] [blame] | 484 | Notes to assist with debugging new devices: |
| 485 | ------------------------------------------- |
| 486 | |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 487 | In debugging new hardware, we highly recommend that you only |
Darran Kartaschew | a476ae9 | 2011-08-08 09:07:30 +0200 | [diff] [blame] | 488 | use the example mtp-* applications that come with libmtp, as other |
| 489 | applications may have their own bugs that may interfere with your |
| 490 | new device working correctly. Using another application instead of |
| 491 | those that come with libmtp just adds another point of failure. |
| 492 | |
| 493 | For debugging, there are 3 main options: |
| 494 | |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 495 | 1. Use the env variable: LIBMTP_DEBUG to increase the |
| 496 | verboseness of the debugging output for any application using |
Darran Kartaschew | a476ae9 | 2011-08-08 09:07:30 +0200 | [diff] [blame] | 497 | libmtp. Relevant codes are: |
| 498 | * 0x00 [0000 0000] : no debug (default) |
| 499 | * 0x01 [0000 0001] : PTP debug |
| 500 | * 0x02 [0000 0010] : Playlist debug |
| 501 | * 0x04 [0000 0100] : USB debug |
| 502 | * 0x08 [0000 1000] : USB data debug |
| 503 | // Codes are hex and binary respectively. Simple add them togther |
| 504 | // to get your desired level of output. |
| 505 | |
| 506 | (Assuming bash) |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 507 | eg: |
Darran Kartaschew | a476ae9 | 2011-08-08 09:07:30 +0200 | [diff] [blame] | 508 | $ export LIBMTP_DEBUG=12 |
| 509 | $ mtp-detect |
| 510 | // To get USB debug and USB data debug information. |
| 511 | |
| 512 | $ export LIBMTP_DEBUG=2 |
| 513 | $ mtp-detect |
| 514 | // To get Playlist debug information. |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 515 | |
Darran Kartaschew | a476ae9 | 2011-08-08 09:07:30 +0200 | [diff] [blame] | 516 | Also note, an application may also use the LIBMTP_debug() API |
| 517 | function to achieve the same options as listed above. |
| 518 | |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 519 | 2. Use "strace" on the various mtp-* commands to see where/what |
Darran Kartaschew | a476ae9 | 2011-08-08 09:07:30 +0200 | [diff] [blame] | 520 | is falling over or getting stuck at. |
| 521 | * On Solaris and FreeBSD, use "truss" or "dtrace" instead on "strace". |
| 522 | * On Mac OS X, use "ktrace" or "dtrace" instead of "strace". |
| 523 | * On OpenBSD and NetBSD, use "ktrace" instead of "strace". |
| 524 | |
| 525 | This will at least help pinpoint where the application is failing, or |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 526 | a device is reporting incorrect information. (This is extremely helpful |
Darran Kartaschew | a476ae9 | 2011-08-08 09:07:30 +0200 | [diff] [blame] | 527 | with devices that have odd disconnection requirements). |
| 528 | |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 529 | The use of these tools may also pinpoint issues with libusb as |
Darran Kartaschew | a476ae9 | 2011-08-08 09:07:30 +0200 | [diff] [blame] | 530 | implemented by each OS vendor or issues with the MTP implementation |
| 531 | on the new device as well, so please be prepared for either case. |
| 532 | |
| 533 | 3. Use "gdb" or similar debugger to step through the code as it is |
| 534 | run. This is time consuming, and not needed just to pinpoint where |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 535 | the fault is. |
Darran Kartaschew | a476ae9 | 2011-08-08 09:07:30 +0200 | [diff] [blame] | 536 | |
Linus Walleij | c36e2a6 | 2011-12-29 21:31:49 +0100 | [diff] [blame] | 537 | The use of gdb or another debugger may also miss or actually cause |
| 538 | command and data timing issues with some devices, leading to false |
Darran Kartaschew | a476ae9 | 2011-08-08 09:07:30 +0200 | [diff] [blame] | 539 | information. So please consider this a last resort option. |
| 540 | |
| 541 | Also please read the "It's Not Our Bug!" section below, as it does |
| 542 | contain some useful information that may assist with your device. |
| 543 | |
| 544 | |
Linus Walleij | 8d799eb | 2009-07-23 22:58:06 +0000 | [diff] [blame] | 545 | Dual-mode devices does not work - last resort: |
| 546 | ---------------------------------------------- |
Linus Walleij | bd7624c | 2007-05-28 10:48:54 +0000 | [diff] [blame] | 547 | |
| 548 | Some devices that are dual-mode are simply impossible to get |
| 549 | to work under Linux because the usb-storage(.ko) kernel |
| 550 | module hook them first, and refuse to release them, even |
Linus Walleij | 94f23d5 | 2007-08-04 19:37:28 +0000 | [diff] [blame] | 551 | when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe |
| 552 | it DOES release it but the device will immediately be probed |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 553 | at the USB mass storage interface AGAIN because it |
Linus Walleij | 94f23d5 | 2007-08-04 19:37:28 +0000 | [diff] [blame] | 554 | enumerates.) |
Linus Walleij | bd7624c | 2007-05-28 10:48:54 +0000 | [diff] [blame] | 555 | |
Linus Walleij | 8d799eb | 2009-07-23 22:58:06 +0000 | [diff] [blame] | 556 | Here is what some people do: |
| 557 | |
| 558 | 1. Plug in the device. |
| 559 | 2. USB-mass storage folder will open automatically. |
| 560 | 3. Unmount the device. |
| 561 | 4. Run mtp-detect. It will most likely fail the first time. |
| 562 | 5. Run mtp-detect again, it might work this time, or fail. Keep running |
| 563 | till it works. 99% it works by the third try. |
| 564 | 6. Once mtp-detect gives you an "Ok", open either Rhythmbox or Gnomad2, |
| 565 | everything should work. |
| 566 | |
Linus Walleij | e20abaf | 2007-12-10 11:20:34 +0000 | [diff] [blame] | 567 | Linux: Try this, if you have a recent 2.6.x Linux kernel, |
Linus Walleij | 584eb8d | 2007-09-05 19:51:27 +0000 | [diff] [blame] | 568 | run (as root) something like: |
| 569 | |
| 570 | > rmmod usb_storage ; mtp-detect |
| 571 | |
| 572 | You can run most any command or a client like gnomad2 or |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 573 | Amarok immediately after the rmmod command. This works |
Linus Walleij | 584eb8d | 2007-09-05 19:51:27 +0000 | [diff] [blame] | 574 | sometimes. Another way: |
Linus Walleij | bd7624c | 2007-05-28 10:48:54 +0000 | [diff] [blame] | 575 | |
Linus Walleij | 94f23d5 | 2007-08-04 19:37:28 +0000 | [diff] [blame] | 576 | * Edit /etc/modprobe.d/blacklist |
Linus Walleij | bd7624c | 2007-05-28 10:48:54 +0000 | [diff] [blame] | 577 | |
| 578 | * Add the line "blacklist usb-storage" |
| 579 | |
| 580 | * Reboot. |
| 581 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 582 | Now none of you USB disks, flash memory sticks etc will be |
Linus Walleij | bd7624c | 2007-05-28 10:48:54 +0000 | [diff] [blame] | 583 | working (you just disabled them all). However you *can* try |
| 584 | your device, and it might have started working because there |
| 585 | is no longer a USB mass storage driver that tries to hook onto |
| 586 | the mass storage interface of your device. |
| 587 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 588 | If not even blacklisting works (check with |
Linus Walleij | 94f23d5 | 2007-08-04 19:37:28 +0000 | [diff] [blame] | 589 | "lsmod | grep usb-storage"), there is some problem with |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 590 | something else and you may need to remove or rename the file |
Linus Walleij | 94f23d5 | 2007-08-04 19:37:28 +0000 | [diff] [blame] | 591 | /lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko |
| 592 | manually. |
| 593 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 594 | If you find the PerfectSolution(TM) to this dilemma, so you |
Linus Walleij | bd7624c | 2007-05-28 10:48:54 +0000 | [diff] [blame] | 595 | can properly switch for individual devices whether to use it |
| 596 | as USB mass storage or not, please tell us how you did it. We |
| 597 | know we cannot use udev, because udev is called after-the-fact: |
| 598 | the device is already configured for USB mass storage when |
| 599 | udev is called. |
| 600 | |
Linus Walleij | e20abaf | 2007-12-10 11:20:34 +0000 | [diff] [blame] | 601 | On Mac OS there is another ugly hack: |
| 602 | |
| 603 | 1. Open up a terminal window |
| 604 | 2. Type: |
| 605 | sudo mv /System/Library/Extensions/IOUSBMassStorageClass.kext |
| 606 | /System/Library/Extensions/IOUSBMassStorageClass.kext.disabled |
| 607 | |
| 608 | and when prompted enter your password. |
| 609 | |
| 610 | 3. Restart. |
| 611 | |
| 612 | To reverse this change, just reverse the filenames: |
| 613 | |
| 614 | sudo mv /System/Library/Extensions/ |
| 615 | IOUSBMassStorageClass.kext.disabled /System/Library/Extensions/ |
| 616 | IOUSBMassStorageClass.kext |
| 617 | |
| 618 | and restart. |
| 619 | |
Linus Walleij | bd7624c | 2007-05-28 10:48:54 +0000 | [diff] [blame] | 620 | |
Linus Walleij | 15def33 | 2006-09-19 14:27:02 +0000 | [diff] [blame] | 621 | Calendar and contact support: |
| 622 | ----------------------------- |
Linus Walleij | d3bdf76 | 2006-02-20 22:21:56 +0000 | [diff] [blame] | 623 | |
Linus Walleij | 3c16fe4 | 2006-04-30 07:53:41 +0000 | [diff] [blame] | 624 | The Creative Zen series can read VCALENDAR2 (.ics) files |
Linus Walleij | 15def33 | 2006-09-19 14:27:02 +0000 | [diff] [blame] | 625 | and VCard (.vcf) files from programs like for example |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 626 | Evolution with the following limitations/conditions: |
Linus Walleij | d3bdf76 | 2006-02-20 22:21:56 +0000 | [diff] [blame] | 627 | |
Linus Walleij | 3c16fe4 | 2006-04-30 07:53:41 +0000 | [diff] [blame] | 628 | - The file must be in DOS (CR/LF) format, use the unix2dos |
| 629 | program to convert if needed |
Linus Walleij | 15def33 | 2006-09-19 14:27:02 +0000 | [diff] [blame] | 630 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 631 | - Repeat events in calendar files do not seem to be supported, |
Linus Walleij | 15def33 | 2006-09-19 14:27:02 +0000 | [diff] [blame] | 632 | entries will only appear once. |
| 633 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 634 | - Calendar (.ics) files should be stored in the folder "My Organizer" |
Linus Walleij | 15def33 | 2006-09-19 14:27:02 +0000 | [diff] [blame] | 635 | when sent to the device (this directory should be autodetected |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 636 | for use with calendar files, otherwise use the option |
Linus Walleij | 15def33 | 2006-09-19 14:27:02 +0000 | [diff] [blame] | 637 | -f "My Organizer" to sendfile for this) Apparently this file can |
| 638 | also contain tasklists. |
| 639 | |
| 640 | - Contact (.vcf) files should be stored in the folder "My Contacts" |
| 641 | when sent to the device. (-f "My Contacts") |
| 642 | |
| 643 | - Some devices are picky about the name of the calendar and |
| 644 | contact files. For example the Zen Microphoto wants: |
| 645 | |
Linus Walleij | b1318d1 | 2006-09-25 14:59:26 +0000 | [diff] [blame] | 646 | Calendar: My Organizer/6651416.ics |
| 647 | Contacts: My Organizer/6651416.vcf |
| 648 | |
| 649 | |
| 650 | Syncing in with Evolution and Creative Devices |
| 651 | ---------------------------------------------- |
| 652 | |
| 653 | Evolution can easily export .ics an .vcf files, but you currently |
| 654 | need some command-line hacking to get you stuff copied over in |
| 655 | one direction host -> device. The examples/ directory contains a script |
| 656 | created for the Creative Zen Microphoto by Nicolas Tetreault. |
| 657 | |
Linus Walleij | 6e8cef4 | 2006-12-03 20:45:04 +0000 | [diff] [blame] | 658 | |
Linus Walleij | d132d8e | 2007-04-03 23:24:54 +0000 | [diff] [blame] | 659 | Lost symbols |
| 660 | ------------ |
| 661 | |
| 662 | Shared libraries can be troublesome to users not experienced with |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 663 | them. The following is a condensed version of a generic question |
Linus Walleij | d132d8e | 2007-04-03 23:24:54 +0000 | [diff] [blame] | 664 | that has appeared on the libmtp mailing list from time to time. |
| 665 | |
| 666 | > PTP: Opening session |
| 667 | > Queried Creative Zen Vision:M |
| 668 | > gnomad2: relocation error: gnomad2: undefined symbol: |
| 669 | > LIBMTP_Get_Storageinfo |
| 670 | > (...) |
| 671 | > Are these type of errors related to libmtp or something else? |
| 672 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 673 | The problem is of a generic nature, and related to dynamic library |
Linus Walleij | d132d8e | 2007-04-03 23:24:54 +0000 | [diff] [blame] | 674 | loading. It is colloquially known as "dependency hell". |
| 675 | (http://en.wikipedia.org/wiki/Dependency_hell) |
| 676 | |
| 677 | The gnomad2 application calls upon the dynamic linker in Linux to |
| 678 | resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol |
| 679 | (ELF symbol, or link point or whatever you want to call them, a |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 680 | symbol is a label on a memory address that the linker shall |
Linus Walleij | d132d8e | 2007-04-03 23:24:54 +0000 | [diff] [blame] | 681 | resolve from label to actual address.) |
| 682 | For generic information on this subject see the INSTALL file and |
| 683 | this Wikipedia page: |
| 684 | |
| 685 | http://en.wikipedia.org/wiki/Library_(computing) |
| 686 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 687 | When Linux /lib/ld-linux.so.X is called to link the symbols compiled |
| 688 | into gnomad2 (or any other executable using libmtp), it examines the |
| 689 | ELF file for the libmtp.so.X file it finds first and cannot resolve |
Linus Walleij | d132d8e | 2007-04-03 23:24:54 +0000 | [diff] [blame] | 690 | the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 691 | problem witj) from it, since it's probably not there. There are many |
Linus Walleij | d132d8e | 2007-04-03 23:24:54 +0000 | [diff] [blame] | 692 | possible causes of this symbol breakage: |
| 693 | |
| 694 | 1) You installed precompiled libmtp and gnomad2 packages (RPMs, debs |
| 695 | whatever) that do not match up. Typical cause: your gnomad2 package was |
| 696 | built against a newer version of libmtp than what's installed on your |
| 697 | machine. Another typical cause: you installed a package you found on |
| 698 | the web, somewhere, the dependency resolution system did not protest |
| 699 | properly (as it should) or you forced it to install anyway, ignoring |
| 700 | some warnings. |
| 701 | |
| 702 | 2) You compiled libmtp and/or gnomad2 from source, installing both or |
| 703 | either in /usr/local/lib and /usr/local/bin. This means at compile-time |
| 704 | gnomad2 finds the libmtp library in /usr/local/lib but at runtime, it |
| 705 | depends on the Linux system wide library loader (/lib/ld-linux.so.X) in |
| 706 | order to resolve the symbols. This loader will look into the file |
| 707 | /etc/ld.so.conf and/or the folder /etc/ld.so.conf.d in order to find |
| 708 | paths to libraries to be used for resolving the symbols. If you have |
| 709 | some older version of libmtp in e.g. /usr/lib (typically installed by a |
| 710 | package manager) it will take precedence over the new version you just |
| 711 | installed in /usr/local/lib and the newly compiled library in |
| 712 | /usr/local/lib will *not* be used, resulting in this error message. |
| 713 | |
| 714 | 3) You really did install the very latest versions (as of writing libmtp |
| 715 | 0.1.5 and gnomad2 2.8.11) from source and there really is no |
| 716 | pre-installed package of either on your machine. In that case I'm |
| 717 | totally lost, I have no idea what's causing this. |
| 718 | |
| 719 | Typical remedies: |
| 720 | |
| 721 | 1) If you don't want to mess around with your system and risk these |
| 722 | situations, only use pre-packaged software that came with the |
| 723 | distribution or its official support channels. If it still breaks, |
| 724 | blame your distribution, they're not packaging correctly. Relying on |
| 725 | properly packaged software and not installing things yourself *is* the |
| 726 | Linux solution to the "dependency hell" problem. |
| 727 | |
| 728 | 2) Read about dynamically linked library handling until the stuff I wrote |
| 729 | about in the previous list sounds like music to your ears, inspect |
| 730 | your /lib, /usr/lib, /usr/local/lib, /etc/ld.so.conf and the |
| 731 | /etc/ld.so.conf.d, remove all pre-packed versions using RPM, APT, |
| 732 | YaST or whatever your distribution uses, compile libmtp and gnomad2 |
| 733 | (or whatever) from source only and you will be enlighted. |
| 734 | |
| 735 | I don't know if this helps you, it's the best answer we can give. |
Linus Walleij | 387e37a | 2008-10-29 17:22:22 +0000 | [diff] [blame] | 736 | |
| 737 | |
| 738 | API is obscure - I want plain files! |
| 739 | ------------------------------------ |
| 740 | |
| 741 | PTP/MTP devices does not actually contain "files", they contain |
| 742 | objects. These objects have file names, but that is actually |
| 743 | just a name tag on the object. |
| 744 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 745 | Folders/directories aren't really such entities: they are just |
Linus Walleij | 387e37a | 2008-10-29 17:22:22 +0000 | [diff] [blame] | 746 | objects too, albeit objects that can act as parent to other |
Linus Walleij | 8aba06d | 2008-12-28 08:26:57 +0000 | [diff] [blame] | 747 | objects. They are called "associations" and are created in atomic |
Linus Walleij | 387e37a | 2008-10-29 17:22:22 +0000 | [diff] [blame] | 748 | fashion and even though there is an MTP command to get all the |
Linus Walleij | 8aba06d | 2008-12-28 08:26:57 +0000 | [diff] [blame] | 749 | associations of a certain association, this command is optional |
| 750 | so it is perfectly possible (and most common, actually) to create |
| 751 | devices where the "folders" (which are actually associations) have |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 752 | no idea whatsoever of what files they are associated as parents to |
Linus Walleij | 387e37a | 2008-10-29 17:22:22 +0000 | [diff] [blame] | 753 | (i.e. which files they contain). This is very easy for device |
Linus Walleij | 8aba06d | 2008-12-28 08:26:57 +0000 | [diff] [blame] | 754 | manufacturers to implement, all the association (i.e. finding out |
| 755 | which files are in a certain folder) has to be done by the MTP |
| 756 | Initiator / host computer. |
Linus Walleij | 387e37a | 2008-10-29 17:22:22 +0000 | [diff] [blame] | 757 | |
| 758 | Moving a file to a new folder is for example very simple in a |
| 759 | "real" file system. In PTP/MTP devices it is often not even possible, |
| 760 | some devices *may* be able to do that. But actually the only |
| 761 | reliable way of doing that is to upload the file to the host, |
Linus Walleij | 8aba06d | 2008-12-28 08:26:57 +0000 | [diff] [blame] | 762 | download it with the new parent, then delete the old file. |
Linus Walleij | 387e37a | 2008-10-29 17:22:22 +0000 | [diff] [blame] | 763 | We have played with the idea of implementing this time consuming |
| 764 | function, perhaps we will. |
| 765 | |
Linus Walleij | 8aba06d | 2008-12-28 08:26:57 +0000 | [diff] [blame] | 766 | Then the issue that in PTP/MTP it is legal for two files to have |
| 767 | exactly the same path as long as their object IDs differ. A |
| 768 | folder/association can contain two files with the exact same name. |
| 769 | (And on the Creative devices this even works, too, though most devices |
| 770 | implicitly fail at this.) Perhaps one could add some custom hook for |
| 771 | handling that, so they become /Foo.mp3 and /Foo.mp3(1) or something |
| 772 | similar, but it's really a bit kludgy. |
| 773 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 774 | Playlists and albums aren't really files, thinking about |
Linus Walleij | 387e37a | 2008-10-29 17:22:22 +0000 | [diff] [blame] | 775 | them as files like the hacks in libgphoto2 is really backwards. They are |
| 776 | called associations and are more like a symbolic link that links in a |
| 777 | star-shaped pattern to all the files that are part of the album/playlist. |
| 778 | Some devices (Samsung) thought that was too complicated and have a |
| 779 | different way of storing playlists in an UTF-16 encoded .spl-like file |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 780 | instead! This is why playlists/albums must have their own structs and |
Linus Walleij | 387e37a | 2008-10-29 17:22:22 +0000 | [diff] [blame] | 781 | functions. |
| 782 | |
Linus Walleij | 8aba06d | 2008-12-28 08:26:57 +0000 | [diff] [blame] | 783 | Plain file access also assumes to be able to write files of an |
| 784 | undetermined size, which is simply not possible in a transactional |
| 785 | file system like PTP/MTP. (See further below.) |
| 786 | |
Linus Walleij | 387e37a | 2008-10-29 17:22:22 +0000 | [diff] [blame] | 787 | |
| 788 | I Want Streaming! |
| 789 | ----------------- |
| 790 | |
| 791 | Streaming reads is easy. Just connect the output file descriptor from |
| 792 | LIBMTP_Get_File_To_File_Descriptor() (and a similar function for tracks) |
| 793 | wherever you want. |
| 794 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 795 | People have connected this to TCP sockets for streaming web servers |
| 796 | etc, works like a charm. Some devices will even survive if the callback |
Linus Walleij | 387e37a | 2008-10-29 17:22:22 +0000 | [diff] [blame] | 797 | functions return non-zero and cancel the download. Some devices will |
| 798 | lock up and even require a reset if you do that. Devices are poorly |
| 799 | implemented so that's life. If you want to stream off a device, the |
| 800 | best idea is always to stream the entire file and discard the stuff |
| 801 | at the end you don't want. It will incur a delay if you e.g. want to |
| 802 | skip between tracks, sadly. |
| 803 | |
| 804 | Then we get to the complicated things: streaming WRITES... |
| 805 | |
| 806 | There is a function: |
| 807 | LIBMTP_Send_File_From_File_Descriptor() (and similar for tracks) |
| 808 | which will write a file to a device from a file descriptor, which may |
| 809 | be a socket or whatever. |
| 810 | |
| 811 | HOWEVER: this requires a piece of metadata with the .filesize properly |
| 812 | set first. |
| 813 | |
| 814 | This is not because we think it is funny to require that, the protocol |
| 815 | requires it. The reason is that PTP/MTP is a transactional file system |
| 816 | and it wants to be able to deny file transfer if the file won't fit on |
| 817 | the device, so the transaction never even starts, it's impossible to |
| 818 | start a transaction without giving file length. |
| 819 | |
| 820 | People really want streaming so I tried a lot of hacks to see if they |
| 821 | would work, such as setting file size to 0xffffffffU or something other |
| 822 | unnaturally big and then aborting the file transfer when the stream ends. |
| 823 | It doesn't work: either the device crashes or the file simply disappears |
| 824 | since the device rolls back all failed transactions. |
| 825 | |
| 826 | So this is an inherent limitation of the PTP/MTP protocol. |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 827 | |
| 828 | |
Linus Walleij | ae89021 | 2012-02-16 01:56:19 +0100 | [diff] [blame] | 829 | I want to remote control my device! |
| 830 | ----------------------------------- |
| 831 | |
| 832 | I have both good and bad news for you. |
| 833 | |
| 834 | The good news is that the MTP protocol has well-defined commands to play |
| 835 | back content on a device. Operation 0xD411 (PTP_DPC_MTP_PlaybackObject) |
| 836 | will start playing back a file on the device (whatever that may mean if |
| 837 | this is not a music or video file), and operation 0xD403 can set the |
| 838 | playback volume to save your ears. Then there are operations to |
| 839 | determine how far into the current file you currently are, so as to |
| 840 | support say progress bars. |
| 841 | |
| 842 | Since these commands have been around since the dawn of the MTP protocol |
| 843 | and since it was developed in cooperation with Creative Technology, this |
| 844 | is probably a requested feature from the Creative people who already had |
| 845 | support for playback on their devices using the PDE protocol back then. |
| 846 | |
| 847 | Anyway, here are the bad news: |
| 848 | [logs]$ grep d411 * |
| 849 | mtp-detect-trekstor-vibez.txt: 0xd411: Playback Object |
| 850 | |
| 851 | Aha there is only one known device in the world which actually supports |
| 852 | playback on the device. So either you go buy the Trekstor Vibez, or you |
| 853 | can forget about this. You could always try asking your hardware vendor |
| 854 | of choice to go implement this. |
| 855 | |
| 856 | Since none of the core developers of libmtp has the Trekstor device, this |
| 857 | is not yet implemented in libmtp. |
| 858 | |
| 859 | |
Linus Walleij | be8b03b | 2009-10-16 21:19:35 +0000 | [diff] [blame] | 860 | I make MTP devices! |
| 861 | ------------------- |
| 862 | |
| 863 | If you are a device vendor there is a lot you can do for libmtp: |
| 864 | |
| 865 | * Please consider assigning one of your employees as a contact person |
| 866 | for libmtp, have them sign up to the libmtp development list and answer |
| 867 | questions and post new device ID:s as they are released to our |
| 868 | mailing list. |
| 869 | |
| 870 | * If you want to help even more, assign someone to look deeper into |
| 871 | error reports on your specific devices, understand why your firmware |
| 872 | may require some special device flags and what can be done about it. |
| 873 | |
| 874 | * Do you have spare devices you can give us? Send them to Richard (Mac |
| 875 | support) or Linus (Linux support). (So far nobody did that except for |
| 876 | Microsoft who sent us a Zune by proxy!) |
| 877 | |
| 878 | Vendors do need help from libmtp too, especially we want to help |
| 879 | vendors improve their MTP stacks, because they all suffer from the |
| 880 | same problem: the lack of a proper conformance test has made many devices |
| 881 | incompliant with the MTP specification as it is published today: most |
| 882 | devices are just compliant with the Windows MTP stack, and don't work |
| 883 | out-of-the-box with libmtp. We need someone on the inside to help in |
| 884 | bug reporting vendors MTP stacks internally so these issues are raised. |
| 885 | A good way to go toward better MTP compliance is to test with an |
| 886 | alternative implementation of the stack. In e.g. IETF standardization |
| 887 | it is compulsory for an RFC to have atleast two independent implementations |
| 888 | for it to reach the status as standard. |
| 889 | |
| 890 | Being compliant with libmtp is also more and more important for |
| 891 | vendors: libmtp is being deployed in some embedded systems like |
| 892 | set-top-boxes etc. It will be very irritating for customers if a device |
| 893 | will not dock properly with some home entertainment equipment just because |
| 894 | it is based on Linux and libmtp and not the Windows MTP stack. |
Linus Walleij | 5f5c69f | 2011-06-26 14:34:13 +0200 | [diff] [blame] | 895 | |
| 896 | Autodetect with gudev |
| 897 | --------------------- |
| 898 | |
| 899 | Previously you would use HAL to detect devices being plugged in. Nowadays |
| 900 | we use udev directly, or though the GNOME libgudev library. LIBMTPs |
| 901 | default udev rules export the proper properties to detect any MTP device |
| 902 | automatically, here is a verbose example derived from gnomad2: |
| 903 | |
| 904 | #define G_UDEV_API_IS_SUBJECT_TO_CHANGE |
| 905 | #include <gudev/gudev.h> |
| 906 | const char * const gudev_subsystems[] = { "usb", NULL }; |
| 907 | GUdevClient *gudev_client; |
| 908 | guint uevent_id; |
| 909 | guint uevent_bus_hooked = 0; |
| 910 | guint uevent_device_hooked = 0; |
| 911 | |
| 912 | |
| 913 | static void uevent_cb(GUdevClient *client, const char *action, GUdevDevice *device, void *data) |
| 914 | { |
| 915 | guint64 devicenum; |
| 916 | guint vendor; |
| 917 | guint model; |
| 918 | guint busnum; |
| 919 | guint devnum; |
| 920 | guint mtpdevice; |
| 921 | |
| 922 | devicenum = (guint64) g_udev_device_get_device_number(device); |
| 923 | g_print("%s event for %s (%"G_GINT64_MODIFIER"x)", action, |
| 924 | g_udev_device_get_sysfs_path (device), devicenum); |
| 925 | |
| 926 | /* get device info */ |
| 927 | vendor = get_property_as_int(device, "ID_VENDOR_ID", 16); |
| 928 | model = get_property_as_int(device, "ID_MODEL_ID", 16); |
| 929 | busnum = get_property_as_int(device, "BUSNUM", 10); |
| 930 | devnum = get_property_as_int(device, "DEVNUM", 10); |
| 931 | mtpdevice = get_property_as_int(device, "ID_MTP_DEVICE", 10); |
| 932 | |
| 933 | if (vendor == 0 || model == 0) { |
| 934 | g_print("couldn't get vendor or model ID for device at (%x:%x)\n", |
| 935 | busnum, devnum); |
| 936 | return; |
| 937 | } else { |
| 938 | g_print("vendor = %x, model = %x, bus = %x, device = %x\n", |
| 939 | vendor, model, busnum, devnum); |
| 940 | } |
| 941 | |
| 942 | if (mtpdevice) { |
| 943 | g_print("device is MTP compliant\n"); |
| 944 | |
| 945 | if (g_str_equal(action, "add") && |
| 946 | uevent_bus_hooked == 0 && |
| 947 | uevent_device_hooked == 0) { |
| 948 | g_print(MTP device plugged in!\n"); |
| 949 | uevent_bus_hooked = busnum; |
| 950 | uevent_device_hooked = devnum; |
| 951 | scan_jukebox(NULL); |
| 952 | } else if (g_str_equal (action, "remove") && |
| 953 | uevent_bus_hooked == busnum && |
| 954 | uevent_device_hooked == devnum) { |
| 955 | g_print("MTP device removed!\n"); |
| 956 | uevent_bus_hooked = 0; |
| 957 | uevent_device_hooked = 0; |
| 958 | } |
| 959 | } |
| 960 | } |
| 961 | |
| 962 | |
| 963 | |
| 964 | (...) |
| 965 | /* |
| 966 | * Monitor udev device events - we're only really interested in events |
| 967 | * for USB devices. |
| 968 | */ |
| 969 | gudev_client = g_udev_client_new(gudev_subsystems); |
| 970 | uevent_id = g_signal_connect_object(gudev_client, |
| 971 | "uevent", |
| 972 | G_CALLBACK(uevent_cb), |
| 973 | NULL, 0); |
Linus Walleij | 187ac2f | 2012-05-02 19:08:03 +0200 | [diff] [blame] | 974 | |
| 975 | SKETCH OF AN OVERVIEW |
| 976 | --------------------- |
| 977 | |
| 978 | Draft agenda for a talk on MTP devices submitted for the Android |
| 979 | builders summit, might come to recycle this: |
| 980 | |
| 981 | - Protocol overview |
| 982 | - libmtp interface |
| 983 | - relation to libgphoto2 |
| 984 | - Device sins |
| 985 | - Android bugs |
| 986 | - Samsungs special Android MTP stack |
| 987 | - SonyEricsson Aricent stack for Xperia Androids pre 4.0, broken headers! |
| 988 | - Detecting from vendor extension, can fix in newer extensions! |
| 989 | - Autoprobing on Linux |
| 990 | - Color devices do not like autoprobing |
| 991 | - Ideas?? |
| 992 | - Mode switch devices? |
| 993 | - MTPZ |