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

doc: fix format.

Browse Source 
Change-Id: I13b33706ba160b0402eb2a06323e9cd74179fc72
This commit is contained in:
Alexander Lenz
2017-09-13 17:00:31 +02:00
parent 6c0f54d988
commit 35fe312214
2 changed files with 52 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
doc/source/protocol/jsonstruct.rst
View File

@ -54,37 +54,41 @@ Siehe auch diskussion im HZB-wiki hierzu....
verwirrend.... verwirrend....
vorerst folgende Festlegung: vorerst folgende Festlegung:
{"equipment_id": "cryo_7",
"firmware": "The SECoP playground", .. code-block:: json
"modules": ["cryo", {"commands": ["stop", {"resulttype": "None",
"arguments": "[]", {"equipment_id": "cryo_7",
"description": "Testing command implementation\\n\\nwait a second" "firmware": "The SECoP playground",
}, "modules": ["cryo", {"commands": ["stop", {"resulttype": "None",
"start", {"resulttype": "None", "arguments": "[]",
"arguments": "[]", "description": "Testing command implementation\\n\\nwait a second"
"description": "normally does nothing,\\n\\nbut there may be modules which _start_ the action here\\n" },
} "start", {"resulttype": "None",
], "arguments": "[]",
"group": "very important/stuff", "description": "normally does nothing,\\n\\nbut there may be modules which _start_ the action here\\n"
"implementation": "secop.devices.cryo.Cryostat", }
"interfaces": ["Drivable", "Readable", "Device"], ],
"parameters": ["status", {"readonly": true, "group": "very important/stuff",
"datatype": ["tuple", ["enum", {"unknown":-1,"idle":100, "warn":200, "unstable":250, "busy":300,"error":400}], "string"], "implementation": "secop.devices.cryo.Cryostat",
"description": "current status of the device" "interfaces": ["Drivable", "Readable", "Device"],
}, "parameters": ["status", {"readonly": true,
"value", {"readonly": true, "datatype": ["tuple", ["enum", {"unknown":-1,"idle":100, "warn":200, "unstable":250, "busy":300,"error":400}], "string"],
"datatype": ["double",0,null], "description": "current status of the device"
"description": "regulation temperature", },
"unit": "K" "value", {"readonly": true,
}, "datatype": ["double",0,null],
"target", {"readonly": false, "description": "regulation temperature",
"datatype": ["double",0,null], "unit": "K"
"description": "target temperature", },
"unit": "K" "target", {"readonly": false,
} "datatype": ["double",0,null],
] "description": "target temperature",
} "unit": "K"
], }
"version": "2017.01" ]
} }
],
"version": "2017.01"
}

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

