Add changes from draft_wip missed when splitting spec

Author: birkenfeld

protocol/specification/datainfo.rst

@@ -12,9 +12,9 @@ to pinpoint the exact meaning of the data to be described.
 SECoP defines some basic data types for numeric quantities, like double_,
 scaled_ and int_.  An enum_ is defined for convenience of not having to remember
 the meaning of values from a reduced set.  A bool_ datatype is similar to a
-predefined Enum, but uses the JSON values true and false.  For non-numeric
-types, a string_ and a blob_ are defined as well.  Finally, matrix_ can
-transport larger multi-dimensional homogeneous arrays.
+predefined enum, but uses the JSON values ``true`` and ``false``.  For
+non-numeric types, a string_ and a blob_ are defined as well.  Finally, matrix_
+can transport larger multi-dimensional homogeneous arrays.
 
 Furthermore, SECoP not only defines basic data types, but also structured
 datatypes.  tuple_ allows aggregation of a fixed amount of values with different
@@ -69,6 +69,18 @@ Related issue: :issue:`042 Requirements of datatypes`
 ``"max"``
     Upper limit. If ``max`` is omitted, there is no upper limit.
 
+.. note::
+
+    When a SEC Node receives a ``"change"`` or ``"do"`` message with a value
+    outside the allowed range [``"min"``, ``"max"``], it MUST reply with an
+    error message.  For readonly parameters, [``"min"``, ``"max"``] indicate a
+    trusted range.  A SEC-Node might send ``"update"`` or ``"reply"`` messages
+    with values outside the trusted range, for example when the value is an
+    extrapolation of the calibrated range. The idea behind this relaxed rule is,
+    that it is better for a SEC-node to send an acquired value outside the range
+    as it is - rather than change its value just to comply with the specified
+    range.  The decision, how to treat such values is left to the ECS.
+
 ``"unit"``
     String giving the unit of the parameter.
 
@@ -138,11 +150,13 @@ Related issue: :issue:`044 Scaled integers`
 ``"min"``, ``"max"``
     The limits of the transported integer, ``min <= max``.  The limits of the
     represented floating point value are ``min*scale`` and ``max*scale``.
+    See also the note on the ``"min"`` and ``"max"`` properties of the
+    :ref:`float` datatype.
 
 .. rubric:: Optional data properties
 
 ``"unit"``
-    String giving the unit of the paramete, as for double_.
+    String giving the unit of the parameter, as for double_.
 
 ``"absolute_resolution"``
     A JSON number specifying the smallest difference between distinct values.
@@ -189,6 +203,8 @@ with 32bit float too.
 
 ``"min"``, ``"max"``
     Integer limits, ``<min>`` <= ``<max>``.
+    See also the note on the ``"min"`` and ``"max"`` properties of the
+    :ref:`float` datatype.
 
 .. rubric:: Optional data properties
 
@@ -235,7 +251,7 @@ Datatype to be used for values that can only have a set of predefined values.
 .. rubric:: Mandatory data property
 
 ``"members"``
-    A JSON object giving all possible values: ``{<name>: <value>, ....}``
+    A JSON object giving all possible values: ``{<name>: <value>, ...}``
 
     ``name``\ s are strings, ``value``\ s are (preferably small) integers.  Both
     ``name``\ s and ``value``\ s MUST be unique within an enum.
@@ -248,7 +264,7 @@ Datatype to be used for values that can only have a set of predefined values.
 
 .. rubric:: Transport
 
-As a JSON-number.  The client may perform a mapping back to the name.
+As a JSON number.  The client may perform a mapping back to the name.
 
 Example: ``200``
 
@@ -391,10 +407,10 @@ value.
 ``"optional"``
     A JSON list giving the names of optional struct elements.
 
-    In 'change' and 'do' commands, the ECS might omit these elements, all other
-    elements must be given.  The effect of a 'change' action with omitted
+    In `change` and `do` commands, the ECS might omit these elements, all other
+    elements must be given.  The effect of a `change` action with omitted
     elements should be the same as if the current values of these elements would
-    have been sent with it.  The effect of a 'do' action with omitted elements
+    have been sent with it.  The effect of a `do` action with omitted elements
     is defined by the implementation.
 
     In all other messages (i.e. in replies and updates), all elements have to be

protocol/specification/descriptive.rst

@@ -109,9 +109,9 @@ Optional Module Properties
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``"visibility"``
-    A string indicating a hint for UIs, for which user roles the module should be
-    displayed, hidden or allow read access only.
-    MUST be one of the values on the two visibility columns. The default is "www".
+    A string giving a hint for UIs, for which user roles the module should be
+    displayed, hidden or allow read access only.  MUST be one of the values on
+    the two visibility columns. The default is ``"www"``.
 
     .. table:: possible combinations of access hints
 
@@ -142,7 +142,7 @@ Optional Module Properties
     * A module with visibility "---" is meant not to be shown in a user interface,
       but might still be used by the client interface internally.
 
-    .. note:: The access is NOT controlled on the SECnode side! The visibility property is just a
+    .. note:: The access is NOT controlled on the SEC node side! The visibility property is just a
               hint to the UI (client) what should be exposed to (or better hidden from) the users
               having different levels of expertise.
               The UI (client) should implement the different access levels.
