readme

Linux平台。一个好用的ptp传输工具。用来从相机向pc传输照片

libptp2 (c)2001-2006 Mariusz Woloszyn <[e-mail]>
ptpcam  (c)2001-2006 Mariusz Woloszyn <[e-mail]>

=====================
*About this software*
=====================

You may find new versions of this software at:
http://libptp.sf.net/

The ./src folder contains following code:
ptp.c		- the main libptp2 code
ptp.h		- libptp2 header files
ptp-pack.c	- this file is included into ptp.c (internal code)
ptpcam.h	- ptpcam header file
ptpcam.c	- the software to manipulate PTP cameras;
		  it does things that you can't do with gphoto2

The libptp2 library is under development yet, but is considered to be
functional and quite stable.
It was written to be used with gphoto2, but can be easily used with any other
software.

==============
*Requirements*
==============

Currently this package requires libusb to build ptpcam.
The libptp2 library itself is transport layer independent and does not require
libusb, however no other transport layer has been tested due to lack
of PTP non-USB devices.
You can obtain libusb at http://libusb.sf.net/
BE AWARE THAT libusb-0.1.10 contained bugs that might affect your camera!
Use newer version or libusb-0.1.8 instead.
If you want to build this library (for test purposes) on a box without
libusb pass --disable-ptpcam option to configure script.
A PTP camera seems to be required also to take full advantage of this package.


==================
*What is libptp2?*
==================

libptp2 is a library used to communicate with PTP devices like still
imaging cameras.
At the current stage you may use ptpcam tool boundled with libptp2 to perform
some basic operations like downloading photos or setting camera properties.
For other operations and GUI you might consider using libgphoto2
(which contains forked version of libptp2 code), gphoto2 and gtkam; 
see http://www.gphoto.org.


===================
*Supported Cameras*
===================

The list of PTP cameras is constantly growing. Most (if not all) USB still
cameras designed after 2002 are PTP compliant. Below is the list of vendors
implementing PTP in their cameras:

* Kodak
* HP
* Nikon
* Canon
* Panasonic
* Olympus
* Konika
* Minolta
* Fuji
* Ricoh
* Sony

Note that for some HP, Nikon, Canon, Sony and possibly other cameras
you have to switch them to PTP mode as in most cases the camera is dual mode:
PTP and USB Mass Storage or PTP and native.
For some cameras it even changes the Product ID number, so don't panic 
just switch the mode.
Don't ask me how to do it. Refer to camera documentation.

Please note that if your camera is supporting PTP it does NOT mean that
it is capable of performing all PTP operations (like triggering capture,
uploading files or tweaking properties). Sony cameras are good example of
poor PTP implementation where the only thing you can do is downloading files.

=============
*Quick Start*
=============

First of all you need kernel USB support. Please refer to your OS
documentation for more info!
For Linux users you need "Preliminary USB device filesystem" and "USB Host
Controller" (the one for your hardware: EHCI, OHCI or UHCI) support in your
kernel.
CAUTION: there was a bug in Linux Kernel 2.4.18 UHCI driver so make sure you
use more recent kernel!
If you got a kernel support, make sure that your usbdevfs is mounted under
/proc/bus/usb. In my case the fstab entry looks like this:

usb     /proc/bus/usb   usbdevfs        defaults,user 0 0