@ -23,7 +23,7 @@ On change-requests the parameter is assumed to be 'target', on trigger-requests
Clients should not rely on this and explicitly state the parametername! Clients should not rely on this and explicitly state the parametername!
All names and keywords are defined to be identifiers in the sense, that they are not longer than 63 characters and consist only of letters, digits and underscore and do not start with a digit. (i.e. T_9 is ok, whereas t{9} is not!) All names and keywords are defined to be identifiers in the sense, that they are not longer than 63 characters and consist only of letters, digits and underscore and do not start with a digit. (i.e. T_9 is ok, whereas t{9} is not!)
No rule is without exception, there is exactly ONE special case: the identify request consists of the literal string '*IDN?\\n' and its answer is formatted like an valid SCPI response for *IDN?. No rule is without exception, there is exactly ONE special case: the identify request consists of the literal string '\*IDN?\\n' and its answer is formatted like an valid SCPI response for \*IDN?.
We rely on the underlying transport to not split messages, i.e. all messages are transported as a whole and no message interrupts another. We rely on the underlying transport to not split messages, i.e. all messages are transported as a whole and no message interrupts another.
@ -59,11 +59,11 @@ Allowed combinations as examples:
Identify Identify
-------- --------
* Request: type A: '*IDN?' * Request: type A: '\*IDN?'
* Reply: special: 'SECoP, SECoPTCP, V2016-11-30, rc1' * Reply: special: 'SECoP, SECoPTCP, V2016-11-30, rc1'
* queries if SECoP protocol is supported and which version it is * queries if SECoP protocol is supported and which version it is
Format is intentionally choosen to be compatible to SCPI (for this query only). Format is intentionally choosen to be compatible to SCPI (for this query only).
It is NOT intended to transport information about the manufacturer of the hardware, but to identify this as a SECoP device and transfer the protocol version! It is NOT intended to transport information about the manufacturer of the hardware, but to identify this as a SECoP device and transfer the protocol version!
Describe Describe
@ -72,8 +72,8 @@ Describe
* Request: type A: 'describe' * Request: type A: 'describe'
* Reply: type C: 'describing <ID> {"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.
<ID> identifies the equipment. It should be unique. Our suggestion is to use something along <facility>_<id>, 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
@ -82,7 +82,7 @@ Activate Async Events
* Request: type A: 'activate' * Request: type A: 'activate'
* Reply: several EVENT lines (initial value transfer) followed by: type A: 'active' * Reply: several EVENT lines (initial value transfer) followed by: type A: 'active'
* Activates sending of Async Events after transferring all live quantities once * Activates sending of Async Events after transferring all live quantities once
and an 'end-of-initial-transfer' marker. After this events are enabled. and an 'end-of-initial-transfer' marker. After this events are enabled.
Deactivate Async Events Deactivate Async Events
@ -109,7 +109,7 @@ Write
* Request: type C: 'change <module>[:<param>] JSON_value' * Request: type C: 'change <module>[:<param>] JSON_value'
* Reply: type C: 'changed <module>:<param> 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.
Trigger Trigger
@ -128,7 +128,7 @@ Heartbeat
* Reply: type A: 'pong' * Reply: type A: 'pong'
* Reply: type B: 'pong <nonce>' * 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.
<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. <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
@ -139,11 +139,13 @@ Events can be emitted any time from the SEC-node (except if they would interrupt
* 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 <module>:<param> 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.
* "e" for the error of the value. * "e" for the error of the value.
* "u" for the unit of the value, if deviating from the descriptive data * "u" for the unit of the value, if deviating from the descriptive data
* further qualifiers, if needed, may be specified. * further qualifiers, if needed, may be specified.
The qualifiers are a dictionary at position 2 of a list, where the value occupies position 1. The qualifiers are a dictionary at position 2 of a list, where the value occupies position 1.
This holds true also for complex datatypes (of value)! This holds true also for complex datatypes (of value)!
@ -160,6 +162,7 @@ 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 <errorclass> JSON_additional_stuff' * Reply: type C: 'ERROR <errorclass> JSON_additional_stuff'
* Following <errorclass> 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.
@ -173,6 +176,7 @@ ERROR
* Disabled: The requested action can not be performed at the moment. (Interlocks?) * Disabled: The requested action can not be performed at the moment. (Interlocks?)
* SyntaxError: A malformed Request was send * SyntaxError: A malformed Request was send
* InternalError: Something that should never happen just happened. * InternalError: Something that should never happen just happened.
The JSON part should reference the offending request and give an explanatory string. The JSON part should reference the offending request and give an explanatory string.
examples: examples:
@ -186,7 +190,7 @@ Examples
-------- --------
(client connects): (client connects):
(client) '*IDN?' (client) '\*IDN?'
(SEC-node) 'Sine2020WP7.1&ISSE, SECoP, V2016-11-30, rc1' (SEC-node) 'Sine2020WP7.1&ISSE, SECoP, V2016-11-30, rc1'
(client) 'describe' (client) 'describe'
(SEC-node) 'describing SECoP_Testing {"modules":{"T1":{"baseclass":"Readable", ... (SEC-node) 'describing SECoP_Testing {"modules":{"T1":{"baseclass":"Readable", ...