From 0d60bbfcf791aaef6a99091f1ee4001b2eb816e3 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 12 Nov 2025 11:01:42 +0100 Subject: [PATCH 1/2] move new RFCs to 1xx number, move RFC process doc to 000 --- issues/README.rst | 2 +- protocol/specification/changes.rst | 6 +++--- protocol/specification/classes.rst | 2 +- protocol/specification/discovery.rst | 2 +- protocol/specification/transport.rst | 2 +- rfcs/{RFC-001-RFC-process.rst => RFC-000-rfc-process.rst} | 2 +- rfcs/{RFC-002-schemata.rst => RFC-102-schemata.rst} | 0 rfcs/{RFC-003-schema-links.rst => RFC-103-schema-links.rst} | 0 rfcs/{RFC-004-systems.rst => RFC-104-systems.rst} | 0 ...{RFC-005-udp-discovery.rst => RFC-105-udp-discovery.rst} | 0 rfcs/{RFC-006-acquisition.rst => RFC-106-acquisition.rst} | 0 rfcs/{RFC-007-websockets.rst => RFC-107-websockets.rst} | 0 rfcs/{RFC-000-template.rst => RFC-template.rst} | 0 13 files changed, 8 insertions(+), 8 deletions(-) rename rfcs/{RFC-001-RFC-process.rst => RFC-000-rfc-process.rst} (98%) rename rfcs/{RFC-002-schemata.rst => RFC-102-schemata.rst} (100%) rename rfcs/{RFC-003-schema-links.rst => RFC-103-schema-links.rst} (100%) rename rfcs/{RFC-004-systems.rst => RFC-104-systems.rst} (100%) rename rfcs/{RFC-005-udp-discovery.rst => RFC-105-udp-discovery.rst} (100%) rename rfcs/{RFC-006-acquisition.rst => RFC-106-acquisition.rst} (100%) rename rfcs/{RFC-007-websockets.rst => RFC-107-websockets.rst} (100%) rename rfcs/{RFC-000-template.rst => RFC-template.rst} (100%) diff --git a/issues/README.rst b/issues/README.rst index 1b2a8e20..a8ca033f 100644 --- a/issues/README.rst +++ b/issues/README.rst @@ -3,7 +3,7 @@ Note SECoP Issues have been replaced by the RFC process, which is described in `RFC 1 -`_. +`_. If there is renewed interest in one of the remaining open issues, please migrate to an RFC before restarting discussion. diff --git a/protocol/specification/changes.rst b/protocol/specification/changes.rst index 3f698092..31ab00ea 100644 --- a/protocol/specification/changes.rst +++ b/protocol/specification/changes.rst @@ -51,11 +51,11 @@ loss of functionality. - The :ref:`matrix ` data type has been specified for datainfo. - The `AcquisitionController`, `AcquisitionChannel` and `Acquisition` interface - classes have been specified (:ref:`rfc-006`). + classes have been specified (:ref:`rfc-106`). -- The UDP discovery protocol has been specified (:ref:`rfc-005`). +- The UDP discovery protocol has been specified (:ref:`rfc-105`). -- Optional SECoP transport over WebSockets has been specified (:ref:`rfc-007`). +- Optional SECoP transport over WebSockets has been specified (:ref:`rfc-107`). Version 1.1 diff --git a/protocol/specification/classes.rst b/protocol/specification/classes.rst index 15e47add..a25f4441 100644 --- a/protocol/specification/classes.rst +++ b/protocol/specification/classes.rst @@ -83,7 +83,7 @@ The following terms are relevant here: quantity. An acquisition can acquire data for one or more channels at the same time. -See also :secop-rfc:`006-acquisition`. +See also :ref:`rfc-106`. .. baseclass:: AcquisitionController diff --git a/protocol/specification/discovery.rst b/protocol/specification/discovery.rst index d2e91c25..1c12aa63 100644 --- a/protocol/specification/discovery.rst +++ b/protocol/specification/discovery.rst @@ -80,4 +80,4 @@ Implementation hints necessary. -See also :ref:`rfc-005`. +See also :ref:`rfc-105`. diff --git a/protocol/specification/transport.rst b/protocol/specification/transport.rst index 5ff8fae0..90ca2aa9 100644 --- a/protocol/specification/transport.rst +++ b/protocol/specification/transport.rst @@ -104,7 +104,7 @@ exchanging raw SECoP messages is not an option. The best alternative is WebSockets (:rfc:`6455`), which are a relatively overhead-free way of exchanging messages between two endpoints in an arbitrary pattern. -See also :ref:`rfc-007`. +See also :ref:`rfc-107`. Implementation in a SEC node ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/rfcs/RFC-001-RFC-process.rst b/rfcs/RFC-000-rfc-process.rst similarity index 98% rename from rfcs/RFC-001-RFC-process.rst rename to rfcs/RFC-000-rfc-process.rst index 0aa883c9..b138c8a2 100644 --- a/rfcs/RFC-001-RFC-process.rst +++ b/rfcs/RFC-000-rfc-process.rst @@ -62,7 +62,7 @@ How to contribute Here we lay out the steps to follow to change the specification. - If you do not have a concrete idea, come talk to us to flesh it out. -- Copy the RFC-000-template.rst file and fill in the details. You can add +- Copy the RFC-template.rst file and fill in the details. You can add sections freely, but try to fill out all the provided ones. - Take the next free number and add it to the template file. Renumbering might happen when the PR is merged. diff --git a/rfcs/RFC-002-schemata.rst b/rfcs/RFC-102-schemata.rst similarity index 100% rename from rfcs/RFC-002-schemata.rst rename to rfcs/RFC-102-schemata.rst diff --git a/rfcs/RFC-003-schema-links.rst b/rfcs/RFC-103-schema-links.rst similarity index 100% rename from rfcs/RFC-003-schema-links.rst rename to rfcs/RFC-103-schema-links.rst diff --git a/rfcs/RFC-004-systems.rst b/rfcs/RFC-104-systems.rst similarity index 100% rename from rfcs/RFC-004-systems.rst rename to rfcs/RFC-104-systems.rst diff --git a/rfcs/RFC-005-udp-discovery.rst b/rfcs/RFC-105-udp-discovery.rst similarity index 100% rename from rfcs/RFC-005-udp-discovery.rst rename to rfcs/RFC-105-udp-discovery.rst diff --git a/rfcs/RFC-006-acquisition.rst b/rfcs/RFC-106-acquisition.rst similarity index 100% rename from rfcs/RFC-006-acquisition.rst rename to rfcs/RFC-106-acquisition.rst diff --git a/rfcs/RFC-007-websockets.rst b/rfcs/RFC-107-websockets.rst similarity index 100% rename from rfcs/RFC-007-websockets.rst rename to rfcs/RFC-107-websockets.rst diff --git a/rfcs/RFC-000-template.rst b/rfcs/RFC-template.rst similarity index 100% rename from rfcs/RFC-000-template.rst rename to rfcs/RFC-template.rst From c753f04dad7670ef58f39c791ca422d5d8fa49d9 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 18 Oct 2025 16:29:58 +0200 Subject: [PATCH 2/2] rfcs: convert first issues --- rfcs/RFC-001-issues.rst | 61 +++++++++++++++++++ rfcs/RFC-002-describe-specifier.rst | 43 +++++++++++++ rfcs/RFC-003-timestamps.rst | 68 +++++++++++++++++++++ rfcs/RFC-004-timeout-property.rst | 38 ++++++++++++ rfcs/RFC-005-qualifiers.rst | 51 ++++++++++++++++ rfcs/RFC-006-keepalive.rst | 40 ++++++++++++ rfcs/RFC-007-time-synchronization.rst | 54 ++++++++++++++++ rfcs/RFC-008-groups.rst | 36 +++++++++++ rfcs/RFC-009-module-meaning.rst | 88 +++++++++++++++++++++++++++ rfcs/RFC-010-name-character-set.rst | 38 ++++++++++++ 10 files changed, 517 insertions(+) create mode 100644 rfcs/RFC-001-issues.rst create mode 100644 rfcs/RFC-002-describe-specifier.rst create mode 100644 rfcs/RFC-003-timestamps.rst create mode 100644 rfcs/RFC-004-timeout-property.rst create mode 100644 rfcs/RFC-005-qualifiers.rst create mode 100644 rfcs/RFC-006-keepalive.rst create mode 100644 rfcs/RFC-007-time-synchronization.rst create mode 100644 rfcs/RFC-008-groups.rst create mode 100644 rfcs/RFC-009-module-meaning.rst create mode 100644 rfcs/RFC-010-name-character-set.rst diff --git a/rfcs/RFC-001-issues.rst b/rfcs/RFC-001-issues.rst new file mode 100644 index 00000000..60b152cf --- /dev/null +++ b/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. diff --git a/rfcs/RFC-002-describe-specifier.rst b/rfcs/RFC-002-describe-specifier.rst new file mode 100644 index 00000000..7049d376 --- /dev/null +++ b/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": ... diff --git a/rfcs/RFC-003-timestamps.rst b/rfcs/RFC-003-timestamps.rst new file mode 100644 index 00000000..d5910e43 --- /dev/null +++ b/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. diff --git a/rfcs/RFC-004-timeout-property.rst b/rfcs/RFC-004-timeout-property.rst new file mode 100644 index 00000000..a141cd80 --- /dev/null +++ b/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. diff --git a/rfcs/RFC-005-qualifiers.rst b/rfcs/RFC-005-qualifiers.rst new file mode 100644 index 00000000..5c8c57a8 --- /dev/null +++ b/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*. diff --git a/rfcs/RFC-006-keepalive.rst b/rfcs/RFC-006-keepalive.rst new file mode 100644 index 00000000..7ff959e3 --- /dev/null +++ b/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. diff --git a/rfcs/RFC-007-time-synchronization.rst b/rfcs/RFC-007-time-synchronization.rst new file mode 100644 index 00000000..86c77a40 --- /dev/null +++ b/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) diff --git a/rfcs/RFC-008-groups.rst b/rfcs/RFC-008-groups.rst new file mode 100644 index 00000000..690569ae --- /dev/null +++ b/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. diff --git a/rfcs/RFC-009-module-meaning.rst b/rfcs/RFC-009-module-meaning.rst new file mode 100644 index 00000000..7c035ea0 --- /dev/null +++ b/rfcs/RFC-009-module-meaning.rst @@ -0,0 +1,88 @@ +- Feature: Module Meaning +- Status: Final +- Submit Date: 2018-02-13 +- Authors: SECoP committee +- Type: Issue +- PR: +- Version: 1.0 + +Summary +======= + +First definition of the `meaning` property for modules. + + +Issue text +========== + +Proposal +........ + +meaning +------- + +For the ECS an automatic detection of the main modules would be desirable. + +For example a SEC Node could tell which sensor would be the closest one to +the sample, which should be registered in the ECS as the sample temperature. + +For this, a module property "meaning" is proposed. This can get one of the +following values: + +* sample_temperature +* magnetic_field + +importance +---------- + +But what to do, if several modules claim to be the sample temperature? +There might be a SEC node controlling cryostat, which has a sample temperature sensor, +but another SEC node controlling an insert with a sample sensor. As the insert +is put into the cryostat, we declare the cryostat to have importance=1 and +the insert an importance=2. To resolve the ambiguity, the ECS chooses the +module with the highest importance to be labelled as the read sample temperature. + +Proposal: + +predefined importance: + + * importance=1 for a device which can not be inserted or added to another one + * importance=2 for a device which can be inserted into an other one + +Higher values are to be used when an additional device may be inserted into an insert +and the like. + +We should allow importance to be a floating point number, in case later a value +between 1 and 2 has to be used. + +Decision +........ + +meaning is a module property with a tuple as its value, with the following two elements: + +* a string from an extensible list of meanings +* a value describing the importance, with the following values + + - 10 means the instrument/beamline (Example: room temperature sensor always present) + - 20 means the surrounding sample environemnt (Example: VTI temperature) + - 30 means an insert (Example: sample stick of dilution insert) + - 40 means an addon added to an insert (Example: a device mounted inside a dilution insert) + +Intermediate values might be used. The range for each category starts at the indicated value minus 5 +and ends below the indicated value plus 5. + +Decision taken at the meeting 2018-02-13 in Grenoble + +Decision (2019-06-13 Lund) on the first items of the list: +---------------------------------------------------------- + + * temperature (temperature of sample) + * temperature_regulation (regulation of sample temperature, if different from above). + * magneticfield + * electricfield + * pressure + * rotation_z (counter clockwise when looked at 'from sky to earth') + * humidity + * viscosity + * flowrate + * concentration diff --git a/rfcs/RFC-010-name-character-set.rst b/rfcs/RFC-010-name-character-set.rst new file mode 100644 index 00000000..70ccd2ee --- /dev/null +++ b/rfcs/RFC-010-name-character-set.rst @@ -0,0 +1,38 @@ +- Feature: Character Set for Names +- Status: Final +- Submit Date: 2018-02-13 +- Authors: SECoP committee +- Type: Issue +- PR: +- Version: 1.0 + +Summary +======= + +Are upper-case letters allowed in identifiers (names of modules, accessibles, +properties)? + + +Issue text +========== + +Uppercase Characters in Identifiers +----------------------------------- + +Actually (V2017-09-14), the following is specified: + +The identifiers are composed by +lowercase ascii letters, digits and underscore, where a digit may not +appear as the first character. Identifiers starting with underscore are +reserved for special purposes like internal use for debugging. The +identifier length is limited (<=63 characters). + +In an outdated part of the documentation it is not +explicitly stated, that identifiers have to be lower case, and also +in some of the running examples contain uppercase identifiers. + +Decision +-------- + +Names may contain uppercased letters as long as the lowercase version is still +unique.