update docs
- to reflect last Meeting - to work on json structure Change-Id: I2ec0eb86958d75b30a8e5d034202136644b675d8
This commit is contained in:
Enrico Faulhaber
parent
bc3253a01a
commit
4e9f7e3eec
@ -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....
|
||||
|
||||
|
||||
87
doc/json_structure.md
Normal file
87
doc/json_structure.md
Normal file
@ -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' : [<property>],
|
||||
'modules' : [<module>] }
|
||||
|
||||
module = { 'properties' : [<property>],
|
||||
'parameter' : [<parameter>],
|
||||
'commands' : [<command>] }
|
||||
|
||||
parameter = { 'properties' : [<property>] }
|
||||
|
||||
commands = { 'properties' : [<property>] }
|
||||
|
||||
property = { 'property-name' : 'property-value' }
|
||||
|
||||
|
||||
ODER
|
||||
====
|
||||
|
||||
node = [ <array_of_properties>, <array_of_modules> ]
|
||||
|
||||
array_of_modules = [ <module>, ... ]
|
||||
|
||||
module = <array_of_properties>, <array_of_params>, <array_of_commands>
|
||||
#OR#
|
||||
module = [<array_of_properties>, <array_of_params>, <array_of_commands>]
|
||||
|
||||
array_of_params = [ <param>, ...]
|
||||
|
||||
param = <array_of_properties>
|
||||
|
||||
array_of_commands = [ <command>, ...]
|
||||
|
||||
command = < array_of_properties>
|
||||
|
||||
array_of_properties = [ <property>, ...]
|
||||
|
||||
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"
|
||||
}
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
|
||||
(Outdated!)
|
||||
|
||||
Struktur der Messages
|
||||
=====================
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user