Skip to content

Commit a706d95

Browse files
birkenfeldbirkenfeld
committed
Update Messages to use Sphinx objects
1 parent 90f60cc commit a706d95

File tree

14 files changed

+730
-728
lines changed

14 files changed

+730
-728
lines changed

‎protocol/specification/descriptive.rst‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -390,12 +390,13 @@ Optional Accessible Properties
390390

391391
``"checkable"``
392392
A boolean value, indicating whether the accessible can be checked with a
393-
``check`` message. If omitted, the accessible is assumed to be not
394-
checkable (``checkable == false``), and the SEC node should reply with an
395-
:ref:`error-report` (``NotCheckable``) error when a ``check`` message is
396-
sent.
393+
`check` message. If omitted, the accessible is assumed to be not
394+
checkable (``checkable == false``), and the SEC node should reply with a
395+
`NotCheckable` error when a `check` message is sent.
397396

398-
:related issue: :issue:`075 New messages check and checked`
397+
.. dropdown:: Related issues
398+
399+
| :issue:`075 New messages check and checked`
399400
400401

401402
Optional Parameter Properties

‎protocol/specification/future.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ design:
6363
Message Handling
6464
----------------
6565

66-
For this, see :ref:`message-overview`.
66+
For this, see :ref:`message-compat`.
6767

6868

6969
Binary representations of the protocol

‎protocol/specification/messages.rst‎

Lines changed: 93 additions & 711 deletions
Large diffs are not rendered by default.

‎protocol/specification/messages/activation.rst‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
``activate``, ``deactivate``: Controlling events
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
.. message:: [request] activate [<module>]
5+
[reply] active [<module>]
6+
[reply] error_activate [<module>] <error-report>
7+
8+
This request triggers the SEC node to send the values of all its modules and
9+
parameters as `update` messages (initial updates). When this is finished, the
10+
SEC node must send an `active` reply (*global activation*).
11+
12+
This initial update is to help the ECS establish a copy of the
13+
'assumed-to-be-current' values. The values transferred are not necessarily read
14+
fresh from the hardware, check the timestamps!
15+
16+
.. note:: An ECS MUST be able to handle the case of an extra update occurring
17+
during the initial phase, i.e. it must handle the case of receiving
18+
more than one update for any valid specifier.
19+
20+
A SEC node might accept a module name as second item of the message
21+
(*module-wise activation*), activating only updates on the parameters of the
22+
selected module. In this case, the "active" reply also contains the module
23+
name.
24+
25+
A SEC node not implementing module-wise activation MUST NOT send the module name
26+
in its reply to an module-wise activation request, and MUST activate all modules
27+
(*fallback mode*).
28+
29+
.. message:: [request] deactivate [<module>]
30+
[reply] inactive [<module>]
31+
32+
A parameterless message. After the "inactive" reply no more updates are
33+
delivered if not triggered by a read message.
34+
35+
Example:
36+
37+
.. code::
38+
39+
> deactivate
40+
< update t1:value [295.13,{"t":1505396348.188388}]
41+
< inactive
42+
43+
.. admonition:: Remark
44+
45+
The update message in the second line was sent before the deactivate message
46+
was treated. After the "inactive" message, the client can expect that no
47+
more untriggered update message are sent, though it MUST still be able to
48+
handle (or ignore) them, if they still occur.
49+
50+
The deactivate message might optionally accept a module name as second item of
51+
the message for module-wise deactivation. If module-wise deactivation is not
52+
supported, the SEC node should ignore a deactivate message which contains a
53+
module name and send an `error_deactivate` reply. This requires the ECS being
54+
able to handle update events at any time!
55+
56+
It is not clear if module-wise deactivation is really useful. A SEC node
57+
supporting module-wise activation does not necessarily need to support
58+
module-wise deactivation.

‎protocol/specification/messages/commands.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
``do``: execute commands
2+
~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
.. message:: [request] do <module>:<command> [<value>]
5+
[reply] done <module>:<command> <data-report>
6+
[reply] error_do <module>:<command> <error-report>
7+
8+
Actions can be triggered with a command. If an action needs significant time to
9+
complete (i.e. longer than a fraction of a second), the information about the
10+
duration and success of such an action has to be transferred via the `status`
11+
parameter.
12+
13+
If a command is specified with an argument, the actual argument is given in the
14+
data part as a JSON value. This may be also a JSON object if the datatype of
15+
the argument specifies that (i.e. the type of the single argument can also be a
16+
struct, tuple or an array, see :ref:`data-types`). The types of arguments must
17+
conform to the declared datatypes from the datatype of the command argument.
18+
19+
A command may have a return value, which may also be structured. The "done"
20+
reply always contains a `data-report` with the return value. If no value is
21+
returned, the data part is set to "null". The "done" message should be returned
22+
quickly, the time scale should be in the order of the time needed for
23+
communications. Still, all side-effects need to be realized and communicated
24+
before sending the `done` message.
25+
26+
.. note::
27+
28+
If a command does not require an argument, an argument MAY still be
29+
transferred as JSON null. A SEC node MUST accept and treat the following
30+
two messages the same:
31+
32+
- ``do <module>:<command>``
33+
- ``do <module>:<command> null``
34+
35+
An ECS SHOULD only generate the shorter version.
36+
37+
Example:
38+
39+
.. code::
40+
41+
> do t1:stop
42+
< done t1:stop [null,{"t":1505396348.876}]
43+
44+
> do t1:stop null
45+
< done t1:stop [null,{"t":1505396349.743}]

