xNightR00T File Manager

NOTE: As of 2006, this file is quite outdated, at least regarding the
      list of supported cameras.


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

For up-to-date camera support details, see the canon.c source file.

 - PowerShot A50 (not tested)
 - PowerShot Pro70
 - PowerShot S10
 - PowerShot S20
 - PowerShot S30
 - PowerShot S40
 - PowerShot S100 / Digital IXUS
 - PowerShot S110 / DIGITAL IXUS v
 - PowerShot S200 / Digital IXUS v2
 - 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 A30
 - PowerShot A40
 - PowerShot A100
 - PowerShot A200
 - PowerShot Pro90 IS (not tested)
 - PowerShot S300 / IXY DIGITAL 300 / Digital IXUS 300
 - EOS D30
 - EOS D60
 - EOS 10D
 - Digital IXUS 330
 - Canon MVX2i / Optura 200 MC
 - EOS 300D / Digital Rebel / KISS Digital
 - a few newer ones, see output of "gphoto2 --list-cameras | grep Canon"

The following cameras operate either with this driver or in PTP mode
with the PTP driver:

 - PowerShot S45 (normal mode)
 - PowerShot G3 (normal mode)
 - PowerShot S230 / Digital IXUS v3 (normal mode)
 - a few newer ones, see output of "gphoto2 --list-cameras | grep Canon"
  
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@lists.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 following cameras, and probably many cameras to come, operate in
either PTP and Canon mode depending on the first data packets sent to
the camera, i.e. depending on whether you use this driver or the PTP
driver:

 - PowerShot A60
 - PowerShot A70

The rewritten canon 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

- Capture images controlled by the computer
  (code courtesy of Emile Snyder and Stephen H. Westin)

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

   "-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!

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


========================================================================
Remote capture on Canon Powershot A40
=====================================

The Canon Powershot A40 supports remote capture with gphoto. However,
not all camera configuration parameters can be set via gphoto. Here
we summarize the current status:

- shutterspeed: can _NOT_ be set; This parameter can not be remotely set,
  most likely due to a camera limitation rather than a gphoto issue. In fact
  even Canon RemoteCapture version 2.7.4.23 for MacOSX does not allow
  setting this parameter.

- aperture: can NOT be set; even Canon RemoteCapture for MacOSX does not
  allow setting this.

- ISO: WORKS. Setting the ISO to one of the supported camera values works
  with gphoto.

- Resolution: WORKS.

- flashmode: WORKS. gphoto2 is able to denable/disable the flash, or set
  it to automatic.

- beep: WORKS. gphoto2 is able to enable/disable the audible beep which
  is emitted by the camera after fucosing the scene.

- zoom: WORKS. gphoto2 can remotely set the zoom. The range of zoom values
  needs to be checked; at the moment the range 1 (no zoom at all) to 9 
  has been observed to work, but it is unclear whether higher values
  work as well.

- macro mode: can _NOT_ be set. Apparently, RemoteCapture 2.7.4.23 is able
  to enable macro mode; however, macro mode should be automatically enabled
  by the camera when necessary (need to be checked)

- exposure compensation: can _NOT_ be set. Apparently, RemoteCapture
  2.7.4.23 is able to set the exposure compensation, while gphoto2 is
  not. Supporting this would probably require additional reverse engineering 
  work on the Canon protocol to understand the commands to issue.


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

* 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