diff --git a/doc/source/protocol/descjson.rst b/doc/source/protocol/descjson.rst index 9081347..792f89b 100644 --- a/doc/source/protocol/descjson.rst +++ b/doc/source/protocol/descjson.rst @@ -1,11 +1,11 @@ Structure of the descriptive json ================================= -* json = {"modules": <list_of_modules>, "properties": <list_of_sec-node_properties>, ...} -* module = {"name": <name_of_module>, "parameters": <list_of_parameters>, "commands": <list_of_commands>, "properties": <list_of_module_properties>} -* parameter = {"name": ..., "properties": <list_of_properties>} -* command = {"name": ..., "properties": <list_of_properties>} -* property = {"name":<name>, "datatype": <datatype>, "value": <value>} +* json = {"modules": , "properties": , ...} +* module = {"name": , "parameters": , "commands": , "properties": } +* parameter = {"name": ..., "properties": } +* command = {"name": ..., "properties": } +* property = {"name":, "datatype": , "value": } -note: property may also be [<name>,<datatype>,<value>] +note: property may also be [,,] diff --git a/doc/source/protocol/history.rst b/doc/source/protocol/history.rst index fbd402a..c89a066 100644 --- a/doc/source/protocol/history.rst +++ b/doc/source/protocol/history.rst @@ -11,12 +11,12 @@ Meeting 29.5.2017 * 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", {<number_value>:<name>}] +* 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", <subtype>] ["tuple", [<list_of_compositing data types>] ["struct", {"name_of_subcomponent":<type of subcomponent>}] +* 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 +* 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) @@ -24,15 +24,15 @@ Meeting 29.5.2017 Merge datatype and validator ++++++++++++++++++++++++++++ -* ["enum", {<number_value>:<json_string>}] -* ["int"] or ["int", <lowest_allowed_value>, <highest_allowed_value>] -* ["double"] or ["double", <lowest_allowed_value>, <highest_allowed_value>] +* ["enum", {:}] +* ["int"] or ["int", , ] +* ["double"] or ["double", , ] * ["bool"] -* ["blob", <maximum_size_in_bytes>] or ["blob", <minimum_size_in_bytes>, <maximum_size_in_bytes>] -* ["string", <maximum_allowed_length>] or ["string", <min_size>, <max_size>] -* ["array", <basic_data_type>, <max_elements>] or ["array", <dtype>, <min_elements>, <max_elements>] -* ["tuple", [ <list_of_dtypes ]] -* ["struct", { <name_of_component_as_json_string>:<dtype>}] +* ["blob", ] or ["blob", , ] +* ["string", ] or ["string", , ] +* ["array", , ] or ["array", , , ] +* ["tuple", [ :}] Examples ++++++++ @@ -55,9 +55,9 @@ Merge datatype and validator ++++++++++++++++++++++++++++ * enum, int, double, bool, tuple, struct as before - * ["blob", <maximum_size_in_bytes>] or ["blob", <maximum_size_in_bytes>, <minimum_size_in_bytes>] - * ["string", <maximum_allowed_length>] or ["string", <max_size_in_bytes>, <minimum_size_in_bytes>] - * ["array", <basic_data_type>, <max_elements>] or ["array", <dtype>, <max_elements>, <min_elements>] + * ["blob", ] or ["blob", , ] + * ["string", ] or ["string", , ] + * ["array", , ] or ["array", , , ] Interface_class diff --git a/doc/source/protocol/messages.rst b/doc/source/protocol/messages.rst index c262169..65500b6 100644 --- a/doc/source/protocol/messages.rst +++ b/doc/source/protocol/messages.rst @@ -2,7 +2,7 @@ SECoP Messages ============== All Messages are formatted in the same way: - <keyword>[<space><specifier>[<space><JSON_formatted_data>]]<linefeed> + [[]] where [] enclose optional parts. This basically results in 3 different possible formattings: @@ -13,7 +13,7 @@ formattings: Note: numerical values and strings appear 'naturally' formatted in JSON, i.e. 5.0 or "a string" -<keyword> is one of a fixed list of defined keywords, <specifier> is either the + 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. @@ -36,14 +36,14 @@ 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 <module>:<command> -> confirmation -> result_event - * Heartbeat <nonce> -> Heartbeat_reply - * Change <module>[:<param>] JSON_VALUE -> confirmation -> readback_event - * TRIGGER <module>[:<param>] -> read_event + * 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. @@ -53,7 +53,7 @@ Warning: One Message per line: Description line can be looooong!!! Allowed combinations as examples: -(replace <..> with sensible stuff) +(replace <..> with sensible stuff) Identify @@ -70,10 +70,10 @@ Describe -------- * Request: type A: 'describe' - * Reply: type C: 'describing <ID> {"modules":{"T1":{"baseclass":"Readable", ....' + * 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. - <ID> identifies the equipment. It should be unique. Our suggestion is to use something along <facility>_<id>, i.e. MLZ_ccr12 or PSI_oven4. + identifies the equipment. It should be unique. Our suggestion is to use something along _, i.e. MLZ_ccr12 or PSI_oven4. Activate Async Events @@ -96,9 +96,9 @@ Deactivate Async Events Execute Command --------------- - * Request: type B: 'do <module>:<command>' for commands without arguments - * Request: type C: 'do <module>:<command> JSON_argument' for commands with arguments - * Reply: type C: 'done <module>:<command> JSON_result' after the command finished + * 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) @@ -106,8 +106,8 @@ Execute Command Write ----- - * Request: type C: 'change <module>[:<param>] JSON_value' - * Reply: type C: 'changed <module>:<param> JSON_read_back_value' + * 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. @@ -115,7 +115,7 @@ Write Trigger ------- - * Request: type B: 'read <module>[:<param>]' + * 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). @@ -124,11 +124,11 @@ Heartbeat --------- * Request: type A: 'ping' - * Request: type B: 'ping <nonce>' + * Request: type B: 'ping ' * Reply: type A: 'pong' - * Reply: type B: 'pong <nonce>' + * Reply: type B: 'pong ' * Replies the given argument to check the round-trip-time or to confirm that the connection is still working. - <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. + 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 @@ -137,7 +137,7 @@ 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 <module>:<param> JSON_VALUE' + * 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. @@ -158,8 +158,8 @@ ERROR ----- * Request: None. can only be a reply if some request fails. - * Reply: type C: 'ERROR <errorclass> JSON_additional_stuff' - * Following <errorclass> are defined so far: + * 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. @@ -203,9 +203,9 @@ Examples merge datatype and validator: ----------------------------- * enum, int, double, bool, tuple, struct as before - * ["blob", <maximum_size_in_bytes>] or ["blob", <maximum_size_in_bytes>, <minimum_size_in_bytes>] - * ["string", <maximum_allowed_length>] or ["string", <max_size_in_bytes>, <minimum_size_in_bytes>] - * ["array", <basic_data_type>, <max_elements>] or ["array", <dtype>, <max_elements>, <min_elements>] + * ["blob", ] or ["blob", , ] + * ["string", ] or ["string", , ] + * ["array", , ] or ["array", , , ] interface_class ---------------