‎protocol/specification/messages/description.rst‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
``describe``: Description
2+
-------------------------
3+
4+
.. message:: [request] describe
5+
[reply] describing . <structure-report>
6+
7+
These messages are normally exchanged directly after requesting `*IDN?`. The
8+
reply contains the "structure report", i.e. a JSON object describing the name of
9+
modules exported and their parameters, together with the corresponding
10+
properties. This is explained in detail in :ref:`descriptive-data`.
11+
12+
The dot (second item in the reply message) is a placeholder for extensibility
13+
reasons and may be changed in a later revision. A client implementing the
14+
current specification MUST ignore it.
15+
16+
.. note:: This reply might be a very long line, no raw line breaks are allowed
17+
in the JSON part. Clients MUST implement a reasonable buffer size for
18+
these replies or use a streaming JSON decoder.
19+
20+
Example:
21+
22+
.. code::
23+
24+
> describe
25+
< describing . {"modules":{"t1":{"interface_classes":["TemperatureSensor","Readable"],"accessibles":{"value": ...
26+

‎protocol/specification/messages/errors.rst‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
.. _error-reply:
2+
3+
``error_*``: Error Replies
4+
--------------------------
5+
6+
Contains an error class from the list below as its second item (the specifier).
7+
The third item of the message is an :ref:`prop-error-report`, containing the
8+
request message (minus line endings) as a string in its first element, a (short)
9+
human readable text as its second element. The third element is a JSON object,
10+
containing possibly implementation specific information about the error (stack
11+
dump etc.).
12+
13+
Example:
14+
15+
.. code::
16+
17+
> read tx:target
18+
< error_read tx:target ["NoSuchModule","tx is not configured on this SEC node", {}]
19+
> change ts:target 12
20+
< error_change ts:target ["NoSuchParameter","ts has no parameter target", {}]
21+
> change t:target -9
22+
< error_change t:target ["BadValue","requested value (-9) is outside limits (0..300)", {}]
23+
> meas:volt?
24+
< error_meas:volt? ["ProtocolError","unknown action", {}]
25+
26+
27+
.. _error-classes:
28+
29+
Error Classes
30+
-------------
31+
32+
Error classes are divided into two groups: persisting errors and retryable
33+
errors. Persisting errors will yield the exact same error message if the exact
34+
same request is sent at any later time. A retryable error may give different
35+
results if the exact same message is sent at a later time, i.e. depends on state
36+
information internal to either the SEC node, the module or the connected
37+
hardware.
38+
39+
.. rubric:: Persisting errors
40+
41+
.. errorclass:: ProtocolError
42+
43+
A malformed Request or on unspecified message was sent. This includes
44+
non-understood actions and malformed specifiers. Also if the message
45+
exceeds an implementation defined maximum size. *Note: this may be
46+
retryable if induced by a noisy connection.*
47+
48+
.. errorclass:: NoSuchModule
49+
50+
The action can not be performed as the specified module is non-existent.
51+
52+
.. errorclass:: NoSuchParameter
53+
54+
The action can not be performed as the specified parameter is non-existent.
55+
56+
.. errorclass:: NoSuchCommand
57+
58+
The specified command does not exist.
59+
60+
.. errorclass:: ReadOnly
61+
62+
The requested write can not be performed on a readonly value.
63+
64+
.. errorclass:: NotCheckable
65+
66+
The requested check can not be performed on the specified parameter
67+
(i.e. on parameters, where no :ref:`checkable <prop-checkable>` property
68+
is present, or if it is set to false).
69+
70+
.. errorclass:: WrongType
71+
72+
The requested parameter change or command can not be performed as the
73+
argument has the wrong type, e.g. a string where a number is expected,
74+
or a struct doesn't have all required members.
75+
76+
.. errorclass:: RangeError
77+
78+
The requested parameter change or command can not be performed as the
79+
argument value is not in the allowed range specified by the ``datainfo``
80+
property. This also happens if an unspecified enum variant is tried to
81+
be used, the size of a blob or string does not match the limits given in
82+
the descriptive data, or if the number of elements in an array does not
83+
match the limits given in the descriptive data.
84+
85+
.. errorclass:: BadJSON
86+
87+
The data part of the message can not be parsed, i.e. the JSON data is
88+
not valid JSON.
89+
90+
.. errorclass:: NotImplemented
91+
92+
A (not yet) implemented action or combination of action and specifier
93+
was requested. This should not be used in productive setups, but is
94+
very helpful during development.
95+
96+
.. errorclass:: HardwareError
97+
98+
The connected hardware operates incorrectly or may not operate at all
99+
due to errors inside or in connected components.
100+
101+
.. rubric:: Retryable errors
102+
103+
.. errorclass:: CommandRunning
104+
105+
The command is already executing. The request may be retried after the
106+
module is no longer BUSY.
107+
108+
.. errorclass:: CommunicationFailed
109+
110+
Some communication (with hardware controlled by this SEC node) failed.
111+
112+
.. errorclass:: TimeoutError
113+
114+
Some initiated action took longer than the maximum allowed time.
115+
116+
.. errorclass:: IsBusy
117+
118+
The requested action can not be performed while the module is BUSY or
119+
the command still running.
120+
121+
.. errorclass:: IsError
122+
123+
The requested action can not be performed while the module is in error
124+
state.
125+
126+
.. errorclass:: Disabled
127+
128+
The requested action can not be performed while the module is disabled.
129+
130+
.. errorclass:: Impossible
131+
132+
The requested action can not be performed at the moment.
133+
134+
.. errorclass:: ReadFailed
135+
136+
The requested parameter can not be read just now.
137+
138+
.. errorclass:: OutOfRange
139+
140+
The value read from the hardware is out of sensor or calibration range.
141+
142+
.. errorclass:: InternalError
143+
144+
Something that should never happen just happened.
145+
146+
.. note:: This list may be extended, if needed. Clients should treat unknown
147+
error classes as generic errors.

‎protocol/specification/messages/heartbeat.rst‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
``ping``: heartbeat
2+
~~~~~~~~~~~~~~~~~~~
3+
4+
.. message:: [request] ping [<token>]
5+
[reply] pong [<token>] <data-report>
6+
7+
In order to detect that the other end of the communication is not dead, this
8+
heartbeat may be sent. The second part of the message (the token) must not contain
9+
a space and should be short and not be re-used. It may be omitted. The reply
10+
will contain exactly the same id.
11+
12+
A SEC node replies with a `pong` message with a `data-report` of a null value.
13+
The :ref:`qualifiers` part SHOULD only contain the timestamp (as member "t") if
14+
the SEC node supports timestamping. This can be used to synchronize the time
15+
between ECS and SEC node.
16+
17+
.. note:: The qualifiers could also be an empty JSON object, indicating lack of
18+
timestamping support.
19+
20+
For debugging purposes, when *id* in the `ping` request is omitted, in the
21+
`pong` reply there are two spaces after `pong`. A client SHOULD always send
22+
an id. However, the client parser MUST treat two consecutive spaces as two
23+
separators with an empty string in between.
24+
25+
Example:
26+
27+
.. code::
28+
29+
> ping 123
30+
< pong 123 [null, {"t": 1505396348.543}]
31+
32+
.. dropdown:: Related Issues
33+
34+
| :issue:`003 Timestamp Format`
35+
| :issue:`007 Time Synchronization`

‎protocol/specification/messages/identification.rst‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
``*IDN?``: Identification
2+
-------------------------
3+
4+
.. message:: [request] *IDN?
5+
[reply] ISSE,SECoP,<revision>,<version>
6+
7+
The syntax of the identification message differs from other messages, as it
8+
is meant to be compatible with IEEE 488.2. The identification request
9+
``*IDN?`` is meant to be sent as the first message after establishing a
10+
connection. The reply consists of 4 comma separated fields:
11+
12+
- The first field ("manufacturer") is always ``ISSE`` (``ISSE&SINE2020`` in
13+
SECoP versions 1.x).
14+
15+
- The second field ("product") is always ``SECoP``.
16+
17+
- The third field can be left empty, or set to a date that indicates the
18+
pre-release draft of the specification is in use, current as of that date.
19+
In that case, the fourth field is the latest released version the
20+
pre-release is based on.
21+
22+
- The fourth field specifies the released version of SECoP that the node
23+
implements.
24+
25+
Examples:
26+
27+
.. code::
28+
29+
> *IDN?
30+
< ISSE,SECoP,,v2.0
31+
32+
> *IDN?
33+
< ISSE,SECoP,2025-12-24,v2.0
34+
35+
> *IDN?
36+
< ISSE&SINE2020,SECoP,V2019-09-16,v1.0

0 commit comments

Comments
 (0)