Newer
Older
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
Schema Injection
================
A schema injection is a modification of a device schema, to bring further
properties visible outside or to update attributes of existing properties
(such as the maximum size of a vector). Any number and types of properties can
be injected, whether parameters or slots.
In this example, we will define a slot that adds a boolean `injectedProperty`.
Begin by defining a slot that will call the `extend` function:
.. code-block:: Python
from karabo.bound import BOOL_ELEMENT, PythonDevice, SLOT_ELEMENT
class MyDevice(PythonDevice):
@staticmethod
def expectedParameters(expected):
(
SLOT_ELEMENT(expected).key('extend')
.displayedName('Extend')
.description('Extend the schema and introduce a new boolean property')
.commit(),
)
# Register the slot in the device schema
def onInitialization(self):
self.KARABO_SLOT(self.extend)
There are two methods to injecting properties: `appendSchema` and `updateSchema`,
both inherited from :class:`karabo.bound.PythonDevice`.
:func:`appendSchema` will add properties to the device, and can be called any
number of time.
:func:`updateSchema` will take the the original schema of the device, and add
the new one to the device. However, it will discard what has been previously
appended or updated!
Nonetheless, if :func:`appendSchema` is called after :func:`updateSchema`, then
the parameters from both injections are kept.
If :func:`updateSchema` is called with an empty schema, then the device will be
reset to its original schema, as defined in :func:`MyDevice.expectedParameters`.
This works, as internally, a device keeps three schemas: its `static` schema,
as defined in `expectedParameters`, the `injected` schema, which is modified on
injections, and the `full` schema, the combination of both which is exposed to
the rest of the ecosystem.
.. code-block:: Python
from karabo.bound import BOOL_ELEMENT, DAQPolicy, Schema
def extend(self):
# Define a new Schema object
schema = Schema()
# Then populate that new Schema
(
BOOL_ELEMENT(schema).key('injectedProperty')
.displayedName('Hello')
.description('A fresh property')
.daqPolicy(DAQPolicy.OMIT)
.readOnly().initialValue(True)
.commit()
# Finally, append the schema to our existing device
self.appendSchema(schema) # Or self.updateSchema(schema)
Once a device has been modified, either of these log messages will be given::
INFO MyDevice : Schema appended
Re-injecting a property, such as `injectedProperty`, will keep its current value
if possible. However, with different types, an error will be raised if the
value cannot be cast e.g. going from `UINT32_ELEMENT` to `INT16_ELEMENT` with a
value out of bound.
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
Check Whether A Property Exists
-------------------------------
If your device has an update loop, you can either use flags to check
whether schema injection has already been done, or use :func:`getFullSchema`:
.. code-block:: Python
def update(self):
if self.getFullSchema().has("injectedProperty"):
self.set("injectedProperty", not self.get("injectedProperty"))
Injected Properties and DAQ
---------------------------
Injected Properties and the DAQ need some ground rules in order to record these
properties correctly.
In order for the DAQ to record injected properties, the DAQ needs to request the
updated schema again, using the Run Controller's :func:`applyConfiguration` slot.
This can be prone to operator errors, and therefore it is recommended that only
properties injected at instantiation to be recorded.
However, a common need for Schema updates is to specify the `maxSize` attribute
fo vector or table elements, as the DAQ only supports fixed length arrays, of
which the size has to be predefined.
For that, there is the special function :func:`karabo.bound.PythonDevice.appendSchemaMaxSize`
which, given a property path and the new length, will update the schema
accordingly.
Such a vector:
.. code-block:: Python
from karabo.bound import NODE_ELEMENT, VECTOR_INT32_ELEMENT
@staticmethod
def expectedParameters(expected):
(
NODE_ELEMENT(expected).key('node').commit(),
VECTOR_INT32_ELEMENT(expected').key('node.vector')
.displayedName('Vector')
.readOnly()
.maxSize(5)
.commit(),
)
Can have its `maxSize` be redefined as follows:
.. code-block:: Python
self.appendSchemaMaxSize('node.vector', 50)
If several updates are made, then it is recommended to set `emitFlag` to false for
all vectors apart of the last one. Only a single update will be then sent:
.. code-block:: Python
self.appendSchemaMaxSize('node.vector0', 50, emitFlag=False)
self.appendSchemaMaxSize('node.vector1', 50, emitFlag=False)
self.appendSchemaMaxSize('node.vector2', 50)