libgphoto2/camlibs/canon/README

========================================================================
About this driver
=================

This driver was written to work with Canon digital cameras without
using any official specs which might exist for the communication
protocols.

For a disclaimer, see the GNU LESSER GENERAL PUBLIC LICENSE as
distributed with the libgphoto2 library.

This driver underwent a fairly complete rewrite around 2002-01-01, so
there may still be some wrinkles to be ironed out, especially with
older cameras.


========================================================================
Cameras supported
=================

 - PowerShot A50 (not tested)
 - PowerShot S10
 - PowerShot S20
 - PowerShot S30
 - PowerShot S40
 - PowerShot S100 / Digital IXUS
 - PowerShot IXY Digital (not tested)
 - PowerShot S300 / Digital IXUS 300
 - PowerShot IXY Digital 300  (not tested)
 - PowerShot G1
 - PowerShot G2
 - PowerShot A10 (not tested after rewrite)
 - PowerShot A20
 - PowerShot Pro90 IS (not tested)
 - EOS D30
 - Digital IXUS 330

Support for the following cameras is mostly there as they were supported
in gphoto 0.4.x but several API changes and rewrites have probably broken
something along the way. If you are interested in fixing it mail 
gphoto-devel@gphoto.net or philm@users.sourceforge.net:
 
 - PowerShot A5
 - PowerShot A5 Zoom
  
It doesn't  work with the  PowerShot  350. However, the  PS350 uses a
vaguely similar protocol, so some parts of the sources can probably be
shared.

The new driver doesn't cache much information any more. Still, if the
camera status changes during a session or if the driver gets stuck for
some other reason, the caches could be manually flushed using
"Configure camera".


========================================================================
Features supported
==================

- RS-232 serial cameras

- USB cameras (well tested)

- List all folders and image and movie files on the camera
  Optionally list all other files, too

- Download all file types from the camera as they are, i.e. without 
  any transformation. This includes CRW (Canon RaW) files, which are
  not processed to a standard image file format yet.

- Download thumbnail for all file types where thumbnails are available
  for

- Delete files. Handles single files and files which have an
  associated thumbnail file which is also removed.

- Download sound annotations to images (not tested)

- Create and Delete folders
  Note that this does not mean that the camera will use your
  directories to store the images.

- Upload files to camera for serial cameras

The following features are still experimental and not completely
working yet. Run configure with CFLAGS set to 

   "-DCANON_EXPERIMENTAL_CAPTURE -DCANON_EXPERIMENTAL_UPLOAD"

(or just one of them, if you want to test only one) to activate
them. Beware that this is work in progress, and no guarantees are
given at all, i.e. even less than the no guarantees we give for the
rest of the driver. 

NOTE: This may CAUSE DAMAGE TO THE CAMERA!

- Capture images controlled by the computer (CANON_EXPERIMENTAL_CAPTURE)
  (code courtesy of Emile Snyder)
  Emile Snyder has implemented most of the remote capture functionality,
  but not everything is understood about these commands yet and some
  camera models have their own will about how well these things work.

- Upload files to camera for USB cameras (CANON_EXPERIMENTAL_UPLOAD)
  (code courtesy of Matthias Kramm)


We are currently also working on support for the raw file format the
Canon cameras use (CRW -Canon RaW files). See

    http://www.shore.net/~dcoffin/powershot/

or
    http://www2.primushost.com/~dcoffin/powershot/

for details on the file format. Currently, only download of CRW files
is supported without any conversion to common image file formats. Use
the programs offered on the website mentioned above for conversion from 
CRW to something else.


========================================================================
Known Bugs
==========

* The PowerShot G1 and PowerShot 90 IS do not work properly when
  operating with the AC power adapter
* Shutting off the camera and rewaking it is not implemented


========================================================================
Change history
==============

For detailed changes, see the file ChangeLog. Yes, someone should
extract the user releavant information from ChangeLog and collect it
here.

Version 9 (17-APRIL-2001)
---------
- support added for
  PowerShot S300 / Digital IXUS 300 /PowerShot IXY Digital 300
  PowerShot A10 / PowerShot A20
  EOS D30


Version 8 (1-APRIL-2001)
---------
- This history have not been updated in a while...
- support for G1, S100, Ixus and Ixy was added
- upload support only on serial


Version 7 (25-JULY-2000)
---------
- Ported to gphoto2


Version 6 (19-MAY-2000)
---------

- Included USB support in the driver
- More options in the configuration file
- Debug output can be mostly disabled
- The driver now sets the "downloaded" bit on downloaded images

Version 5 (09-MAY-2000)
---------

- Support for  full-speed transfers (115200)
- Most protocol commands are  implemented, or at least discovered (see
  the 'Protocol' file)
- USB protocol description
- Get/Set owner name
- Get date
- Get firmware rev.
- Get battery status
- Use libgpio for serial transfers
- More reliable error recovery
- Better configuration dialog
- Support for all current powershot models (A5 to S20)
- Low battery condition detection


Version 4 (3-SEP-1999)
---------

 - changed uint16_t to unsigned short and removed inclusion of stdint.h, for
   compatibility :-(


Version 3 (1-SEP-1999)
---------

 - lowered number of tries when initializing from 50 to 10 (50 was for
   experiments)
 - increased camera ID buffer to be large enough for PS350 responses
 - serial input is now flushed before testing or attempting synchronization
 - directories are now sorted alphabetically, implicitly ordering images by
   date
 - fixed a few memory leaks in directory handling
 - added arbitrary file download to Configure/Configure Camera (experimental;
   very fragile)


Version 2 (29-AUG-1999)
---------

 - integrated into gphoto-2.3.5 (from CVS)
 - added support for large directories (listing occupies > 1 message)
 - receive timeout is now raised from 1 to 10 seconds after first response
 - renamed a50_select_disk to a50_disk_info. It now returns disk capacity
   and available space.
 - completed CRC table
 - properly integrated into gPhoto
 - lots of cleanups


Version 1 (27-AUG-1999)
---------

 - a little bit of code cleanup, added a50.h, doc/, full recursive download
   in canon.c, and fixed a few documentation bugs, adjusted send/receive
   buffers
 - a50_send_msg incremented seq_tx when skipping retransissions while waiting
   for ACK


Version 0 (27-AUG-1999)
---------

 - initial release which demonstrates most functions in a way that's
   completely useless for gPhoto


========================================================================
To do
=====

Quite outdated. See the TODO file for more current information.
 
- code structure is still pretty ugly. Things that absolutely need fixing:
  - command codes and fffbs are spread all over the place
  - "ping" (empty message) should probably be merged into normal message
    handling; perhaps also 03 message -> wait_for_ack can be merged too
  - psa50.c must not invoke GUI functions
  - change many fprintf(stderr,... to GUI calls or callbacks
- improve error handling: distinguish between severe and harmless errors
  (e.g. duplicate EOT vs. ten timeouts in a row)
- find out how error recovery works (need traces)
- get traces for other operations:
   - idle period/restart (keepalive ?)
   - upload file, create directory
- find out how to avoid blocking gPhoto during transfer