update docs

- to reflect last Meeting
- to work on json structure

Change-Id: I2ec0eb86958d75b30a8e5d034202136644b675d8

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 <json_description>'
+
+  * '(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....
+