From df28b23ed1aabd230cfbd12d342d32a107ae126e Mon Sep 17 00:00:00 2001 From: Maria Date: Thu, 9 Jan 2014 15:13:41 +0100 Subject: Add manual of the GObject Tango device --- docs/manual.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 114 insertions(+), 1 deletion(-) (limited to 'docs') 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.
+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
+Menu _Tools_ → Server Wizard
+Server name → ds_UcaDevice
+Instance name → my_server _(name can be chosen freely)_
+Next
+Cancel + +[2] Register Classes and Instances
+In tab _Server_: context menu on ds_UcaDevice → my_server → Add Class
+Class: UcaDevice
+Devices: `iss/name1/name2`
+Register server
+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
+context menu on device → Device wizard
+Property StorageDevice: _address of previously registered ImageDevice instance_ + +[5] Setup properties for ImageDevice
+context menu on device → Device wizard
+PixelSize: how many bytes per pixel for the images of this camera?
+GrabbingDevice: _address of previously registered UcaDevice instance_ + +[6] Finish
+restart ds_UcaDevice + +## FAQ + +_UcaDevice refuses to start up...?_
+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?_
+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?_
+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?_
+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?_
+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. -- cgit v1.2.3