(NO, the entry in fstab isn't enough, you have to type: mount /proc/bus/usb).
If you want to run ptpcam as regular user read this:
http://gphoto.sourceforge.net/doc/manual/permissions-usb.html
although I suggest performing all tests as root unless you're security
paranoid.

If you have a PTP camera connected to your computer it should be detected by
invoking "ptpcam --list-devices".
In my case the output looks like this:

root@emsi(chroot):~# ptpcam --list-devices
Listing devices...
bus/dev vendorID/prodID device model
002/035 0x040A/0x0400   Kodak mc3
002/036 0x040A/0x0500   DX3500 Digital Camera
001/027 0x040A/0x0160   DC4800 Zoom Digital Camera

If you get something like this:

emsi@emsi(chroot):~> ptpcam --list-devices
Listing devices...
bus/dev vendorID/prodID device model
ERROR: Could not open session!
Try to reset the camera.

it means that you did not read carefully what I wrote above about running
ptpcam as regular user or your camera has stalled (needs reset).

If you need some more debug try --verbose or --verbose=2 thus increasing the
verbose level.

What if you get "Found no PTP devices"?
If you're sure that your camera is a PTP camera please check your OS usb
config. In case of Linux make sure that you have usbdevfs mounted under
/proc/bus/usb. If so read the output of 'cat /proc/bus/usb/devices' and check
if your camera is listed there.
It might be that your camera is not in PTP mode. To verify so, issue:

cat /proc/bus/usb/devices | grep "Cls=06"

If you find something like this:

I:  If#= 0 Alt= 0 #EPs= 3 Cls=06(still) Sub=01 Prot=01 Driver=(none)
                          ^^^^^^^^^^^^^
that means that your camera is in PTP mode and should be detected.
If there is no interface of Class 6 refer to camera documentation to find
how to switch it into PTP mode.

You may also try to use --force option while listing cameras or talking to
it, but don't use it unless you really know what you are doing!!!
--force forces ptpcam to talk to non PTP devices [which makes sense only in
case of PTP device with interface class other than 6 (PTP), like Kodak DC240
with PTP firmware]. BE AWARE that talking PTPish to non PTP devices may
cause harmful damage!!!


============
*What next?*
============

I guess that you'd like to download images or tweak camera properties? ;)

Use "ptpcam --get-all-files" to download all images from your camera.
By default all images are copied to local folder and filename and creation
time is preserved. By default the download operation skips a file if it
finds one with the same name in local folder. This enables you to do
quick-sync downloading only the newly captured files. Of course you can
request to overwrite existing files passin --overwrite on command line.
You may also download a specific file using --get-file=HANDLE providing object
handle as a parameter (you can find it with --list-files).
If ptpcam detects more than one camera you need to pass --bus=BUS-NUMBER and,
or --dev=DEV-NUMBER arguments otherwise ptpcam tries to talk to first detected
camera. If you specify only bus or dev number ptpcam talks to first matching
camera.

To list all available camera properties use "ptpcam --list-properties"
Unfortunately if you have bought a high-end camera or a very expensive PTP
camera it DOES NOT mean that it supports setting any properties. The problem
is that manufacturers do not specify in documentation what properties or
operations are supported by the given camera. In most cases you never know
until you buy the camera. [I'll try to provide a list of supported camera
properties and operations on libptp.sf.net]

Let's say that you get something like this:

root@emsi(chroot):~# ptpcam --list-properties
Listing properties...
Querying: DX3500 Digital Camera
0x5001 : Battery Level

It means that your camera (in this case DX3500 Digital Camera) supports only
one property, which is "Battery Level" (property number 0x5001). Not much,
but you still can try to list its value:

root@emsi(chroot):~# ptpcam --show-property=5001
Camera: DX3500 Digital Camera
Property 'Battery Level'
Current value is 100
Factory default value is 100
The property is read only, enumerated. Allowed values are:
0
10
100

As you can see --show-property argument does not require 0x, that's for your
convenience. ;)
The output of this command is quite verbose. It tells you about Current value,
Factory default value and the property type. The property type may vary among
different cameras! In this camera 'Battery Level' is read only and
enumerated. Allowed values are 0, 10 and 100 which (more or less) means:
0 - low battery lever (may shut down immediately), 10 - medium battery
level, 100 - full battery level. However for a different camera this
property may be defined as range of 1 to 100 with step of 1.
That's just an example.

Now let's look at the list of properties of another camera:

root@emsi(chroot):~# ptpcam --list-properties
Listing properties...
Querying: DC4800 Zoom Digital Camera
0x5001 : Battery Level
0x5003 : Image Size
0x5004 : Compression Setting
0x5005 : White Balance
0x5006 : RGB Gain
0x5007 : F-Number
0x5008 : Focal Length
0x5009 : Focus Distance
0x500a : Focus Mode
0x500b : Exposure Metering Mode
0x500c : Flash Mode
0x500d : Exposure Time
0x500e : Exposure Program Mode
0x500f : Exposure Index (film speed ISO)
0x5010 : Exposure Bias Compensation
0x5011 : Date Time
0x5013 : Still Capture Mode
0x5015 : Sharpness
0x5016 : Digital Zoom
0x5017 : Effect Mode
0x5018 : Burst Number
0x501c : Focus Metering Mode
0xd001 : EK Color Temperature
0xd002 : EK Date Time Stamp Format
0xd003 : EK Beep Mode
0xd004 : EK Video Out
0xd005 : EK Power Saving
0xd006 : EK UI Language

All properties of numbers starting with 0x50 are standard PTP properties,
although for many of them the type (enumerated or range) and value meaning
are NOT specified by the PTP standard and may vary among different cameras!
The properties starting with 0xd0 are PTP extension (in this case EK means
Eastman Kodak extension) and in most cases are not known to public at all.
Probably you will have to reverse-engineer their meaning (I'm eager to
receive a feedback from you in such case! ;).


==========================
* Setting property values*
==========================

For example if you'd like to change the 'Image Size' property you have to do
that in two steps. First display the property using --show-property switch.
Determine whether the property is settable, what is the type of value
(a number or string) and which values are supported!
Keep in mind that some properties are settable only in certain camera
states or modes. Also the valid values may vary depending on current camera
state!
OK. Let's get back to our example. To display property 'Image Size',
which number is 0x5003 you have to type:

