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

This driver is for Canon cameras. It underwent a fairly complete rewrite
around 2002-01-01, so we list camera support for both the old and the
new driver here. Note that the old driver is not being developed any
more. The new driver will take over all functions as its successor.


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

The new driver works with the following models:

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

The old driver worked with the following models:

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

This old driver can be checked into your CVS source tree by changing
to camlibs/canon and running "cvs update -r Before_GPFileSystem"
there.

The support of the following cameras is mostly there as they were supported
in gphoto 0.4.x but an API change broke the support as they handle files a 
little differently. 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 old driver cached a lot of information. 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 (currently not tested)

- 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 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)

The following features are probably or surely not working (yet :-)

- Create and Delete folders (not tested, but worked in the past)

- Upload files to camera (not tested, but worked in the past)

- Capture images controlled by the computer (still to be implemented)

We are currently 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.


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

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
=====

Not very up to date contact gphoto-devel@gphoto.net if you wish to 
contribute.
 
- 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
