ProtocolNewProposal

Framing

The framing is done with # as start and newline (ASCII code 13) as frame end. If one wants to send # or newline as data it should be escaped. TODO: perhaps update so that it works with both \r\n and \n

When a client connects to the device it sends an info command
#info\n

The device then responds by listing all its signals in separate frames.

Signals

Digital output

Upon info:
#dout id\n

When the client wants to change the value of the signal it sends
#id 1\n in order to set it
#id 0\n in order to clear it

In the gui a digital signal can be displayed as a checkbox indicating its status.

Digital input

Upon info:
#din id\n

When the device wants to update the client with a new value of the signal it sends
#id 1\n in order to set it
#id 0\n in order to clear it

In the gui a digital signal can be displayed as a "grayed out" checkbox indicating its status.

Analog output

Upon info:
#aout id unit min_value_in_unit min_value_in_unit min_value_raw max_value_raw\n

For example, a signal called dac0 that represents an 8 bit dac that outputs a voltage between 0 and 2.55 volts:

#aout dac0 V 0 3.3 0 1023\n

When the client wants to change the value of the dac it sends:
#id raw_value

• id is the signal id
• raw_value is the "raw" value, so in the example above if one wishes to set the dac 0.56 volt #dac0 56

In the gui an analog input can be represented by a seekbar.

Analog input

Upon info:
#ain id unit min_value_in_unit min_value_in_unit min_value_raw max_value_raw\n

For example, a signal called adc0 that represents an 8 bit adc that reads a voltage between 0 and 2.55 volts:

#ain adc0 V 0 3.3 0 1023\n

In the gui an analog input can be represented by a gauge.

Trace input

A trace is a signal with two components x and y.
Upon info:
#tout id x_unit x_units_per_lsb y_unit y_units_per_lsb\n

In order to add data to a trace the device sends:
#id x_raw_value y_raw_value\n
The device can also send multiple values on the same line as long as they are x-y pairs.
#id x0 y0 x1 y1 x2 y2 x3 y3 \n

• id is the id of the trace to which data should be appended
• x0 y0 is the first x-y pair
• x1 y1 is the next pair
• etc...

In order to speed up the transfers of large amounts of data the device can send binary data directly:
#id bin format binaryblob

• id is the id of the trace for which the binary data should be appended
• bin keyword that indicates that binary data should be added
• format the format of the data, int8/uint8...int/uint64 with increments of 8. format can also be float, double.
• binaryblob the binary data that represents the xy-pairs that should be added to the trace.

The device can also indicate that a trace is to be cleared and a new trace started by:
#id clear\n

A trace can be represented as a plot in the gui.

Event output

An event input is an event sent to the device from the client. In the client an event can be represented by a button which sends the event when pressed.

Upon info the device responds with:
#eout id\n

When an event occurs in the client the following frame is sent:
#id\n

Event input

The device can also send events to the client.

Upon info:
#ein id\n

When the device wants to send an event to the client it sends:
#id\n

In the gui and event could be represented by a message in a textbox.

String input

Upon info
#sin id\n

When the device wants to send a a string it sends the following frame:

#id New important text\n
All the text after the space after the id will be the string.

In the gui a string output can be represented by a label

String output

Upon info
#sout id\n

When the client wants to send a a string it sends the following frame:

#id New important text\n
All the text after the space after the id will be the transmitted string.

In the gui a string input can be represented by a textbox and a send button

Text i/o

In the gui a text io can be represented by a textbox, when the user types text in it it will be sent character by character to the device. The device can send framed strings to the textbox.

Upon info:
#tio id\n

The client sends data to the text i/o one character at a time by sending a frame like:
For the text i/o the height in the layout hint shall be the number of lines in the textbox.
#id c\n

• id is the id of the text i/o to which the data should be sent
• c the character to be added

The device can send an arbitrary length string to the client by sending:
#id all new text to be added\n

• id is the id of the text i/o to which the data should be sent
• all the data after the space after the id will be added.

Layout hints

Is only sent by the device upon an info request.
Information hint
The frame below sets a help/description text for the next signal that is sent.
#info informative text about the next widget\n

weight hint

TODO, this will probably change once the ui has been implemented for a few different systems to see what the different layout magers supports and behaves.

To change the weight for the coming signals in the ui a weight frame can be sent:
#w weight_width weight_height\n
The weight that is sent is used for all the following widgets until a new weight is set.

Layout line continuation hint
The default behavior is to place each ui-element on a new line in the layout, however to place multiple elements on the same line the continue hint can be sent.
#cont\n

Plot hint
By default all traces will be shown in the same plot but to create a new plot a plot hint can be given:
#plot\n
For the plots the height weight will be interpreted as a percentage of the UI-display size.

Busy

When the device is busy and does not want to receive any more commands from the client it can send a busy frame.
#busy\n
The client shall not send any more frames until an idle frame has been received.

Idle

The device tells the client that it has exited a busy state.
#idle\n