=== Camera driver tutorial ===

The aim of this tutorial is to create a camera (CCD) driver. In order to be
hardware independent, the created driver will not correspond to any existing
camera - it will create a test (dummy) driver, which can be used to show how
the RTS2 works.

The believe is that this tutorial will enable interesting parties to write own
camera driver for theirs special hardware.

=== Preparations - creating source file, Makefile ===

First, change to rts2/src/camd directory. That is the directory where most of
the driver resides. 

New camera driver shall be added to Makefile, so it will be properly generated
when automake machinery is invoked. To do this, add following lines to the end
of Makefile.am (in rts2/src/camd):

<code make>

bin_PROGRAMS += rts2-camd-test
rts2_camd_test_SOURCES = test.cpp

</code>

Please note that as variables in Makefile.am must contain legal characters for
shell variable name, '-' shall be replaced with '_'. Hence
rts2_camd_test_SOURCES is used, instead of rts2-camd-test_SOURCES. The automake
machinery takes care of replacing '-' with '_' in final executable name.

The above lines instruct automake to add 'rts2-camd-test' among names of binary
programs make shall produce. And tells make, that rts2-camd-test shall be
produced from test.cpp source.

=== Adding the source code ===

Looking into
[[http://svn.code.sf.net/p/rts-2/code/trunk/rts-2/include/camd.h|include/camd.h]]
file, you will find that there are two pure virtual methods:

<code c++>
		virtual int startExposure () = 0;

		virtual int doReadout () = 0;
</code>

We need to implement those. We also need to set width and height of the chip in
initChips. The generated data needs to be send with sendReadoutData method. See
the code below for full example:

<code c++>
#include "camd.h"
#include "utilsfunc.h"

#define TEST_WIDTH 100
#define TEST_HEIGHT 200

namespace rts2camd
{

class Test:public Camera
{
	public:
		Test (int argc, char **argv):Camera (argc, argv)
		{
			initCameraChip (TEST_WIDTH, TEST_HEIGHT, 0, 0);
		}

	protected:

		virtual int startExposure ()
		{
			return 0;
		}

		virtual int doReadout ()
		{
			uint16_t data[TEST_WIDTH * TEST_HEIGHT];
			for (int i = 0; i < TEST_WIDTH * TEST_HEIGHT; i++)
				data[i] = random_num () * 100;

			int ret = sendReadoutData ((char*) data, TEST_WIDTH * TEST_HEIGHT * sizeof (uint16_t), 0);
			if (ret < 0)
				return ret;

			if (getWriteBinaryDataSize () == 0)
				return -2;
			return 0;
		}
};

}

int main (int argc, char **argv)
{
	rts2camd::Test testcam (argc, argv);
	return testcam.run ();
}
</code>

Place this content to src/camd/test.cpp and you are ready to build.

=== Building rts2-camd-test ===

First, you need to make sure the changes in Makefile.am propagates to
Makefile.in and then to Makefile. Usually, you will need at least to run
automake RTS2 top directory (the directory with src and include subdirectories,
usually rts2). After running automake, just run make && sudo make install.

That should make rts2-camd-test available in the path. To launch those, just:

<code bash>
rts2-centrald
rts2-camd-test
</code>

=== Testing camera test driver ===

First, run rts2-mon to verify you see C0 in device list. Your terminal window shall look like depicted below:

Then, run rts2-xfocusc -d C0 to get images from the camera. This shall create
window with random content of the image, as depicted below:

=== Complicating it ===

If you follow sucesfully the example to this line, congratulations - you
created working sceleton of the camera driver. To make it work with your
hardware, just implement startExposure and doReadout methods to start an
exposure and get data from the camera.