RTS2 communication protocol

This document describes protocol which RTS2 uses to communicate between devices.

0. Terms

Client is programm which call connect to connect to server. Server is programm
which calls listen to listen for incoming connection. All other terms have they
common value.

1. History

Protocol was inspired by SMTP and POP3 protocols, which are used to send or
retrive email to/from server. It was originally designed with following
constraint:

- protocol should be ASCII readable, so we will not run to problems with
  different endians, and we will be able to debug flow of informations in
  protocol

- client sends to server commands, server reply with data

- protocol should be TCP/IP based, as TCP layer ensures reliability of data
  connection, which we haven't to care about.

During development, second constraint was dropped as it appeared necessary to
enable server to send command to client and vice versa with data. That resulted
in V prefix for values, so they can be distinguished from commands. That change
happen in release 0.5 of RTS2.

Originally states doesn't use error mask (see 2c for description). Error mask
was added in 0.5 branch. States converge to one state per server in release
0.7.

It was originally expected that clients will query for values with info,
baseinfo etc. call. That wsa droped in favour of server notifing all clients
when value changed (telescope change location, new filter is selected,..).

2. Protocol

Protocol is ASCII based, eg. all numeric values are expressed in decimal
numbers, ASCII encoded. Each sentense in protocol is delimited by \n (0x013)
character, optionally followed by \r (0x010).

2a. Commands

Commands are send in plain ASCII form. Command parameters are separated by at
least one blank character.

Example:

expose 0 1 10

2b. Command return

When command complete, command return is send. Command return start with '+' or
'-' character, followed by 3 digit number, representing return code. '+' depict
sucessfull command return, '-' depict error during command execution.

Example:

+000 OK

2c. Values

Values starts with 'V' character. That way they are distinguished from command.
Follow value name with value. Value type is not given - it's hard-coded on
server side in send call, on client side with call to addValue (see
src/utils/rts2devclient.cpp for examples).

Example:

V exposure 10.0

2d. Extra values

Apart from V values, which are standart values seen on all (or most) setups,
there can be values, which should be recorded to FITS header of produced image,
but are non-standart, so they cannot be added to standart values that RTS2
write to image.

For such values, you can use EXTRA VALUES. New extra value can be added in
device constructor with method addExtraValue.

Client devices process meta-information send by the device during communication
setup. Clients classes, which produce FITS files (currently only camera) then
write extra tags to FITS file.

Example of definition (integer value):

ED dith_mode i Dither wedge mode of operation (IR camera)

Example of value transmission:

EV 1

2e. States

States changes are reported with messages starting with 'S' character. There is
new state (numerical value), and optional description of state change cause.

Example:

S 1 exposure started

2f. Messages

Messages are prefixed with 'M'. They were originally used to send changes of
priority, but I think that was dropped. I'm not sure whenever messages are used
anymore - most probably they were completly abandoned.

Example:

M 1145788.876 C0 Exposure started

2g. Data transfer

RTS2 needs to transfer huge amount of data. Commands/values related to data
transfer are prefixed with D.

Example:

D connect ir1.osn.iaa.es 22876 32256

2h. Priority changes

Priority changes are prefixed with P. They are send only by centrald.

Example:

P 100 0

2i. Values change

Values changes are prefixed with X. Those commands are used to change value of the device.
X is followed by value name, operation (=,+ or -) and new value as string.

Example:

X GAIN = 20

3. Command strategy

Before command proceed with end reply (+000 OK in most cases), it must:

- send value update which reflect command state. E.g. when command is
  expousure, server send V exposure etc.
  
- send any state change - that's critical so client can block futher execution
  of code correctly to next state change.

Example of communication should enlight that issue a bit - so read it first.

4. Example of communication

Here is example of communication between RTS2 client (xfocusc) and RTS2 device
(camd), which leads to exposure on camera and readout of camera data. Data
which client (xfocusc) sends to server are marked with ->, data which server
sends back with <-. Lines begining with # are comments - they aren't part of
communication:

-> cooltemp -10
<- +000 Success

-> expose 0 1 120
<- V exposure 120.0
<- V ccd_temperature -10.2
<- V temperature_setpoint -10.0
<- S img_chip 1 exposure chip started
<- +000 Success

# after exposure finish

<- S img_chip 4 exposure chip finished

-> readout 0
<- D connect C0 5565 3145784

# create data connection to port 5565 on host C0, expect 3145784 bytes of data

<- S img_chip 2 reading chip started
<- +000 Success

<- S img_chip 0 reading chip finished

