Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Software triggering on Debian GNU Linux
THIS IS OBSOLETE AND HERE FOR HISTORICAL REFERENCE. WE HAVE FOCUSED ALL OUR EFFORTS ON A SPREADS BASED WORKFLOW.
Get the source at https://github.com/DIYBookScanner/spreads .
Get a preconfigured standalone book scanner kit at http://diybookscanner.eu .
The big picture
This document will help you configure your diybookscanner for software triggering.
Before connecting your Canon PowerShot cameras to a computer, please configure the generic firmware of your Canon PowerShot cameras according to https://github.com/markvdb/diybookscanner/blob/master/misc/settings.md . Triple check this or expect reliability problems!
Also, get two small sticker labels: one for the left camera and one for the right one.
This document assumes you have already got a USB foot pedal to use with your cameras as in the http://diybookscanner.eu kit. If not, you can always use your computer's keyboard to trigger the cameras instead. Not very handy, but it will certainly work!
Find a computer. Some considerations:
- You will need at least three, preferably four free usb 2.0 ports, not counting two for an eventual usb mouse and keyboard. On a desktop, six usb ports would be ideal.
- Remove and disable as many peripherals as possible.
- Connect the cameras and usb foot pedal to the computer as directly as possible, without any usb hubs.
- If you just want to dump the pictures to a usb stick, a very modest old machine will suffice.
- If you want to do image postprocessing on this machine too, you want a more powerful machine.
This section explains how to install the triggering software onto a Debian or Ubuntu workstation. Some basic Debian or Ubuntu knowledge is expected here.
Ubuntu users can directly paste the below commands into their terminal. Debian users should use the root user directly instead of prepending "sudo " to every command that requires superuser rights.
First, we are going to install some of the packages needed to build our software:
apt-get install gphoto2 build-essential subversion git libusb-dev lua5.1 liblua5.1 liblua5.1-dev
We can check if these dependencies are installed:
dpkg -l gphoto2 build-essential subversion git libusb-dev lua5.1 liblua5.1 liblua5.1-0-dev
Ptpcam is the software we are going to use to configure and trigger the cameras. What we are using is not ptpcam proper, but a fork by the CHDK project. One of the things the fork adds is ptpcam remote configuration and triggering functionality.
Compiling from source
First, we go to the directory where code for system wide use is normally compiled:
user@scanner:~$ sudo cd /usr/src
We download the latest revision of ptpcam:
user@scanner:~$ sudo svn co http://subversion.assembla.com/svn/chdkde/trunk/tools/ptpcam/
We jump into our downloaded source code:
user@scanner:~$ sudo cd ptpcam
We create the ptpcam executable:
user@scanner:~$ sudo make
Let's check if we created it successfully:
user@scanner:~$ /usr/src/ptpcam/ptpcam --help
This should result in ptpcam documentation scrolling by (middle part left out [...]):
USAGE: ptpcam [OPTION] Options: --bus=BUS-NUMBER USB bus number [...] -h, --help Print this help message --chdk[=command] CHDK mode. Interactive shell unless optional command is given. Run interactive shell and press 'h' for a list of commands.
We make ptpcam available to all users in the standard place:
user@scanner:~$ sudo ln -s /usr/src/ptpcam/ptpcam /usr/bin/ptpcam
The keypedal script configures and triggers the cameras.
We go to the standard place for executables:
user@scanner:~$ sudo cd /usr/bin
Let's download the script here:
user@scanner:~$ sudo wget https://github.com/markvdb/diybookscanner/raw/master/misc/test_keypedal.sh
Make sure everyone has the right to run it:
user@scanner:~$ sudo chmod a+x test_keypedal.sh
Camera configuration script
This script will teach your cameras which one is left and which one is right.
Since we're in the right place, we just download it...
user@scanner:~$ sudo wget https://github.com/markvdb/diybookscanner/raw/master/misc/configure_cameras.sh
... and we make sure it is executable:
user@scanner:~$ sudo chmod a+x configure_cameras.sh
chdk is the alternative Canon PowerShot firmware we use to remotely trigger the cameras via usb. Cameras purchased from http://diybookscanner.eu should have come with a preconfigured sd card for running it.
In order to test this, please:
- Lock the sd card by moving the mini switch on the device to the “lock” position.
- Insert the sd card into the camera.
- Boot the camera. You should now see the CHDK logo flash by at boot time.
Avoiding competition for our cameras
The desktop environment on Debian and Ubuntu auto connects to cameras when it detects them on the usb port. We don't want that, because it causes interference with the gphoto2 and ptpcam software we are using.
On a dedicated machine for book scanning, you may want to switch auto connection off permanently. On a machine also used for other purposes, you may want to switch auto connection off before scanning and on again afterwards. Here's how to do that:
user@scanner:~$ sudo apt-get remove --purge gvfs-backends
Double checking if you have removed the gvfs-backends package is easy:
user@scanner:~$ dpkg -s gvfs-backends|grep Status
The following works on Debian 7.0 "wheezy", and (TODO: test) probably on Ubuntu 12.04 too:
gsettings set org.gnome.desktop.media-handling automount "false" gsettings set org.gnome.desktop.media-handling automount-open "false"
Obviously, to reverse:
gsettings set org.gnome.desktop.media-handling automount "true" gsettings set org.gnome.desktop.media-handling automount-open "true"
Setting camera orientation
Now we want our cameras to remember which one is left or right. Have the two cameras and usb cables ready. Now let's run the configuration script and follow the instructions within:
user@scanner:~$ sudo configure_cameras.sh
If the camera has not been used for a while, the setting may not stick if you power it off immediately. This is because the internal backup battery is not charged. Charge the main battery or attach a power supply and leave the camera powered off overnight. At this point you should be able to set the ownername consistently.
Now is the time to label your cameras. It's best to do this on the back side to avoid reflection.
Running the camera triggering script
Please make sure that both cameras are on and connected to your computer. Connect the foot pedal too connected to your computer. Now we are ready to run the camera triggering script:
Please follow the instructions in the script.
The result of this should be a folder with
Various internals and troubleshooting
Listing the cameras
After attaching the cameras, please look closely at the output of these commands, especially the usb information:
user@scanner:~$ gphoto2 --auto-detect
user@scanner:~$ ptpcam --list-devices
Setting camera orientation manually
(NOTE: Setting /main/settings/ownername is problematic on Debian 6.0, but it should run fine from Debian 7.0 onwards)
Make sure to replace the usb port information with what you learned from listing the camera devices!
user@scanner:~$ gphoto2 --port usb:001,025 --set-config /main/settings/ownername=left
user@scanner:~$ gphoto2 --port usb:001,026 --set-config /main/settings/ownername=right
Now let's check if the camera orientation has been set correctly. Make sure only one camera is connected. Then ask for its orientation information:
user@scanner:~$ gphoto2 --get-config /main/settings/ownername
Repeat this step for the second camera.
Some nice tricks for testing cameras individually:
- Connect one camera.
- See if it gets detected:
user@scanner:~$ ptpcam --list-devices
Checking hardware revision and CDHK version
user@scanner:~$ ptpcam --chdk` luar get_buildinfo() script:1 1:ret:'platform a810 build_date May 15 2013 build_number 1.1.0-2774 build_time 04:44:32 version CHDK platsub 100e build_revision 0 platformid 12863 os dryos '
Testing from the interactive console
- Start the remote control console:
user@scanner:~$ ptpcam --chdk
conn >> mode 1
conn >> luar zoom()
conn >> lua shoot()
Testing from the bash prompt
- Switch the camera to recording mode. The camera should now open up:
user@scanner:~$ ptpcam --chdk=”mode 1”
- Make the camera zoom one step:
user@scanner:~$ ptpcam --chdk=”lua zoom()”
- Make the camera shoot once:
user@scanner:~$ ptpcam --chdk=”lua shoot()”
###fuser If you're experiencing difficulties that sound like "resource busy", try to find out if another process is using the camera:
user@scanner:~$ sudo fuser -v /dev/bus/usb/00x/00y
camera "powers down"
Is your camera crashing or automatically powering down?
- When powering down, it will close the lens.
- When crashing, the lens if open will stay open.
camera powers down
You don't want your camer to auto power down when using it in the book scanner. The scanners in the http://diybookscanner.eu kit come with an AC adapter anyway, right? Please double check the original Canon camera firmware settings and disable auto power down.
Try to reproduce it. Interesting to know:
- Is it always the same camera crashing? This might point at a hardware problem with the SD card or the camera.
Some things you may try to avoid your camera crashing:
- Make sure not to play with focus settings in chdk.
- Triple check that flash is disabled in the generic firmware settings.
- Check the foot pedal and how you press it. It should write just one character ("b") when pushing it.
- Switch the cards between the cameras. Don't ask me why this would help, but I've been assured it helped on one occasion.
- Unplug all other USB devices.
- Make sure you are not running Debian/Ubuntu on a vm or on an old computer with USB 1.1 ports.
- Replace the AC adapter. Run on batteries for some time instead.
- Replace the camera itself.
- Make sure you have as much light on your cradle as possible. If the camera needs to seek for focus for too long because of bad lighting conditions, it might not have enough time to shoot and let the computer download. Ask it to shoot again while it's still busy and it will crash!