rfcs: convert first issues

Author: birkenfeld

rfcs/RFC-001-issues.rst

@@ -0,0 +1,61 @@
+- Feature: About SECoP Issues
+- Status: Obsolete
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+This issue describes the "SECoP Issues", the original format of documents that
+preceded the RFC system.  As such, it is no longer relevant, please see
+:ref:`rfc-000` for the current rules for discussing SECoP extensions.
+
+
+Issue text
+==========
+
+The idea behind SECoP Issues is to document properly what was proposed,
+what was discussed, what was decided and why it was decided.
+
+An issue might take different states:
+
+(u) unspecified
+---------------
+
+A vague idea, but no proposal written down yet.
+
+(p) proposed
+------------
+
+A proposal should contain the motivation. As long as nobody else
+joins into a discussion, the state remains *proposed*.
+
+(d) under discussion
+--------------------
+
+This state is kept until a decision is taken.
+
+(f) finalizing
+--------------
+
+This state is kept until the specification change is agreed.
+
+( ) closed
+----------
+
+After a decision the state is *closed*. The issue is not deleted,
+even if the decision was to not follow further the proposal.
+This is helpful if somebody later raises a similar issue.
+However, it should be possible to reopen an issue, if new
+arguments arise.
+
+Remark:
+-------
+
+At the meeting in Lund (13th June 2018), it was agreed not to follow the proposal
+of creating a new state "extensible" for an issue containing an extensible
+list. Instead, an new issue should be created, containing the added elements.
+A full actual list should be added each time.

rfcs/RFC-002-describe-specifier.rst

@@ -0,0 +1,43 @@
+- Feature: Equipment ID in Describing Message
+- Status: Rejected
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Could the equipment ID go into the "specifier" field of the "describing"
+message?
+
+
+Issue text
+==========
+
+The equipment ID is a SEC node property, and it is therefore redundant
+to put it as the second item of the describe message.
+
+However as the describe/describing message might be extended later, for
+example to get the description of single modules only, we should specify
+a fixed word for the second item of the describe message, for example the
+keyword "ALL" or "All".
+
+At the meeting in Berlin (2017-05-30) this was discussed, but it was not
+yet decided the the keyword should be exactly. Until a final decision,
+SECoP clients should ignore the second item.
+
+Opinions
+--------
+
+We should use key keyword ALL (Markus Zolliker).
+
+Decision
+--------
+
+The decision was taken to use a bare period as placeholder:
+
+.. code::
+
+    describing . {"modules": ...

rfcs/RFC-003-timestamps.rst

@@ -0,0 +1,68 @@
+- Feature: Timestamp Format
+- Status: Final
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Which format should timestamps in value qualifiers take?
+
+
+Issue text
+==========
+
+Proposals for the timestamp format are:
+
+ISO time format
+---------------
+
+A date+time string in ISO format like "2017-06-21T13:30:01.123456+02:00"
+
+The fractional seconds are optional, but the timezone has to be given. Z is allowed instead of +00:00.
+
+Advantages:
+
+* human readable
+
+Disadvantages:
+
+* needs more conversion efforts, as the time is internally already stored as
+  numbers on mosts systems (supporting math operations)
+* although the ISO standard is clearly defined, there is a risk that time zones
+  and daylight saving time is not handled properly
+
+Fractional Unix Time
+--------------------
+
+Seconds since 1970-01-01T00:00:00+00:00, represented as a number. When converted
+to a IEEE double, a resolution of 1 usec can be kept for dates up to 2112.
+
+Advantages:
+
+* if a double is used as an internal representation, no conversion is
+  needed. using a double as an internal time representation has the advantage,
+  that math operations can be done for free.
+* relative times for systems with no synchronized clock can be represented
+  easily
+
+Disadvantages:
+
+* not human readable (or at least not easily: time differences in seconds are
+  still visible)
+
+Discussion
+----------
+
+1) Human readibility was judged less important than easy implementaion by the majority.
+
+2) Implementing relative times is also easier.
+
+Decision
+--------
+
+At the meeting in Berlin (2017-05-30) the attendes decided for "Fractional Unix Time".
+The resolution of the timestamp depends on the hardware, but must be at least one second.

rfcs/RFC-004-timeout-property.rst

@@ -0,0 +1,38 @@
+- Feature: The Timeout SEC Node Property
+- Status: Final
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Specifies how to select a suitable response timeout for a SEC node.
+
+
+Issue text
+==========
+
+For a SECoP client, in order to detect that a connection to a SECoP server is dead,
+'ping' messages can be sent. When no 'pong' message is received within a specified
+time, then the client can consider the connection as dead.
+
+If the server does not specify a the SEC node property 'timeout', the timeout
+is assumed to be 3s.
+
+Opinions
+--------
+
+On the meeting in Garching (2017-09-14) it was proposed to fix this a standard.
+
+
+Decision
+--------
+
+It is assumed that when a SEC node is not replying within *timeout*
+seconds, the client may assume that the SEC node is dead or stuck.
+
+If *timeout* is not specfied as a SEC node property. it is assumed to
+be 10 seconds.

