linse/frappy
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: remove html escapes.

Browse Source 
Change-Id: I9e5f31ecff93e17dfee344cdc74c0ff9bd1b4600
This commit is contained in:
Alexander Lenz
2017-09-13 15:38:44 +02:00
parent e813197db6
commit 4e1dd2507e
3 changed files with 48 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
doc/source/protocol/descjson.rst
View File

@ -1,11 +1,11 @@
Structure of the descriptive json Structure of the descriptive json
================================= =================================
* json = {"modules": &lt;list_of_modules&gt;, "properties": &lt;list_of_sec-node_properties&gt;, ...} * json = {"modules": <list_of_modules>, "properties": <list_of_sec-node_properties>, ...}
* module = {"name": &lt;name_of_module&gt;, "parameters": &lt;list_of_parameters&gt;, "commands": &lt;list_of_commands&gt;, "properties": &lt;list_of_module_properties&gt;} * module = {"name": <name_of_module>, "parameters": <list_of_parameters>, "commands": <list_of_commands>, "properties": <list_of_module_properties>}
* parameter = {"name": ..., "properties": &lt;list_of_properties&gt;} * parameter = {"name": ..., "properties": <list_of_properties>}
* command = {"name": ..., "properties": &lt;list_of_properties&gt;} * command = {"name": ..., "properties": <list_of_properties>}
* property = {"name":&lt;name&gt;, "datatype": &lt;datatype&gt;, "value": &lt;value&gt;} * property = {"name":<name>, "datatype": <datatype>, "value": <value>}
note: property may also be [&lt;name&gt;,&lt;datatype&gt;,&lt;value&gt;] note: property may also be [<name>,<datatype>,<value>]

28
doc/source/protocol/history.rst
View File

