diff --git a/doc/source/playground/client/index.rst b/doc/source/client/index.rst similarity index 100% rename from doc/source/playground/client/index.rst rename to doc/source/client/index.rst diff --git a/doc/source/playground/facility/demo/cryo.rst b/doc/source/facility/demo/cryo.rst similarity index 100% rename from doc/source/playground/facility/demo/cryo.rst rename to doc/source/facility/demo/cryo.rst diff --git a/doc/source/playground/facility/demo/index.rst b/doc/source/facility/demo/index.rst similarity index 100% rename from doc/source/playground/facility/demo/index.rst rename to doc/source/facility/demo/index.rst diff --git a/doc/source/playground/facility/demo/test.rst b/doc/source/facility/demo/test.rst similarity index 100% rename from doc/source/playground/facility/demo/test.rst rename to doc/source/facility/demo/test.rst diff --git a/doc/source/playground/facility/ess/epics.rst b/doc/source/facility/ess/epics.rst similarity index 100% rename from doc/source/playground/facility/ess/epics.rst rename to doc/source/facility/ess/epics.rst diff --git a/doc/source/playground/facility/ess/index.rst b/doc/source/facility/ess/index.rst similarity index 100% rename from doc/source/playground/facility/ess/index.rst rename to doc/source/facility/ess/index.rst diff --git a/doc/source/playground/facility/index.rst b/doc/source/facility/index.rst similarity index 100% rename from doc/source/playground/facility/index.rst rename to doc/source/facility/index.rst diff --git a/doc/source/playground/facility/mlz/amagnet.rst b/doc/source/facility/mlz/amagnet.rst similarity index 100% rename from doc/source/playground/facility/mlz/amagnet.rst rename to doc/source/facility/mlz/amagnet.rst diff --git a/doc/source/playground/facility/mlz/entangle.rst b/doc/source/facility/mlz/entangle.rst similarity index 100% rename from doc/source/playground/facility/mlz/entangle.rst rename to doc/source/facility/mlz/entangle.rst diff --git a/doc/source/playground/facility/mlz/index.rst b/doc/source/facility/mlz/index.rst similarity index 100% rename from doc/source/playground/facility/mlz/index.rst rename to doc/source/facility/mlz/index.rst diff --git a/doc/source/playground/framework/datatypes.rst b/doc/source/framework/datatypes.rst similarity index 100% rename from doc/source/playground/framework/datatypes.rst rename to doc/source/framework/datatypes.rst diff --git a/doc/source/playground/framework/errors.rst b/doc/source/framework/errors.rst similarity index 100% rename from doc/source/playground/framework/errors.rst rename to doc/source/framework/errors.rst diff --git a/doc/source/playground/framework/index.rst b/doc/source/framework/index.rst similarity index 100% rename from doc/source/playground/framework/index.rst rename to doc/source/framework/index.rst diff --git a/doc/source/playground/gui/index.rst b/doc/source/gui/index.rst similarity index 100% rename from doc/source/playground/gui/index.rst rename to doc/source/gui/index.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 72ea416..46a1f63 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,12 +1,14 @@ -Welcome to SECoP's documentation! -================================= +Welcome to FRAPPY documentation! +================================ .. toctree:: :maxdepth: 2 - protocol/index - playground/index - + server/index + client/index + framework/index + gui/index + facility/index Indices and tables diff --git a/doc/source/playground/index.rst b/doc/source/playground/index.rst deleted file mode 100644 index b829df7..0000000 --- a/doc/source/playground/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -Playground documentation -======================== - -.. toctree:: - :maxdepth: 2 - - server/index - client/index - framework/index - gui/index - facility/index - - diff --git a/doc/source/playground/server/protocol/encoding.rst b/doc/source/playground/server/protocol/encoding.rst deleted file mode 100644 index 642c681..0000000 --- a/doc/source/playground/server/protocol/encoding.rst +++ /dev/null @@ -1,6 +0,0 @@ -SECoP Encoding -============== - -.. automodule:: secop.protocol.encoding.secop - :members: - diff --git a/doc/source/playground/server/protocol/framing/demo.rst b/doc/source/playground/server/protocol/framing/demo.rst deleted file mode 100644 index 2f74dba..0000000 --- a/doc/source/playground/server/protocol/framing/demo.rst +++ /dev/null @@ -1,7 +0,0 @@ -Demo -==== - -.. automodule:: secop.protocol.framing.demo - :members: - - diff --git a/doc/source/playground/server/protocol/framing/eol.rst b/doc/source/playground/server/protocol/framing/eol.rst deleted file mode 100644 index 43f2933..0000000 --- a/doc/source/playground/server/protocol/framing/eol.rst +++ /dev/null @@ -1,6 +0,0 @@ -EOL -=== - -.. automodule:: secop.protocol.framing.eol - :members: - diff --git a/doc/source/playground/server/protocol/framing/index.rst b/doc/source/playground/server/protocol/framing/index.rst deleted file mode 100644 index 43c7659..0000000 --- a/doc/source/playground/server/protocol/framing/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Framings -======== - -.. toctree:: - :maxdepth: 3 - - demo - eol - null - rle - diff --git a/doc/source/playground/server/protocol/framing/null.rst b/doc/source/playground/server/protocol/framing/null.rst deleted file mode 100644 index 1816b44..0000000 --- a/doc/source/playground/server/protocol/framing/null.rst +++ /dev/null @@ -1,6 +0,0 @@ -Null -==== - -.. automodule:: secop.protocol.framing.null - :members: - diff --git a/doc/source/playground/server/protocol/framing/rle.rst b/doc/source/playground/server/protocol/framing/rle.rst deleted file mode 100644 index 6083b3e..0000000 --- a/doc/source/playground/server/protocol/framing/rle.rst +++ /dev/null @@ -1,6 +0,0 @@ -RLE -=== - -.. automodule:: secop.protocol.framing.rle - :members: - diff --git a/doc/source/protocol/commands.rst b/doc/source/protocol/commands.rst deleted file mode 100644 index 434bf1e..0000000 --- a/doc/source/protocol/commands.rst +++ /dev/null @@ -1,22 +0,0 @@ -Commands -======== - -The "done" message should be returned quickly, the time scale should -be in the order of the time needed for communications. Actions which have -to wait for physical changes, can be triggered with a command. -The information about the success of such an action has to be transferred -via parameters, namely the status parameter. - -A command has at least the following properties: - -:description: - tell what this command does - -:arguments: - a list of datatypes for the command arguments (may be empty) - -:resulttype: - the type of the result (may be null) - - - diff --git a/doc/source/protocol/datatypes.rst b/doc/source/protocol/datatypes.rst deleted file mode 100644 index f2bf134..0000000 --- a/doc/source/protocol/datatypes.rst +++ /dev/null @@ -1,173 +0,0 @@ -Datatypes -========= - -double ------- - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["double"] *or* - | ["double", ] *or* - | ["double", , ] - | - | if is not given or null, there is no upper limit - | if is null or not given, there is no lower limit - - * - Transport example - - | 3.14159265 - - * - Datatype in C/C++ - - | double - -int ---- - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["int"] *or* - | ["int", ] *or* - | ["int", , ] - | - | if is not given or null, there is no upper limit - | if is null or not given, there is no lower limit - - * - Transport example - - | -55 - - * - Datatype in C/C++ - - | int64_t - -bool ----- - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["bool"] - - * - Transport example - - | true - - * - Datatype in C/C++ - - | int64_t - - -enum ----- - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["enum", { : , ....}] - - * - Transport example - - | 2 - - * - Datatype in C/C++ - - | int64_t - - -string ------- - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["string"] *or* - | ["string", ] *or* - | ["string", , ] - | - | if is not given, it is assumed as 255. - | if is not given, it is assumed as 0. - | if the string is UTF-8 encoded, the length is counting the number of bytes, not characters - - * - Transport example - - | "hello!" - - * - Datatype in C/C++ API - - | char \* - -blob ----- - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["blob", ] *or* - | ["blob", , ] - | - | if is not given, it is assumed as 0. - - * - Transport example - - | "AA==" (base64 encoded) - - * - Datatype in C/C++ API - - | struct {int64_t len, char \*data} - -array ------ - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["array", , ] *or* - | ["array", , , ] - | - | if is not given, it is assumed as 0. - | the length is the number of elements - - * - Transport example - - | [3,4,7,2,1] - - * - Datatype in C/C++ API - - | [] - -tuple ------ - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["tuple", [, , ...]] - - * - Transport example - - | [0,"idle"] - - * - Datatype in C/C++ API - - | struct - -struct ------- - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["struct", { : , : , ....}] - - * - Transport example - - | {"x": 0, "y": 1} - - * - Datatype in C/C++ API - - | struct - | - | might be null diff --git a/doc/source/protocol/descjson.rst b/doc/source/protocol/descjson.rst deleted file mode 100644 index 792f89b..0000000 --- a/doc/source/protocol/descjson.rst +++ /dev/null @@ -1,11 +0,0 @@ -Structure of the descriptive json -================================= - -* json = {"modules": , "properties": , ...} -* module = {"name": , "parameters": , "commands": , "properties": } -* parameter = {"name": ..., "properties": } -* command = {"name": ..., "properties": } -* property = {"name":, "datatype": , "value": } - -note: property may also be [,,] - diff --git a/doc/source/protocol/descprop.rst b/doc/source/protocol/descprop.rst deleted file mode 100644 index befcf45..0000000 --- a/doc/source/protocol/descprop.rst +++ /dev/null @@ -1,48 +0,0 @@ -Descriptive properties -====================== - -Mandatory descriptive properties --------------------------------- - -parameter-properties -++++++++++++++++++++ - -* name (implicit) -* datatype -* readonly (bool) - -module-properties -+++++++++++++++++ - -* interface_class [list_of_strings] (MAY be empty) - -SEC-Node-properties -+++++++++++++++++++ - -* no mandatory properties - -Optional descriptive properties -------------------------------- - -parameter-properties -++++++++++++++++++++ - -* unit (string), SHOULD be given if meaningful (if not given: unitless) (empty string: unit is one) -* description (string), SHOULD be given -* visibility -* group (identifier) (MUST start with an uppercase letter) (if empty string: treat as not specified) - -module-properties -+++++++++++++++++ - -* description (string), SHOULD be given -* visibility -* group (identifier) (MUST start with an uppercase letter) (if empty string: treat as not specified) -* meaning ??? -* importance ??? - -SEC-Node-properties -+++++++++++++++++++ - -* description (string), SHOULD be given - diff --git a/doc/source/protocol/diagram/module_description.png b/doc/source/protocol/diagram/module_description.png deleted file mode 100755 index 53c5019..0000000 Binary files a/doc/source/protocol/diagram/module_description.png and /dev/null differ diff --git a/doc/source/protocol/diagram/module_property.png b/doc/source/protocol/diagram/module_property.png deleted file mode 100755 index 64acb64..0000000 Binary files a/doc/source/protocol/diagram/module_property.png and /dev/null differ diff --git a/doc/source/protocol/diagram/properties.png b/doc/source/protocol/diagram/properties.png deleted file mode 100755 index aff8c4a..0000000 Binary files a/doc/source/protocol/diagram/properties.png and /dev/null differ diff --git a/doc/source/protocol/diagram/property.png b/doc/source/protocol/diagram/property.png deleted file mode 100755 index 4b73318..0000000 Binary files a/doc/source/protocol/diagram/property.png and /dev/null differ diff --git a/doc/source/protocol/diagram/sec_node_description.png b/doc/source/protocol/diagram/sec_node_description.png deleted file mode 100755 index 4272070..0000000 Binary files a/doc/source/protocol/diagram/sec_node_description.png and /dev/null differ diff --git a/doc/source/protocol/diagram/sec_node_property.png b/doc/source/protocol/diagram/sec_node_property.png deleted file mode 100755 index a0e9091..0000000 Binary files a/doc/source/protocol/diagram/sec_node_property.png and /dev/null differ diff --git a/doc/source/protocol/heartbeat.rst b/doc/source/protocol/heartbeat.rst deleted file mode 100644 index 3df64c6..0000000 --- a/doc/source/protocol/heartbeat.rst +++ /dev/null @@ -1,8 +0,0 @@ -Heartbeat -========= -* ping gets an 'intended looptime' argument (as number in seconds or null to disable) -* server replys as usual -* if the server received no new message within twice the indended looptime, it may close the connection. -* if the client receives no pong within 3s it may close the connection -* later discussions showed, that the ping/pong should stay untouched and the keepalive time should be (de-)activated by a special message instead. Also the 'connection specific settings' from earlier drafts may be resurrected for this.... - diff --git a/doc/source/protocol/hierarchy.rst b/doc/source/protocol/hierarchy.rst deleted file mode 100644 index bb48f80..0000000 --- a/doc/source/protocol/hierarchy.rst +++ /dev/null @@ -1,9 +0,0 @@ -Hirarchy -======== - -* group property (currently a identifier like string, may be extended to tree like substrucutres by allowing ':') -* visibility (enum(3:expert, 2:advanced, 1:user)) (default to 1 if not given) - if visibility is set to user: everybody should see it - if visibility is set to advanced: advanced users should see it - if visibility is set to expert: only 'experts' should see it - diff --git a/doc/source/protocol/history.rst b/doc/source/protocol/history.rst deleted file mode 100644 index c89a066..0000000 --- a/doc/source/protocol/history.rst +++ /dev/null @@ -1,73 +0,0 @@ -History -======= - -Meeting 29.5.2017 ------------------ - -* for api: float is 'double' -* everything countable is int64_t -* description is string (UTF-8 without embedded \0) (zero terminated for API) -* names / identifiers are: [_a-z][_a-z0-9]{0,63} -* BLOB is [length, string_encoding (base64 or json_string) ] ??? -* enum is transferred by value (api: int64_t) -* basic data types: string, BLOB(maxsize), int, double, bool, enum(mapping) -* encode as ["string"] ["blob"] ["int"] ["double"] ["bool"] ["enum", {:}] -* send as json_string [length, json_string] number number 0_or_1 number_value -* complex data types: array, tuple, struct -* encode as: ["array", ] ["tuple", [] ["struct", {"name_of_subcomponent":}] -* send as [array] [array} {mapping} -* forbid: structs in structs, nesting level > 3, arrays may only contain basic types + tuple -* essential features should not rely on complex data types -* fallback: if ECS can not handle a non-basic datatype: handle as string containing the JSON-representation. -* mandatory for all ECS: enum, int, double, string, bool, tuple(enum,string) - -Merge datatype and validator -++++++++++++++++++++++++++++ - -* ["enum", {:}] -* ["int"] or ["int", , ] -* ["double"] or ["double", , ] -* ["bool"] -* ["blob", ] or ["blob", , ] -* ["string", ] or ["string", , ] -* ["array", , ] or ["array", , , ] -* ["tuple", [ :}] - -Examples -++++++++ - -* status: ["tuple", [ ["enum", {0:"init", 100:"idle", 200:"warn", 300:"busy"}], ["string", 255] ] ] -* p/pi/pid-triple: ["array", ["double", 0, 100], 1, 3] - - -Meeting 30.5.2017 ------------------ - -* data values can be transferred as json_null, meaning: no value yet -* json_null can not be used inside structured data types -* property name for datatype is "datatype" - -Meeting 11.9.2017 ------------------ - -Merge datatype and validator -++++++++++++++++++++++++++++ - - * enum, int, double, bool, tuple, struct as before - * ["blob", ] or ["blob", , ] - * ["string", ] or ["string", , ] - * ["array", , ] or ["array", , , ] - - -Interface_class -+++++++++++++++ - - * Drivable, Writable, Readable, Module (first character uppercase, no middle 'e') - - -transfer_of_blob -++++++++++++++++ - - * transport-encoding as base64-encoded string (no prefixed number of bytes....) - diff --git a/doc/source/protocol/index.rst b/doc/source/protocol/index.rst deleted file mode 100644 index a3227a3..0000000 --- a/doc/source/protocol/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -Protocol documentation -====================== - -.. toctree:: - :maxdepth: 1 - - motivation - secop_v2017-09-14 - issue_1 - issue_2 - issue_3 - issue_4 - issue_5 - issue_6 - issue_7 - issue_8 - issue_9 - issue_10 - outdated - history - meeting_2017_11_27 - diff --git a/doc/source/protocol/issue_1.rst b/doc/source/protocol/issue_1.rst deleted file mode 100644 index e1ac595..0000000 --- a/doc/source/protocol/issue_1.rst +++ /dev/null @@ -1,27 +0,0 @@ -SECoP Issue 1: About SECoP Issues -================================= - -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: - -proposed --------- - -A proposal should contain the motivation. As long as nobody else -joins into a discussion, the state remains *proposed* - -under discussion ----------------- - -This state is kept until there is a decision taken. - -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 rises a similar issue. -However, it should be possible to reopen an issue, if new -arguments arise. diff --git a/doc/source/protocol/issue_10.rst b/doc/source/protocol/issue_10.rst deleted file mode 100644 index e15a721..0000000 --- a/doc/source/protocol/issue_10.rst +++ /dev/null @@ -1,45 +0,0 @@ -SECoP Issue 10: Character set for Names (under discussion) -========================================================== - -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 the outdated part of the documentation (`outdated Messages`_) it is not -explicitly stated, that identifiers have to be lower case, and also -in some of the running examples contain uppercase identifiers. - -.. _`outdated Messages`: messages.html - -Discussion -~~~~~~~~~~ - -Markus: - For me, it is not that important, if uppercase characters are allowed or not, but, - identifiers must be unique independent of case, i.e. it is not allowed to have two - different modules "t" and "T", on a SEC node. And we should take a decision soon. - -Default parameters 'value' and 'target' ---------------------------------------- - -In the implementation, in the "read" and "update" messages ":value" can be just -replaced by "", and in "change" and "changed" message ":target" can -be replaced by "". - -Discussion -~~~~~~~~~~ - -Markus: - I prefer not to allow these shortcuts. We also have to distinguish module properties - from properties of the module parameter 'value'. - - - - diff --git a/doc/source/protocol/issue_2.rst b/doc/source/protocol/issue_2.rst deleted file mode 100644 index 5737564..0000000 --- a/doc/source/protocol/issue_2.rst +++ /dev/null @@ -1,22 +0,0 @@ -SECoP Issue 2: Equipment ID in Describing Message (under discussion) -==================================================================== - -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 --------- diff --git a/doc/source/protocol/issue_3.rst b/doc/source/protocol/issue_3.rst deleted file mode 100644 index 13bae59..0000000 --- a/doc/source/protocol/issue_3.rst +++ /dev/null @@ -1,47 +0,0 @@ -SECoP Issue 3: SECoP Timestamp Format (closed) -============================================== - -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". diff --git a/doc/source/protocol/issue_4.rst b/doc/source/protocol/issue_4.rst deleted file mode 100644 index b307822..0000000 --- a/doc/source/protocol/issue_4.rst +++ /dev/null @@ -1,18 +0,0 @@ -SECoP Issue 4: Timeout (under discussion) -========================================= - -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 --------- diff --git a/doc/source/protocol/issue_5.rst b/doc/source/protocol/issue_5.rst deleted file mode 100644 index 377f146..0000000 --- a/doc/source/protocol/issue_5.rst +++ /dev/null @@ -1,34 +0,0 @@ -SECoP Issue 5: Definition of the term 'Property' (under discussion) -=================================================================== - -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 an other term than -'qualifiers', but definitely does not like the terms 'live properties' and -'descriptive properties', as two different things share the same name. - - -Decision --------- diff --git a/doc/source/protocol/issue_6.rst b/doc/source/protocol/issue_6.rst deleted file mode 100644 index 7f87ca8..0000000 --- a/doc/source/protocol/issue_6.rst +++ /dev/null @@ -1,23 +0,0 @@ -SECoP Issue 6: Keep Alive (under discussion) -============================================ - -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 --------- diff --git a/doc/source/protocol/issue_7.rst b/doc/source/protocol/issue_7.rst deleted file mode 100644 index 8e995b5..0000000 --- a/doc/source/protocol/issue_7.rst +++ /dev/null @@ -1,24 +0,0 @@ -SECoP Issue 7: Time Synchronization (under discussion) -====================================================== - -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. - -The recommended mechanism is (proposal by Markus): - -After connecting to a server, the client records its internal time before sending -a ping request. - -If the pong request does not contain a timestamp, -the client knows, that the SEC node does not provide timestamps and -therefore it has to create timestamps on the time of reception of messages. - -If the returned timestamp lies between the time the ping message was sent and the -time the pong message was received, it does not need to correct the timestamps. - -If not, the average of the 'ping' time and the 'pong' time is calculated and -the difference to the received timestamp is used for correcting further -timestamps. - -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. diff --git a/doc/source/protocol/issue_8.rst b/doc/source/protocol/issue_8.rst deleted file mode 100644 index ebe09b9..0000000 --- a/doc/source/protocol/issue_8.rst +++ /dev/null @@ -1,15 +0,0 @@ -SECoP Issue 8: Groups (under discussion) -======================================== - -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. - -Groups must start with uppercase letters. - -The "group" property may contain colons (':') as separator, -in order to construct a hierarchy of more than one level. - diff --git a/doc/source/protocol/issue_9.rst b/doc/source/protocol/issue_9.rst deleted file mode 100644 index cde2c83..0000000 --- a/doc/source/protocol/issue_9.rst +++ /dev/null @@ -1,39 +0,0 @@ -SECoP Issue 9: Module Meaning (under discussion) -================================================ - -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. diff --git a/doc/source/protocol/jsonstruct.rst b/doc/source/protocol/jsonstruct.rst deleted file mode 100644 index 8fa7f8c..0000000 --- a/doc/source/protocol/jsonstruct.rst +++ /dev/null @@ -1,92 +0,0 @@ -JSON structure -============== - -> Mit JSON Freeze meine ich nur Arrays von Objekten also: -> -Node hat ein Array von Properties und ein Array von Modulen -> -Module haben ein Array von Properties, ein Array von Parametern und ein Array von Commands -> -Parameter und Commands haben jeweils ein Array von Properties - -node = { 'properties' : [], - 'modules' : [] } - -module = { 'properties' : [], - 'parameter' : [], - 'commands' : [] } - -parameter = { 'properties' : [] } - -commands = { 'properties' : [] } - -property = { 'property-name' : 'property-value' } - - -ODER ----- - -node = [ , ] - -array_of_modules = [ , ... ] - -module = , , -#OR# -module = [, , ] - -array_of_params = [ , ...] - -param = - -array_of_commands = [ , ...] - -command = < array_of_properties> - -array_of_properties = [ , ...] - -property = 'name', 'value' -#OR# -property = ['name', 'value'] -#OR# -property = {'name' : 'value'} - -Oder ganz anders? - -Siehe auch diskussion im HZB-wiki hierzu.... - -verwirrend.... - -vorerst folgende Festlegung: - -.. code-block:: json - - {"equipment_id": "cryo_7", - "firmware": "The SECoP playground", - "modules": ["cryo", {"commands": ["stop", {"resulttype": "None", - "arguments": "[]", - "description": "Testing command implementation\\n\\nwait a second" - }, - "start", {"resulttype": "None", - "arguments": "[]", - "description": "normally does nothing,\\n\\nbut there may be modules which _start_ the action here\\n" - } - ], - "group": "very important/stuff", - "implementation": "secop.devices.cryo.Cryostat", - "interfaces": ["Drivable", "Readable", "Device"], - "parameters": ["status", {"readonly": true, - "datatype": ["tuple", ["enum", {"unknown":-1,"idle":100, "warn":200, "unstable":250, "busy":300,"error":400}], "string"], - "description": "current status of the device" - }, - "value", {"readonly": true, - "datatype": ["double",0,null], - "description": "regulation temperature", - "unit": "K" - }, - "target", {"readonly": false, - "datatype": ["double",0,null], - "description": "target temperature", - "unit": "K" - } - ] - } - ], - "version": "2017.01" - } diff --git a/doc/source/protocol/meeting_2017_11_27.rst b/doc/source/protocol/meeting_2017_11_27.rst deleted file mode 100644 index 3826970..0000000 --- a/doc/source/protocol/meeting_2017_11_27.rst +++ /dev/null @@ -1,240 +0,0 @@ -Meeting at PSI 2017.11.27 - 2017.11.29 -====================================== - -participants: - * Eddy Lelievre-Berna - * Klaus Kiefer - * Markus Zolliker - * Anders Petterson - * Niklas Ekström - * Lutz Rossa - * Frank Wutzler - * Enrico Faulhaber - -.. contents:: Inhaltsverzeichnis - :local: - :depth: 2 - -27.11.2017 -++++++++++ - -Agenda topic: general remarks ------------------------------ - -perception of SECoP seems suboptimal therefore we want to - - * create an forum on the ISSE webpage (+linking to the documentation) - * update/rewrite the documentation first - * provide a SHORT overview of SECoP (max 2 pages, no details) - * provide a readonly copy of SECoP on github (or other PUBLIC site) - - * Eddy mentions some critisism (by others), that information about SECoP was difficult or not at all to be found. - -.. todo:: - An new, short overview shall be created by HZB (i.e. Frank) - - -SECoP from our point of view: - - * self describing protocol to control hardware - * flexible, modular - * unifying the big number of existing, incompatible (proprietary) protocols, for which often not even an API is provided - * provides an api - * wants to achieve interoperability between facilities - -.. todo:: - All committee members should be contributors to the SECoP github project - - -Agenda topic: discussion about issues -------------------------------------- - - * Markus created the Issues, everybody likes the approach - * a discussion about the different ways to handle tickets/issues with redmone/github/in a repo ensures. - * the discussion broadens about documentation/issue change tracking, rights for modification/merge - -.. todo:: - result is: we try to use the github workflow for documentation (as wiki) and issues (as topics) - -Agenda topic: HZB SECoP dll: current status -------------------------------------------- - - * programmatic creation of SEC-nodes via CreateNode, AddModule, AddParameter, AddCommand, AddProperty - * finalise with NodeComplete (also enable access from outside) - * builds a multithreaded server for each Node, each Module is handled by it's own thread - * building keeps an internal state and should be singlethreaded! - * Variant data type (with unit tests) implemented in a C compliant way - * LabVIEW test case (calling the DLL from LabVIEW) working - * view issues left: (note: still prototype!) - * closedown with non-QT application sometimes crashes - * validation not yet 100% complete - * refactoring - * live demo of a needle valve controller controlled by a small LabVIEW demo programm emebdding the dll, beeing controlled by a simple network client (entering secop protocol messages by hand) - * accesscontrol can be done via multiple nodes exporting a (posible readonly) subset of modules/parameters - -New problems found: - 1) not all json libraries accept plain json-values like '1.234', but only json-documents - 2) concentrate on the 'working' ones - 3) open an issue for this (for documenting this) - 4) a way out could be to jsonify the whole message, if we would ever need it - 5) Lutz found a (workaround) way to handle this: - * while reading a SECoP value (JSON value), the code surrounds the value with brackets ('[' value ']'), reads it with its library and takes the first element - * when writing a SECoP value, you generate a JSON array of one element, convert it with the JSON library to a string and remove the surrounding brackets. - -.. todo:: - create an Issue to document this. - -Discussion about access control: - - * currently SECoP itself does not provide access control (except read/write property) - * we rely on existing network solutions (bind to local port, use SSL Server, use multiple 'view' nodes) - * agreement, that access control is not part of SECoP - -.. todo:: - open an closed issue documenting this discussion - - -Agenda Topic: Issues inside the playground-protocol-documentation ------------------------------------------------------------------ - - * overview of the current Issues - -.. note:: - * a lengthy discussion about how to proceed ensures - * followed by a discussion about delayed change/commit of parameters, changing multiple parameters 'at once' - * discussing commons and differences between start, pause, continue and stop - * discussion is postponed without result - -.. todo:: - create an Issue for starting or synchronizing disjunct hw-modules (possible delegated to other SEC-Nodes) - -.. todo:: - create an Issue to collect uses case for: - * different kinds of HW (different parameter setting with respect to starting) - -.. todo:: - create an Issue (to be discussed) for: - * reading the (RO) target parameter gives you the HW value - * if there is no start command available, writing to the (RW) wanted_target starts the action - else you need to call start() after writing to wanted_target. - In any case, the target parameter reflects the value used by the hw. - - Lutz thinks that looking at the status (and predefining a view values for it) may be sufficient and - to have an additional parameter 'wanted_target' can be avoided. - - - -28.11.2017 -++++++++++ - -Agenda Topic: discussion about the definition of pause/stop/start/shutdown --------------------------------------------------------------------------- - -.. todo:: make an issue about the start/stop/pause/shutdown commands - not all commands must always be implemented, but if they are implemented, they have a predefined meaning to it - AND - if somebody want to implement something with the predefined meaning, it must be with the predefined name - -Agenda Topic: timestamps: mandatory or optional ------------------------------------------------ - - * providing timestamp is highly recommend, but stays optional - * timestamps are (still) fractional unix time with a resolution of at least seconds - * SEC-node implementor decides about implemented resolution - -.. todo:: document this in an Issue - -Agenda Topic: Interfaceclasses ------------------------------- - - * discussion about custom vs. predefined parameters and properties - * proposal to introduce 'features' in addition to base interface_class - * features are listed by name in an additional module property called 'features' - * explicit listing of 'features' seems better than guessing them from the existence of parameters - * features have predefined 'dependencies', excludes, set of parameters with predefined meanings - * Open question: how to figure out the difference of an unknown base class to a known base class? - * Markus proposes to use just Features then. - - -.. todo:: create an Issue for documenting this and for discussing it later in more detail - -Agenda Topic: discussing existing Issues ----------------------------------------- - - 1) Issues: agreement to use Issues for documenting, closed - 2) Equipment_id is stored as a node property and is no longer part of the describing reply: agreement, closed - 3) already closed - 4) default timeout: change default to 10s, agreement, closed - 5) name change: live properties -> qualifiers to avoid misunderstands: agreement, closed - 6) keep alive: leave as to be discussed - 7) time synchronisation: leave to be discussed - SEC-Nodes have its correct timestamp (provided by other means), have their own invented time, or no timestamps at all. - agreement: the kind of SEC-node clock shall be noted as node property in the descriptive data. (this part closed) - to be discussed: name of the node property (proposal: clock, datatype: Enum(None=0, relative=1, absolute=2) - 8) groups+hierarchy: leave as to discussed - 9) meaning/importance: leave as to be discussed - 10) Names and upper/lowercase: names can be uppercased as long as the lowercase version is still unique. agreement, close - 11) giving only module name for read/update/event request are extended with :value or :target: agreement on not specifying this. - Clients are not allowed to use it, servers may support it but it is non-standard behaviour. - -.. todo:: Issue 11 is still coded as second part of Issue 10 -> split it (Markus) - -.. todo:: create an Issue about providing a mean to set the SEC-nodes clock from the ECS side. - -.. note:: Klaus and Eddy leaving at this point - - -Agenda Topic: Grouping/Hierachy (Issue 8) ------------------------------------------ - - * discussion about namespaces and use cases for groups - * grouping is 'giving modules or parameters a name to allow guis to group them together' - * the (lowercase) name of a (parameter)group is not allowed to clash with (lowercased) names of parameters of the same module - * the (lowercase) name of a (module)group is not allowed to clash with (lowercased) names of modules of the same node - * agreement, closing this issue - - -.. todo:: create an Issue for PID tables - - -Topic: handling of driver generated timestamps in the HZB-DLL -------------------------------------------------------------- - - 1) initiate the timestamp with NAN before calling the HW-read_a_value callback, which may provide an timestamp - 2) if configured to do so, a NAN timestamp is replaced after the callback with the current time - 3) if the timestamp is still NAN (or not expressable by digits), it is NOT send - -.. todo:: @Frank: document this ! - - -Discussion about activate/deactivate ------------------------------------- - - * normally values for all values are send before the activated reply is sent - * there are very rare cases where a value can (not yet) be determined. In this case it is acceptable to send a null value. - * a null value is also accepted when setting parameters of a complex datatype and not all members shall be updated. - -.. todo:: create an issue about the usage of null - -.. note:: tour around PSI - -.. note:: presentation of the SEA and SICS concept by Markus Zolliker - -.. note:: detailed showcase of the HZB-DLL source - -.. note:: we need more use cases and sequencediagrams - - -29.11.2017 -++++++++++ - - * detailed presentation of the playground - * discussion about implementation details - * structure of config files - * introduction to writing secop modules + how to configure them - * live demo - - * fixing the amagnet - * discussing error propagation (bugs in hw-driver) - -.. note:: meeting was closed around 14:30 diff --git a/doc/source/protocol/messages.rst b/doc/source/protocol/messages.rst deleted file mode 100644 index 06fbd67..0000000 --- a/doc/source/protocol/messages.rst +++ /dev/null @@ -1,232 +0,0 @@ -SECoP Messages -============== - -All Messages are formatted in the same way: - [[]] - -where [] enclose optional parts. This basically results in 3 different possible -formattings: - - * type A: "keyword\\n" - * type B: "keyword specifier\\n" - * type C: "keyword specifier JSON_data\\n" - -Note: numerical values and strings appear 'naturally' formatted in JSON, i.e. 5.0 or "a string" - - is one of a fixed list of defined keywords, is either the -name of the module optionally followed by ':' + the name of a command or parameter, -or one of a fixed list of predefined keywords, depending on the message keyword. - -At the moment it is considered syntactic sugar to omit the parametername in a request. -In replies the SEC-node (in the playground) will always use the correct parameter. -On change-requests the parameter is assumed to be 'target', on trigger-requests it is -assumed to be 'value'. Clients should not rely on this and explicitly state the parametername! - -All names and keywords are defined to be identifiers in the sense, that they are not longer -than 63 characters and consist only of letters, digits and underscore and do not start -with a digit. (i.e. T_9 is ok, whereas t{9} is not!) -No rule is without exception, there is exactly ONE special case: the identify request -consists of the literal string '\*IDN?\\n' and its answer is formatted like an valid SCPI -response for \*IDN?. - -We rely on the underlying transport to not split messages, i.e. all messages are -transported as a whole and no message interrupts another. - -Also: each client MUST at any time correctly handle incoming event messages, even -if it didn't activate them! - -Implementation node: -Both SEC-node and ECS-client can close the connection at any time! - - -List of Intents/Actions: ------------------------- - - * Identify -> Ident - * Describe -> Description - * Activate Events -> initial data transfer -> end-of-transfer-marker - * Deactivate Async Events -> confirmation - * Command : -> confirmation -> result_event - * Heartbeat -> Heartbeat_reply - * Change [:] JSON_VALUE -> confirmation -> readback_event - * TRIGGER [:] -> read_event - -At any time an Event may be replied. Each request may also trigger an Error. - -Line-ending is \lf. -\cr is ignored and never send. -Warning: One Message per line: Description line can be looooong!!! - - -Allowed combinations as examples: -(replace <..> with sensible stuff) - - -Identify --------- - - * Request: type A: '\*IDN?' - * Reply: special: 'SECoP, SECoPTCP, V2016-11-30, rc1' - * queries if SECoP protocol is supported and which version it is - - The format is intentionally choosen to be compatible to SCPI (for this query only). - It is NOT intended to transport information about the manufacturer of the hardware, but to identify this as a SECoP device and transfer the protocol version! - - -Describe --------- - - * Request: type A: 'describe' - * Reply: type C: 'describing {"modules":{"T1":{"baseclass":"Readable", ....' - * request the 'descriptive data'. The format needs to be better defined and - may possibly just follow the reference implementation. - - identifies the equipment. It should be unique. Our suggestion is to use something along _, i.e. MLZ_ccr12 or PSI_oven4. - - -Activate Async Events ---------------------- - - * Request: type A: 'activate' - * Reply: several EVENT lines (initial value transfer) followed by: type A: 'active' - * Activates sending of Async Events after transferring all live quantities once - and an 'end-of-initial-transfer' marker. After this events are enabled. - - -Deactivate Async Events ------------------------ - - * Request: type A: 'deactivate' - * Reply: type A: 'inactive' - * Deactivate sending of async Events. A few events may still be on their way until the 'inactive' message arrives. - - -Execute Command ---------------- - - * Request: type B: 'do :' for commands without arguments - * Request: type C: 'do : JSON_argument' for commands with arguments - * Reply: type C: 'done : JSON_result' after the command finished - * start executing a command. When it is finished, the reply is send. - The JSON_result is the a list of all return values (if any), appended with qualifiers (timestamp) - - -Write ------ - - * Request: type C: 'change [:] JSON_value' - * Reply: type C: 'changed : JSON_read_back_value' - * initiate setting a new value for the module or a parameter of it. - - Once this is done, the read_back value is confirmed by the reply. - - -Trigger -------- - - * Request: type B: 'read [:]' - * Reply: None directly. However, one Event with the read value will be send. - * Read the requested quantity and sends it as an event (even if events are disabled or the value is not different to the last value). - - -Heartbeat ---------- - - * Request: type A: 'ping' - * Request: type B: 'ping ' - * Reply: type A: 'pong' - * Reply: type B: 'pong ' - * Replies the given argument to check the round-trip-time or to confirm that the connection is still working. - - may not contain . It is suggested to limit to a string of up to 63 chars consisting of letters, digits and underscore not beginning with a digit. If is not given (Type A), reply without it. - - -EVENT ------ - -Events can be emitted any time from the SEC-node (except if they would interrupt another message). - - * Request: None. Events can be requested by Trigger or by Activating Async Mode. - * Reply: type C: 'event : JSON_VALUE' - * Informs the client that a parameter got changed its value. - - In any case the JSON_value contain the available qualifiers as well: - * "t" for the timestamp of the event. - * "e" for the error of the value. - * "u" for the unit of the value, if deviating from the descriptive data - * further qualifiers, if needed, may be specified. - - The qualifiers are a dictionary at position 2 of a list, where the value occupies position 1. - This holds true also for complex datatypes (of value)! - - examples: - - * 'update T1:value [3.479, {"t":"149128925.914882", "e":0.01924}] - * 'update T1:p [12, {"t":"149128927.193725"}]' - * 'update Vector:value [[0.01, 12.49, 3.92], {"t":"149128925.914882"}]' - - -ERROR ------ - - * Request: None. can only be a reply if some request fails. - * Reply: type C: 'ERROR JSON_additional_stuff' - * Following are defined so far: - - NoSuchDevice: The action can not be performed as the specified device is non-existent. - - NoSuchParameter: The action can not be performed as the specified parameter is non-existent. - - NoSuchCommand: The specified command does not exist. - - CommandFailed: The command failed to execute. - - CommandRunning: The command is already executing. - - ReadOnly: The requested write can not be performed on a readonly value.. - - BadValue: The requested write or Command can not be performed as the value is malformed or of wrong type. - - CommunicationFailed: Some communication (with hardware controlled by this SEC-Node) failed. - - IsBusy: The reequested write can not be performed while the Module is Busy - - IsError: The requested action can not be performed while the module is in error state. - - Disabled: The requested action can not be performed at the moment. (Interlocks?) - - SyntaxError: A malformed Request was send - - InternalError: Something that should never happen just happened. - - The JSON part should reference the offending request and give an explanatory string. - - examples: - - * 'ERROR Disabled ["change", "V15", "on", "Air pressure too low to actuate the valve.", {"exception":"RuntimeException","file":"devices/blub/valve.py", "line":13127, "frames":[...]}]' - * 'ERROR NoSuchDevice ["read","v19", "v19 is not configured on this SEC-node"]' - * 'ERROR SyntaxError "meas:Volt?" - - -Examples --------- - -:: - - (client connects): - (client) '\*IDN?' - (SEC-node) 'Sine2020WP7.1&ISSE, SECoP, V2016-11-30, rc1' - (client) 'describe' - (SEC-node) 'describing SECoP_Testing {"modules":{"T1":{"baseclass":"Readable", ... - (client) 'activate' - (SEC-node) 'update T1 [3.45,{"t":"149128925.914882","e":0.01924}]' - ... - (SEC-node) 'active' - (SEC-node) 'update T1 [3.46,{"t":"149128935.914882","e":0.01912}]' - (client) 'ping fancy_nonce_37' - (SEC-node) 'pong fancy_nonce_37' - (SEC-node) 'update T1 [3.49,{"t":"149128945.921397","e":0.01897}]' - ... - -merge datatype and validator: ------------------------------ - * enum, int, double, bool, tuple, struct as before - * ["blob", ] or ["blob", , ] - * ["string", ] or ["string", , ] - * ["array", , ] or ["array", , , ] - -interface_class ---------------- - * Drivable, Writable, Readable, Module (first character uppercase, no middle 'e') - -transfer_of_blob ----------------- - * transport-encoding as base64-encoded string (no prefixed number of bytes....) - diff --git a/doc/source/protocol/modsubset.rst b/doc/source/protocol/modsubset.rst deleted file mode 100644 index 5a6bd33..0000000 --- a/doc/source/protocol/modsubset.rst +++ /dev/null @@ -1,8 +0,0 @@ -Activate subset of modules -========================== - -* activate/deactivate may get an optional 2nd argument and work only on this. -* add equipment_id [_0-9a-zA-A]{4,} as SEC-node property (mandatory) (prefixed with ficility/manufacturer) -* change response to 'describe' to 'describing ALL ' -* '(de-)activate samething' -> '(de-)activated something' - diff --git a/doc/source/protocol/motivation.rst b/doc/source/protocol/motivation.rst deleted file mode 100644 index bbd9ce0..0000000 --- a/doc/source/protocol/motivation.rst +++ /dev/null @@ -1,18 +0,0 @@ -Motivation -========== - - * SECoP motivation proposal - * simple, inclusive and self describing - * write drivers only once - * different institutes wrote their own driver collection which fulfils all their needs and it works reliable - * as secondary effect the standard drivers still can be used so their are well tested and may become more reliable - -SECoP ------ - -The SECoP (Sample Environment Communication Protocol) is an Inclusive, Simple and Self Explaining (ISSE) communication protocol. -Inclusive means, that facilities can use this protocol and don't have to change their work flow (rewrite drivers completely or organize and handle hardware in a specific way to fulfil SECoP requirements). -Simple means it should be easy to integrate and to use. -Self Explaining means that with SECoP, not only the pure data is transported. It also transports meta data, which allows environment control software to configure by itself. -The benefit of SECoP will be to circulate expensive devices between different facilities with minimised effort for configuration and integration. -This should result in an increased utilisation of expensive equipment. \ No newline at end of file diff --git a/doc/source/protocol/notes.rst b/doc/source/protocol/notes.rst deleted file mode 100644 index 3ec21ef..0000000 --- a/doc/source/protocol/notes.rst +++ /dev/null @@ -1,42 +0,0 @@ -Notes -===== - -No installation required or recommended ---------------------------------------- - -everything runs directly from the checkout. - -you need: - - python2.7.* - - pip - - linux OS (Mac may work as well) - -install requirements with pip: -$ sudo pip install -r requirements.txt - -to execute a program, prefix its name with bin/, e.g.: -$ bin/make_doc.py -$ bin/server.py start test - -a testsuite is planned but nothing is there yet. - -Structure ---------- - -* bin contains the executables (make_doc.py, server.py) -* doc is the root node of the docu (see index.md) -* etc contains the configurations for the server(s) and devices -* html contains the docu after make_doc.py was run -* log contains some (hopefully) log output from the servers -* pid contains pidfiles if a server is running -* src contains the python source - - * src/client: client specific stuff (proxy) - * src/devices: devices to be used by the server (and exported via SECoP) - * src/lib: helper stuff (startup, pidfiles, etc) - * src/protocol: protocol specific stuff - * src/errors.py: internal errors - * src/server.py: device-managing part of the server (transport is in src/protocol/transport) - * src/validators.py: validators used by the devices. may be moved to src/protocol - - diff --git a/doc/source/protocol/outdated.rst b/doc/source/protocol/outdated.rst deleted file mode 100644 index 6535e47..0000000 --- a/doc/source/protocol/outdated.rst +++ /dev/null @@ -1,20 +0,0 @@ -Outdated documentation -====================== - -.. toctree:: - :maxdepth: 0 - - messages - descprop - hierarchy - descjson - timeformat - modsubset - heartbeat - jsonstruct - datatypes - commands - todo - notes - - diff --git a/doc/source/protocol/secop_v2017-09-14.rst b/doc/source/protocol/secop_v2017-09-14.rst deleted file mode 100644 index a05d093..0000000 --- a/doc/source/protocol/secop_v2017-09-14.rst +++ /dev/null @@ -1,924 +0,0 @@ -SECoP: Sample Environment Communication Protocol -################################################ - -V2017-09-14 - -Goal -==== - -The main goal of the "committee for the standardization of sample -environment communication" is to establish a common standard protocol -SECoP for interfacing sample environment equipment to experiment control -software. - - Definition: Experiment Control Software ECS - Software controlling the hardware for carrying out an experiment. Includes the user - interface. Usually speaks several protocols with different parts of the instrument. - Often also called instrument control. - -There is a task (7.1) within the European framework SINE2020 also -dealing with this subject. In its description we read: - - ... The standard should be defined in a way that it is compatible - with a broad variety of soft- and hardware operated at the different - large scale facilities. … The adoption of this standard will greatly - facilitate the installation of new equipment and the share of - equipment between the facilities. ... - -This does also cover the aims of the committee. - -The idea is, that a sample environment apparatus can easily be moved -between facilities and instruments/beamlines. As long as the facilities -have implemented a SECoP client within its ECS, and on the apparatus a -SECoP server is implemented as the SEC node, using the apparatus for an -experiment should be straightforward. An ECS can be built in a way, that -the configuration of a SEC node may be as short as entering a network -address, as the description can be loaded over the protocol (in -addition, the electronic communication link, electricity and may be -cooling water or pressurized air etc. have to be connected, but that is -out of scope …) - - Definition: Sample Environment Control Node (SEC node) - Computing unit or process or task, connected to all control units (temperature controller, flow controller, pressure sensor ...) of a sample environment, bridge to the ECS. SECoP specifies how ECS speaks with the SEC node. - The SEC node allows the ECS to access a set of modules (and their parameters) via the SECoP. It also provides a list of accessible modules and parameters. - -Other requirements ------------------- - -- the protocol should be easy to use - -- it should be easy to implement in connection with existing ECSs and - sample environment control software - -- it should be possible to be implemented on the most common platforms - (operating systems and programming languages) - -- 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, which allows a 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 - -Hardware Abstraction -==================== - -Modules -------- - - Definition: Module - One logical component of an abstract view of the sample environment. Can at least be read. - May be ’driven' (set new setpoint). May have parameters influencing how it achieves - its function (e.g. PID parameters). May have some additional diagnostics (read-only) parameters. - May provide some additional status information (temperature stable?, setpoint reached?) - Reading a module returns the result of the corresponding physical measurement. - -In earlier discussion we used the term "device" for module, which might -be misleading, as "device" is often used for an entire apparatus, like a -cryomagnet or humidity cell. In the context of SECoP, an apparatus in -general is composed of several modules. For example different -temperature sensors in one apparatus can be seen as different modules. - -An SEC node controls several (or one or no) modules. Modules also have -some descriptive data (name, type, list\_of\_parameters, -list-of\_commands,...). - -Parameters ----------- - -A module has several parameters associated with it. A parameter is -addressed by the combination of module and parameter name. Module names -have to be unique within an SEC node, parameter names have to be unique -within a module. - -Module and parameter names should be in english (incl. acronyms), using -only ascii letters and some additional characters (see section "Message -Syntax"). A maximum name length might be imposed. - - Definition: Parameter - The main parameter of a module is its value. Writable parameters may influence the - measurement (like PIDs). Additional parameters may give more information about its - state (running, target reached), or details about its functioning (heater power) for - diagnostics purposes. Parameters with a predefined meaning are listed in the standard, - they must always be used in the same way. Custom parameters are defined by the - implementation of the SEC node, the ECS can use them only in a general way, as their - meaning is not known. - - -The following parameters are predefined (extensible): - -- **value** - -- **status** (consists of two elements: a status with predefined values - as "idle","busy","error", and a describing text). - *Remark: it is proposed to add additional states (starting, - started, pausing, paused, stopping, warning). It has to be - discussed, if this (and therefore a start and pause command) - makes sense. Generally we want to keep the number of states as - small as possible here.* - -- **target** (not present, if the module is not writable) - -- **pollinterval** (double, a hint for the module for the polling interval in seconds) - -The following parameters were discussed at the meeting in - -- **ramp** (writable parameter, desired ramp. Units: main units/min) - -- **use\_ramp** (writable, 1 means: use given ramp, 0 means: go as fast as possible) - -- **setpoint** (ramping setpoint, read only) - -- **time\_to\_target** (read only, expected time to reach target) - - -Commands --------- - -A module may also have commands associated with it. A command is -addressed by the combination of module and parameter name. Like -parameters, command names have to be unique within a module, and should -be in english (incl. acronyms), using only ascii letters and some -additional characters (see section "Message Syntax"). A maximum name -length might be imposed. - - Definition: Command - Commands are provided to initiate specified actions of the module. - They should return immediately after that action is initiated, i.e. - should not wait until some other state is reached. Commands may get - an argument list and may return a result list. - Commands with a predefined meaning are listed in the standard, - they must always be used in the same way. - -Custom commands are defined by the implementation of the SEC node, the -ECS can use them only in a general way, as their meaning is not known. - -So far the only command defined (for driveable modules) is ‘stop’ (no -arguments, no result). When a modules target is changed, it is 'driving' -to a new value until the target is reached or until its stop command -is sent. -It is still to be discussed, what this exactly means for temperature -devices (heater off vs. ‘stay at current temp’). - -The following commands are predefined (extensible): - -- stop (stop a running action) - -proposed further commands: - -- start, pause (proposed from ILL) - -- shutdown (go to safe state) - - -Properties ----------- - -*definition of properties to be rewitten, see* `SECoP issue 5`_ - - Definition: Properties - Parameters have a value, live properties and descriptive properties. All properties have a predefined name and meaning. - - Live Properties - Properties which change their value during an experiment. - - Descriptive Properties - Properties that do not change during an experiment. They describe the usage of the parameter. - - -Live Properties (or *qualifiers* ?) are optional. - -There are currently only 2 live properties: - -- timestamp (named ‘t’ in the proposed syntax). The time when the - parameter has changed or was verified/measured (when no timestamp - is given, the ECS should use the time of the update message as - the timestamp) - -- sigma (named ‘e’ in the proposed syntax). The uncertainty of a - measurement (default: unspecified) - -other live properties might be added later to the standard. - -For a list of descriptive properties see chapter "Descriptive Data". - -Classes -------- - -The idea is, that the ECS can determine the functionality of a module -from its class. - -Base classes (recommended): - -- Readable - -- Writable (must have a target parameter) - -- Drivable (a Writable, must have a stop command, the status parameter will indicate - busy for a longer-lasting operation) - -Examples of classes: - -- CryomagnetSupply (a Drivable, with ramp and optional a persistent - switch) - -- TemperatureLoop (a Drivable, with PIDs, optional with ramp) - -The standard contains a list of classes, and a specification of the -functionality for each of them. The list might be extended over time. -Already specified base classes may be extended in later releases of the -specification, but earlier definitions will stay intact, i.e. no -removals or redefinitions will occur. - -The module class is in fact a list of classes (highest level class -first). The ECS chooses the first class from the list which is known to -it. - -Protocol -======== - -The basic element of the protocol are messages. - -Message Syntax --------------- - -A message is one line of text, coded in ASCII (may be extended to UTF-8 -later if needed). - -A message ends with a line feed character (ASCII 10), it may be preceded -by a carriage return character (ASCII 13), which must be ignored. A -message starts with a keyword, followed optionally by one space and a qualified name -or another item not containing spaces, followed optionally by one space and a JSON -formatted value. Note: numerical values and strings appear 'naturally' formatted -in JSON, i.e. 5.0 or "a string". - -A qualified name consists of a module identifier, a colon as separator -and a parameter or command identifier. 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). - -A SEC node might implement custom messages for debugging purposes, which are not -part of the standard. Custom messages start with an underscore or might just be -an empty line. The latter might be used as a request for a help text, when logged -in from a command line client like telnet or netcat. Messages not starting with -an underscore and not defined in the following list are reserved for future extensions. - -Message Summary -~~~~~~~~~~~~~~~ - -.. list-table:: - :widths: 20 20 60 - :header-rows: 1 - - * - message - - message kind - - syntax - - * - identification - - request - - **\*IDN?** - - * - - - reply - - ISSE&SINE2020\ **,SECoP,**\ *version,add.info* - - * - description - - request - - **describe** - - * - - - reply - - **describing ALL** *description* - - * - activate updates - - request - - **activate** *[module]* - - * - - - reply (after first updates) - - **active** *[module]* - - * - update - - - - - - * - - - asynchronous msg. - - **update** *module*\ **:**\ *parameter value* - - * - deactivate updates - - request - - **deactivate** *[module]* - - * - - - reply - - **inactive** *[module]* - - * - change value - - request - - **change** *module*\ **:**\ *parameter value* - - * - - - reply - - **changed** *module*\ **:**\ *parameter value* - - * - read request - - request - - **read** *module*\ **:**\ *parameter* - - * - - - reply - - **update** *module*\ **:**\ *parameter value* - - * - execute command - - request - - **do** *module*\ **:**\ *command [argument]* - - * - - - reply - - **done** *module*\ **:**\ *command [result]* - - * - error - - - - - - * - - - reply (on any message) - - **error** *errortype* *info* - - * - heartbeat - - request - - **ping** *[id]* - - * - - - reply - - **pong** *[id]* [\ **{"t":** *localtime* **}**\ ] - -Identification -~~~~~~~~~~~~~~ - -The syntax of the identification message differs a little bit from other -messages, as it should be compatible with IEEE 488.2. The identification -request "\ **\*IDN?**\ " is meant to be sent as the first message after -establishing a connection. The reply consists of 4 comma separated -fields, where the second and third field determine the used protocol. - -In this and in the following examples, messages sent to the server are marked with "> ", -and messages sent to the client are marked with "< " - -Example: - -.. code:: - - > *IDN? - < ISSE&SINE2020,SECoP,V2017-05-30,rc1 - -Description -~~~~~~~~~~~ - -The next messages normally exchanged are the description request and -reply. The reply is a structured JSON value describing the name of -modules exported and their parameters, together with the corresponding -properties. - -Example: - -.. code:: - - > describe - < describing PSI\_MP03 {"modules":["t1",["class":[ "temperature\_sensor","readable"],"parameters":["value", ... - -It is not yet clear what the second item in the reply message should be. -In this example it is the equipment ID, but this is redundant, as -"equipment_id" is also a SEC node property. -See `SECoP Issue 2`_ (Equipment ID in Describing Message) - -Remark: -this reply might be a very long line, no line breaks are allowed in the -JSON value. - -Activate Updates -~~~~~~~~~~~~~~~~ - -The parameterless "activate" request triggers the SEC node to send the -values of all its modules and parameters as update messages. When this -is finished, the SEC node must send an "active" reply. - -A SEC node might accept a module name as second item of the -message, activating only updates on the parameters of the module. -In this case, the "active" reply also contains the module names. - -A SEC Node not implementing module-wise activation must not sent the module -name in its reply, and must activate all modules. - -Update -~~~~~~ - -When activated, update messages are delivered without explicit request -from the client. The value is a JSON array with the value as its first -element, and an JSON object containing the qualifiers (live properties) -as its second element: - -"t": the timestamp (recommended, when the system has a synchronized -time, the format is fractional seconds since 1970-01-01T00:00:00+00:00) - -See also `SECoP Issue 3`_ (Timestamps) - -"e": the error of the quantity (optional) - -Example: - -.. code:: - - > activate - < update t1:value [295.13,{"t":1505396348.188388,"e":0.01}] - < update t1:status [[400,"heater broken or disconnected"],{"t":1505396348.288388}] - < active - -Deactivate Updates -~~~~~~~~~~~~~~~~~~ - -A parameterless message. After the "inactive" reply no more updates are -delivered if not triggered by a read message. - -Example: - -.. code:: - - > deactivate - < update t1:value [295.13,{"t":1505396348.188388}] - < inactive - -remark: the update message in the second line was sent before the deactivate message -was treated. After the "inactive" message, the client can expect that no more untriggered -update message are sent. - -The deactivate message might optionally accept a module name as second item -of the message for module-wise deactivation. If module-wise deactivation is not -supported, it should ignore a deactivate message which contains a module name. - -Remark: it is not clear, if module-wise deactivation is really useful. A SEC Node -supporting module-wise activation does not necessarily need to support module-wise -deactivation. - -Change Value -~~~~~~~~~~~~ - -the change value message contains the name of the module or parameter -and the value to be set. The value is JSON formatted, but note that for -a floating point value this is a simple decimal coded ASCII number. As -soon as the set-value is read back from the hardware, a "changed" -message is sent (in case updates are activated). If the value is not -stored in hardware, the "changed" message can be sent immediately. - -Example on a connection with activated updates. Live properties are replaced by {...} for brevity here. - -.. code:: - - > read mf:status - < update mf:status [[100,"OK"],{...}] - < change mf:target 12 - < update mf:status [[300,"ramping field"],{...}] - < changed mf:target [12,{...}] - -The status changes from "idle" to "busy". The ECS will be informed with a further update message on mf:status, when the module has finished ramping. - -Read Request -~~~~~~~~~~~~ - -With the read request message the ECS may ask the SEC node to update a -value as soon as possible, without waiting for the next regular update. -The reply is an update message. If updates are not activated, the -message can be treated like a read message in a request-reply scheme as -in the previous SECoP proposal. - -Example: - -.. code:: - - > read t1:value - < update t1:value [295.13,{"t":1505396348.188}] - > read t1:status - > update t1:status [[100,"OK"],{"t":1505396348.548}] - -Command -~~~~~~~ - -A command may have arguments. Multiple arguments can be given as a JSON list. -A command may also have a return value. The "done" reply always contains the -JSON part with at least the timestamp, if supported. If no value is returned, -the data part is set to "null". -The "done" message should be returned quickly, the time scale should be in the -order of the time needed for communications. Actions which have to wait for physical -changes, can be triggered with a command. The information about the success of -such an action has to be transferred via parameters, namely the status parameter. - -Example: - -.. code:: - - > do t1:stop - < done t1:stop [null, {"t": 1505396348.876}] - -Error Reply -~~~~~~~~~~~ - -Contains an error class from the list below as its second item. -The third item of the message is a JSON list, -containing the related request message as its first element, a human readable text -as its second element. The third element is a JSON-Object, containing possibly -implementation specific information about the error (stack dump etc.). - -Example: - -.. code:: - - > read tx:target - < error NoSuchModule ["read tx:target", "tx is not configured on this SEC node", {}] - > read ts:target - < error NoSuchParameter ["read ts:target", "ts has no parameter target", {}] - > meas:volt? - < error SyntaxError ["meas:volt?", "unknown keyword", {}] - -Error Classes - -.. list-table:: - :widths: 20 80 - - * - NoSuchModule - - The action can not be performed as the specified module is non-existent. - - * - NoSuchParameter - - The action can not be performed as the specified parameter is non-existent. - - * - NoSuchCommand - - The specified command does not exist. - - * - CommandFailed - - The command failed to execute. - - * - CommandRunning - - The command is already executing. - - * - ReadOnly - - The requested write can not be performed on a readonly value.. - - * - BadValue - - The requested write or Command can not be performed as the value is malformed or of wrong type. - - * - CommunicationFailed - - Some communication (with hardware controlled by this SEC-Node) failed. - - * - IsBusy - - The reequested write can not be performed while the Module is Busy - - * - IsError - - The requested action can not be performed while the module is in error state. - - * - Disabled - - The requested action can not be performed at the moment. (Interlocks?) - - * - SyntaxError - - A malformed Request was send - - * - InternalError - - Something that should never happen just happened. - - -Timeout Issues / Heartbeat -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In order to detect that the other end of the communication is not dead, -a heartbeat may be sent. The second part of the message (the id) may -not contain a space and should be short. It may be omitted. The reply -will contain exactly the same id. - -A SEC node might also decide to close a connection when it gets no -messages for a certain time. The mechanism is under discussion. - -Generally speaking: both -ECS and SEC side needs to be aware that the other side may close the -connection at any time! - -Example: - -.. code:: - - > ping 123 - < pong 123 {"t": 1505396348.543} - -The "pong" message has an additional function: it sends back the time -on the server, if it supports timestamps. This can be used to -synchronize the time. - -See also `SECoP Issue 4`_ (Timeout), `SECoP Issue 6`_ (Keep Alive), -`SECoP Issue 3`_ (Timestamps) or `SECoP Issue 7`_ (Time Synchronization) - -Multiple Connections --------------------- - -A SEC node may accept only a limited number of connections, downto 1. -However, each SEC node should support as many connections as technically -feasible. - -Details about how to multiplex multiple connections onto one are to be -discussed. - - -Descriptive Data ----------------- - -Format of Descriptive Data -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The format of the descriptive data is JSON, as all other data in SECoP. - - -.. for creating the railroad diagrams see: http://bottlecaps.de/rr/ui -.. source EBNF: -.. SEC_node_description ::= '{' (SEC_node_property ( ',' SEC_node_property)* )? '}' -.. SEC_node_property ::= property | ( '"modules":' '[' (name ',' module_description (',' name ',' module_description)*)? ']') -.. module_description ::= '{' (module_property ( ',' module_property)* )? '}' -.. module_property ::= property | ( '"parameters":' '[' (name ',' properties (',' name ',' properties)*)? ']') | ( '"commands":' '[' (name ',' properties (',' name ',' properties)*)? ']') -.. properties ::= '{' (property ( ',' property)* )? '}' -.. property ::= (name ':' property_value) - -SEC node description -^^^^^^^^^^^^^^^^^^^^ - - .. image:: diagram/sec_node_description.png - :alt: SEC_node_description ::= '{' (SEC_node_property ( ',' SEC_node_property)* )? '}' - -SEC node property -^^^^^^^^^^^^^^^^^ - - .. image:: diagram/sec_node_property.png - :alt: SEC_node_property ::= property | ( '"modules":' '[' (name ',' module_description (',' name ',' module_description)*)? ']') - -module description -^^^^^^^^^^^^^^^^^^ - - .. image:: diagram/module_description.png - :alt: module_description ::= '{' (module_property ( ',' module_property)* )? '}' - -module property -^^^^^^^^^^^^^^^ - - .. image:: diagram/module_property.png - :alt: module_property ::= property | ( '"parameters":' '[' (name ',' properties (',' name ',' properties)*)? ']') | ( '"commands":' '[' (name ',' properties (',' name ',' properties)*)? ']') - -properties -^^^^^^^^^^ - - .. image:: diagram/properties.png - :alt: properties ::= '{' (property ( ',' property)* )? '}' - -property -^^^^^^^^ - - .. image:: diagram/property.png - :alt: property ::= (name ':' property_value) - - -SEC Node Properties -~~~~~~~~~~~~~~~~~~~ - -there might be properties such as a timeout which are relevant for the -communication of a SEC node. - -- **equipment_id** - -- **description** (mandatory, a text describing the node, in general, the first - line is a short description (line break \\n)) - -- **firmware** (optional, a string describing the version of the SEC node software) - -- **timeout** (optional value in seconds, a SEC node should be able to respond within - a time well below this value. Default: 3 sec, see `SECoP issue 4`_ ) - - -Module Properties -~~~~~~~~~~~~~~~~~ - -- **description** (mandatory, a text describing the parameter) - -- **visibility** (1=expert, 2=advanced, 3=user (default)), Note: this - does not imply that the access is controlled. It may just be a - hint to the UI for the amount of exposed modules. (optional) - -- **interface\_class** (a list of classes for the module, for example - ["Temperature", "DrivableWithRamp", "Drivable", "Readable"]), - mandatory - -- **group** (optional, identifier, may contain ':' which may be interpreted as path separator) - (*see* `SECoP issue 8`_) - -- **meaning**, **importance** (*see* `SECoP issue 9`_) - - -Parameter Properties -~~~~~~~~~~~~~~~~~~~~ - -- **description** (mandatory, a text describing the parameter, mandatory) - -- **readonly** (mandatory) - -- **datatype** (mandatory, see `Data Types`_) - -- **unit** (default: unitless, should be given, if meaningfull, empty string: unit is one) - -- **visibility** (3=expert, 2=advanced, 1=user (default)), Note: this - does not imply that the access is controlled. It may just be a - hint to the UI for the amount of exposed parameters. (optional) - -- **group** (optional, identifier, may contain ':' which may be interpreted as path separator) - (*see* `SECoP issue 8`_) - -Data Types ----------- - -double -~~~~~~ - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["double"] *or* - | ["double", ] *or* - | ["double", , ] - | - | if is not given or null, there is no upper limit - | if is null or not given, there is no lower limit - - * - Transport example - - | 3.14159265 - - * - Datatype in C/C++ - - | double - -int -~~~ - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["int"] *or* - | ["int", ] *or* - | ["int", , ] - | - | if is not given or null, there is no upper limit - | if is null or not given, there is no lower limit - - * - Transport example - - | -55 - - * - Datatype in C/C++ - - | int64_t - -bool -~~~~ - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["bool"] - - * - Transport example - - | true - - * - Datatype in C/C++ - - | int64_t - - -enum -~~~~ - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["enum", { : , ....}] - - * - Transport example - - | 2 - - * - Datatype in C/C++ - - | int64_t - - -string -~~~~~~ - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["string"] *or* - | ["string", ] *or* - | ["string", , ] - | - | if is not given, it is assumed as 255. - | if is not given, it is assumed as 0. - | if the string is UTF-8 encoded, the length is counting the number of bytes, not characters - - * - Transport example - - | "hello!" - - * - Datatype in C/C++ API - - | char \* - -blob -~~~~ - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["blob", ] *or* - | ["blob", , ] - | - | if is not given, it is assumed as 0. - - * - Transport example - - | "AA==" (base64 encoded) - - * - Datatype in C/C++ API - - | struct {int64_t len, char \*data} - -array -~~~~~ - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["array", , ] *or* - | ["array", , , ] - | - | if is not given, it is assumed as 0. - | the length is the number of elements - - * - Transport example - - | [3,4,7,2,1] - - * - Datatype in C/C++ API - - | [] - -tuple -~~~~~ - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["tuple", [, , ...]] - - * - Transport example - - | [0,"idle"] - - * - Datatype in C/C++ API - - | struct - -struct -~~~~~~ - -.. list-table:: - :widths: 20 80 - :stub-columns: 1 - - * - Datatype - - | ["struct", { : , : , ....}] - - * - Transport example - - | {"x": 0, "y": 1} - - * - Datatype in C/C++ API - - | struct - | - | might be null - -.. _`SECoP Issue 2`: SECoP_Issues/issue_2.html -.. _`SECoP Issue 3`: SECoP_Issues/issue_3.html -.. _`SECoP Issue 4`: SECoP_Issues/issue_4.html -.. _`SECoP issue 5`: SECoP_issues/issue_5.html -.. _`SECoP Issue 6`: SECoP_Issues/issue_6.html -.. _`SECoP Issue 7`: SECoP_Issues/issue_7.html -.. _`SECoP issue 8`: SECoP_issues/issue_8.html -.. _`SECoP issue 9`: SECoP_issues/issue_9.html diff --git a/doc/source/protocol/timeformat.rst b/doc/source/protocol/timeformat.rst deleted file mode 100644 index 409ca35..0000000 --- a/doc/source/protocol/timeformat.rst +++ /dev/null @@ -1,7 +0,0 @@ -Timeformat -========== - -* format goes to 'timestamp since epoch as double with a resolution of at least 1ms' -* SEC-node-property: timestamp is accurate or relative -* Or: extend pong response contains the localtime (formatted as a timestamp) - diff --git a/doc/source/protocol/todo.rst b/doc/source/protocol/todo.rst deleted file mode 100644 index 2bee8ab..0000000 --- a/doc/source/protocol/todo.rst +++ /dev/null @@ -1,101 +0,0 @@ -========= -Todo List -========= - -Open questions -============== - -* Datatype for a mapping (like the calibration for the amagnet) -* How to set a Mapping or an enum (with all the name-value mappings) in the configfile? -* use toml vs. ini parser? -* error handling should be more consistent -* error-info stuff should be consistent -* dynamic device creation / modification (i.e. how to set the mapping of an enum during runtime?) -* propagation of units from main value to params -* switch params+cmds to 'accessibles'/attributes and keep in orderdDict? - -> needs Datatype for a function -* datatype for funcion: is argin a list anyway, or just one (structured) argument? - (so far we use a list and argout is a single datatype (which may be stuctured)) -* polling: vendor specific or do we propose a common way to handle it? - (playground uses a per-device pollinterval. params may be polled less often) -* interface classes !!! (maybe with feature mixins like WindowTimeout?) -* hardware access: unify? how? -* demo-hardware? -* If more than one connection exists: shall all events be relayed to all listeners? -* how about WRITE/COMMAND replies? Shall they go to all connected clients? -* structure of descriptive data needs to be specified -* same for JSON_stuff for Error Messages -* 'changed' may be 'readback' -* 'change' may be 'write' -* 'read' may be 'poll' -* the whole message may be json object (bigger, uglier to read) -* which events are broadcast or unicast? -* do we need a way to correlate a reply with a request? - - -Todos -===== - -Structure ---------- - - * stronger structure insides src - - * src/server for everything server related - * src/client for everything client related (ProxyDevice!) - * src/protocol for protocol specific things - - * need subtree for different implementations to play with - - * src/lib for helpers and other stuff - - * possibly a parallel src tree for cpp version - - -Client ------- - - * maybe start with a python shell and some import magic - * later a GUI may be a good idea - * client: one connection for each device? - * another connection for async data? - - -Server ------- - - * rewrite MessageHandler to be agnostic of server - * move encoding to interface - * allow multiple interfaces per server - * fix error handling an make it consistent - -Device framework ----------------- - - * supply properties for PARAMS to auto-generate async data units - * self-polling support - * generic devicethreads - * proxydevice - * make get_device uri-aware - - -Testsuite ---------- - - * need a testsuite (pytest) - * embedded tests inside the actual files grow difficult to maintain - - -Documentation -------------- - - * transfer build docu into wiki via automated jobfile - - - - -Transfer of blobs via json --------------------------- - - * use base64 - diff --git a/doc/source/playground/server/configuration.rst b/doc/source/server/configuration.rst similarity index 100% rename from doc/source/playground/server/configuration.rst rename to doc/source/server/configuration.rst diff --git a/doc/source/playground/server/index.rst b/doc/source/server/index.rst similarity index 100% rename from doc/source/playground/server/index.rst rename to doc/source/server/index.rst diff --git a/doc/source/playground/server/modules.rst b/doc/source/server/modules.rst similarity index 100% rename from doc/source/playground/server/modules.rst rename to doc/source/server/modules.rst diff --git a/doc/source/playground/server/protocol/index.rst b/doc/source/server/protocol/index.rst similarity index 73% rename from doc/source/playground/server/protocol/index.rst rename to doc/source/server/protocol/index.rst index fa819cc..2b01466 100644 --- a/doc/source/playground/server/protocol/index.rst +++ b/doc/source/server/protocol/index.rst @@ -4,7 +4,5 @@ protocol stack .. toctree:: :maxdepth: 3 - encoding - framing/index interface/index diff --git a/doc/source/playground/server/protocol/interface/index.rst b/doc/source/server/protocol/interface/index.rst similarity index 100% rename from doc/source/playground/server/protocol/interface/index.rst rename to doc/source/server/protocol/interface/index.rst diff --git a/doc/source/playground/server/protocol/interface/tcp.rst b/doc/source/server/protocol/interface/tcp.rst similarity index 100% rename from doc/source/playground/server/protocol/interface/tcp.rst rename to doc/source/server/protocol/interface/tcp.rst diff --git a/doc/source/playground/server/protocol/interface/zmq.rst b/doc/source/server/protocol/interface/zmq.rst similarity index 100% rename from doc/source/playground/server/protocol/interface/zmq.rst rename to doc/source/server/protocol/interface/zmq.rst diff --git a/doc/source/playground/server/starting.rst b/doc/source/server/starting.rst similarity index 100% rename from doc/source/playground/server/starting.rst rename to doc/source/server/starting.rst