rfcs/RFC-005-qualifiers.rst

@@ -0,0 +1,51 @@
+- Feature: Definition of the term 'Qualifier'
+- Status: Final
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Specifies qualifiers as the "properties" of live data.
+
+
+Issue text
+==========
+
+The definition as in SECoP V2016-11-30 draft is not very consistent.
+
+As decriptive data we have:
+
+- SEC node properties
+- module properties
+- parameters properties
+- command properties
+
+Live data may be:
+- value
+- timestamp 't'
+- sigma 'e'
+
+It is confusing to use the same term 'property' for live data and for
+descriptive data.
+
+The section with the definition of properties has to be rewritten.
+
+Opinions
+--------
+
+Enrico proposed to name live data like timestamps and sigma *qualifiers*.
+
+Markus supports this. He would be happy also with a term other than
+*qualifiers*, but definitely does not like the terms *live properties* and
+*descriptive properties*, as two different things share the same name.
+
+
+Decision
+--------
+
+Additional information transported with an update message like timestamps and
+sigma are called *qualifiers*.

rfcs/RFC-006-keepalive.rst

@@ -0,0 +1,40 @@
+- Feature: Keep Alive
+- Status: Rejected
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Does the SEC node need a mechanism to detect "dead" client connections?
+
+
+Issue text
+==========
+
+For a SECoP server, in order to detect that a client connection is dead,
+it might close a connection with no messages within a defined period of time.
+
+The discussed mechanism is:
+
+The SECoP client has to set the connection parameter 'keepalive' to a value
+representing the number of seconds it will send 'ping' (or other) messages.
+The SECoP server can close connections with no messages for a time period
+well above this value (more than 10% higher).
+
+Opinions
+--------
+
+Markus proposes to mention the 10 % in the specification.
+It should also be mentioned, that for keeping the connection alive
+any message might be sent instead of the ping message.
+
+Decision
+--------
+
+We close this issue, not defining such a mechanism.
+If in an implementation pending dead connections arise to be problem
+to the SEC node server, we might reopen the issue.

rfcs/RFC-007-time-synchronization.rst

@@ -0,0 +1,54 @@
+- Feature: Time Synchronization
+- Status: Rejected
+- Submit Date: 2018-02-13
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Handling of timestamp clock differences between node and client.
+
+
+Issue text
+==========
+
+As a SECoP server and a SECoP client might not run with a common clock,
+the SECoP client should be able to correct for time slips.
+
+On the meetings in Berlin and Garching in 2017 it was proposed to put this into
+the standard, the exact wording has to be decided.
+
+Agreement
+---------
+
+The kind of SEC-node clock shall be noted as node property in the descriptive data.
+
+Proposal
+--------
+
+A SEC-node property called *clock* describes the kind of clock.
+
+datatype: Enum(none=0, relative=1, absolute=2)
+
+The default is *none*.
+
+Discussion
+----------
+
+It might happen that for some parameters no timestamps are delivered while
+on others there are.
+What should the client do when *none* is specified, but a timestamp
+is delivered on a parameter? Is this a violation of the protocol, or should the
+client ignore the timestamp?
+
+Decision
+--------
+
+The ECS can easily detect if the clock is accurate enough by sending a ping
+command. If the timestamp delivered by the pong message lies between the
+time the ping message was sent and the pong message was received, then the
+timestamp can be trusted, else the ECS might record the time shift and decide to
+use relative times. (Decision taken at the meeting 2018-02-13 in Grenoble)

rfcs/RFC-008-groups.rst

@@ -0,0 +1,36 @@
+- Feature: Groups
+- Status: Final
+- Submit Date: 2018-02-13
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Definition of the `group` property for modules and accessibles.
+
+
+Issue text
+==========
+
+Proposal
+--------
+
+Modules as well as parameters may have a property "group".
+If the client has the possibility to group modules and/or
+parameters, it should use this information for grouping.
+
+The lowercase version of module group names must not clash
+with the lowercase version of a module name.
+The lowercase version of parameter group names must not clash
+with the lowercase version of a parameter names on the same module.
+
+The "group" property may contain colons (':') as separator,
+in order to construct a hierarchy of more than one level.
+
+Decision
+--------
+
+Accepted at the meeting 2018-02-13 in Grenoble.