@ -11,12 +11,12 @@ Meeting 29.5.2017
* BLOB is [length, string_encoding (base64 or json_string) ] ??? * BLOB is [length, string_encoding (base64 or json_string) ] ???
* enum is transferred by value (api: int64_t) * enum is transferred by value (api: int64_t)
* basic data types: string, BLOB(maxsize), int, double, bool, enum(mapping) * basic data types: string, BLOB(maxsize), int, double, bool, enum(mapping)
* encode as ["string"] ["blob"] ["int"] ["double"] ["bool"] ["enum", {&lt;number_value&gt;:&lt;name&gt;}] * encode as ["string"] ["blob"] ["int"] ["double"] ["bool"] ["enum", {<number_value>:<name>}]
* send as json_string [length, json_string] number number 0_or_1 number_value * send as json_string [length, json_string] number number 0_or_1 number_value
* complex data types: array, tuple, struct * complex data types: array, tuple, struct
* encode as: ["array", &lt;subtype&gt;] ["tuple", [&lt;list_of_compositing data types&gt;] ["struct", {"name_of_subcomponent":&lt;type of subcomponent&gt;}] * encode as: ["array", <subtype>] ["tuple", [<list_of_compositing data types>] ["struct", {"name_of_subcomponent":<type of subcomponent>}]
* send as [array] [array} {mapping} * send as [array] [array} {mapping}
* forbid: structs in structs, nesting level &gt; 3, arrays may only contain basic types + tuple * forbid: structs in structs, nesting level > 3, arrays may only contain basic types + tuple
* essential features should not rely on complex data types * 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. * 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) * mandatory for all ECS: enum, int, double, string, bool, tuple(enum,string)
@ -24,15 +24,15 @@ Meeting 29.5.2017
Merge datatype and validator Merge datatype and validator
++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++
* ["enum", {&lt;number_value&gt;:&lt;json_string&gt;}] * ["enum", {<number_value>:<json_string>}]
* ["int"] or ["int", &lt;lowest_allowed_value&gt;, &lt;highest_allowed_value&gt;] * ["int"] or ["int", <lowest_allowed_value>, <highest_allowed_value>]
* ["double"] or ["double", &lt;lowest_allowed_value&gt;, &lt;highest_allowed_value&gt;] * ["double"] or ["double", <lowest_allowed_value>, <highest_allowed_value>]
* ["bool"] * ["bool"]
* ["blob", &lt;maximum_size_in_bytes&gt;] or ["blob", &lt;minimum_size_in_bytes&gt;, &lt;maximum_size_in_bytes&gt;] * ["blob", <maximum_size_in_bytes>] or ["blob", <minimum_size_in_bytes>, <maximum_size_in_bytes>]
* ["string", &lt;maximum_allowed_length&gt;] or ["string", &lt;min_size&gt;, &lt;max_size&gt;] * ["string", <maximum_allowed_length>] or ["string", <min_size>, <max_size>]
* ["array", &lt;basic_data_type&gt;, &lt;max_elements&gt;] or ["array", &lt;dtype&gt;, &lt;min_elements&gt;, &lt;max_elements&gt;] * ["array", <basic_data_type>, <max_elements>] or ["array", <dtype>, <min_elements>, <max_elements>]
* ["tuple", [ &lt;list_of_dtypes ]] * ["tuple", [ <list_of_dtypes ]]
* ["struct", { &lt;name_of_component_as_json_string&gt;:&lt;dtype&gt;}] * ["struct", { <name_of_component_as_json_string>:<dtype>}]
Examples Examples
++++++++ ++++++++
@ -55,9 +55,9 @@ Merge datatype and validator
++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++
* enum, int, double, bool, tuple, struct as before * enum, int, double, bool, tuple, struct as before
* ["blob", &lt;maximum_size_in_bytes&gt;] or ["blob", &lt;maximum_size_in_bytes&gt;, &lt;minimum_size_in_bytes&gt;] * ["blob", <maximum_size_in_bytes>] or ["blob", <maximum_size_in_bytes>, <minimum_size_in_bytes>]
* ["string", &lt;maximum_allowed_length&gt;] or ["string", &lt;max_size_in_bytes&gt;, &lt;minimum_size_in_bytes&gt;] * ["string", <maximum_allowed_length>] or ["string", <max_size_in_bytes>, <minimum_size_in_bytes>]
* ["array", &lt;basic_data_type&gt;, &lt;max_elements&gt;] or ["array", &lt;dtype&gt;, &lt;max_elements&gt;, &lt;min_elements&gt;] * ["array", <basic_data_type>, <max_elements>] or ["array", <dtype>, <max_elements>, <min_elements>]
Interface_class Interface_class

56
doc/source/protocol/messages.rst
View File

@ -2,7 +2,7 @@ SECoP Messages
============== ==============
All Messages are formatted in the same way: All Messages are formatted in the same way:
&lt;keyword&gt;[&lt;space&gt;&lt;specifier&gt;[&lt;space&gt;&lt;JSON_formatted_data&gt;]]&lt;linefeed&gt; <keyword>[<space><specifier>[<space><JSON_formatted_data>]]<linefeed>
where [] enclose optional parts. This basically results in 3 different possible where [] enclose optional parts. This basically results in 3 different possible
formattings: formattings:
@ -13,7 +13,7 @@ formattings:
Note: numerical values and strings appear 'naturally' formatted in JSON, i.e. 5.0 or "a string" Note: numerical values and strings appear 'naturally' formatted in JSON, i.e. 5.0 or "a string"
&lt;keyword&gt; is one of a fixed list of defined keywords, &lt;specifier&gt; is either the <keyword> is one of a fixed list of defined keywords, <specifier> is either the
name of the module optionally followed by ':' + the name of a command or parameter, 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. or one of a fixed list of predefined keywords, depending on the message keyword.
@ -36,14 +36,14 @@ Both SEC-node and ECS-client can close the connection at any time!
List of Intents/Actions: List of Intents/Actions:
------------------------ ------------------------
* Identify -&gt; Ident * Identify -> Ident
* Describe -&gt; Description * Describe -> Description
* Activate Events -&gt; initial data transfer -&gt; end-of-transfer-marker * Activate Events -> initial data transfer -> end-of-transfer-marker
* Deactivate Async Events -&gt; confirmation * Deactivate Async Events -> confirmation
* Command &lt;module&gt;:&lt;command&gt; -&gt; confirmation -&gt; result_event * Command <module>:<command> -> confirmation -> result_event
* Heartbeat &lt;nonce&gt; -&gt; Heartbeat_reply * Heartbeat <nonce> -> Heartbeat_reply
* Change &lt;module&gt;[:&lt;param&gt;] JSON_VALUE -&gt; confirmation -&gt; readback_event * Change <module>[:<param>] JSON_VALUE -> confirmation -> readback_event
* TRIGGER &lt;module&gt;[:&lt;param&gt;] -&gt; read_event * TRIGGER <module>[:<param>] -> read_event
At any time an Event may be replied. Each request may also trigger an Error. At any time an Event may be replied. Each request may also trigger an Error.
@ -53,7 +53,7 @@ Warning: One Message per line: Description line can be looooong!!!
Allowed combinations as examples: Allowed combinations as examples:
(replace &lt;..&gt; with sensible stuff) (replace <..> with sensible stuff)
Identify Identify
@ -70,10 +70,10 @@ Describe
-------- --------
* Request: type A: 'describe' * Request: type A: 'describe'
* Reply: type C: 'describing &lt;ID&gt; {"modules":{"T1":{"baseclass":"Readable", ....' * Reply: type C: 'describing <ID> {"modules":{"T1":{"baseclass":"Readable", ....'
* request the 'descriptive data'. The format needs to be better defined and * request the 'descriptive data'. The format needs to be better defined and
may possibly just follow the reference implementation. may possibly just follow the reference implementation.
&lt;ID&gt; identifies the equipment. It should be unique. Our suggestion is to use something along &lt;facility&gt;_&lt;id&gt;, i.e. MLZ_ccr12 or PSI_oven4. <ID> identifies the equipment. It should be unique. Our suggestion is to use something along <facility>_<id>, i.e. MLZ_ccr12 or PSI_oven4.
Activate Async Events Activate Async Events
@ -96,9 +96,9 @@ Deactivate Async Events
Execute Command Execute Command
--------------- ---------------
* Request: type B: 'do &lt;module&gt;:&lt;command&gt;' for commands without arguments * Request: type B: 'do <module>:<command>' for commands without arguments
* Request: type C: 'do &lt;module&gt;:&lt;command&gt; JSON_argument' for commands with arguments * Request: type C: 'do <module>:<command> JSON_argument' for commands with arguments
* Reply: type C: 'done &lt;module&gt;:&lt;command&gt; JSON_result' after the command finished * Reply: type C: 'done <module>:<command> JSON_result' after the command finished
* start executing a command. When it is finished, the reply is send. * 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) The JSON_result is the a list of all return values (if any), appended with qualifiers (timestamp)
@ -106,8 +106,8 @@ Execute Command
Write Write
----- -----
* Request: type C: 'change &lt;module&gt;[:&lt;param&gt;] JSON_value' * Request: type C: 'change <module>[:<param>] JSON_value'
* Reply: type C: 'changed &lt;module&gt;:&lt;param&gt; JSON_read_back_value' * Reply: type C: 'changed <module>:<param> JSON_read_back_value'
* initiate setting a new value for the module or a parameter of it. * 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. Once this is done, the read_back value is confirmed by the reply.
@ -115,7 +115,7 @@ Write
Trigger Trigger
------- -------
* Request: type B: 'read &lt;module&gt;[:&lt;param&gt;]' * Request: type B: 'read <module>[:<param>]'
* Reply: None directly. However, one Event with the read value will be send. * 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). * 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).
@ -124,11 +124,11 @@ Heartbeat
--------- ---------
* Request: type A: 'ping' * Request: type A: 'ping'
* Request: type B: 'ping &lt;nonce&gt;' * Request: type B: 'ping <nonce>'
* Reply: type A: 'pong' * Reply: type A: 'pong'
* Reply: type B: 'pong &lt;nonce&gt;' * Reply: type B: 'pong <nonce>'
* Replies the given argument to check the round-trip-time or to confirm that the connection is still working. * Replies the given argument to check the round-trip-time or to confirm that the connection is still working.
&lt;nonce&gt; may not contain &lt;space&gt;. 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 &lt;nonce&gt; is not given (Type A), reply without it. <nonce> may not contain <space>. 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 <nonce> is not given (Type A), reply without it.
EVENT EVENT
@ -137,7 +137,7 @@ EVENT
Events can be emitted any time from the SEC-node (except if they would interrupt another message). 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. * Request: None. Events can be requested by Trigger or by Activating Async Mode.
* Reply: type C: 'event &lt;module&gt;:&lt;param&gt; JSON_VALUE' * Reply: type C: 'event <module>:<param> JSON_VALUE'
* Informs the client that a parameter got changed its value. * Informs the client that a parameter got changed its value.
In any case the JSON_value contain the available qualifiers as well: In any case the JSON_value contain the available qualifiers as well:
* "t" for the timestamp of the event. * "t" for the timestamp of the event.
@ -158,8 +158,8 @@ ERROR
----- -----
* Request: None. can only be a reply if some request fails. * Request: None. can only be a reply if some request fails.
* Reply: type C: 'ERROR &lt;errorclass&gt; JSON_additional_stuff' * Reply: type C: 'ERROR <errorclass> JSON_additional_stuff'
* Following &lt;errorclass&gt; are defined so far: * Following <errorclass> are defined so far:
* NoSuchDevice: The action can not be performed as the specified device is non-existent. * 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. * NoSuchParameter: The action can not be performed as the specified parameter is non-existent.
* NoSuchCommand: The specified command does not exist. * NoSuchCommand: The specified command does not exist.
@ -203,9 +203,9 @@ Examples
merge datatype and validator: merge datatype and validator:
----------------------------- -----------------------------
* enum, int, double, bool, tuple, struct as before * enum, int, double, bool, tuple, struct as before
* ["blob", &lt;maximum_size_in_bytes&gt;] or ["blob", &lt;maximum_size_in_bytes&gt;, &lt;minimum_size_in_bytes&gt;] * ["blob", <maximum_size_in_bytes>] or ["blob", <maximum_size_in_bytes>, <minimum_size_in_bytes>]
* ["string", &lt;maximum_allowed_length&gt;] or ["string", &lt;max_size_in_bytes&gt;, &lt;minimum_size_in_bytes&gt;] * ["string", <maximum_allowed_length>] or ["string", <max_size_in_bytes>, <minimum_size_in_bytes>]
* ["array", &lt;basic_data_type&gt;, &lt;max_elements&gt;] or ["array", &lt;dtype&gt;, &lt;max_elements&gt;, &lt;min_elements&gt;] * ["array", <basic_data_type>, <max_elements>] or ["array", <dtype>, <max_elements>, <min_elements>]
interface_class interface_class
--------------- ---------------