From 4e9f7e3eecc425f36df1ef6a78d7fddc221707a3 Mon Sep 17 00:00:00 2001 From: Enrico Faulhaber Date: Wed, 21 Jun 2017 17:34:10 +0200 Subject: [PATCH] update docs - to reflect last Meeting - to work on json structure Change-Id: I2ec0eb86958d75b30a8e5d034202136644b675d8 --- doc/SECoP_Messages.md | 131 ++++++++++++++++++++++++++++++++++++++++++ doc/json_structure.md | 87 ++++++++++++++++++++++++++++ doc/messages.md | 2 + 3 files changed, 220 insertions(+) create mode 100644 doc/json_structure.md diff --git a/doc/SECoP_Messages.md b/doc/SECoP_Messages.md index 666b18c..69a8383 100644 --- a/doc/SECoP_Messages.md +++ b/doc/SECoP_Messages.md @@ -215,3 +215,134 @@ Discussion & open Points * ... +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", {<number_value>:<name>}] + * 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>}] + * 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", {<number_value>:<json_string>}] + * ["int"] or ["int", <lowest_allowed_value>, <highest_allowed_value>] + * ["blob"] or ["blob", <minimum_size_in_bytes or 0>, <maximum_size_in_bytes>] + * ["double"] or ["double", <lowest_allowed_value>, <highest_allowed_value>] + * ["string"] or ["string", <maximum_allowed_length>] or ["string", <min_size>, <max_size>] + * ["bool"] + * ["array", <basic_data_type>] or ["array", <dtype>, <min_elements>, <max_elements>] + * ["tuple", [ <list_of_dtypes ]] + * ["struct", { <name_of_component_as_json_string>:<dtype>}] + +examples: + + * status: ["tuple", [ ["enum", {0:"init", 100:"idle", 200:"warn", 300:"busy"}], ["string", 255] ] ] + * p/pi/pid-triple: ["array", ["double", 0, 100], 1, 3] + + +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" + + +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 + + +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 + +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>} + +note: property may also be [<name>,<datatype>,<value>] + +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) + +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' + +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/json_structure.md b/doc/json_structure.md new file mode 100644 index 0000000..ce3b555 --- /dev/null +++ b/doc/json_structure.md @@ -0,0 +1,87 @@ +> 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: +{"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": ["Driveable", "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/messages.md b/doc/messages.md index 001ed3e..a0bbaaa 100644 --- a/doc/messages.md +++ b/doc/messages.md @@ -1,4 +1,6 @@ +(Outdated!) + Struktur der Messages =====================