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

Update docu to reflect current implementation.

Browse Source 
Change-Id: Iccaa51114b09ad31814ad2590e106d8466692b3e
This commit is contained in:
Enrico Faulhaber 2016-12-09 15:21:14 +01:00
parent 002c843d74
commit 0432f01e16
1 changed files with 31 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
doc/SECoP_Messages.md
View File

@ -18,6 +18,11 @@ Note: numerical values and strings appear 'naturally' formatted in JSON, i.e. 5.
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.
At the moment it is considered syntactic sugar to omit the parametername in a request.
In replies the SEC-node (in the playground) will always use the correct parameter.
On change-requests the parameter is assumed to be 'target', on trigger-requests it is assumed to be 'value'.
Clients should not rely on this and explicitly state the parametername!
All 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!)
We rely on the underlying transport to not split messages, i.e. all messages are transported as a whole and no message interrupts another.
@ -90,18 +95,18 @@ 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 B: 'doing <module>:<command>' for commands without arguments
* Reply: type C: 'doing <module>:<command> JSON_argument' for commands with arguments
* start executing a command. When it is finished, an event is send.
* Reply: type C: 'done <module>:<command> 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)
Write
-----
* Request: type C: 'change <module>[:<param>] JSON_value'
* Reply: type C: 'changing <module>[:<param>] JSON_value' # direct reply
* Reply: type C: 'changed <module>:<param> JSON_read_back_value'
* initiate setting a new value for the module or a parameter of it.
Once this is done, the new value is confirmed by an event.
Once this is done, the read_back value is confirmed by the reply.
Trigger
@ -127,26 +132,22 @@ 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 Command, Change or Trigger or by Activating Async Mode.
* Reply: type C: 'update <module>[:<param>] JSON_VALUE' # follows a TRIGGER
* Reply: type C: 'changed <module>[:<param>] JSON_VALUE' # follows a CHANGE
* Reply: type B: 'done <module>:<command>' # follows a COMMAND without return value
* Reply: type C: 'done <module>:<command> JSON_VALUE' # follows a COMMAND with return value
* Informs the client that a value has changed its value or that a command is finished (and what the return value, if any, was).
* Request: None. Events can be requested by Trigger or by Activating Async Mode.
* Reply: type C: 'event <module>:<param> 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.
* "e" for the error of the value.
* "u" for the unit of the value, if deviating from the descriptive data
* further qualifiers, if needed, may be specified.
The qualifiers are a dictionary at position 2 of a list, where the value occupies position 1.
This holds true also for complex datatypes!
This holds true also for complex datatypes (of value)!
examples:
* 'update T1 [3.479, {"t":"149128925.914882", "e":0.01924}]
* 'changed T1:p [12, {"t":"149128927.193725"}]'
* 'done T1:stop'
* 'update Vector [[0.01, 12.49, 3.92], {"t":"149128925.914882"}]'
* 'event T1:value [3.479, {"t":"149128925.914882", "e":0.01924}]
* 'event T1:p [12, {"t":"149128927.193725"}]'
* 'event Vector:value [[0.01, 12.49, 3.92], {"t":"149128925.914882"}]'
ERROR