README for dc1394ctrl v0.1

09.03.2002
Benjamin Hummel <benjamin@datamaze.de>


What is this?
~~~~~~~~~~~~~

dc1394ctrl is a tool to control several features of IEEE1394 digital cameras (NOT camcorders).
Its main use is in saving and loading of feature sets and in shell scripts.

Prerequisites
~~~~~~~~~~~~~

* Obviously a working IEEE1394 subsystem (especially raw1394 module).
  I've tested it with a 2.4.17 kernel, but other kernels might work as well.
  (You might use gscanbus and coriander (see below) to test your IEEE1394 setup)

* libraw1394

* libdc1394

* And of course gcc, make, etc. to compile.


How to compile
~~~~~~~~~~~~~~

Compilation is as simple as typing
	make
in the source directory


Commandline options
~~~~~~~~~~~~~~~~~~~

dc1394ctrl understands the following options:

 -d, --direct
	with this you can supply commands at the command line. Every parameter after this one
	is treated as command (be sure to quote commands with spaces,
		e.g. dc1394ctrl -d "camera 1" "set bri 200")
	The commands will get negative line numbers when reported.

 -h, --help
 	the usual help screen

 -n, --noread
 	don't enter interactive mode. Useful with -d

 -s, --strict
 	using this option makes dc1394ctrl exit, if it finds a syntax error

Commands
~~~~~~~~

Once started, dc1394ctrl gives you a prompt to enter your commands (of course only if you didn't pipe another
program into it or used the -d switch).

Currently the following commands are known (note: every command supports the -h/--help switch to display help):

 camera [-h] [--help] <cam>
 	set the actual camera to <cam>, where <cam> is a number between 0 and num_cams - 1.
	If you use it with the special value "max" (this means: enter "camera max") it doesn't change
	the camera but prints the number of cameras available.

 info   [-h] [--help] <info> [<info>[..]]
 	prints info on some camera internals (vendor, model,..).
	Usually you will set <info> to "all" to get all info, but there are other values. You can get
	these via "info -h".

 get    [-h] [--help] [-l] [--long] <feature> [<feature>[..]]
 	get short or long (-l/--long) information about a given feature. To get a list of known features
	try either "help features" or "help alias" (quite long).
	You can also use "all" or "available" as feature to _get_ all or only the available features.

 help   [-h] [--help] [<command>]
 	use help without options to display a list of commands. help <command> is the same as "<command> -h".
	Type "help features" to get a list of known features or "help alias" to get a list of supported
	aliases for these features (often shorter).

 mode   [-h] [--help] [-f] [--force] <feature> <mode>
	set the mode of <feature> to <mode>. <feature> may be one of the features found when using
	"help features" or an available alias ("help alias"). <mode> may be either "manual"|"man"|"m" or
	"auto"|"a". When using -f/--force you can stop dc1394ctrl from testing if the mode is supported.
	(This might be useful, if your camera reports this wrong)

 quit   [-h] [--help]
 	oviously ends your dc1394ctrl session

 set    [-h] [--help] [-f] [--force] <feature> <value>
 	set the value of <feature> to <value>. <feature> may be one of the features found when using
	"help features" or an available alias ("help alias"). <value> should be a positive number between
	the minimum and maximum values for that feature. (You can find these using "get -l feature").
	When using -f/--force you can stop dc1394ctrl from testing if value is in the supported min-max range
	(This might be useful, if your camera reports this wrong)

Note: everthing following a "#", ";" or "/" is ignored until the next newline is reached, so you can use
      these to add comments.


Basic usage
~~~~~~~~~~~

The main usage for dc1394ctrl (the problem it was written for) might be the ability to save the current
camera settings (optionally modify them) and reset them later.

To do this setup your camera features the way you want them. For this you might use corriander
(http://sourceforge.net/projects/coriander) or dc1394ctrl (the preferred way ;-)). Of course every other
program should work equally fine as the feature values are stored in the camera (or the driver or somewhere
else; I don't know, but not in the program).

To save the settings you would use
	dc1394ctrl -n -d "get avail" > my_save_file
or if you want your third camera instead of the default camera (camera 0) and want more comments in the file
	dc1394ctrl -n -d "camera 2" "get -l all" > my_save_file_2

The files already contain valid dc1394ctrl commands because this is the way "get" displays them.
You may now edit these files:
	vi my_save_file
	xemacs my_save_file_2

To reload these files to your camera use
	dc1394ctrl < my_save_file
or to change the settings of camera 2
	dc1394ctrl -d "camera 1" < my_save_file_2


Troubleshooting
~~~~~~~~~~~~~~~

First note:
	dc1394ctrl is not for camcorders or USB cameras. It only works with IEEE1394 cameras supported
	by libdc1394.

At first you should check if your IEEE1394 system is running correctly. To ensure this use
gscanbus (http://www.ivistar.de/0500opensource.php3?lang=en) for general IEEE1394 testing
and coriander (http://sourceforge.net/projects/coriander) to test your camera.

General problems with IEEE1394 or your camera can't be solved with dc1394ctrl. Check the following
sites for answers:
	http://sourceforge.net/projects/linux1394
	http://linux1394.sourceforge.net
		These are the development sites for the linux IEEE1394 subsytem

	http://sourceforge.net/projects/libraw1394
		This is the development home for libraw1394, which is heavily used by most
		IEEE1394 apps.

	http://sourceforge.net/projects/libdc1394
		Here libdc1394 is developed. This is the lib used for cameras.

If this doesn't address your problem or even dc1394ctrl doesn't compile on your system although all
libraries are in place you should have a look on the dc1394ctrl home (http://www.datamaze.de/dc1394ctrl/)
or write me an email to <dc1394ctrl@datamaze.de>.

Bugs
~~~~

None known.
If you find any, please report them to <dc1394ctrl@datamaze.de>

Updates
~~~~~~~

The newest version of dc1394ctrl (as well as older versions) should always be
available at http://www.datamaze.de/dc1394ctrl
