Protocol

[Protocol]

Introduction

Initially the idea with this protocol was to have it completely human readable and to work as a CLI, however when it was decided to add some of the new UI elements such as plots etc. it seemd nice to add framing to the commands which make it slightly less easy to use as a CLI, but it is still works.

I think most readers can just skip most of this document and just read the example part.

Also, i dont feel that the current version of the protocol is very good, i just wanted something quick and dirty so i could start the project. If you have suggestions on improvements please suggest them,

Framing

The framing is done by escape sequences. '[' for frame start and ']' for frame end. Every character after a \ shall be treated as an escape sequence and will not be interpreted as data, except for \ which is . Just as the normal escape sequences.

NOTE, this framing is not implemented yet, but will be soon. The current framing is ## for start and >> for end. Also no definition of what to do when you want to send ## or >> in your data, which sucks. This will be changed soon.

UI elements

Corbomite supports a few different elements with some associated commands, either explicit or implicit by the argument order. The different elements are listed here. Most if not all elements will have a layout line which has some information about how the element should be represented graphically and some commands to modify the elements at a later stage.

Label

Labels are just text that will show up in the graphical layout to give information to the user.

label id weight initial text

• label is the label command itself which tells that this line in the layout describes a label.

• id is a unique name that is used to reference the label.

• weight is the weight of the label in the user interface, so a label with weight 2 should be twice as wide as a button with the weight 1.

• All of the characters after the whitespace after the weight number until the end of line is the text that will initially be placed in the label.

Example of a layout line for a label:
label lbl1 Useful information to the user

Nothing is sent when the user presses the label. So it is just for information.

When the device wants to change the text on the label the device can send
\[lbl1 New update information to the user\]

Button

Layout:

button id weight initial text

• button is the button command itself which tells that this line in the layout describes a button.

• id is the name is a unique name that is used to reference the button.

• weight is the weight of the button in the user interface, so a button with weight 2 should be twice as wide as a button with the weight 1.

• All of the characters after the whitespace after the weight number until the end of line is the text that will initially be placed on the button.

Example of a layout line for a button:

button btn1 1 My very important button\n

When the button is pressed on the client it will respond by sending a frame that just contains the buttons name. so \[btn1\] in the above example.

In order to change the text of a button a device can send
\[name My new awesome text\]

Progressbar

Layout:
progressbar id weight max initial

• id is the name is a unique name that is used to reference the progress bar.

• weight is the weight of the progress bar in the user interface, so a progress bar with weight 2 should be twice as wide as a progress bar with the weight 1.

• max is the maximum value the progress bar can represent, they always start at 0.

• initial is the initial value the progress bar will indicate when it is created.

For example:
progressbar pb1 1 0 100
will create a progress bar with id pb1 that will go from 0 to 100.

Nothing happens when the user tries to interact with the progress bar.

In order to change the value indicated on the progress bar the device can send:
\[pb1 37\]
in order to update the progress bar pb1 to show value 37.

Seekbar

A seek bar is like a progress bar but it has a "slider" which the user can use to change its value.

Layout:
seekbar id weight max initial

• id is the name is a unique name that is used to reference the seek bar.

• weight is the weight of the seek bar in the user interface, so a seek bar with weight 2 should be twice as wide as a seek bar with the weight 1.

• max is the maximum value the seek bar can represent, they always start at 0.

• initial is the initial value the seek bar will indicate when it is created.

For example:
seek sb1 1 0 255
will create a seek bar with id sb1 that will go from 0 to 255.

When the user changes the value of the seekbar the client will send a frame:
id value

• id is the id of the seek bar for which the value was changed.
• value is the new value.

Example:
\[sb1 168\] will be sent from the client to the device when the value was changed.

In order to change the value indicated on the seek bar the device can send:
\[sb1 49\]
in order to update the seek bar sb1 to show value 49.

Plot

TODO

Textbox

A testbox in which the user and the device can communicate via text. Practical for debug messages or as a small console.

Layout:
textbox id weight lines initial_text

• id is the name is a unique name that is used to reference the text box.

• weight is the weight of the text box in the user interface, so a text box with weight 2 should be twice as wide as a text box with the weight 1.

• lines The number of lines displayed in the text box.

• initial_text All of the characters after the whitespace after the lines number until the end of line is the text that will initially be displayed in th textbox.

Example:
textbox tb1 1 6 My little textbox

when data is added to the text box by the user it will be sent character by character in the follwoing frame
id c

• id is the id of the textbox.
• c the character that was added.

for example, when the user types 'hello' in tb1 the following frames will be sent
\[tb1 h\]
\[tb1 e\]
\[tb1 l\]
\[tb1 l\]
\[tb1 o\]

Commands:

The textbox supports two commands from the device:

app
Append text in the textbox. All characters after the whitespace after app will be ppended to the text box.
Example:
\[tb1 app new text\]
will append 'new text' to the textbox tb1.

set
Set text in the textbox. The textbox will be cleared and all characters after the whitespace after set will be appended to the text box.
Example:
\[tb1 set completely new text\]
will set the content of tb1 to 'completely new text'.

Newline

All widgets are added in a row in the layout, sending the newline command will add widgets to a line below.
newline id weight

• id the id of the newline
• weight the weight for the height of the newline.

Layout

When the client sends \[i\] to the device it shall respond by listing all its widgets and layouts of these. One widget on each line. See the example:

Example

First the client connects to the device, once connected the client will send:
\[i\]
Indicating that it wants information about the device.
The device will then respond by sending a layout frame. A layout frame starts with the command layout followed by a newline, then there is a line for each widget:

\[layout
button b1 1 Test button
button b2 1 Another button
newline nl1 1
progressbar pb1 1 1000
newline nl2 1
seekbar sb1 1 2000 1000
\]

The example above will create a layout with two buttons on the top row, then a progress bar on the row below that and on a row below the progress bar there will be a seek bar.