########################################################################
# A short guide to setting up and using gphoto2
########################################################################


===========
1. Overview
===========

Gphoto2 consists of two libraries (libgphoto2 and libgphoto2_port) and
a command line frontend (gphoto2). Other (GUI) frontends are available
as separate packages.

In order to get access to the camera, your frontend process requires
write permissions to the respective device special file, e.g. to
/dev/ttyS3 or /proc/bus/usb/1/012. 

For security reasons, we strongly recommend not to run any gphoto2
frontend as root. So you have to set up the permissions of your camera
device accordingly. This is described in chapter 2 - Setting up
permissions. 

Then you can run your frontend. For the command line gphoto2 frontend,
this is described in the file gphoto2-cli.txt.


=========================
2. Setting up permissions
=========================


2.1 Serial ports
================

[ I don't have any experience with serial ports for user processes. So
  take this section with a grain of salt. ]

If you have a serial port reserved for the camera, you may just chown
the device file to the user you want to run gphoto2 as.


2.2 USB ports
=============

As USB allows hotplugging of devices, there is a mechanism that
dynamically creates the device files for the devices currently
connected and switched on.

The operating system has to determine which users may access a device
dynamically. As the operating system cannot determine this by itself,
there have to be some helper applications.


2.2.1 USB ports on Linux
========================

On Linux systems, from the 2.4 kernel series on, the kernel supports
hotplugging. You may have to compile a kernel with hotplug support if
you're not already running one. You may have to install the hotplug
package (http://linux-hotplug.sourceforge.net/) if you don't have it
already.

You can find out if your kernel has hotplug support by looking for the
file /proc/sys/kernel/hotplug. If it exists, you have a hotplug
enabled kernel. If "cat /proc/sys/kernel/hotplug" prints the path to
your hotplug binary (usually /sbin/hotplug) and this binary exists,
you are ready to rock.

Note that the following solution does *not* provide real security, but
it allows you to run gphoto2 as a non-root user and avoids chance
conflicts between to different users accessing the camera.

0. Load your USB driver and mount the USB device filesystem, i.e. e.g.
      modprobe usb-uhci
      modprobe usb-ohci
      mount -t usbdevfs /proc/bus/usb
   Modern distributions like Redhat 7.2 handle this automatically.

1. Add the output of "gphoto2 --print-usb-usermap" to
   /etc/hotplug/usb.usermap

2. Choose the right /etc/hotplug/usb/usbcam script for you.
   Example scripts are found in packages/ in the source tree
   and in linux-hotplug/ after installation and in the doc dir of 
   the binary package. Choose one, adapt it for your needs, and copy
   it to /etc/hotplug/usb/usbcam.

   a) The most simple solution is using usbcam.console. This
      changes the permissions so that the user owning /dev/console can
      access the camera. This works if you're logging in with
      pam_console, i.e. e.g. using gdm on Redhat Linux. You may want
      to check with "ls -l /dev/console" whether this usbcam.console
      will work for you. /dev/console must belong to the user you are
      logged in as.

   b) If you want only one user to have access to the camera, use
      usbcam.user and change it accordingly.

   c) If you want multiple users to have access to the camera, put all
      of these users in one group - either a special "camera" group or
      a generic "users" group will do - and use that group in the
      "chgrp" line in usbcam.group.

   Don't forget to make the script executable.

4. Plug in the camera and switch it on - your /var/log/messages 
   will now display some messages.

5. Run gphoto2 or any other libgphoto2 frontend and enjoy :-)


=========================================
3. Specifying the port and camera you use
=========================================

libgphoto2 identifies a camera two values:
a) the port it is connected to
b) the name of the camera

How these may be specified is discussed in the following paragraphs.


3.1 Serial ports
================

Serial ports are named like "serial:/dev/ttyS2" if you want to use the
serial device "/dev/ttyS2".


3.2 USB ports
=============

As USB works with auto detection, you do not have to specify a device
file. Therefore you just use the gphoto2 port "usb:".


3.3 Name of the camera
======================

The model name of the camera does not have to be specified when using
the "usb:" port. Otherwise you can specify a camera model like 
"Canon PowerShot G1". You will be better off choosing the model from
the list of supported models rather than just trying to type your
camera model.