summaryrefslogtreecommitdiffstats
path: root/docs/tango.rst
blob: fa90b56aab57836f52add8434debc7873ac420f4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
The GObject Tango device
========================

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.