########################################################################
# A short guide to setting up and using gphoto2
########################################################################
# This file has been made obsolete by the chapter
#               "Setting up your system ..."
# in the gphoto2.xml file and in the generated
# - HTML manual in manual/
# - PDF manual in gphoto2.pdf
########################################################################


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

The configuration of these helper applications is explained in the
following section.


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

As gphoto2 provides a user space driver, in order to have gphoto2
access your camera, you have to disable all kernel drivers which want
to handle the camera themselves (e.g. the Linux dc2xx driver).

On Linux systems, you have basically two options to allow user access
to USB devices:
a) allow a certain user/group or the world access to ALL USB devices
   by mounting /proc/bus/usb with adequate user and/or group 
   permissions (default is world-readable and root-only-writable,
   which is good)
b) use hotplug and allow access only to the USB devices you want to be
   accessible (you need /proc/bus/usb mounted here as well, but not
   mounted writable by anybody else than root)

Solution b) has a huge advantage over a): It doesn't allow the
user/group to interfere with or eavesdrop on any other USB devices
which might be attached, such as USB keyboards, fingerprint reader or
similar. The following paragraphs thus describe setting up b).

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

Also note that the following solution does *not* provide absolute
security and that you know the security implications of the respective
usbcam script you are going to use.

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
   This makes hotplug recognise all USB cameras which your version 
   of gphoto2 supports and makes hotplug run the usbcam script you
   choose in step 2 whenever one of these cameras is attached.

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. The directory /etc/hotplug should
   already exists, whereas it may be that you have to create the
   directory /etc/hotplug/usb.

   All three scripts shipped with gphoto2 also have extensive
   commentary explaining their usage in more detail.

   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 script will work for you: /dev/console must
      belong to the user you want to run the gphoto2 frontend 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, add all
      of these users to one group - either a special "camera" group or
      a generic "users" group will do - and use that group in
      usbcam.group.

3. Make your script /etc/hotplug/usb/usbcam executable.

4. Plug in the camera and switch it on. If you already did so, please
   unplug and/or switch off first. The kernel will now notice that
   your camera has been connected and, hopefully finding no kernel
   driver for the device, will ask hotplug to do something about it.

   Hotplug will then look into /etc/hotplug/usb.usermap and find that
   the "usbcam" script is to be called for the newly attached
   device. Thus /etc/hotplug/usb/usbcam is executed, hopefully setting
   the device permissions correctly. 

   Your /var/log/messages will contain some messages to that effect.

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. 
