diff --git a/doc/gphoto2.xml b/doc/gphoto2.xml index 082c99b9c..faba755c3 100644 --- a/doc/gphoto2.xml +++ b/doc/gphoto2.xml @@ -1,8 +1,357 @@ - + + + + The gPhoto2 Manual + + + The gPhoto2 + Team + + + Tim + Waugh + +
twaugh@redhat.com
+
+
+ + Hans Ulrich + Niedermann + +
gp@n-dimensional.de
+
+
+
+
+ + + Short guide to setting up and using + <xref linkend="gphoto2-cli"/> and <xref linkend="libgphoto2"/> + +
+ Overview + + gPhoto2 consists of two libraries + ( and + ) and + a command line frontend (). + Other (GUI) frontends (like e.g. gtkam) 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 + + 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 + frontend + , + this is described in the man + page. + +
+ +
+ Setting up permissions for serial (RS232) 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. + +
+ +
+ Setting up permissions for 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. + + + +
+ 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: + + + + + 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) + + + + + + use hotplug (http://linux-hotplug.sourceforge.net/) + 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 has a huge advantage over + : 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 + . + + + + 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. + + + + + + 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. + + + + + + Add the output of gphoto2 --print-usb-usermap to + /etc/hotplug/usb.usermap + This makes hotplug recognise all USB cameras which your version + of supports and makes + hotplug run the + usbcam script you choose in step + whenever one of these + cameras is attached. + + + + + + Choose the right + /etc/hotplug/usb/usbcam + script for you. + Example scripts are found in + packages/linux-hotplug + 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. + + + + usbcam.console + + + 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. + + + + + usbcam.user + + + If you want only one user to have access to the camera, use + usbcam.user and change it + accordingly. + + + + + usbcam.group + + + If you want multiple users to have access to the camera, add all + of these users to one group - either a special + group + camera + or a generic group + users + will do - and use that group in + usbcam.group. + + + + + + + + Make your script file + /etc/hotplug/usb/usbcam + executable. + + + + + + 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 syslog + file will contain some messages to that effect. + + + + Run or any other + frontend and enjoy :-) + + +
+
+
+ Specifying the port and camera you use + + libgphoto2 identifies a camera two values: + + + the port it is connected to + + + the name of the camera + + + + + How these may be specified is discussed in the following + sections. + + +
+ Serial ports + + Serial ports are named like + serial:/dev/ttyS2 + if you want to use the serial device + /dev/ttyS2. + +
+ +
+ 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:. + +
+ +
+ 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 G2. + You will be better off choosing the model from + the list of supported models rather than just trying to type + your camera model. + +
+
+
+ - gPhoto2 + The gPhoto2 Reference @@ -665,15 +1014,17 @@ See also - , - gphoto2.txt, - http://www.gphoto.org/ + , + , + gphoto2.txt, + http://www.gphoto.org/ +