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
163
164
165
166
|
.. _udp_api:
ecFlow UDP
**********
.. caution::
ecFlow's UDP server is experimental, actively under implementation, and its details are subject to change.
The documentation reflects the current implementation status.
Compilation
===========
ecFlow UDP API provides a lightweight (and low level) proxy to interact with ecFlow server.
The build of ecFlow UDP server can be enabled (ON) or disabled (OFF) using cmake option:
.. code::
-DENABLE_UDP=ON
When the ecFlow UDP server is enabled, the build produces the following additional executables:
- **ecflow_udp**, the actual ecFlow UDP server
- **ecflow_udp_client**, an ecFlow UDP client capable of sending a text payload to the UDP server
When launched, the server will by default listen to port 8080. This can be changed with command line option ``-p``,
``--port``. The option ``--verbose`` can be used to enable logging output.
.. Important::
The communication between the ecFlow UDP server and the ecFlow server is done in clear text. At the moment,
no encryption is applied to the exchanged information.
Starting ecFlow UDP server
==========================
The ecFlow UDP server is started with the following command:
.. code-block:: shell
ecflow_udp --verbose [--port <ecflow-udp-port>]
By default the ecFlow UDP server expects ecFlow server to be available at localhost:3141. This can be changed by
customizing the environment variables ``ECF_HOST`` and ``ECF_PORT`` before starting the ecFlow UDP server, or by
using the CLI options ``--ecflow_host`` and ``--ecflow_port`` (n.b. the CLI options override the environment variables).
Command Line Options and Environment Variables
==============================================
ecFlow UDP options can be controlled either with command line options or with environment variables.
All environment variables with "UDP" are new.
.. list-table::
:header-rows: 1
* - Command line option
- Environment variable
- Default Value
- Description
* - --http
-
- false
- Use HTTP to contact the ecFlow server
* - --ecflow_host
- ECF_HOST
- localhost
- ecFlow server hostname
* - --ecflow_port
- ECF_PORT
- 3141
- ecFlow server port
* - --port,-p
- ECF_UDP_PORT
- 8080
- ecFlow UDP port
* - --verbose
- ECF_UDP_VERBOSE
- false
- Enable verbose mode
* - --version,-v
-
- false
- Display version information
Authentication
==============
ecFlow UDP forwards basic authentication information, as part of the request, to the ecFlow server
where the authentication takes place considering the available mechanisms (e.g whitelist files,
password based authentication).
ecFlow UDP Requests
===================
The current implementation of ecFlow UDP allows the following task requests:
- update the value of a meter
- update the value of a label
- set/clear an event
Each of the operations can be triggered be sending a JSON-formatted request to ecFlow UDP server.
The following sections present the description of the request format.
Update meter value
------------------
.. code:: json
{
"method": "put",
"version": "1",
"header": {
"task_rid": "<task-remote-identifier>",
"task_password": "<task-password>",
"task_try_no": "<task-try-number>"
},
"payload": {
"command": "meter",
"path": "</path/to/task>",
"name": "<meter-name>",
"value": "<new-meter-value>"
}
}
Update label value
------------------
.. code:: json
{
"method": "put",
"version": "1",
"header": {
"task_rid": "<task-remote-identifier>",
"task_password": "<task-password>",
"task_try_no": "<task-try-number>"
},
"payload": {
"command": "label",
"path": "</path/to/task>",
"name": "<label-name>",
"value": "<new-label-value>"
}
}
Set/clear event value
---------------------
.. code:: json
{
"method": "put",
"version": "1",
"header": {
"task_rid": "<task-remote-identifier>",
"task_password": "<task-password>",
"task_try_no": "<task-try-number>"
},
"payload": {
"command": "event",
"path": "</path/to/task>",
"name": "<event-name>",
"value": "<new-event-value>" // the value is either 1 to set or 0 to clear the event
}
}
|
