reworking messages
1) start 'bin/secop-server test' 2) connect to localhost port 10767 3) enter help<enter> 4) enjoy Change-Id: I488d5f9cdca8c91c583691ab23f541a4a8759f4e
This commit is contained in:
Enrico Faulhaber
372
doc/protocols/simple_communication_protocol.rst
Normal file
372
doc/protocols/simple_communication_protocol.rst
Normal file
@ -0,0 +1,372 @@
|
||||
Simple communication protocol
|
||||
=============================
|
||||
| *Version 0.0.2*
|
||||
| *Copyright 2012: Alexander Lenz, Dr. Enrico Faulhaber*
|
||||
|
||||
|
||||
Table of contents
|
||||
-----------------
|
||||
|
||||
.. contents::
|
||||
.. sectnum::
|
||||
|
||||
Disambiguation
|
||||
--------------
|
||||
|
||||
Device
|
||||
''''''
|
||||
A device is a logical part of the complete system. This may be any piece of hardware which
|
||||
can be accessed seperately. Also a logical axis, implemented with multiple motors can be a device.
|
||||
|
||||
Parameter
|
||||
'''''''''
|
||||
A parameter is a device depended value which represents (usually) a physical value.
|
||||
It can be read only or read-/writeable.
|
||||
|
||||
Messages
|
||||
--------
|
||||
|
||||
The messages are devided into commands and responses.
|
||||
|
||||
A command consists of the device of interest, the relevant parameter, an operator
|
||||
that specifies what should happen, and a value if neccessary.
|
||||
|
||||
::
|
||||
|
||||
Commands: <device>/<parameter><operator><value_if_any>\n
|
||||
|
||||
You will get a response for each command (\ **even if it failed!**\ ).
|
||||
These reponses consist of an error code, the mirrored command (to verify for what command the response is related)
|
||||
and a value if requested.
|
||||
|
||||
::
|
||||
|
||||
Response: <error_code> <mirrored_command><value_if_any>\n
|
||||
|
||||
|
||||
For limitations regarding the message contents, have a look at: `Limitations`_
|
||||
|
||||
|
||||
|
||||
Operators
|
||||
---------
|
||||
|
||||
? (Request)
|
||||
'''''''''''
|
||||
This operator can be used to request data.
|
||||
In the most cases, you want to request the value of device parameter:
|
||||
|
||||
**Command**
|
||||
::
|
||||
|
||||
<device>/<parameter>?\n
|
||||
|
||||
**Response**
|
||||
::
|
||||
|
||||
<error_code> <device>/<parameter>=<value_if_success>\n
|
||||
|
||||
= (Set)
|
||||
'''''''
|
||||
This operator can be used to write a device value.
|
||||
|
||||
**Command**
|
||||
::
|
||||
|
||||
<device>/<parameter>=<value>\n
|
||||
|
||||
**Response**
|
||||
::
|
||||
|
||||
<error_code> <device>/<parameter>=<value>\n
|
||||
|
||||
|
||||
Protocol error codes
|
||||
--------------------
|
||||
|
||||
In case of an error, you get the following response:
|
||||
|
||||
::
|
||||
|
||||
<error_code> <mirrored_command>
|
||||
|
||||
|
||||
The following errors describe errors of the protocol, not the device.
|
||||
|
||||
======================= ==============
|
||||
**Error** **Error code**
|
||||
======================= ==============
|
||||
No error 0
|
||||
Unknown error 1
|
||||
Connection error 2
|
||||
Command unknown 3
|
||||
Device unknown 4
|
||||
Parameter unknown 5
|
||||
Format error 6
|
||||
Value out of limits 7
|
||||
Param not writable 8
|
||||
Not allowed 9
|
||||
======================= ==============
|
||||
|
||||
Device stati
|
||||
------------
|
||||
|
||||
The following status codes describe the device status and can be requested via:
|
||||
|
||||
::
|
||||
|
||||
<device>/status:\n
|
||||
|
||||
|
||||
========== ===========
|
||||
**Status** **Meaning**
|
||||
========== ===========
|
||||
IDLE Device is alive and ready to accept commands.
|
||||
BUSY Device is performing some action and therefore busy. It doesn't accept new commands. All Parameters can be read.
|
||||
ERROR Something bad happened, a manual action is required. Some command could unexpectedly not be performed.
|
||||
UNKNOWN Unknown device state.
|
||||
========== ===========
|
||||
|
||||
|
||||
Limitations
|
||||
-----------
|
||||
|
||||
Naming & Formatting
|
||||
'''''''''''''''''''
|
||||
|
||||
- Device names are all lower case and can consist of letters, numbers and underscores (no whitespace!).
|
||||
- Device names consist of up to 80 characters.
|
||||
- Parameter names are all lower case and can consist of letters, numbers and underscores (no whitespace!).
|
||||
- Parameter names consist of up to 80 characters.
|
||||
- Floating point numbers are using a decimal point (5.23).
|
||||
- Lists are commma-separated and enclosed by square brackets ([entry1,entry2,entry3]).
|
||||
- Strings are enclosed by single ticks ('str').
|
||||
- Messages consist of up to 256 characters.
|
||||
|
||||
Devices
|
||||
'''''''
|
||||
|
||||
General
|
||||
"""""""
|
||||
All devices have to support at least the following parameters:
|
||||
|
||||
**status**
|
||||
This **read only** parameters describes the current device state.
|
||||
It contains a list with two items.
|
||||
|
||||
1. A short constant status string (Have a look at: `Device stati`_)
|
||||
2. A longer description which can contain any character except a comma!
|
||||
|
||||
**parameters**
|
||||
This **read only** parameter represents a list of all available parameters of the given device.
|
||||
It contains a comma seperated list with all parameter names.
|
||||
|
||||
Readable
|
||||
""""""""
|
||||
All devices which provide any type of readable value have to support the general parameters and at leas the following:
|
||||
**value**
|
||||
This **read only** parameter represents the current 'main value'.
|
||||
It contains a single value which can be a float or integer number, or a string.
|
||||
|
||||
Writable
|
||||
""""""""
|
||||
All devices for which you can set a value have to support at least the general parameters, all parameters of `Readable`_ devices and the following:
|
||||
**target**
|
||||
This **read/write** parameter represents the device's target value.
|
||||
It contains a single value which can be a float or integer number, or a string.
|
||||
If you set the target value, the device goes into 'BUSY' state and tries to reach that value.
|
||||
The current value can be requested by the 'value' parameter.
|
||||
|
||||
Server device
|
||||
"""""""""""""
|
||||
The server have to provide a device for direct communication with the protocol server.
|
||||
It has to provide at least the parameters of a general device (`Devices`_) plus the following:
|
||||
|
||||
**devices**
|
||||
A list of all available devices.
|
||||
**version**
|
||||
A version string which identifies the protocol version, the server implements.
|
||||
|
||||
The server device can be queried by omitting the <device> parameter (+ the '/').
|
||||
::
|
||||
|
||||
devices?\n
|
||||
version?\n
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
Let's have a look at some examples:
|
||||
|
||||
+---------------+---------------------------------+
|
||||
|**Device:** |temp_ctrl |
|
||||
+---------------+---------------------------------+
|
||||
|**Type:** |Temperature controller (Moveable)|
|
||||
+---------------+---------------------------------+
|
||||
|**Parameters:**| - status **(mandatory)** |
|
||||
| | - parameters **(mandatory)** |
|
||||
| | - value **(mandatory)** |
|
||||
| | - target **(mandatory)** |
|
||||
| | - ... |
|
||||
+---------------+---------------------------------+
|
||||
|
||||
Requesting the current setpoint (target)
|
||||
''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
**Command**
|
||||
|
||||
::
|
||||
|
||||
temp_ctrl/target?\n
|
||||
|
||||
**Response**
|
||||
|
||||
::
|
||||
|
||||
0 temp_ctrl/target=0.42\n
|
||||
|
||||
Setting the setpoint (target)
|
||||
'''''''''''''''''''''''''''''
|
||||
|
||||
**Command**
|
||||
|
||||
::
|
||||
|
||||
temp_ctrl/target=0.21\n
|
||||
|
||||
**Response**
|
||||
|
||||
::
|
||||
|
||||
0 temp_ctrl/target=0.21\n
|
||||
|
||||
Setting an out-of-bounds setpoint (target)
|
||||
''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
**Command**
|
||||
|
||||
::
|
||||
|
||||
temp_ctrl/target=-7.5\n
|
||||
|
||||
**Response**
|
||||
|
||||
::
|
||||
|
||||
7 temp_ctrl/target=-7.5\n
|
||||
|
||||
|
||||
Requesting the status
|
||||
'''''''''''''''''''''
|
||||
|
||||
**Command**
|
||||
|
||||
::
|
||||
|
||||
temp_ctrl/status?\n
|
||||
|
||||
**Response**
|
||||
|
||||
::
|
||||
|
||||
0 temp_ctrl/status=BUSY,I'm ramping!\n
|
||||
|
||||
Requesting the device list
|
||||
''''''''''''''''''''''''''
|
||||
|
||||
**Command**
|
||||
|
||||
::
|
||||
|
||||
/devices?\n
|
||||
|
||||
**Response**
|
||||
|
||||
::
|
||||
|
||||
0 /devices=temp_ctrl,another_dev1,another_dev2\n
|
||||
|
||||
.. Allowed extensions
|
||||
------------------
|
||||
|
||||
Additional operators
|
||||
''''''''''''''''''''
|
||||
|
||||
\* (Wildcard)
|
||||
"""""""""""""
|
||||
This operator is a little more advanced than the others.
|
||||
It represents a wild card and can be combined with other operators.
|
||||
The response you will get, are multiple messages which contain:
|
||||
::
|
||||
|
||||
<error_code> <the_mirrored_command> <answer_for_the_operator>
|
||||
|
||||
If you want to request all parameters of a device, it will be:
|
||||
|
||||
**Command**
|
||||
::
|
||||
|
||||
<device>/*?\n
|
||||
|
||||
**Response**
|
||||
*Multiple*
|
||||
::
|
||||
|
||||
<error_code> <device>/*? <device>/<parameter>=<value>\n
|
||||
|
||||
Examples
|
||||
^^^^^^^^
|
||||
Requesting all parameters
|
||||
*************************
|
||||
|
||||
**Command**
|
||||
|
||||
::
|
||||
|
||||
temp_ctrl/*?\n
|
||||
|
||||
**Response**
|
||||
::
|
||||
|
||||
0 temp_ctrl/*? temp_ctrl/status=BUSY,I'm ramping!\n
|
||||
0 temp_ctrl/*? temp_ctrl/parameters=status,parameters,value,target\n
|
||||
0 temp_ctrl/*? temp_ctrl/value=0.21\n
|
||||
0 temp_ctrl/*? temp_ctrl/target=0.42\n
|
||||
|
||||
Recommendations
|
||||
---------------
|
||||
Interfaces
|
||||
''''''''''
|
||||
|
||||
We provide some recommendations for the interface configuration when using the simple communication protocol:
|
||||
|
||||
Serial (RS232)
|
||||
""""""""""""""
|
||||
|
||||
If you are using a serial connection, you should use the following configuration:
|
||||
|
||||
============= ==============
|
||||
**Baudrate** 9600 or 115200
|
||||
**Data bits** 8
|
||||
**Parity** None
|
||||
**Stop bits** 1
|
||||
============= ==============
|
||||
|
||||
Network (TCP)
|
||||
"""""""""""""
|
||||
|
||||
If you are using a TCP based network connection, you should use the following configuration:
|
||||
|
||||
======== =====
|
||||
**Port** 14728
|
||||
======== =====
|
||||
|
||||
Network (UDP)
|
||||
"""""""""""""
|
||||
|
||||
We recommend not to use UDP connections at all, as the protocol was not designed for such connections.
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user