root@emsi(chroot):~# ptpcam --show-property=5003
Camera: DC4800 Zoom Digital Camera
Property 'Image Size'
Data type is 0xffff
Current value is "2160x1440"
Factory default value is "2160x1440"
The property is settable, enumerated. Allowed values are:
"2160x1440"
"1800x1200"
"1536x1024"
"1080x720"

As you can see, this camera supports four different image sizes. The
property value is a string (values are printed within quotation marks).
To change 'Image Size' property pass --val=VALUE option to ptpcam while still
specifying the property with --set-property=PROPERTY_NUMBER.
Note that only certain values are allowed.

In our example let it look like this:

root@emsi(chroot):~# ptpcam --set-property=5003 --val=1080x720
Camera: DC4800 Zoom Digital Camera
Property 'Image Size'
Data type is 0xffff
Current value is "2160x1440"
Factory default value is "2160x1440"
The property is settable, enumerated. Allowed values are:
"2160x1440"
"1800x1200"
"1536x1024"
"1080x720"
Setting property value to '1080x720'

If everything goes OK, no error is displayed. You may verify, of course,
if the property value was set properly.
If you get something like this:

PTP: Invalid Device Prop Value

it indicates that the property value was not set due to invalid values.

Keep in mind that in most cases changing one property may cause another one
property to change! That happens especially in any Automated modes!!!

FIXME: The device should report that another property was changed issuing
DevicePropChanged event! We may catch that and report to user.

=================
*Common problems*
=================

Sometimes it might happen that the device claims to support given property
but does not respond to --show-property request. In most cases it's because of
improper PTP implementation on the camera side.
Sometimes the list of supported properties might vary while changing
camera mode.
Moreover, given property may not have any meaning in a certain camera state.
For example setting or getting 'Focus Distance' property may not be allowed
in automated camera mode! In such case try to switch the camera to manual
mode.
For example my Kodak DC4800 fails over --show-property=5006
(which is "RGB Gain") if RGB Gain is not set. It looks like this:

root@emsi(chroot):~# ptpcam --show-property=5006
Camera: DC4800 Zoom Digital Camera
Property 'RGB Gain'
ERROR: Could not get device property description!
Try to reset the camera.

In such a case you need to issue a --reset request to the camera:

root@emsi(chroot):~# ptpcam --reset
Resetting input pipe!
Device status OK

It's a good practice to verify whether the reset went OK issuing
--list-devices. Sometimes one or two more reset may be needed to properly
reset the camera.


=========================
*Standard PTP Properties*
=========================


Below I am providing a short list of properties and their meaning values
according to PTP specification.

0x5001 : Battery Level
	 DataType: UINT8
	 Forms: Enum, Range
	 PTP standard does not define any special values, however for number
	 of Kodak devices 0 means no power (alternative power source), 10
	 means medium battery lever and 100 means full battery.

0x5002 : Functional Mode
	 DataType: UINT16
	 Forms: Enum
	 This property indicates whether the device is in an alternate mode
	 that provides a different set of capabilities (i.e. supported
	 operations, properties, events, etc.). If the device supports only
	 one mode, this value should always be zero.
	 PTP standard specifies following values:
	 0x0000 - Standard Mode
	 0x0001 - Sleep State
	 All other values with bit 15 set to 0 are Reserved.
	 All values with bit 15 set to 1 are Vendor Specific.

0x5003 : Image Size
	 DataType: String
	 Forms: Enum, Range
	 "This property describes the height and width of the image that will 
	 be captured in pixels supported by the device." The string is of the
	 format "WxH" where the W represents the width and the H represents
	 the height represented as unsigned integers.

0x5004 : Compression Setting
	 DataType: UINT8
	 Forms: Enum, Range
	 Quoted from PTP (PIMA 15740) specs:
	 "Compression setting is a property intended to be as close as is
	 possible to being linear with respect to perceived image quality
	 over a broad range of scene content, and is represented by either a
	 range or an enumeration of integers. Low integers are used to
	 represent low quality (i.e. maximum compression) while high
	 integers are used to represent high quality (i.e. minimum
	 compression). No attempt is made in this standard (PTP) to assign
	 specific values of this property with any absolute benchmark, so
	 any available settings on a device are relative to that device only
	 and are therefore device-specific."

0x5005 : White Balance
	 DataType: UINT16
	 Forms: Enum
	 PTP standard specifies following values:
	 0x0000 - Undefined
	 0x0001 - Manual
	 0x0002 - Automatic
	 0x0003 - One-push Automatic
	 0x0004 - Daylight
	 0x0005 - Fluorescent
	 0x0006 - Tungsten
	 0x0007 - Flash
	 All other values with bit 15 set to zero are reserved.
	 All values with bit 15 set to 1 are vendor-defined.

	 Manual means that white balance is set directly using the RGB Gain
	 (0x5006) property.
	 Automatic indicates that the device sets this property using some