readme

USB Host 开发中支持数码相机的源码。即Picture To Picture协议的完整实现

In most cases 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.
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
	 kind of automatic mechanism.
	 One-push Automatic means that the user must press the capture
	 button while pointing objective at a white field, at which time the
	 device determines the white balance setting.
	 Daylight means that the device sets the white balance to a value
	 that is suitable for daylight use.
	 Tungsten means that the device sets the white balance to a value
	 that is suitable for use with a tungsten light source.
	 Flash means that the white balance is set to a value that is
	 suitable for flash conditions.

0x5006 : RGB Gain
	 DataType: String
	 Forms: Enum, Range
	 This property takes the form of a string that is parsed as follows:
	 "R:G:B" where the R represents the red gain, the G represents the
	 green gain, and the B represents the blue gain. For example, for
	 an RGB ratio of red=2, green=3 and blue=4, the RGB string could be
	 "2:3:4" or "200:300:400". Each part of the RGB string is in decimal
	 form of UINT16 integer.

0x5007 : F-Number
	 DataType: UINT16
	 Forms: Enum
	 This property represents the aperture of the lens. The units are
	 equal to the F-Number scaled by 100.
	 Example values are: 280 (2.8), 560 (5.6), 800 (8), etc.

0x5008 : Focal Length
	 DataType: UINT32
	 Forms: Enum, Range
	 This property represents the 35mm equivalent focal length. The
	 units are equal to focal length in millimeters multiplied by 100.

0x5009 : Focus Distance
	 DataType: UINT16
	 Forms: Enum, Range
	 Value of this property represents the focus distance in
	 millimeters. A value of 0xFFFF means infinity.

0x500a : Focus Mode
	 DataType: UINT16
	 Forms: Enum
	 PTP standard specifies following values:
	 0x0000 - Undefined
	 0x0001 - Manual
	 0x0002 - Automatic
	 0x0003 - Automatic Macro (close-up)
	 All other values with bit 15 set to zero are reserver.
	 All values with bit 15 set to 1 are vendor-defined.

0x500b : Exposure Metering Mode
	 DataType: UINT16
	 Forms: Enum
	 PTP standard specifies following values:
	 0x0000 - Undefined
	 0x0001 - Average
	 0x0002 - Center-weighted-average
	 0x0003 - Multi-spot
	 0x0004 - Center-spot
	 All other values with bit 15 set to zero are reserved.
	 All values with bit 15 set to 1 are vendor-defined.

0x500c : Flash Mode
	 DataType: UINT16
	 Forms: Enum
	 PTP standard specifies following values:
	 0x0000 - Undefined
	 0x0001 - Auto flash
	 0x0002 - Flash off
	 0x0003 - Fill flash
	 0x0004 - Red eye auto
	 0x0005 - Red eye fill
	 0x0006 - External flash
	 All other values with bit 15 set to zero are reserved.
	 All values with bit 15 set to 1 are vendor-defined.

0x500d : Exposure Time
	 DataType: UINT32
	 Forms: Enum, Range
	 This property represents the shutter speed. It has units of seconds
	 scaled by 10000.
	 For example:
	 40 means 1/250 sec.
	 80 means 1/125 sec.
	 160 means 1/62.5 sec. and so on.

0x500e : Exposure Program Mode
	 DataType: UINT16
	 Forms: Enum
	 PTP standard specifies following values:
	 0x0000 - Undefined
	 0x0001 - Manual
	 0x0002 - Automatic
	 0x0003 - Aperture Priority
	 0x0004 - Shutter Priority
	 0x0005 - Program Creative (greater depth of field)
	 0x0006 - Program Action (faster shutter speed)
	 0x0007 - Portrait
	 All other values with bit 15 set to zero are reserved.
	 All values with bit 15 set to 1 are vendor-defined.

0x500f : Exposure Index (film speed ISO)
	 DataType: UINT16
	 Forms: Enum, Range
	 Value of this property represents the emulation of film speed
	 setting. The setting corresponds to the ISO designations. A value of
	 0xFFFF means automatic ISO setting.

0x5010 : Exposure Bias Compensation
	 DataType: INT16
	 Forms: Enum, Range
	 Value of this property represents the exposure compensation. The
	 units are in "stops" scaled by 1000. The setting values are in
	 APEX.
	 For example the value of -2000 (means 4X less energy on sensor)
	 two stops less exposure (darker image). The value of 1500 means
	 one and a half stops more exposure (2.25X more energy on sensors).

0x5011 : Date Time
	 DataType: String
	 Forms: none
	 Value of this property represents the device date and time in ISO
	 8601 format. It's a string of "YYYYMMDDThhmmss.s", where YYYY
	 represents the year, MM represents the month (01-12), DD is the day
	 of the month (01-31), T is a constant character, hh represents the
	 hour since midnight (00-23), mm is the minutes (00-59) past the
	 hour and ss.s is the seconds past the minute, with the ".s" being