Merge pull request #25 from ufo-kit/roi

Add manual of the GObject Tango device

1 files changed, 114 insertions, 1 deletions

diff --git a/docs/manual.md b/docs/manual.md
index 7c13d61..5755ba7 100644
--- a/docs/manual.md
+++ b/docs/manual.md
@@ -526,5 +526,118 @@ grabbing time:
 
 # The GObject Tango device
 
-[TODO: Get more information from Volker Kaiser and/or Mihael Koep]
+UcaDevice is a generic Tango Device that wraps `libuca` in order to make libuca controlled cameras available as Tango devices.
 
+## Architecture
+
+UcaDevice is derived from GObjectDevice and adds libuca specific features like start/stop recording etc. 
+
+The most important feature is _acquisition control_. UcaDevice is responsible for controlling acquisition of images from libuca. The last aquired image can be accessed by reading attribute `SingleImage`.
+
+UcaDevice is most useful together with ImageDevice. If used together, UcaDevice sends each aquired image to ImageDevice, which in turn does configured post-processing like flipping, rotating or writing the image to disk.
+
+## Attributes
+
+Besides the dynamic attributes translated from libuca properties UcaDevice has the following attributes:
+
+* `NumberOfImages (Tango::DevLong)`: how many images should be acquired? A value of -1 means unlimited _(read/write)_
+* `ImageCounter (Tango::DevULong)`: current number of acquired images _(read-only)_
+* `CameraName (Tango::DevString)`: name of libuca object type _(read-only)_
+* `SingleImage (Tango::DevUChar)`: holds the last acquired image
+
+## Acquisition Control
+
+In UcaDevice acquisition control is mostly implemented by two `yat4tango::DeviceTasks`: _AcquisitionTask_ and _GrabTask_. _GrabTask_'s only responsibility is to call `grab` on `libuca` synchronously and post the data on to AcquisitionTask. 
+
+_AcquisitionTask_ is responsible for starting and stopping GrabTask and for passing image data on to `ImageDevice` (if exisiting) and to `UcaDevice` for storage in attribute `SingleImage`. It counts how many images have been acquired and checks this number against the configured `NumberOfImages`. If the desired number is reached, it stops GrabTask, calls `stop_recording` on `libuca` and sets the Tango state to STANDBY.
+
+## Plugins
+
+As different cameras have different needs, plugins are used for special implementations. Plugins also makes UcaDevice and Tango Servers based on it more flexible and independent of libuca implementation. 
+
+## Pco
+
+The Pco plugin implements additional checks when writing ROI values.
+
+## Pylon
+
+The Pylon plugin sets default values for `roi-width` and `roi-height` from libuca properties `roi-width-default` and `roi-height-default`.
+
+## Installation 
+
+Detailed installation depends on the manifestation of UcaDevice. <br />
+All manifestations depend on the following libraries:
+
+* YAT
+* YAT4Tango
+* Tango
+* GObjectDevice
+* ImageDevice
+
+## Build
+
+    export PKG_CONFIG_PATH=/usr/lib/pkgconfig
+    export PYLON_ROOT=/usr/pylon
+    export LD_LIBRARY_PATH=$PYLON_ROOT/lib64:$PYLON_ROOT/genicam/bin/Linux64_x64
+    git clone git@iss-repo:UcaDevice.git
+    cd UcaDevice
+    mkdir build
+    cd build
+    cmake ..
+    make
+
+
+## Setup in Tango Database / Jive
+
+Before `ds_UcaDevice` can be started, it has to be registered manually in the Tango database. With `Jive` the following steps are necessary:
+
+[1] Register Server <br />
+Menu _Tools_ &#8594; Server Wizard <br />
+Server name &#8594; ds_UcaDevice <br />
+Instance name &#8594; my_server  _(name can be chosen freely)_  <br />
+Next <br />
+Cancel
+
+[2] Register Classes and Instances <br />
+In tab _Server_: context menu on ds_UcaDevice &#8594; my_server &#8594; Add Class <br />
+Class: UcaDevice <br />
+Devices: `iss/name1/name2` <br />
+Register server <br />
+same for class ImageDevice
+
+[3] Start server
+
+    export TANGO_HOST=anka-tango:100xx
+    export UCA_DEVICE_PLUGINS_DIR=/usr/lib(64)
+    ds_UcaDevice pco my_server
+
+[4] Setup properties for UcaDevice <br />
+context menu on device &#8594; Device wizard <br />
+Property StorageDevice: _address of previously registered ImageDevice instance_
+
+[5] Setup properties for ImageDevice <br />
+context menu on device &#8594; Device wizard <br />
+PixelSize: how many bytes per pixel for the images of this camera? <br />
+GrabbingDevice: _address of previously registered UcaDevice instance_
+
+[6] Finish <br />
+restart ds_UcaDevice
+
+## FAQ
+
+_UcaDevice refuses to start up...?_ <br />
+Most likely there is no instance registered for class UcaDevice. Register an instance for this class and it should work.
+
+_Why does UcaDevice depend on ImageDevice?_ <br />
+UcaDevice pushes each new Frame to ImageDevice. Polling is not only less efficient but also prone to errors, e.g. missed/double frames and so on. Perhaps we could use the Tango-Event-System here! 
+
+## Open Questions, Missing Features etc.
+
+_Why do we need to specify `Storage` for UcaDevice and `GrabbingDevice` for ImageDevice?_ <br />
+ImageDevice needs the Tango-Address of UcaDevice to mirror all Attributes and Commands and to forward them to it. UcaDevice needs the Tango-Address of ImageDevice to push a new frame on reception. A more convenient solution could be using conventions for the device names, e.g. of the form `$prefix/$instance_name/uca` and `$prefix/$instance_name/image`. That way we could get rid of the two Device-Properties and an easier installation without the process of registering the classes and instances in `Jive`.
+
+_Why does UcaDevice dynamically link to GObjectDevice?_ <br />
+There is no good reason for it. Packaging and installing would be easier if we linked statically to `GObjectDevice` because we would hide this dependency. Having a separate `GObjectDevice` is generally a nice feature to make `GObjects` available in Tango. However, there is currently no GObjectDevice in use other than in the context of UcaDevice.
+
+_Why must the plugin name be given as a command line parameter instead of a Device-Property?_ <br />
+There is no good reason for it. UcaDevice would be easier to use, if the plugin was configured in the Tango database as a Device-Property for the respective server instance.