@@ -261,13 +261,24 @@ Optional Module Properties
 .. _implementor:
 
 ``"implementor"``
-    An optional string giving the implementor of a module, defining the meaning
+    A string giving the implementor of a module, defining the meaning
     of custom status values, custom properties and custom accessibles.  The
     implementor must be globally unique, for example 'sinq.psi.ch'.  This may
     be achieved by including a domain name, but it does not need to be a
     registered name, and other means of assuring a global unique name are also
     possible.
 
+``"implementation"``
+    A string indicating information about the implementation of the
+    module, like a Python class.
+
+    Example: ``"secop_psi.ppms.Field"``
+
+``"features"``
+    A list of supported features of a module.
+
+    Example: ``["HasOffset"]``
+
 
 Accessible Description
 ----------------------
@@ -319,9 +330,9 @@ Optional Accessible Properties
               for grouping of modules within a node.
 
 ``"visibility"``
-    A string indicating a hint for UIs, for which user roles the accessible should be
-    displayed, hidden or allow read access only.
-    MUST be one of the values on the two visibility columns. The default is "www".
+    A string giving a hint for UIs, for which user roles the accessible should
+    be displayed, hidden or allow read access only.  MUST be one of the values
+    on the two visibility columns.  The default is ``"www"``.
 
     .. table::
 

protocol/specification/intro.rst

@@ -52,8 +52,8 @@ Other requirements
 - The protocol should be defined in way that allows a maximum **compatibility**:
   Newer and older versions of the syntax should be compatible.
 
-- The protocol should be defined in a way that allows maximum **flexibility**:
-  A simple (= with minimal features) ECS implementation should be able to
-  communicate with a complex SEC node (with a lot of features), and an ECS with
-  a rich number of features should be able to cope with a simple SEC node,
-  implementing only a minimum number of features/functionality.
+- The protocol should be defined in a way that allows maximum **flexibility**: A
+  simple (= equipped with minimal functionality) ECS implementation should be
+  able to communicate with a complex SEC node (with wide-ranging functionality),
+  and an ECS with extensive functionality should be able to deal with a simple
+  SEC node that implements only a minimum of features.

protocol/specification/messages.rst

@@ -588,24 +588,26 @@ Example:
 .. code::
 
     > read tx:target
-    < error_read tx:target ["NoSuchModule","tx is not configured on this SEC node", {}]
+    < error_read tx:target ["NoSuchModule", "tx is not configured on this SEC node", {}]
     > change ts:target 12
-    < error_change ts:target ["NoSuchParameter","ts has no parameter target", {}]
+    < error_change ts:target ["NoSuchParameter", "ts has no parameter target", {}]
     > change t:target -9
-    < error_change t:target ["BadValue","requested value (-9) is outside limits (0..300)", {}]
+    < error_change t:target ["RangeError", "requested value (-9) is outside limits (0..300)", {}]
     > meas:volt?
-    < error_meas:volt?  ["ProtocolError","unknown action", {}]
+    < error_meas:volt?  ["ProtocolError", "unknown action", {}]
 
 
 .. _error-classes:
 
 _`Error Classes`:
     Error classes are divided into two groups: persisting errors and retryable
     errors.  Persisting errors will yield the exact same error message if the
-    exact same request is sent at any later time.  A retryable error may give
-    different results if the exact same message is sent at a later time, i.e.
-    depends on state information internal to either the SEC node, the module or
-    the connected hardware.
+    exact same request is sent at a later time without other interactions
+    inbetween.
+
+    A retryable error may give different results if the exact same message is
+    sent at a later time, i.e.  depends on state information internal to either
+    the SEC node, the module or the connected hardware.
 
     .. list-table:: Persisting errors
         :widths: 20 80

protocol/specification/modules.rst

@@ -64,7 +64,7 @@ Definition: Command
     ECS can use them only in a general way, as their meaning is not known.
 
 The following section describes the currently predefined accessibles, this list
-will be extended continuously.
+will be extended in new versions.
 
 
 Basic Parameters
@@ -109,11 +109,12 @@ Command ``"stop"``
 Command ``"go"``
     Optional command for starting an action.  If the ``go`` command is present,
     changing any parameter (especially the 'target' parameter) does not yet
-    initiate any action leading to a BUSY state.  In contrast, if no 'go'
-    command is present, changing the target will start an action trying to
-    change the value to get closer to the target, which usually leads to a BUSY
-    state.  Changing any parameter, which has an impact on measured values,
-    should be executed immediately.
+    initiate any action leading to a ``BUSY`` state.
+
+    In contrast, if no 'go' command is present, changing the target will start
+    an action trying to change the value to get closer to the target, which
+    usually leads to a BUSY state.  Changing any parameter, which has an impact
+    on measured values, should be executed immediately.
 
 Command ``"hold"``
     Optional command on a drivable.  Stay more or less where you are, cease
@@ -600,7 +601,7 @@ functionality in a specific way.
     module with the feature ``"HasOffset"`` must have a parameter ``offset``,
     which indicates to all clients that the transmitted raw values for the
     parameters ``value`` and ``target`` are to be converted to corrected values
-    (at the client side) by the following formulas:
+    (on the client side) by the following formulas:
 
     For reading the parameters ``value`` and ``target``: