________________________________________________________________________
________________________________________________________________________

    PTPro v1.0 
    Copyright (c) 2006 Richard L Walsh <rich@e-vertise.com>

    PTPro incorporates the following copyrighted material:
    * libptp2  - Copyright (c) 2001-2005 Mariusz Woloszyn
    * libusb   - Copyright (c) 2001 Johannes Erdfelt
    * usbcalls - Copyright (c) 2001,2002 Markus Montkowski

    PTPro is released under the GNU Public License;
    see COPYING for the entire text of the license.

________________________________________________________________________

Introduction
________________________________________________________________________

PTPro is a commandline utility for retrieving pictures and information
from your PTP (Picture Transfer Protocol) based digital camera.  PTPro
uses only generic PTP features so it should work with most cameras
produced in the last few years but it will be unable to exploit any
special features they may have.  As of the release date, it has only
been tested with a Canon Powershot A610.

________________________________________________________________________

Installation
________________________________________________________________________

PTPro relies on Markus Montkowski's usbresmg.sys device driver which
is included in the PTPro package.  Many OS/2-eCS systems already have
it installed, but if yours doesn't, copy it somewhere convenient
(e.g. \OS2\BOOT), add this line to config.sys, then reboot:
    DEVICE=X:\OS2\BOOT\USBRESMG.SYS

PTPro also requires libc06.dll which you can get from:
    ftp://ftp.netlabs.org/pub/gcc/libc-0.6.0-ga2.zip

__________________________________________________________________________

Usage
__________________________________________________________________________

All commandline options must be specified individually, each with a
leading hyphen ('-'), e.g.:  ptpro -l -v  _not_  ptpro -lv


First use
=========
After attaching your camera, you may have to set it to "playback" mode
(e.g. on my Canon, there's a switch on the back). Then, enter this at
the commandline:  ptpro -d   You should see a display like this:

 Device list
 ===========
 Bus  Device  VendorID  ProductID  Device
  1      2     0x04A9    0x30FD    Canon PowerShot A610

If instead you get "Found no PTP devices", try:  ptpro -d -F
The '-F' forces the app to treat all USB devices as PTP devices.  This
sometimes works with older cameras that don't fully comply with the PTP
standard.  If it does work, note the device number.  You will have to
specify it for all subsequent commands to ensure PTPro talks to your
camera and not your mouse or printer, e.g.:  ptpro -F --dev=2 [etc...]


Normal use
==========
Entering ptpro -h will give you a complete list of commands.  Below
is a description of each:


List files:  ptpro -l  (that's a lowercase 'L')
-----------
This will display a listing of all files stored on the camera, e.g.:

 File list  Canon PowerShot A610
 =========  ====================

 Handle      Size     Date     Time   Name
    7     1721916  2006-01-15  00:52  IMG_0196.JPG
    8      870851  2006-01-15  00:53  IMG_0197.JPG
    9     1730758  2006-01-15  00:54  IMG_0198.JPG
   10     1699399  2006-01-15  00:56  IMG_0199.JPG
   11     1126038  2006-01-15  23:54  IMG_0200.JPG
   13     1558298  2006-01-15  23:56  IMG_0201.JPG
   14     1589410  2006-01-15  23:56  IMG_0202.JPG
 [etc...]

The 'Handle' identifies a file and is needed to retrieve it.  PTPro
ignores folders, so there may be gaps in the numbering (e.g. notice
that handle 12 is missing - it's a folder, so it was omitted).


Save files:  ptpro -f [range] [filename]
-----------
You can save one or more files to disk, and can optionally rename them
by supplying a filename pattern.  If you want to replace an existing
file on disk, add the '-r' (replace) option to the command.

[range]
Range uses the handle numbers obtained from a file listing (see above).
Typically, it's entered as 'first-last' (e.g. '23-54').  Note that the
hyphen ('-') is required.  To save a single file, just enter a single
handle.

You can also use an asterisk ('*') instead.  Use a single asterisk to
save all files (e.g. ptpro -f *), or use it in a range to start at the
first file or end at the last file (e.g. '*-54' or '77-*').

[filename]
You can specify a path where PTPro should save your files, e.g.
     ptpro -f * g:\pix\holiday\*

You can also have it rename them if you wish.  The characters '*' and '#'
have special meanings:

'*' copies the file's current name and/or extension.  You can combine
    '*' with other characters to extend the file's original name, e.g.
        ptpro -f 12-17 *-cats.*

'#' inserts an ascending sequence number into the name.  Follow it with
    the value you want to start at, e.g.
        ptpro -f 12-17 cats#0097.*
    Note the leading zeroes here:  PTPro always outputs at least as many
    digits as you entered.  In this case, you'll get a four-digit number.
    Use this to ensure filenames are sorted in the correct order.

If your camera supplies the date & time a picture was taken, it will
be used as the file's creation date & last-write date.  Otherwise,
the current date & time will be used.


Save thumbnails:  ptpro -t [range] [filename]
----------------
Saving thumbnails is identical to saving full-sized picture files.
Of course, your camera must support the ability to retrieve them.


Erase files:  ptpro -e [range]
------------
Erasing files requires a range of handles like saving them does.
Please be careful:  you will not be prompted to confirm deletion!


Get file info:  ptpro -i [range]
--------------
This provides extended information about a given file.  For a picture
file, it shows the size (in pixels) of the picture and its thumbnail,
their formats, write-protection status, etc.  For non-picture objects,
additional info will help identify what the handle refers to.

Since the listing for each handle is fairly long, you'll probably want
to retrieve info for one handle at a time.


Other options
-------------
-c  Displays info about your camera such as its serial number, the
    format(s) it uses to save pictures, and the formats it uses for
    other files it creates.

-s  Shows info about your camera's storage (memory) capabilities,
    both built-in and external (i.e. flash memory card).

-o  List the operations or functions your camera can perform - PTPro
    supports a subset of these.  In addition to operations required
    by the PTP standard, many manufacturers have added their own
    features.  Since most of these are undocumented, they may be
    identified in the listing as 'unknown'.

-p  Lists the names of the properties or settings for your camera.  Since
    many (all?) of these are proprietary, their names may be unknown.

-g  Get or set the value of a specific property.
    To get a property, use:
        ptpro -g [number]  where [number] was one listed using '-p'
    To set a property, use:
        ptpro -g [number] --val=[xxx]  where [xxx] is the new value

-R  This is supposed to reset the camera in case it hangs.  Whether
    it actually does anything remains to be seen (when in doubt, turn
    the camera off, then back on).

-v  When entered as '-v' or '-v1', displays error messages generated
    by libptp2 and libusb (two libraries that PTPro uses).
    When entered as '-v2', provides debugging messages from PTPro and
    its libraries.

________________________________________________________________________

Known Problem
________________________________________________________________________

Using the included version of usbresmg.sys and IBM's USB drivers
v10.158, I encountered a single, major problem:

 -  when a camera operation times-out, the USB driver fails to unlock
    the memory buffer passed to it by the program.  Even though the
    program runs to completion, it is never flushed from the system.
    It's exe remains locked and the command prompt never returns.
    The only way to close the OS/2 window is to reboot.

    Note: this happened to me every time I tried to use GPhoto2,
    which is why I developed PTPro.  With PTPro, it only occurs
    if I turn off my camera while saving a large number of photos.

________________________________________________________________________
________________________________________________________________________

Rich Walsh <rich@e-vertise.com>
Ft Myers, FL

March 15, 2006
________________________________________________________________________

