GUI-O Developer Manual GUI-O Team
Document version history
Version Change Log Date
0.9.0 Pre-release 28 Aug, 2020 0.9.1 • Updated documentation on file handling (File 1 Sep, 2020 I/O) and sharing • Added MQTT QoS information • Fixed typos and corrected spelling • Replaced GUI-O website image (LB widget) • Added explanation for abbreviations 0.9.2 • Fixed typos 9 Sep, 2020 • Quick Examples updated with widget response 0.9.3 • Removed specific widgets clear request 19 Sep, 2020 • Added multi screen support text • Added text explaining chart zoom reset 0.9.4 • Replaced 'PUBT' with 'PUB' in IoT user handling 24 Sep, 2020 section • Added link to current user name and password for GUI-O MQTT broker 0.9.5 • Updated 'Quick pairing' menu image 15 Nov, 2020 • Added 'Direct device pairing' section • Updated 'IoT transport protocol' section • Updated 'UI settings change request' section 0.9.6 • MAJOR CHANGE: re-implemented widgets 6 Dec, 2020 sizing. The widget sizes are now specified in percent (%) of DPW and DPH, while taking into account various aspect ratios of different devices. Removed SCA parameter • Added text, font family and font size property to BT widget • Fixed typo when using @hls command • Added width, height and background color property to LB widget • Re-implemented response mechanism for TG, SL and CB widget • Removed response mechanism for BT, NI, TI and TU widget
2 GUI-O Team
• Modified default parameter for VI play state (now playing by default) • Added HIW parameter to BSR, BST and BSE widgets • Added developer mode section 0.9.7 • Removed @disp command and updated 8 Dec, 2020 developer mode section (added display info) • Updated LB parameters (removed height parameter and updated width parameter) 0.9.8 • Fixed LB default width parameter 13 Dec, 2020 • Added HIW parameter to BT and changed all HIW defaults to disabled • Added explanation regarding ASR parameter and landscape orientation • Added "pairingResponseDetail" to device pairing protocol • Updated CH plotting - parameter XP can be omitted when Time or Sweep chart types are used 0.9.9 • Added "incoming messages logging" to 22 Dec, 2020 developer mode • Corrected the text in the footer under "Expected response feature section" - only TG, SL and CB support this feature • Added notes about recommendation of ASR parameter usage 0.9.10 • Added new widget (IML) 29 Dec, 2020 • Updated examples with new sizing concept (percent (%) of DPW and DPH) • Removed light switch example 0.9.11 • Added disclaimer 04 Jan, 2021 0.9.12 • Added "outgoing messages logging" to 12 Jan, 2021 developer mode 0.9.13 • Added gradient color support for SL, CB, BT and 5 Feb, 2021 BSR widgets • Added a new font (Simplifica) 0.9.14 • Added new widget (LST) 9 Feb 2021
3 GUI-O Team
• Enabled programmatic "active" item index selection for LST, IML and TU widgets 0.9.15 • Added new fonts 22 Apr, 2021 • Added clear / reset screen orientation command (restore default orientation to portrait mode) 0.9.16 • Added SHVL and VLP parameters to CH widget 30 May, 2021 • LB widget now supports multiple spaces within text 0.9.17 • Added response to user interaction for |IM and 25 July, 2021 |IML widgets (press, long press and scrolling) 0.9.18 • Added CA (calendar) widget 14 Aug, 2021 • Added date / time stamp support to File I/O 0.9.19 • Typo fix 30 Aug, 2021 • Added additional explanation to introduction section 0.9.20 • Added General settings section 18 Sep, 2021 • Added Capture screen section • Minor fixes to IM and IML widgets 0.9.21 • Added TSC parameter description to @gse 1 Oct, 2021 command 0.9.22 • Added |GRID widget and @quitapp command 5 Oct, 2021 1.0.0 First official release TBD
4 GUI-O Team
Disclaimer: This material is provided by the GUI-O Team "as is". The GUI-O Team assumes no responsibility or liability for any errors or omissions in the content of this manual. The information contained in this manual is provided on an "as is" basis with no guarantees of completeness, accuracy, usefulness or timeliness and without any warranties of any kind whatsoever, express or implied. The GUI-O Team does not warrant that this manual and any information of material downloaded from the GUI- O site, will be uninterrupted, error-free, omission-free or free of viruses or other harmful items. You are solely responsible for determining whether GUI-O application is compatible with your equipment and other software installed on your equipment. You are also solely responsible for the protection of your equipment and backup of your data, and the GUI-O Team will not be liable for any damages you may suffer in connection with using, modifying, or distributing GUI-O application.
2021 GUI-O is a trademark of the GUI-O Team. All rights reserved.
5 GUI-O Team
Table of Contents INTRODUCTION...... 14 WIDGETS OVERVIEW...... 16 HARDWARE OVERVIEW...... 21 GRAPHICAL INTERFACE OVERVIEW...... 22 Main screen...... 22 Open settings menu...... 22 Send initialize request...... 22 Demo banner...... 23 Settings menu...... 24 Quick connect...... 24 Connections...... 25 Bluetooth with optional IoT forwarding...... 25 Bluetooth LE with optional IoT forwarding...... 25 USB with optional IoT forwarding...... 26 Standalone IoT...... 26 Quick pair...... 27 Generate QR code...... 28 Scan QR code...... 28 Direct device pairing...... 28 IoT devices...... 31 COMMUNICATION PROTOCOL...... 32 Requests and responses...... 32 Initialization request...... 33 Clear widgets request...... 33 Clear hardware objects request...... 33 Clear orientation request...... 33 Loading screen request...... 33 General settings change request...... 34 UI settings change request...... 34 Capture screen request...... 35 Settings menu visibility request...... 35 Switch screen request...... 35 Quit application request...... 35 IoT transport protocol...... 37 IoT users handling...... 40 IoT broker...... 41 QUICK START...... 42
6 GUI-O Team
WIDGETS API...... 43 General notes...... 43 Scalability...... 43 Color values encoding...... 44 Text (string) encoding...... 45 Parameter types...... 45 Visual stacking order...... 45 Expected response feature...... 45 Multiple screen support...... 46 Getting started tutorial...... 46 Toggle...... 49 Parameters...... 49 Create command...... 50 Update command...... 51 On enabled state change...... 51 Quick-start example...... 51 Slider...... 53 Parameters...... 53 Create command...... 55 Update command...... 55 On value change...... 55 Quick-start example...... 56 Circular bar...... 57 Parameters...... 57 Create command...... 59 Update command...... 60 On value change...... 60 Quick-start example...... 60 Number input...... 62 Parameters...... 62 Create command...... 63 Update command...... 63 On input change...... 63 Quick-start example...... 63 Text input...... 65 Parameters...... 65 Create command...... 66 Update command...... 66 On input change...... 66 Quick-start example...... 66
7 GUI-O Team
Scrollable text area...... 68 Parameters...... 68 Create command...... 69 Update command...... 69 Quick-start example...... 70 Calendar...... 71 Parameters...... 71 Create command...... 72 Update command...... 72 On input change...... 72 Quick-start example...... 73 Button...... 74 Parameters...... 74 Create command...... 75 Update command...... 76 On pressed...... 76 Quick-start example...... 76 Label...... 77 Parameters...... 77 Create command...... 78 Update command...... 79 Quick-start example...... 79 Status indicator...... 81 Parameters...... 81 Create command...... 82 Update command...... 82 Quick-start example...... 82 Image...... 83 Parameters...... 83 Create command...... 84 Update command...... 84 On user interaction...... 84 Quick-start example...... 85 Image list...... 86 Parameters...... 86 Create command...... 87 Update command...... 87 On scrolling finished...... 87 On user interaction...... 88 Quick-start example...... 88
8 GUI-O Team
Video...... 90 Parameters...... 90 Create command...... 91 Update command...... 91 Quick-start example...... 91 Chart...... 93 Parameters...... 94 Create command...... 96 Update command...... 97 Plotting chart data...... 97 Quick-start example...... 98 Bar chart...... 99 Parameters...... 99 Create command...... 100 Update command...... 101 Quick-start example...... 101 Pie chart...... 103 Parameters...... 103 Create command...... 104 Update command...... 105 Quick-start example...... 105 Doughnut chart...... 106 Parameters...... 106 Create command...... 107 Update command...... 108 Quick-start example...... 108 List...... 109 Parameters...... 109 Create command...... 110 Update command...... 110 On item selection...... 110 Quick-start example...... 111 Spinnable list...... 112 Parameters...... 112 Create command...... 113 Update command...... 113 On item selection...... 113 Quick-start example...... 114 Pie...... 115 Parameters...... 115
9 GUI-O Team
Create command...... 116 Update command...... 116 Quick-start example...... 116 Rectangle...... 118 Parameters...... 118 Create command...... 119 Update command...... 119 Quick-start example...... 119 Triangle...... 121 Parameters...... 121 Create command...... 122 Update command...... 122 Quick-start example...... 122 Ellipse...... 124 Parameters...... 124 Create command...... 125 Update command...... 125 Quick-start example...... 125 Line...... 127 Parameters...... 127 Create command...... 128 Update command...... 128 Quick-start example...... 128 Arc...... 129 Parameters...... 129 Create command...... 130 Update command...... 130 Quick-start example...... 130 Grid...... 131 Parameters...... 131 Create command...... 132 Update command...... 132 Quick-start example...... 132 HARDWARE API...... 133 General notes...... 133 SMS handler...... 134 Parameters...... 134 Send SMS...... 134 Receive SMS...... 134 Audio player...... 136
10 GUI-O Team
Parameters...... 136 Create command...... 136 Update command...... 136 Tone player...... 137 Parameters...... 137 Create command...... 137 Update command...... 137 Activate tone player...... 137 Real-time clock (RTC)...... 138 Parameters...... 138 Create command...... 138 Update command...... 138 On real-time clock report...... 138 Position sensor (GPS)...... 140 Parameters...... 140 Create command...... 140 Update command...... 140 On position report...... 141 Vibrator...... 142 Parameters...... 142 Create command...... 142 Update command...... 142 Activate vibrator...... 142 Camera capture...... 143 Parameters...... 143 Create command...... 143 Update command...... 143 Capture image...... 144 File I/O...... 145 Parameters...... 146 Create command...... 147 Write command...... 147 Read command...... 147 Screen orientation...... 148 Parameters...... 148 Create command...... 148 Update command...... 148 Orientation change...... 149 Battery status...... 150 Parameters...... 150
11 GUI-O Team
Create command...... 150 Update command...... 150 On battery status report...... 150 Device sensors...... 152 Parameters...... 152 Create command...... 153 Update command...... 153 On sensor reading report...... 153 DEVELOPER MODE...... 154 KNOWN ISSUES...... 156 APPENDIX A...... 157 Supported USB devices...... 157 APPENDIX B...... 158 Supported application fonts...... 158 APPENDIX C...... 159 Supported date and time formats...... 159 APPENDIX D...... 161 External URL handling...... 161 APPENDIX E...... 162 Humidity and temperature monitor...... 162
12 GUI-O Team
Abbreviations
Abbreviation Explanation
GUI Graphical User Interface UI User Interface UID (uid) Unique Identifier UUID Universally Unique Identifier MCU Microcontroller Unit SMS Short Message Service I/O Input / Output USB Universal Serial Bus IoT Internet of Things SPP Serial Port Profile (Bluetooth context) LE Low Energy (Bluetooth context) USB OTG USB On-The-Go LAN Local Area Network TLS Transport Layer Security QR Quick Response (QR code context) CR Carriage return LF Line feed APP Application API Application programming interface URL Uniform Resource Locator ASCII ASCII as in character encoding standard
13 GUI-O Team
INTRODUCTION What is GUI-O application? GUI-O application enables you to create flexible, high-end GUIs (graphical user interfaces) on Android platforms using WiFi, Mobile network, Bluetooth or USB interface. No Android coding is required!
How does it work? GUI-O application is an ASCII command interpreter that uses a simple protocol to create highly customizable widgets such as toggles, sliders, dials, charts (for full list see WIDGETS OVERVIEW) with simultaneous access to the device built-in sensors and actuators (for full list see HARDWARE OVERVIEW). A typical setup involves using a microcontroller unit (MCU) to send commands to the application (and vice versa) to build a custom, interactive GUI. By stacking widgets on top of each other and fully controlling their visual properties, more complex and professional graphical user interfaces can be created. The possibilities are unlimited – what will you Connect . Create . Control?
The example in Figure 1 shows the principle of operation. GUI-O application requests initialization (@init\r\n) and in this case, the MCU responds by creating a toggle widget (|TG UID:tg1 X:50 Y:60\r\n). When the user presses the toggle, the application sends this information back to the MCU (@tg1 1\r\n), which can act accordingly by turning on the light.
Figure 1. Principle of operation using toggle widget example.
14 GUI-O Team
What does the manual contain? This manual provides all necessary information for getting started with the GUI-O application. For quick reference all available widget types and their corresponding visual examples are listed first. Note that each widget has numerous customizable properties which can be controlled through the WIDGETS API. All available hardware types which can be controlled through the HARDWARE API are listed next. In order to familiarize with the look and feel of the application, the GRAPHICAL INTERFACE OVERVIEW section explores the application’s main features. Finally, the section COMMUNICATION PROTOCOL provides detailed explanation on how to use the simple ASCII protocol to build a fully functional, responsive GUI.
15 GUI-O Team
WIDGETS OVERVIEW The following widget types are available:
Widget type Visual example
Toggle
Slider
Circular bar
Number input
Text input
Scrollable text area
16 GUI-O Team
Widget type Visual example
Calendar
Button
Label
Status indicator
Defined by the image which is loaded Image from local or online resource. Defined by the images which are loaded from local or online resource. Image Image list selection provides feedback on currently selected image. Defined by the video which is loaded from Video local or online resource.
17 GUI-O Team
Widget type Visual example
Chart: - XY chart - Time chart - Sweep chart
Bar chart
Pie chart
18 GUI-O Team
Widget type Visual example
Doughnut chart
List
Spinnable list
Pie
Rectangle
Triangle
19 GUI-O Team
Widget type Visual example
Ellipse
Line
Arc
Grid (helper widget for positioning other widgets)
All widget based types can be customized in various ways, changing their visual properties (and functional properties where applicable). See detailed description for each widget in the WIDGETS API section of this manual.
20 GUI-O Team
HARDWARE OVERVIEW The following hardware types are available1: • SMS handler • Audio player • Tone player • Real-time clock (RTC) • Position sensor (GPS) • Vibrator • Camera capture • File I/O • Screen orientation • Battery status • Device sensors: ➢ Accelerometer ➢ Altimeter ➢ Ambient light sensor ➢ Ambient temperature sensor ➢ Compass ➢ Distance sensor ➢ Gyroscope ➢ Holster sensor ➢ Humidity sensor ➢ IR Proximity sensor ➢ Lid sensor ➢ Light sensor ➢ Magnetometer ➢ Orientation sensor ➢ Pressure sensor ➢ Proximity sensor ➢ Rotation sensor ➢ Tap sensor ➢ Tilt sensor
See detailed description for each hardware type in the HARDWARE API section of this manual.
1 device must support the features by the underlying hardware
21 GUI-O Team
GRAPHICAL INTERFACE OVERVIEW Main screen Figure 2 below shows the main interface of the application. This is the default display, waiting for initialization over WiFi, Mobile network, Bluetooth or USB interface.
Figure 2. Default display when the application is opened. Open settings menu Opens the settings menu, where all application specific settings can be set. These include connection type (WiFi, Mobile network, Bluetooth, USB or connection combination), device search, IoT settings and other. See Settings menu section for more information.
Send initialize request Sends the initialization request over the currently active connection type. This request can also be automatic and depends on the user specific settings. See COMMUNICATION PROTOCOL section for more information.
22 GUI-O Team
Demo banner Visible in DEMO application mode only. The countdown timer starts when the first message is transmitted or received by the application. After the timer expires, a popup window is shown which needs to be closed by the user and the countdown timer is reset.
23 GUI-O Team
Settings menu Figure 3 below shows the root level of the opened settings menu. Menu entries that are more complex are described in the following sections.
Figure 3. Root settings menu. Quick connect Quick connect automatically stores previously connected devices and displays them in a list. This is applicable for Bluetooth devices only. If the list contains a single Bluetooth device and auto connect feature is enabled, the application will automatically try to (re)connect with the listed device. If multiple devices are available, the user is presented with a selection list.
24 GUI-O Team
Connections Connections enable switching the default connection type and controlling various aspects of the selected connection type. The following connections are available:
Bluetooth with optional IoT forwarding Connect to the application using classic Bluetooth serial port profile (SPP). Used to control local device or forward messages using IoT connection to also control remote devices (see Figure 4 below). See IoT transport protocol for more information regarding IoT.
Figure 4. Schematic representation of Bluetooth, Bluetooth LE and USB connection with optional IoT. Left side – any device with Bluetooth, Bluetooth LE or USB capabilities, Middle – local application, Right side – remote applications.
Bluetooth LE with optional IoT forwarding Connect to the application using custom Low Energy Bluetooth services, characteristics and descriptors (descriptors must support notifications). Used to control local device or forward messages using IoT connection to also control remote devices (see Figure 4). See IoT transport protocol for more information regarding IoT.
25 GUI-O Team
USB with optional IoT forwarding Connect to the application using USB OTG (On-The-Go) and FTDI capable device. Used to control local device or forward messages using IoT connection to also control remote devices (see Figure 4). See IoT transport protocol for more information regarding IoT.
Standalone IoT This puts the application in a standalone IoT mode as shown in Figure 5 below. Any external MCU with internet access that conforms to the MQTT v3.1.1 protocol can send messages to the application and receive messages from the application. Note that the code running on the MCU must implement its own MQTT protocol (see https://mqtt.org/software/ for MQTT client library implementation for various devices). See IoT transport protocol for more information regarding IoT.
Figure 5. Schematic representation of standalone IoT connection. Left side – any device with WiFi, LAN or internet access capabilities, Right side – remote applications.
26 GUI-O Team
NOTE: Regardless of the connection type used, all message payloads must conform to the application ASCII protocol, described in the COMMUNICATION PROTOCOL section. Connection to the MQTT broker in any IoT scenario supports only secure connections (TLS protocol).
Quick pair Quick pair enables pairing multiple devices into an IoT network by generating unique id tokens. The tokens are basically publish and subscribe topics that conform to the MQTT v3.1.1 protocol (see IoT transport protocol). Multiple unique publish and subscribe topics can be registered and handled within the application. This enables identification of remote IoT devices. Figure 6 below shows the contents of the 'Quick pair' menu.
Figure 6. Quick pair menu.
27 GUI-O Team
Generate QR code Create a new device and corresponding QR code for pairing with another GUI-O application. This can be used to establish a communication channel in scenarios where the following connection types are used (see Figure 4):
1. Bluetooth and IoT 2. Bluetooth LE and IoT 3. Usb and IoT
NOTE: The payload of the QR code is encoded and can only be scanned by another device running the GUI-O application.
Scan QR code Scan the QR code which was generated by Generate QR code procedure. Also scan the QR code of any created device under IoT devices menu to add / copy an existing device (and its corresponding communication channel).
Direct device pairing The main steps of the GUI-O pairing procedure are shown in Figure 7. Pairing can be performed with any device that has WiFi capabilities and can work both in "access point" mode (other WiFi devices can connect to it) and "stationary mode" (it can connect to other WiFi devices). The pairing procedure is as follows:
1. From within the GUI-O application, user selects 'Direct device pairing'. 2. User enters the device name (required) and user name (optional). 3. User is presented with Android WiFi settings, where the WiFi of the pairing device is selected. After successful connection, user returns to the GUI-O application. 4. GUI-O application starts searching for surrounding WiFi networks (excluding the WiFi of the selected pairing device). 5. User selects the preferred WiFi (with network capabilities) and inputs its password. 6. After the preferred WiFi is selected and user inputs the WiFi password, the GUI-O application sends the pairing data in .json format. The .json object key- value pairs are as follows:
{ "networkSsid": "ssid", "networkPassword": "pass",
28 GUI-O Team
"mqttHostName": "host_name", "mqttUserName": "user_name", "mqttUserPassword": "mqttPass", "subscribeTopic": "sub_topic", "publishTopic": "pub_topic" }
7. The pairing device should permanently store the data after receiving it and then return the same data in .json format. Additionally, the return data must contain another key-value pair ("pairingResponse":
{ "pairingResponse": 0, "pairingResponseDetail": "detail", "networkSsid": "ssid", "networkPassword": "pass", "mqttHostName": "host_name", "mqttUserName": "user_name", "mqttUserPassword": "mqttPass", "subscribeTopic": "sub_topic", "publishTopic": "pub_topic" }
8. Next, the pairing device should exit "access point" mode and connect to the WiFi using the network credentials (values of 'networkSsid' and 'networkPassword' keys) that the GUI-O application provided.
9. After the pairing device exits the "access point" mode, the Android device should connect to the network capable WiFi automatically (this depends on the WiFi system settings). If not, the user must manually connect to the network via WiFi or data, otherwise the GUI-O application will warn the user when IoT connection is requested.
10. Note that the GUI-O application helps the user with step-by-step information messages during the pairing procedure.
29 GUI-O Team
NOTE: the pairing procedure can be performed multiple times. It is up to the implementation on the pairing device side, how this is handled. With every successful pairing procedure, the GUI-O application will store all parameters necessary for establishing connection.
Figure 7. Direct device pairing procedure.
30 GUI-O Team
IoT devices Add, remove, share or enable / disable IoT devices. IoT devices are automatically added during Generate QR code, Scan QR code and Direct device pairing procedure. IoT devices can also be added manually. Sharing an IoT device enables embedding the communication channel into your application. This can be for example used for quickly testing your application.
NOTE: Enable or disable the device by pressing on the device name field. Only one device can be active at a time. To switch between all available IoT devices during operation, use the Quick connect menu.
31 GUI-O Team
COMMUNICATION PROTOCOL The GUI-O application uses a simple ASCII based command protocol to establish a two-way messaging system between an Android powered device and any MCU that supports Bluetooth, Bluetooth LE, USB or IoT capable interface.
A concept of key-value pairs is used to control various parameters, properties and values of the objects (i.e., widgets and hardware based types). All objects require construction and initialization before they can be used or referenced. A pseudo command to create a new object starts with a pipe character (7Chex):
|HEADER
@
Similarly, when the object returns a value or sends data, the message also begins with
'@' character (40hex):
@
For step-by-step detailed explanation regarding the messaging protocol see Getting started tutorial and sections of the manual that describe available parameters, properties and values for each individual widget and hardware based type.
IMPORTANT NOTE: All commands must be terminated with LF ("\n") or CRLF ("\r\n"); without the quotes. All responses and requests from the application are CRLF terminated.
Requests and responses This section describes important general commands that are necessary when working with the GUI-O application, such as requesting initialization or clearing the widgets from the screen.
Notation 'APP → MCU' denotes that the command originates on the GUI-O application side and is sent to the microcontroller unit. Analogously, notation 'MCU → APP' denotes that the command originates on the microcontroller unit side and is sent to the GUI-O application.
32 GUI-O Team
Initialization request Direction: APP → MCU
Trigger to request initialization from MCU (i.e., request to create widgets and hardware instances). The request can be triggered by the application:
• manually by pressing the initialization button (see Main screen)
• automatically by enabling auto connect on application startup
The application sends the following command:
@init\r\n
Clear widgets request Direction: 'MCU → APP'
Request to clear all on-screen displayed widget instances:
@cls\r\n
Clear hardware objects request Direction: 'MCU → APP'
Request to clear all created hardware instances:
@clh\r\n
Clear orientation request Direction: 'MCU → APP'
Request to clear / reset the screen orientation to default, portrait mode:
@clo\r\n
Loading screen request Direction: 'MCU → APP'
Request to show loading screen, which can be useful before changing the UI appearance:
@sls\r\n
Request to hide loading screen:
33 GUI-O Team
@hls %1\r\n where %1 represents animation duration in milliseconds.
General settings change request Direction: 'MCU → APP'
Request to change the general application behavior:
@gse COD:%1 TSC:%2\r\n
NOTE: All parameters can be set separately or together in a single request message.
If value of COD parameter (%1) is set to one (1), the widget and hardware components responses are comma delimited and space delimited if %1 is set to zero (0). Space delimited format is the default and is restored on every application start. So, in cases where comma delimited responses are required, the MCU must send this command (@gse COD:1\r\n), before performing any further interactions with the widgets and hardware components.
The TSC parameter is used to change the encapsulation of any string parameter payload. If command @gse TSC:34\r\n is requested (this is the default value), all string commands must be encapsulated in double quote (") characters for correct parsing on the APP side. For example, to set the text of the Label, the TXT parameter must have the following form: TXT:"Label text" (see Label section). The following encapsulating characters are supported:
@gse TSC:34\r\n for double quote character ("), e.g. TXT:"Label text"
@gse TSC:39\r\n for single quote character ('), e.g. TXT:'Label text'
@gse TSC:42\r\n for asterisk character (*), e.g. TXT:*Label text*
@gse TSC:126\r\n for tilde character (~), e.g. TXT:~Label text~
Note that the TSC value represents the character's decimal value.
UI settings change request Direction: 'MCU → APP'
Request to change UI basic appearance:
@guis ASR:%1 BGC:%2\r\n
34 GUI-O Team where %1 represents the requested aspect ratio and %2 the UI background color in hex format (i.e., #RRGGBB or #AARRGGBB, see Color values encoding). The parameters can be sent individually.
IMPORTANT NOTE: It is recommended to always specify the ASR value.
IMPORTANT NOTE: Correctly setting the ASR parameter is important to maintain scalability of your UI across devices with different pixel resolution and pixel density. For more information see Scalability.
Capture screen request Direction: 'MCU → APP'
Request to capture the current APP screen:
@caps\r\n
If capture is successful, the captured screen image is saved in the caps_
Request to show or hide settings menu programmatically:
@smv VIS:%1\r\n where setting %1 to zero (0) hides and setting %1 to one (1) shows the settings menu. Switch screen request Direction: 'MCU → APP'
Request to switch active UI screen:
@sci SCI:%1\r\n where %1 represents the screen index. Valid values range from zero (0) to two (2), therefore up to three (3) screens are supported. If widgets are created on multiple screens, use this command to switch between screens. For more information see Multiple screen support.
Quit application request Direction: 'MCU → APP'
35 GUI-O Team
Request to quit the GUI-O application:
@quitapp\r\n
36 GUI-O Team
IoT transport protocol The GUI-O application implements MQTT protocol v3.1.1, which uses a publish- subscribe architecture that enables secure transport of messages between multiple devices. The main MQTT advantages are:
• Lightweight and bandwidth friendly (perfect for cellular networks)
• Reliability of messages delivery
• Bi-directional communication
• Scalable to multiple (virtually unlimited number of) IoT devices
• Secure (data encryption with TLS and user / certificate authentication)
The basic principle of operation is that an arbitrary client device publishes a message with a specific topic and anyone who wants a copy of that message will subscribe to that topic. Each client device can send and receive data by publishing or subscribing to topics. The security is maintained by the broker server, which handles distribution of all published messages to the endpoint client devices. This means that the client devices do not exchange any messages directly, which in turn increases the level of security.
See http://mqtt.org/ for detailed information about the MQTT protocol. Furthermore, numerous client libraries are available and can easily be used on the MCU side. In such cases, the GUI-O application can operate in IoT standalone mode and exchange messages with the MCU(s). For further reference, see https://mqtt.org/software/.
Figure 8 explains the concept of publish-subscribe architecture more clearly. Suppose that a master and three clients ('client1', 'client2' and 'client3') are connected to the MQTT broker. The master publishes (different) data to different topics and each of the client is subscribed to the relevant topics. This means that 'client1' and 'client2' will not receive messages that are intended for 'client3' and vice versa. In turn, each of the clients publishes its own data to a specific topic to which the master is subscribed. The master can thus determine the point of origin of the received message.
37 GUI-O Team
New publish and subscribe topics are always unique and can be added in the following ways:
1) By generating a QR code (see Generate QR code)
Typical scenario is shown in Figure 4. The "master" GUI-O application is connected to a device in any of the following modes: Bluetooth and IoT, Bluetooth LE and IoT or Usb and IoT. The "master" GUI-O application generates a QR code, which is scanned by the remote GUI-O applications that work in Standalone IoT mode. The IoT communication channel is established.
2) By scanning a QR code (see Scan QR code)
Typical scenarios are shown in Figure 4 and Figure 5. The remote GUI-O application(s) work in Standalone IoT mode. Remote applications can scan the QR code generated by the "master" device or can scan any QR code that is shared via the IoT devices menu.
3) By pairing with another WiFi capable device (see Direct device pairing)
Typical scenario is shown in Figure 5. The GUI-O application works in Standalone IoT mode. Through the pairing procedure, a new communication channel is created.
4) Manually (see IoT devices)
Typical scenario is shown in Figure 5. The GUI-O application works in Standalone IoT mode. The created device must be shared and the communication channel embedded in your application.
38 GUI-O Team
Client2 Client1 Publish to: Publish to: 'sub_B' 'sub_A' Subscribe to: Subscribe to: 'pub_B' 'pub_A' Master Publish to: 'pub_A' 'pub_B' 'pub_C' 'pub_A' 'sub_A' Subscribe to: 'sub_A' 'pub_B' 'sub_B' 'pub_A' 'sub_C' 'pub_B' 'pub_C' 'sub_B'
'pub_C' 'sub_A' 'sub_B' 'sub_C' 'sub_C'
Client3 Publish to: 'sub_C' Subscribe to: 'pub_C'
Figure 8. Publish-subscribe architecture explained.
To distinguish between various clients (and to decrease the data transfer load), the GUI-O application internally implements optimized topics handling by attributing the data to a specific user. The topics generated via the QR code mechanism are universally unique identifiers (UUID2), which are 16-byte (128-bit) numbers in the following format:
• xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
During the pairing process, a user name can additionally be set, which appends it to the UUID number:
• xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/'user name'
2 More information about the UUID uniqueness can be found at https://www.rfc-editor.org/info/rfc4122
39 GUI-O Team
All characters after the first slash character ('/') are used internally by the application as a part of the GUI-O communication protocol to help distinguish between various users. See IoT users handling below.
IoT users handling Take Figure 8 as a reference and suppose a master generates a publish-subscribe QR code with a user name 'james_bond'. The new publish topic on the master device becomes:
• UUID_1/james_bond and the new subscribe topic becomes:
• UUID_2/james_bond where 'UUID_1' and 'UUID_2' represent two distinct 16-byte (128-bit) numbers. When the 'client1' scans the QR code, the new publish topic on the 'client1' device becomes:
• UUID_2/james_bond and the new subscribe topic becomes:
• UUID_1/james_bond
Please notice that the master publish and 'client1' subscribe topics are the same. Similarly, the 'client1' publish and master subscribe topics are the same. This is intended behavior, since 'client1' must be subscribed to the topic that master publishes and vice versa. The same process applies for adding new users / clients (e.g., 'client2', 'client3', etc.).
When 'client1' triggers initialization request (see Send initialize request), the following message is sent to the topic 'UUID_2/james_bond':
@init usr:james_bond\r\n
Furthermore, any message that 'client1' sends is equipped by the 'usr:james_bond' field. If 'usr' has no value, no user name was specified. NOTE: If the connection configuration is set-up as shown in Figure 4, the message is forwarded to the Bluetooth or USB interface, before finally reaching its destination on the MCU side.
When the master wants to send any message to the client(s) in configuration as shown in Figure 4, it must specify the destination (i.e., publish topic or user name) within the message payload under the "PUB" parameter. For example, if the master
40 GUI-O Team needs to clear all widgets from the 'client1' display, it should send the following message:
@cls PUB:"james_bond"\r\n or alternatively using the entire publish topic notation instead of just the user name:
@cls PUB:"UUID_1/james_bond"\r\n
If the master wants to send the same message to multiple users, the publish topics / user names in "PUB" should be delimited by a comma character (2Chex).
In case of the set-up shown in Figure 5, the implementation on the MCU master side must make sure that all outgoing messages are published to the correct topic (full name qualification, i.e., 'UUID_1/james_bond').
Please check the WIDGETS API and HARDWARE API sections for more information on how to create various widgets and hardware instances, respectively.
IMPORTANT NOTE: All messages use the highest quality of service level (i.e., QoS 2). This guarantees that each message is received only once by the intended recipients.
IoT broker We offer our own broker server for testing purposes (mqtt.gui-o.com, port 8883). The server uses TLS encryption and requires a client certificate, user name and password to authenticate. The certificate is included in the GUI-O application and the current user name and password can be found on the GUI-O website (https://www.gui- o.com) on the IoT example page.
41 GUI-O Team
QUICK START Currently, the GUI-O application does not have any external PC designer tool for generating the appropriate ASCII commands. Therefore, to get started see 'Quick-start examples' for each supported widget in the WIDGETS API section. For further reference, see also APPENDIX E, where multiple widgets are used simultaneously in order to get started with more complex, real-life applications.
42 GUI-O Team
WIDGETS API Widgets are custom GUI components that have various parameters which control their visual appearance and in some cases also their functionality.
Basic parameters such as unique identifier ("UID") and widget's relative position ("X" and "Y") are mandatory, while others are optional and are determined by the widget type. In cases where optional parameters are not specified, the default parameters are automatically supplied by the GUI-O application.
Every parameter consists of parameter header and parameter payload. The parameter header and its corresponding payload are separated by the colon character (3Ahex). Multiple parameters can be delimited by the space or comma character (20hex and 2Chex, respectively) or combination of both. For improved user readability it is advised that the delimiters usage is consistent, at least within an individual command.
General notes A NOTE ON UID PARAMETER: Each widget must be created with a unique identifier parameter ("UID"). GUI-O application does not allow multiple "UID" parameters with the same name (in such case, an error will be reported). The "UID" parameter is basically a reference to a widget; all data sent to the widget or received from the widget depends on this parameter.
Scalability For any responsive UI, it is important that the graphical elements (widgets) adjust to various screen sizes and pixel densities. The GUI-O application uses dip (device independent pixel) units as a base for sizing all widgets. Therefore, all widgets' sizes are specified in percentage (%) of effective dip screen width (DPW) and dip screen height (DPH).
To achieve scalability across various devices, the aspect ratio parameter (ASR) should be set accordingly, before creating any widgets. To set the ASR parameter, see UI settings change request. Two cases can be considered:
1. If ASR parameter is set, the effective screen size (DPWE and DPHE) is calculated from available screen size (DPW and DPH) in such a way, that the aspect ratio of
43 GUI-O Team
widgets is preserved and all widgets fit on the screen, without cropping. This is the recommended way to create widgets in order to achieve scalability over various devices.
Example: Assuming, we are developing a UI on a (reference) device with the following parameters:
▪ 1080 (W) x 1920 (H) pixels
▪ DPW = 360, DPH = 640 (note that DPW and DPH values of the current device can be retrieved from the developer mode menu - see DEVELOPER MODE) DPW 360 First, we calculate the reference ASR parameter as: ASR= = =0.5625 . DPH 640 Next, we set the ASR parameter using @guis ASR:0.5625\r\n command (see UI settings change request). Finally, we can start creating widgets. If another device is used, all widgets will be scaled considering this aspect ratio.
IMPORTANT NOTE: It is recommended to always specify the ASR value.
IMPORTANT NOTE: The ASR parameter must always be specified with respect to portrait orientation of the device, even when developing UI for landscape orientation. The GUI-O application automatically applies the correct ratio based on device orientation. See Screen orientation section for details on how to switch between various orientation modes.
2. If the ASR parameter is not set, the effective screen size (DPWE and DPHE) is the same as the available screen size (DPW and DPH) of the current device. This is NOT the recommended way to to create widgets as they will appear stretched on other devices.
Color values encoding All color values are specified in the following hex formats:
• #RRGGBB or
• #AARRGGBB where RR, GG and BB represent two digit hexadecimal number for red, green and blue color channel, respectively. Additionally, AA represents alpha channel, which can
44 GUI-O Team be used to control transparency of the set color. To preview various colors, use a third-party color generator, e.g., https://htmlcolorcodes.com.
Text (string) encoding In addition to basic ASCII character set, all widgets that display text have support for UTF-8 encoding. The GUI-O application can also parse literal unicode escape sequences (i.e., starting with \u, followed by 4 hexadecimal digits). For example, the following string "Angle \u03B1\u2080 = 22 deg" produces the following output:
Angle α0 =22deg . To preview various characters and the corresponding unicode escape sequences, see online resources, e.g., https://www.rapidtables.com/code/text/unicode-characters.html.
Parameter types In general, there are three types of parameter values:
1) string type, which is enclosed with two double quote characters (22hex) and can contain spaces (e.g., "this is a string type"). This is used for example to specify widget text and url's.
2) non-string type, which cannot contain spaces and represents values such as int, float, double, boolean. This is used to specify for example widget width, height, etc.
3) color type, which starts with the hashtag character (23hex) and cannot contain spaces (e.g., #FF00FF). This is used to specify color values of the widgets, background, etc.
Visual stacking order The stacking order of widgets is based on the order they are created. The widget created last has the highest stacking order and visually hides all widgets on layers below (unless the widget is transparent). The touch events are delivered to the widget that is on the highest layer in the visual stacking order and is able to receive touch events.
Expected response feature Widgets that enable user interaction can request explicit confirmation (i.e. acknowledge) that the user command was successfully received by the MCU. Parameters that control this are: 1) "RTO" parameter, which sets the acknowledge
45 GUI-O Team timeout in milliseconds and 2) "CRE" parameter which must be sent by the MCU with payload of value one (1) and before the acknowledge timeout expires. For example, if RTO:1000 is set, the widget expects to receive CRE:1 within 1000 milliseconds after the user interaction.
This feature is supported for specific widgets only3.
Multiple screen support The widgets can be created on up to three (3) screens, without the need to re-initialize the user interface from the MCU side. By default, all widgets are created on the base screen, unless specified otherwise. To specify on which screen the widget is created, the SCI: command should be used when creating the widget. The command SCI:0 places the widget on the base screen, the SCI:1 command on the second screen and the SCI:2 command on the third screen. The commands are also listed in the parameters table for each widget type in the following sections.
In order to transition between screens during operation, the commands from Figure 9 should be used.
@sci SCI:1\r\n @sci SCI:2\r\n Base Second Third screen screen screen
@sci SCI:0\r\n @sci SCI:1\r\n
Figure 9. Screen transition commands .
Getting started tutorial In order to reference any widget, it needs to be created (i.e. instantiated) first. Creating the widget enables one-way or two-way communication, where applicable.
Let's take a Toggle widget as an example (note that all other widgets types behave in a similar fashion). To create a Toggle widget, a minimal command is required (all parameters should be separated by space or comma character):
3 The following widgets support this feature: Toggle, Slider, Circular bar.
46 GUI-O Team
|TG UID:tg1 X:50 Y:50\r\n
In the command above, we specify:
• component identifier: |TG
• unique identifier: UID:tg1
• horizontal position in % of screen width: X:50
• vertical position in % of screen height: Y:50
• command terminator: \r\n
All other parameters are set to their corresponding default values (see Parameters for Toggle). We could also explicitly specify all other parameters using customized values within the same command. For example, to create a Toggle rotated by 45 degrees, the following command is required:
|TG UID:tg1 X:50 Y:50 ROT:45.0\r\n
Any parameter can be arbitrarily chained to the command, unless explicitly stated otherwise.
After the widget is created it can be referenced at any time by its "UID" parameter (tg1 in the example above). This implies that "UID" parameter cannot be changed once the component is created! To modify the parameters of existing Toggle widget, the following format is required:
@tg1 X:20 W:20.0 ROT:80.5 RTO:5000\r\n
In the command above, we specify:
• unique identifier, i.e., widget reference: @tg1
• change of horizontal position in % of screen width: X:20
• change in width to 20% of effective screen width (see Scalability): W:20.0
• change in rotation to 80.5 degrees: ROT:90
• set response timeout in msec on toggle state change: RTO:5000
• command terminator: \r\n
47 GUI-O Team
Some widgets such as Toggle are also "active", which means they react to user input. For example, when Toggle state changes to on user press enabled, the following status is emitted:
@tg1 1\r\n
When "RTO" parameter is set to greater than zero (0), the above command is preceded by a question mark character:
?@tg1 1\r\n
The question mark character denotes that the receiver of the status message must send a response within the time interval specified by the "RTO" parameter (see "RTO" and "CRE" under Parameters).
The following sections explain the interaction with various widgets and their parameters in more details.
48 GUI-O Team
Toggle Parameters Parameter Description Default value header TG Component identifier UID: Unique identifier. Mandatory Horizontal screen position (% screen X: parameters width). Y: Vertical screen position (% screen height). W: Width (% screen width). 18.0 H: Height (% screen height). 3.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Disabled background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Enabled background color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). HAW: Handle width (% screen width). 8.0 HAH: Handle height (% screen width). 8.0 HAR: Handle radius (% screen width). 4.0 HAP: Handle padding (% screen width). 0.0 Handle color (#AARRGGBB / #RRGGBB - HAC: #00D3D3D3 hex format). Handle image file name (with extension). The image is displayed as a handle and scaled to handle size, while preserving "qrc:///gui/graphics/ IP: aspect ratio. To unload the image, set the handle_icon.svg" value to empty string. (internal resource) Can be an external URL (see APPENDIX D). Shadow effect: SHE: 0 – Not enabled 1 1 – Enabled
49 GUI-O Team
Parameter Description Default value header Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). Enabled state: EN: 0 – Not enabled 0 1 – Enabled RAD: Border radius (% screen width). 1.5 Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Response timeout in msec. If this value is greater than zero (0), the widget expects a response within the specified timeout RTO: interval (see "CRE"). Otherwise a warning 0 notification is generated. The widget expects no response by setting the value to 0. Command received confirmation. If "RTO" value is set to greater than zero (0), this confirmation must be received within the CRE: 1 specified timeout interval. Otherwise a warning notification is generated and last toggle state is restored. Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|TG UID:tg1 X:50 Y:50\r\n
50 GUI-O Team
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@tg1 RAD:2.0 OPA:0.5\r\n
Other applicable parameters can be chained to the above command in any order.
On enabled state change When the widget state is changed to enabled, the application sends the following info:
• @tg1 1\r\n
• ?@tg1 1\r\n (response expected, see Expected response feature)
When the widget state is changed to disabled, the application sends the following info:
• @tg1 0\r\n
• ?@tg1 0\r\n (response expected, see Expected response feature)
Quick-start example |TG UID:tg1 X:50 Y:30 W:20 H:3 ROT:0 SHE:1 BGC:#121212 FGC:#6D9DC5 EN:0 RAD:2
51 GUI-O Team
@tg1 0 @tg1 1
|TG UID:tg1 X:50 Y:30 W:20 H:3 ROT:0 SHE:1 BGC:#121212 FGC:#990000 EN:1 RAD:2
52 GUI-O Team
Slider Parameters Parameter Description Default value header SL Component identifier UID: Unique identifier. Mandatory Horizontal screen position (% screen X: parameters width). Y: Vertical screen position (% screen height). W: Width (% screen width). 60.0 H: Height (% screen height). 2.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Slider unfilled background color BGC: #4C4C4C (#AARRGGBB / #RRGGBB - hex format). Slider filled background color FGC: #6D9DC5 (#AARRGGBB / #RRGGBB - hex format). Slider filled secondary background color (#AARRGGBB / #RRGGBB - hex format). SFGC: The color is linearly interpolated between #6D9DC5 FGC and SFGC, creating a linear gradient effect. HAW: Handle width (% screen width). 8.0 HAH: Handle height (% screen width). 8.0 HAR: Handle radius (% screen width). 4.0 Handle color (#AARRGGBB / #RRGGBB - HAC: #00D3D3D3 hex format).
53 GUI-O Team
Parameter Description Default value header Handle image file name (with extension). The image is displayed as a handle and scaled to handle size, while preserving "qrc:///gui/graphics/ IP: aspect ratio. To unload the image, set the handle_icon.svg" value to empty string. (internal resource) Can be an external URL (see APPENDIX D). Shadow effect: SHE: 0 – Not enabled 1 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). VAL: Value between LVAL and HVAL. 0.0 LVAL: Minimum value. 0.0 HVAL: Maximum value. 100.0 Update rule: UD: 0 – Send update on control release 0 1 – Send update on value change RAD: Border radius (% screen width). 1.0 Show handle: SHH: 0 – Hidden 1 1 – Shown Control enabled: CE: 0 – Disabled 1 1 – Enabled Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen
54 GUI-O Team
Parameter Description Default value header Response timeout in msec. If this value is greater than zero (0), the widget expects a response within the specified timeout RTO: interval (see "CRE"). Otherwise a warning 0 notification is generated. The widget expects no response by setting the value to 0. Command received confirmation. If "RTO" value is set to greater than zero (0), this confirmation must be received within the CRE: 1 specified timeout interval. Otherwise a warning notification is generated and last value is restored. Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|SL UID:sl1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@sl1 LVAL:20.0 HVAL:120.0\r\n
Other applicable parameters can be chained to the above command in any order.
On value change When the widget value is changed, the application sends the following info:
• @sl1 20.0\r\n
55 GUI-O Team
• ?@sl1 20.0\r\n (response expected, see Expected response feature)
Quick-start example |SL UID:sl2 X:50 Y:50 W:60 H:2.5 ROT:0 SHE:1 BGC:#121212 FGC:#6D9DC5 RAD:1.5 VAL:25 LVAL:1 HVAL:100 UD:0
@sl2 80
56 GUI-O Team
Circular bar Parameters Parameter Description Default value header CB Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 40.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Secondary foreground color (#AARRGGBB / #RRGGBB - hex format). The color is SFGC: #6D9DC5 conically interpolated between FGC and SFGC, creating a conical gradient effect. HAW: Handle width (% screen width). 6.0 HAH: Handle height (% screen width). 6.0 HAR: Handle radius (% screen width). 3.0 Handle color (#AARRGGBB / #RRGGBB - HAC: #00D3D3D3 hex format). Handle image file name (with extension). The image is displayed as a handle and scaled to handle size, while preserving "qrc:///gui/graphics/ IP: aspect ratio. To unload the image, set the handle_icon.svg" value to empty string. (internal resource) Can be an external URL (see APPENDIX D).
57 GUI-O Team
Parameter Description Default value header Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). VAL: Value between LVAL and HVAL. 0.0 LVAL: Minimum value. 0.0 HVAL: Maximum value. 100.0 Update rule: UD: 0 – Send update on control release 0 1 – Send update on value change FSZ: Font pixel height (% screen height). 2.0 Font family (see APPENDIX B for fonts FFA: "font0" support). BTH: Bar thickness (% screen width). 3.5 Text and ticks color (#AARRGGBB / TXTC: #6D9DC5 #RRGGBB in hex format). XTC: Number of major ticks. 10 YTC: Number of minor ticks. 5 Start angle (degrees from 3'o clock). If STA: value is greater than end angle, the 215 direction is CW, else CCW. End angle (degrees from 3'o clock). If ENA: value is greater than start angle, the -35 direction is CCW, else CW. Needle visibility: SHN: 0 – Not visible 0 1 – Visible Needle / ticks color (#AARRGGBB / NC: #6D9DC5 #RRGGBB in hex format). NT: Needle thickness (% screen width). 0.3 Endings: RCA: 0 – Flat 1 1 – Rounded
58 GUI-O Team
Parameter Description Default value header Control enabled: CE: 0 – Not enabled 1 1 – Enabled Ticks visibility: SHT: 0 – Not visible 0 1 – Visible Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Response timeout in msec. If this value is greater than zero (0), the widget expects a response within the specified timeout RTO: interval (see "CRE"). Otherwise a warning 0 notification is generated. The widget expects no response by setting the value to 0. Command received confirmation. If "RTO" value is set to greater than zero (0), this confirmation must be received within the CRE: 1 specified timeout interval. Otherwise a warning notification is generated and last value is restored. Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|CB UID:cb1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
59 GUI-O Team
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@cb1 XTC:5 SHN:1\r\n
Other applicable parameters can be chained to the above command in any order.
On value change When the widget value is changed, the application sends the following info:
• @cb1 20.5\r\n
• ?@cb1 20.5\r\n (response expected, see Expected response feature)
Quick-start example |CB UID:cb1 X:50 Y:62 W:45 ROT:0 SHE:1 BGC:#121212 FGC:#6D9DC5 VAL:75 RCA:1 LVAL:0 HVAL:200 STA:225 ENA:-45 BTH:6 SHN:0 NC:#000000 NT:0.3 HAW:2 HAH:2 CE:0 SHT:1 TXTC:#000000 XTC:5 YTC:4 FSZ:1.2 UD:0
|CB UID:cb2 X:50 Y:62 W:45 ROT:0 SHE:1 BGC:#121212 FGC:#990000 VAL:75 RCA:1 LVAL:0 HVAL:200 STA:225 ENA:-45 BTH:6 SHN:1 NC:#000000 NT:0.3 HAW:2 HAH:2 CE:1 SHT:1 TXTC:#000000 XTC:5 YTC:4 FSZ:1.2 UD:0
60 GUI-O Team
@cb2 157.5
61 GUI-O Team
Number input NOTE: This widget allows only input of valid numbers.
Parameters Parameter Description Default value header NI Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 20.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). VAL: Value. 0.0 FSZ: Font pixel height (% screen height). 3.0 Font family (see APPENDIX B for fonts FFA: "font0" support). RAD: Border radius (% screen width). 0.0 BTH: Border thickness (% screen width). 0.3
62 GUI-O Team
Parameter Description Default value header Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|NI UID:ni1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@ni1 FFA:"font1"\r\n
Other applicable parameters can be chained to the above command in any order.
On input change When the widget input is changed, the application sends the following info (assuming number '15' is entered):
• @ni1 15\r\n
Quick-start example |NI UID:ni1 X:50 Y:38 W:80 VIS:1 ROT:0 BGC:#6D9DC5 FGC:#121212 SHE:1 FSZ:3 FFA:"font0" RAD:1 BTH:0.2 VAL:0
63 GUI-O Team
@ni1 12345
64 GUI-O Team
Text input Parameters Parameter Description Default value header TI Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 30.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). FSZ: Font pixel height (% screen height). 2.5 Font family (see APPENDIX B for fonts FFA: "font0" support). RAD: Border radius (% screen width). 0.0 BTH: Border thickness (% screen width). 0.3
TXT: Text (UTF-8 unicode support via \u empty string escape sequence, i.e. \u03B1 for α).
65 GUI-O Team
Parameter Description Default value header Text mode (0 – normal, 1 – password, 2 – TXTM: 0 no echo, 3 – password echo while editing). Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|TI UID:ti1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@ti1 FFA:"font1"\r\n
Other applicable parameters can be chained to the above command in any order.
On input change When the widget input is changed, the application sends the following info (assuming string "GUI-O rules" is entered):
• @ti1 GUI-O rules\r\n
Quick-start example |TI UID:ti1 X:50 Y:38 ROT:0 W:80 VIS:1 BGC:#6D9DC5 FGC:#121212 SHE:1 FSZ:3 RAD:1 BTH:0.2 TXTM:0 TXT:"Input TEXT"
66 GUI-O Team
@ti1 Text entered
67 GUI-O Team
Scrollable text area NOTE: This widget can be scrolled horizontally and vertically. Adding new text causes the cursor to jump into a new line.
Parameters Parameter Description Default value header TA Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 50.0 H: Height (% screen height). 30.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). FSZ: Font pixel height (% screen height). 2.5 Font family (see APPENDIX B for fonts FFA: "font0" support).
68 GUI-O Team
Parameter Description Default value header Text (UTF-8 unicode support via \u TXT: "" escape sequence, i.e. \u03B1 for α). Max line count size. When the max line count limit is reached, the oldest line gets BSZ: 500 discarded. This parameter can be changed dynamically. Clear all history: CL: 0 – No change 0 1 – Clear Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|TA UID:ta1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@ta1 TXT:"GUI-O rules" BSZ:100\r\n
Other applicable parameters can be chained to the above command in any order.
69 GUI-O Team
Quick-start example |TA UID:ta1 X:50 Y:50 W:80 H:40 VIS:1 BGC:#121212 FGC:#6D9DC5 SHE:1 FSZ:2.5 RAD:1.5 BSZ:250 CL:1
@ta1 TXT:"Text-1" @ta1 TXT:"Text-2" @ta1 TXT:"Text-3" @ta1 TXT:" ." @ta1 TXT:" ." @ta1 TXT:" ."
70 GUI-O Team
Calendar Parameters Parameter Description Default value header CA Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 70.0 H: Height (% screen height). 30.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: 0.0 – Transparent 1.0 – Opaque OPA: 1.0 The opacity change is animated. You can use this to hide the widget after the user selects the date. ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). FSZ: Font pixel height (% screen height). 3.0 Font family (see APPENDIX B for fonts FFA: "font0" support). BTH: Border thickness (% screen width). 0.3
71 GUI-O Team
Parameter Description Default value header
Date in yyyy-MM-dd format. For example, to set the calendar date to 14 Aug, 2021, DAT: the following string should be sent: 2021- empty string 08-14. To set the date to current date, an empty string should be sent (i.e., ""). Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|CA UID:ca1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator. By default, the current date is selected when the widget is created.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter (the DAT parameter sets the requested calendar date - if DAT parameter is an empty string, the current date as reported by the device, is selected):
@ca DAT:"2021-08-14" FFA:"font1"\r\n
Other applicable parameters can be chained to the above command in any order.
On input change When the widget date changes (by user interaction), the application sends the following info (assuming the user selects 14 Aug 2021):
• @ca 2021-08-14\r\n
72 GUI-O Team
Quick-start example |CA UID:ca1 X:50 Y:50 W:70 H:30 VIS:1 ROT:0 BGC:#4C4C4C FGC:#6D9DC5 SHE:1 BTH:0.3
73 GUI-O Team
Button Parameters Parameter Description Default value header BT Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 25.0 H: Height (% screen height). 5.0 Height is width. If this is enabled, width is used for height, which enables drawing a HIW: square button. 0 0 – Disabled 1 – Enabled Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Secondary background color (#AARRGGBB / #RRGGBB - hex format). SBGC: The color is linearly interpolated between #4C4C4C BGC and SBGC, creating a linear gradient effect. Linear gradient direction: LOR: 0 – Horizontal 0 1 – Vertical Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled
74 GUI-O Team
Parameter Description Default value header Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). Font pixel height (% screen height). Font FSZ: automatically scales to fit within width 2.5 and height if too large. Font family (see APPENDIX B for fonts FFA: "font0" support). Text with support for: UTF-8 unicode using escape sequence (e.g. \u0026) Basic html - bold - italic TXT: "Button"
- new line
- paragraph - underlined text , where \u0022 is unicode for double quotes. RAD: Border radius (% screen width). 1.0 BTH: Border thickness (% screen width). 0.25 SVAL: Text string sent on button press. "Button" Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
75 GUI-O Team
|BT UID:bt1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@bt1 RAD:2.0 BTH:1.0\r\n
Other applicable parameters can be chained to the above command in any order.
On pressed When the widget is pressed, the application sends the following info (based on set "SVAL" parameter value):
• @bt1 Button\r\n
Quick-start example |BT UID:bt1 X:50 Y:50 W:20 H:7 VIS:1 ROT:0 RAD:1 BGC:#121212 FGC:#6D9DC5 SHE:1 BTH:0.5 TXT:"" SVAL:"Button pressed"
@bt1 Button pressed
76 GUI-O Team
Label Parameters Parameter Description Default value header LB Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). Width (% screen width). If width is set to zero (0), the width of the text is determined by the length of the W: text itself. 0.0 If width is greater than zero (0), the text is truncated at the end if its length is greater than the set width. Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / #00000000 BGC: #RRGGBB - hex format). Only shown (transparent) when width is greater than zero (0). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). FSZ: Font pixel height (% screen height). 2.5
77 GUI-O Team
Parameter Description Default value header Font family (see APPENDIX B for fonts FFA: "font0" support). Text with support for: UTF-8 unicode using escape sequence (e.g. \u0026) Basic html - bold - italic TXT: "Label"
- new line
- paragraph - underlined text , where \u0022 is unicode for double quotes. Treat text as url link: URL: 0 – Not enabled 0 1 – Enabled Alignment with respect to the "X" and "Y" screen position parameter: ALP: 0 – Center 0 1 – Align left 2 – Align right Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|LB UID:lb1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
78 GUI-O Team
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@lb1 TXT:"GUI-O rules"\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |LB UID:lb1x X:50 Y:30 ROT:0 VIS:1 SHE:1 BGC:#121212 FGC:#6D9DC5 FSZ:4 FFA:"font1" TXT:"GUI-O Example"
|LB UID:lb21 X:10 Y:50 ROT:0 SHE:1 BGC:#121212 FGC:#6D9DC5 FSZ:3 URL:1 ALP:1 FFA:"font0" TXT:"http://www.gui-o.com/"
79 GUI-O Team
80 GUI-O Team
Status indicator Parameters Parameter Description Default value header SI Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width) parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 10.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Disabled color (#AARRGGBB / #RRGGBB - BGC: #4C4C4C hex format). Enabled color (#AARRGGBB / #RRGGBB - FGC: #6D9DC5 hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). Enabled state: EN: 0 – Not enabled 0 1 – Enabled Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen PUB: Comma delimited publish topics for not set
81 GUI-O Team
Parameter Description Default value header remote devices. If this parameter is set, the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|SI UID:si1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@si1 EN:1 FGC:#00FF00\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |SI UID:si1 X:50 Y:50.5 W:10 VIS:1 SHE:1 BGC:#121212 FGC:#6D9DC5 EN:1
82 GUI-O Team
Image NOTE: This widget also supports loading and playing animated images (GIF files). Note that by default the animation does not play automatically. Use PLS parameter to automatically start animation when the image is created.
Parameters Parameter Description Default value header IM Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 50.0 H: Height (% screen height). 30.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). Image file name (with extension). IP: Can be an external URL (see APPENDIX not set D). Playing state for animated images: 0 – Stop PLS: 0 1 – Play 2 – Pause
83 GUI-O Team
Parameter Description Default value header Scale mode: 0 – Auto 1 – Stretch SCM: 2 2 – Preserve aspect fit 3 – Preserve aspect crop 4 – No scale (original size) Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|IM UID:im1 X:50 Y:50 IP:"
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@im1 SCM:4\r\n
Other applicable parameters can be chained to the above command in any order.
On user interaction When the widget is pressed, the application sends the following info:
• @im1 1\r\n
When the widget is long pressed, the application sends the following info:
• @im1 2\r\n
84 GUI-O Team
Quick-start example Loading as a local resource: |IM UID:imx X:50 Y:50 W:60 H:60 ROT:0 SHE:0 VIS:1 OPA:1 SCM:2 IP:"airplane.png"
Loading as a web or local resource: |IM UID:imx X:50 Y:50 W:60 H:60 ROT:0 SHE:0 VIS:1 OPA:1 SCM:2 IP:"https://homepages.cae.wisc.edu/~ece533/images/airplane.png"
NOTE: please check that URL image path exists!
85 GUI-O Team
Image list NOTE: This widget supports scrolling through series of images and provides feedback on currently selected image.
Parameters Parameter Description Default value header IML Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 60.0 H: Height (% screen height). 20.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Page indicator handle width (% screen width). This is the width of a single indicator. Page indicator shows the HAW: 2.0 number of images in a list and the currently selected image. Set value to zero (0.0) to hide. Page indicator handle color HAC: #6D9DC5 (#AARRGGBB / #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format).
86 GUI-O Team
Parameter Description Default value header Comma delimited image file names (with extension). IPS: not set Can be a list of external URLs (see APPENDIX D). List index; this positions the selected item LI: in the center view. The items in the list are 0 indexed from 0 to listSize-1. Scroll direction: LOR: 0 – Horizontal scrolling 0 1 – Vertical scrolling Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|IML UID:iml1 X:50 Y:50 IPS:"
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@iml1 LOR:1\r\n
Other applicable parameters can be chained to the above command in any order.
On scrolling finished When the image is selected, i.e., scrolling is finished (movement stops), the application sends the following info:
87 GUI-O Team
• @iml1
On user interaction When the widget is pressed, the application sends the following info:
• @iml1
When the widget is long pressed, the application sends the following info:
• @iml1
Quick-start example Loading as a local resource (page indicator hidden using HAW:0 command): |IML UID:iml X:50 Y:50 W:60 H:30 ROT:0 HAW:0 SHE:0 VIS:1 OPA:1 IPS:"airplane.png,arctichare.png,baboon.png,frymire.png,monarch.pn g"
Loading as a web or local resource (page indicator hidden using HAW:0 command): |IML UID:iml X:50 Y:50 W:60 H:30 ROT:0 HAW:0 SHE:0 VIS:1 OPA:1 IPS:"https://homepages.cae.wisc.edu/~ece533/images/airplane.png,ht tps://homepages.cae.wisc.edu/~ece533/images/ arctichare.png,https://homepages.cae.wisc.edu/~ece533/images/ baboon.png,https://homepages.cae.wisc.edu/~ece533/images/ frymire.png,https://homepages.cae.wisc.edu/~ece533/images/ monarch.png"
88 GUI-O Team
@iml 0 @iml 2
NOTE: please check that all URL image paths exist!
89 GUI-O Team
Video Parameters Parameter Description Default value header VI Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 50.0 H: Height (% screen height). 30.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). Video file name (with extension). VP: Can be an external URL (see APPENDIX not set D). Playing state: 0 – Stop PLS: 1 1 – Play 2 – Pause Volume, relative to the Android media VOL: 1.0 volume (0.0 – 1.0).
90 GUI-O Team
Parameter Description Default value header Scale mode: 0 – Auto 1 – Stretch SCM: 2 2 – Preserve aspect fit 3 – Preserve aspect crop 4 – No scale (original size) Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|VI UID:vi1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@vi1 PLS:2 VOL:1.0\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example Loading as a local resource: |VI UID:vi1 X:50 Y:50 W:80 H:80 VIS:1 OPA:1 ROT:0 SHE:1 VP:"Video1.mp4" PLS:1 VOL:0.2 SCM:0
91 GUI-O Team
92 GUI-O Team
Chart The following chart types are supported:
1. XY chart
XY chart type plots the points as Pi(xi, yi), where xi and yi are the specified arbitrary coordinates on X and Y axis, respectively.
2. Time chart
Time chart type plots the points as Pi(ti, yi), where yi is the specified arbitrary
coordinate in Y direction. The X coordinate (ti) is time-based and reflects the
date / time of the received yi value. The date / time display format can be specified using the "CDTF" parameter.
3. Sweep chart
Sweep chart type plots the points as Pi(i, yi), where yi is the specified arbitrary coordinate in Y direction. The X coordinate ranges from i = 0 ... BSZ - 1, where "BSZ" is the specified buffer size (see Parameters). The sweep chart resolution (res) is therefore defined by "BSZ", "XLO" and "XHI" parameters as follows:
res = (XHI - XLO) / BSZ
For example, if XLO = 0, XHI = 30, BSZ = 300, the resolution is equal to 0.1. This means that the plot value in X direction is increased by 0.1, before a new point is plotted.
NOTES: After the chart is created using a specified type (XY, Time or Sweep chart), its type cannot be changed. All chart types use auto scaling, when necessary. Any chart type can be zoomed interactively via the "pinch-zoom" gesture. See parameter "PZO" for further details.
93 GUI-O Team
Parameters Parameter Description Default value header CH Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 70.0 H: Height (% screen height). 20.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #FFFFFF #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled SHHR: Shadow horizontal offset (% screen width) 0.5 SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). FSZ: Font pixel height (% screen height). 1.0 FFA: Font family. "font0" RAD: Border radius (% screen width). 0.5 BTH: Border thickness (% screen width). 0.3 Chart type: 0 – Time chart CHT: 0 1 – XY chart 2 – Sweep chart Chart date time format. CDTF: HH:mm:ss Available for time chart only.
94 GUI-O Team
Parameter Description Default value header Buffer size. When the buffer limit is reached, the oldest points get discarded. BSZ: 512 This parameter can only be set upon component creation. Buffer margin for sweep chart drawing. This value is multiplied with "BSZ" parameter and determines the number of oldest points that are discarded and not BMA: plotted when chart redraws (e.g. value of 0.1 0.1 discards 10% of oldest points when redrawing). Valid value range is: 0.05 – 0.5. Available for sweep chart only. CHN: Chart title. empty string AT: Axes thickness (% screen width). 0.1 LT: Line thickness (% screen width). 0.25 XTC: Number of major ticks. 5 YTC: Number of minor ticks. 5 Horizontal margin, i.e. border – axis XMA: 5.0 margin (% screen width). Vertical margin, i.e. border – axis margin YMA: 3.5 (% screen height). XLO: Initial X axis minimum value . 0.0 XHI: Initial X axis maximum value . 10.0 YLO: Initial Y axis minimum value. 0.0 YHI: Initial Y axis maximum value. 10.0 Show zero axis: 0 – Hidden SHZA: 0 1 – Shown Not available for time chart. Show zero labels: 0 – Hidden SHZL: 0 1 – Shown Not available for time chart. Show value labels (applicable for last value only): SHVL: 1 0 – Hidden 1 – Shown
95 GUI-O Team
Parameter Description Default value header Value label (fixed) precision, i.e., number VLP: 0 of decimal places for value labels. Show grid: SHG: 0 – Hidden 1 1 – Shown DRA: Fill area below chart plot. 1 Fill area transparency. Any value between: DRAT: 0.0 – Transparent 0.25 1.0 – Opaque Pinch zoom: 0 – Disabled 1 – Enabled Allows zooming in / out via two finger PZO: pinch gesture. Scaling is limited between 0 50% and 200% of original size. On disabled, the scaling is reset to default. NOTE: quick double press on the chart also resets the scaling to default. Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|CH UID:ch1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
96 GUI-O Team
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@ch1 DRA:0 SHG:0 CHN:"GUI-O chart"\r\n
Other applicable parameters can be chained to the above command in any order.
Plotting chart data Parameter Description Default value header X point coordinate(s). XP: For Time or Sweep chart type this Mandatory parameter can be omitted. parameters YP: Y point coordinate(s). PLI: Plot identifier(s). id0 Plot color(s) (#AARRGGBB / #RRGGBB - PLC: #000000 hex format). Clear plot: CL: 0 – No change 0 1 – Clear Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
NOTE: Multiple plots can be drawn onto a single chart. In such cases, all point values should be specified within a single command (this also optimizes the drawing routine). For example, assuming that the current chart "UID" is 'ch1', the following command will plot two points, under different plot id's on the same chart:
@ch1 PLI:"id0,id1" PLC:"#ff0000,#0000ff" XP:"0.0,0.0" YP:"10.3,20.4"\r\n
The parameters are combined based on the order they are specified. Therefore, the command will plot to: • id0 using color #ff0000, point(0.0,10.3) • id1 using color #0000ff, point(0.0,20.4)
97 GUI-O Team
NOTE: Currently, each draw command must always specify the 'XP' parameter, even when it is not used (in case of time chart and sweep chart).
Quick-start example |SORI UID:sori1 HID:sori ORI:2 SEN:1
|CH UID:pl1 X:62 Y:55 W:70 H:80 VIS:1 OPA:1 BGC:#454546 FGC:#FFFFFF CHT:0 SHE:1 FSZ:1.2 CHN:"Chart GUI-O" RAD:1 BTH:0.1 AT:0.1 LT:0.5 XTC:5 YTC:10 XMA:5 YMA:5 YLO:-106 YHI:-55 SHG:1 DRAT:0.15
@pl1 PLI:"pl0,pl1,pl2,pl3,pl4" PLC:"#990000,#F7DC6F,#82E0AA,#5DADE2,#BB8FCE" YP:"-55,-60,-65,-70,-73" XP:"0,0,0,0,0" @pl1 PLI:"pl0,pl1,pl2,pl3,pl4" PLC:"#990000,#F7DC6F,#82E0AA,#5DADE2,#BB8FCE" YP:"-45,-58,-60,-65,-74" XP:"0,0,0,0,0" @pl1 PLI:"pl0,pl1,pl2,pl3,pl4" PLC:"#990000,#F7DC6F,#82E0AA,#5DADE2,#BB8FCE" YP:"-48,-55,-62,-64,-76" XP:"0,0,0,0,0" @pl1 PLI:"pl0,pl1,pl2,pl3,pl4" PLC:"#990000,#F7DC6F,#82E0AA,#5DADE2,#BB8FCE" YP:"-52,-54,-65,-66,-74" XP:"0,0,0,0,0" @pl1 PLI:"pl0,pl1,pl2,pl3,pl4" PLC:"#990000,#F7DC6F,#82E0AA,#5DADE2,#BB8FCE" YP:"-55,-58,-60,-68,-70" XP:"0,0,0,0,0" @pl1 PLI:"pl0,pl1,pl2,pl3,pl4" PLC:"#990000,#F7DC6F,#82E0AA,#5DADE2,#BB8FCE" YP:"-51,-60,-62,-66,-68" XP:"0,0,0,0,0" @pl1 PLI:"pl0,pl1,pl2,pl3,pl4" PLC:"#990000,#F7DC6F,#82E0AA,#5DADE2,#BB8FCE" YP:"-55,-57,-64,-67,-66" XP:"0,0,0,0,0" @pl1 PLI:"pl0,pl1,pl2,pl3,pl4" PLC:"#990000,#F7DC6F,#82E0AA,#5DADE2,#BB8FCE" YP:"-58,-56,-66,-65,-60" XP:"0,0,0,0,0" @pl1 PLI:"pl0,pl1,pl2,pl3,pl4" PLC:"#990000,#F7DC6F,#82E0AA,#5DADE2,#BB8FCE" YP:"-52,-54,-64,-69,-58" XP:"0,0,0,0,0" @pl1 PLI:"pl0,pl1,pl2,pl3,pl4" PLC:"#990000,#F7DC6F,#82E0AA,#5DADE2,#BB8FCE" YP:"-50,-52,-65,-63,-55" XP:"0,0,0,0,0"
98 GUI-O Team
Bar chart NOTE: The parameters "MCHV" and "MCHL" can only be set when creating the widget. In order to change the aforementioned parameters, the widget must be cleared and re-created (to clear widget(s), see Clear widgets request).
Parameters Parameter Description Default value header MBCH Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 70.0 H: Height (% screen height). 20.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #FFFFFF #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). FSZ: Font pixel height (% screen height). 1.0 Font family (see APPENDIX B for fonts FFA: "font0" support).
99 GUI-O Team
Parameter Description Default value header RAD: Border radius (% screen width). 0.5 BTH: Border thickness (% screen width). 0.3 Plot color (#AARRGGBB / #RRGGBB - hex PLCO: #4C4C4C format). AT: Axes thickness (% screen width). 0.1 Horizontal margin, i.e. border – axis XMA: 4.0 margin (% screen width). Vertical margin, i.e. border – axis margin YMA: 3.0 (% screen height). Show grid: SHG: 0 – Hidden 1 1 – Shown "1.0, 4.0, MCHV: Comma separated data values. 9.0, 16.0, 25.0" "bar0, bar1, MCHL: Comma separated data labels. bar2, bar3, bar4" Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires the following parameters:
|MBCH UID:mbch1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
100 GUI-O Team
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@mbch1 FFA:"font1" FSZ:2.5\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |MBCH UID:mbch1 X:50 Y:50 W:70 H:30 OPA:1 ROT:0 SHE:1 VIS:1 FSZ:1.2 BGC:#121212 FGC:#6D9DC5 BTH:0.5 AT:0.1 XMA:7 YMA:7 SHG:1 MCHV:"1.0,4.0,9.0,16.0,25.0" MCHL:"bar1,bar2,bar3,bar4,bar5"
|MBCH UID:mbch1 X:50 Y:50 MCHV:"1.0,4.0,9.0,16.0,25.0" MCHL:"10,20,30,40,50"
101 GUI-O Team
102 GUI-O Team
Pie chart NOTE: The parameters "MCHV", "MCHL" and "MCHC" can only be set when creating the widget. In order to change the aforementioned parameters, the widget must be cleared and re-created (to clear widget(s), see Clear widgets request).
Parameters Parameter Description Default value header MPCH Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 70.0 H: Height (% screen height). 20.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #FFFFFF #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). RAD: Border radius (% screen width). 0.5 BTH: Border thickness (% screen width). 0.3
103 GUI-O Team
Parameter Description Default value header Horizontal margin, i.e. border – axis XMA: 4.0 margin (% screen width). Vertical margin, i.e. border – axis margin YMA: 3.0 (% screen height). "1.0, 4.0, MCHV: Comma separated data values. 9.0, 16.0, 25.0" "point0, point1, MCHL: Comma separated data labels. point2, point3, point4" "#C0BDA5, #CC978E, MCHC: Comma separated color values. #6D9DC5, #FF3864, #261447" Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|MPCH UID:mpch1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
104 GUI-O Team
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@mpch1 RAD:1.0\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |MPCH UID:mpch1 X:50 Y:50 W:80 H:40 OPA:1 ROT:0 SHE:1 VIS:1 BGC:#121212 FGC:#6D9DC5 BTH:0.1 XMA:5 YMA:5 MCHV:"28.0,4.0,9.0,26.0,25.0" MCHL:"Pie1,Pie2,Pie3,Pie4,Pie5" MCHC:"#990000,#F7DC6F,#82E0AA,#6D9DC5,#BB8FCE"
105 GUI-O Team
Doughnut chart NOTE: The parameters "MCHV", "MCHL" and "MCHC" can only be set when creating the widget. In order to change the aforementioned parameters, the widget must be cleared and re-created (to clear widget(s), see Clear widgets request).
Parameters Parameter Description Default value header MDCH Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 70.0 H: Height (% screen height). 20.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #FFFFFF #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). RAD: Border radius (% screen width). 0.5 BTH: Border thickness (% screen width). 0.3
106 GUI-O Team
Parameter Description Default value header Horizontal margin, i.e. border – axis XMA: 4.0 margin (% screen width). Vertical margin, i.e. border – axis margin YMA: 3.0 (% screen height). "1.0, 4.0, MCHV: Comma separated data values. 9.0, 16.0, 25.0" "point0, point1, MCHL: Comma separated data labels. point2, point3, point4" "#C0BDA5, #CC978E, MCHC: Comma separated color values. #6D9DC5, #FF3864, #261447" Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|MDCH UID:mdch1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
107 GUI-O Team
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@mdch1 RAD:1.0\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |MDCH UID:mdch1 X:50 Y:50 W:80 H:40 OPA:1 ROT:0 SHE:1 VIS:1 BGC:#121212 FGC:#6D9DC5 BTH:0.5 XMA:5 YMA:5 MCHV:"27.0,18.0,18.0,35.0,11.0" MCHL:"Pie1,Pie2,Pie3,Pie4,Pie5" MCHC:"#990000,#F7DC6F,#82E0AA,#6D9DC5,#BB8FCE"
108 GUI-O Team
List Parameters Parameter Description Default value header LST Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 50.0 H: Height (% screen height). 10.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). FSZ: Font pixel height (% screen height). 3.0 Font family (see APPENDIX B for fonts FFA: "font0" support). "item0, item1, item2, DAL: Data values. item3, item4, item5"
109 GUI-O Team
Parameter Description Default value header List index; this positions the selected item LI: in the center view. The items in the list are 0 indexed from 0 to listSize-1. Scroll direction: LOR: 0 – Horizontal scrolling 0 1 – Vertical scrolling Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|LST UID:lst1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@lst1 DAL:"p1,p2,p3,p4,p5,p6"\r\n
Other applicable parameters can be chained to the above command in any order.
On item selection When the widget item "p1" is selected, the application sends the following info:
• @lst1 p1\r\n
110 GUI-O Team
Quick-start example |LST UID:lst1 X:50 Y:50 W:50 H:10 OPA:1 ROT:0 SHE:1 VIS:1 FGC:#6D9DC5 FSZ:3 FFA:"font0" DAL:"item0,item1,item2,item3,item4,item5"
111 GUI-O Team
Spinnable list Parameters Parameter Description Default value header TU Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 15.0 H: Height (% screen height). 15.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). FSZ: Font pixel height (% screen height). 3.0 Font family (see APPENDIX B for fonts FFA: "font0" support).
112 GUI-O Team
Parameter Description Default value header "0, 1, 2, DAL: Data values. 3, 4, 5" List index; this positions the selected item LI: in the center view. The items in the list are 0 indexed from 0 to listSize-1. Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|TU UID:tu1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@tu1 DAL:"p1,p2,p3,p4,p5,p6"\r\n
Other applicable parameters can be chained to the above command in any order.
On item selection When the widget item "p1" is selected, the application sends the following info:
• @tu1 p1\r\n
113 GUI-O Team
Quick-start example |TU UID:tu1 X:50 Y:50 W:40 H:20 OPA:1 ROT:0 SHE:1 VIS:1 BTH:0.5 BGC:#121212 FGC:#6D9DC5 FSZ:2 FFA:"font1" DAL:"0,10,20,30,40,50,60,70,80,90"
@tu1 60
114 GUI-O Team
Pie Parameters Parameter Description Default value header PI Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 40.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width) 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). BTH: Border thickness (% screen width). 0.25 Start angle (degrees from 3'o clock). Value STA: 0 must be less than End angle. End angle (degrees from 3'o clock). Value ENA: 45 must be more than Start angle.
115 GUI-O Team
Parameter Description Default value header Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|PI UID:pi1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@pi1 STA:25 ENA:95\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |PI UID:pi1 X:50 Y:50 W:70 VIS:1 ROT:0 BGC:#990000 FGC:#A3A3A3 SHE:1 BTH:0.1 STA:0 ENA:45 |PI UID:pi2 X:50 Y:50 W:70 VIS:1 ROT:0 BGC:#F7DC6F FGC:#A3A3A3 SHE:1 BTH:0.1 STA:50 ENA:125 |PI UID:pi3 X:50 Y:50 W:70 VIS:1 ROT:0 BGC:#82E0AA FGC:#A3A3A3 SHE:1 BTH:0.1 STA:130 ENA:145 |PI UID:pi4 X:50 Y:50 W:70 VIS:1 ROT:0 BGC:#6D9DC5 FGC:#A3A3A3 SHE:1 BTH:0.1 STA:150 ENA:225 |PI UID:pi5 X:50 Y:50 W:70 VIS:1 ROT:0 BGC:#BB8FCE FGC:#A3A3A3 SHE:1 BTH:0.1 STA:230 ENA:355
116 GUI-O Team
117 GUI-O Team
Rectangle Parameters Parameter Description Default value header BSR Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 10.0 H: Height (% screen height). 15.0 Height is width. If this is enabled, width is used for height, which enables drawing a HIW: square. 0 0 – Disabled 1 – Enabled Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Secondary background color (#AARRGGBB / #RRGGBB - hex format). SBGC: The color is linearly interpolated between #4C4C4C BGC and SBGC, creating a linear gradient effect. Linear gradient direction: LOR: 0 – Horizontal 0 1 – Vertical Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled
118 GUI-O Team
Parameter Description Default value header Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). RAD: Border radius (% screen width). 0.0 BTH: Border thickness (% screen width). 0.25 Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|BSR UID:bsr1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@bsr1 ROT:25\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |BSR UID:bsr1 X:50 Y:50 W:80 H:25 VIS:1 ROT:0 RAD:2 BGC:#6D9DC5 FGC:#121212 SHE:1 BTH:0.5
119 GUI-O Team
120 GUI-O Team
Triangle Parameters Parameter Description Default value header BST Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 20.0 H: Height (% screen height). 15.0 Height is width. If this is enabled, width is used for height, which enables drawing a HIW: equilateral triangle. 0 0 – Disabled 1 – Enabled Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). BTH: Border thickness (% screen width). 0.25
121 GUI-O Team
Parameter Description Default value header Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|BST UID:bst1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@bst1 ROT:25\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |BST UID:bst1 X:50 Y:50 W:60 H:30 HIW:0 SHE:1 ROT:0 BTH:0.2 BGC:#6D9DC5 FGC:#121212
122 GUI-O Team
123 GUI-O Team
Ellipse Parameters Parameter Description Default value header BSE Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 20.0 H: Height (% screen height). 15.0 Height is width. If this is enabled, width is used for height, which enables drawing a HIW: circle. 0 0 – Disabled 1 – Enabled Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). BTH: Border thickness (% screen width). 0.25
124 GUI-O Team
Parameter Description Default value header Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|BSE UID:bse1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@bse1 ROT:25\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |BSE UID:bse1 X:50 Y:50 W:30 H:42 HIW:0 SHE:1 ROT:0 BTH:0.2 BGC:#6D9DC5 FGC:#121212
125 GUI-O Team
126 GUI-O Team
Line NOTE: The (X, Y) center of the widget is on its start point. This makes the rotation of the widget more intuitive.
Parameters Parameter Description Default value header BSL Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Foreground color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 width). SHVR: Shadow vertical offset (% screen width). 0.5 SHR: Shadow radius (% screen width). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). LEN: Length (% screen width). 25.0 BTH: Border thickness (% screen width). 0.25 Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen
127 GUI-O Team
Parameter Description Default value header Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|BSL UID:bsl1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@bsl1 ROT:25\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |BSL UID:bsl1 X:5 Y:50 SHE:1 LEN:90 BTH:0.2 BGC:#121212 FGC:#6D9DC5
128 GUI-O Team
Arc Parameters Parameter Description Default value header BSA Component identifier UID: Unique identifier. Horizontal screen position (% screen Mandatory X: width). parameters Y: Vertical screen position (% screen height). W: Width (% screen width). 20.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Background color (#AARRGGBB / BGC: #4C4C4C #RRGGBB - hex format). Shadow effect: SHE: 0 – Not enabled 0 1 – Enabled Shadow horizontal offset (% screen SHHR: 0.5 height). SHVR: Shadow vertical offset (% screen height). 0.5 SHR: Shadow radius (% screen height). 0.5 Shadow color (#AARRGGBB / #RRGGBB - SHC: #80000000 hex format). BTH: Arc thickness (% screen height). 4.0 STA: Start angle (degrees from 3'o clock). 0 ENA: End angle (degrees from 3'o clock). 45 Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen
129 GUI-O Team
Parameter Description Default value header Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters:
|BSA UID:bsa1 X:50 Y:50\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@bsa1 STA:-20 ENA:20\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |BSA UID:bsa1 X:50 Y:50 W:50 SHE:1 ROT:0 BTH:4 BGC:#6D9DC5 STA:0 ENA:135
130 GUI-O Team
Grid Parameters Parameter Description Default value header GRID Component identifier UID: Unique identifier. Horizontal screen position (% screen X: width). The (X, Y) position denotes the Mandatory top-left point of the grid. parameters Vertical screen position (% screen height). Y: The (X, Y) position denotes the top-left point of the grid. W: Width (% screen width). 100.0 H: Height (% screen height) 100.0 Visibility: VIS: 0 – Hidden 1 1 – Shown Opacity. Any value between: OPA: 0.0 – Transparent 1.0 1.0 – Opaque ROT: Rotation (deg). 0 Foreground / grid color (#AARRGGBB / FGC: #6D9DC5 #RRGGBB - hex format). LT: Grid thickness (% screen width). 0.3 Grid step in horizontal (X) direction (% XSTP: 25 screen width) Grid step in horizontal (Y) direction (% YSTP: 10 screen height) Screen position index: 0 – base screen SCI: 0 1 – second screen 2 – third screen Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
131 GUI-O Team
Create command Minimal command requires only mandatory parameters:
|GRID UID:grid1 X:0 Y:0\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing widget, it must be referenced using the value of "UID" parameter:
@grid1 XSTP:10 FGC:#FF0000\r\n
Other applicable parameters can be chained to the above command in any order.
Quick-start example |GRID UID:grid1 X:0 Y:0 W:100 H:50 XSTP:10 YSTP:10
|GRID UID:grid2 X:0 Y:50 W:100 H:50 XSTP:25 YSTP:25 FGC:#FF0000
132 GUI-O Team
HARDWARE API Hardware components allow out-of-the-box interaction with various hardware that is built into the Android powered device. This enables the communication with various sensors and actuators or even data writing to a file and reading from it.
Basic parameters such as unique identifier ("UID") and hardware identified ("HID") are mandatory, while others are optional and are determined by the hardware component type. In cases where optional parameters are not specified, the default parameters are automatically supplied by the GUI-O application.
Every parameter consists of parameter header and parameter payload. The parameter header and its corresponding payload are separated by the colon character (3Ahex). Multiple parameters can be delimited by the space or comma character (20hex and 2Chex, respectively) or combination of both. For improved user readability it is advised that the delimiters usage is consistent, at least within an individual command.
General notes A NOTE ON UID PARAMETER: Each hardware component must be created with a unique identifier parameter ("UID"). GUI-O application does not allow multiple "UID" parameters with the same name (in such case, an error will be reported). A "UID" parameter is basically a reference to a crated hardware component; all sent and received data for a specific hardware component depends on this parameter.
In terms of communication protocol, the interaction with hardware components is analogous to widgets interaction. For reference see Getting started tutorial.
133 GUI-O Team
SMS handler4 SMS (Short Message Service) handler enables sending messages to other devices as well as receiving messages from other devices.
NOTE: User must give explicit, one-time permission to send and receive SMSes as this may incur additional costs.
Parameters Parameter Description Default value header Mandatory SMS Component identifier parameter Comma delimited phone numbers that SMSN: not set are enclosed in double quotes. Message string enclosed in double quotes. SMSM: not set This is the payload of the sms.
Send SMS To send an SMS to any arbitrary number (e.g., number0 and number1 in the example below), the following command is required:
|SMS SMSN:"number0,number1" SMSM:"Hello from GUI-O"\r\n
Receive SMS When a device (which is running the GUI-O application) receives an SMS starting with #sms, the message is formatted and forwarded to the currently active connection (see Connections), finally reaching the MCU side. The message is formatted as follows (all fields are separated by space character):
#sms
4 Due to some restrictions imposed by Google regarding high risk or sensitive permissions, the SMS functionality is not applicable for application that is published on the Google Store. However, the SMS functionality can still be used within the stand-alone version of the application (see https://www.gui-o.com)
134 GUI-O Team that receiving multi-lined messages is not possible as the message will not be parsed correctly.
135 GUI-O Team
Audio player Parameters Parameter Description Default value header AUD Component identifier Mandatory UID: Unique identifier. parameters Audio file name with extension. AP: Can be an external URL (see APPENDIX not set D). Playing state: 0 – Stop PLS: 0 1 – Play 2 – Pause Volume, relative to the device media VOL: 1.0 volume (0.0 – 1.0) Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only "UID" parameter:
|AUD UID:aud1\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing hardware component, it must be referenced using the value of "UID" parameter:
@aud1 PLS:2 VOL:0.5\r\n
Other applicable parameters can be chained to the above command in any order.
136 GUI-O Team
Tone player Parameters Parameter Description Default value header TON Component identifier Mandatory UID: Unique identifier. parameters HID: Must be set to "ton" (without quotes). Duration of tone in msec. Ignored if tone EDUR: duration is shorter. 500 Maximum duration limited to 5000 msec. Tone type number. For reference see: TONT: https://developer.android.com/reference/ 24 android/media/ToneGenerator Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters ("UID" and "HID" parameter):
|TON UID:ton1 HID:ton\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing hardware component, it must be referenced using the value of "UID" parameter:
@ton1 EDUR:500\r\n
Other applicable parameters can be chained to the above command in any order.
Activate tone player In order to activate the tone player instance with the set parameters, it needs to be referenced by the "UID" parameter:
@ton1 1\r\n
137 GUI-O Team
Real-time clock (RTC) Parameters Parameter Description Default value header RTC Component identifier Mandatory UID: Unique identifier. parameters HID: Must be set to "rtc" (without quotes). Real-time clock report rate in Hz. Valid RTCR: 1.0 range: 0.01 – 10.0 Hz. Real-time clock state: RTCE: 0 – Not enabled 1 1 – Enabled "yyyy/mm/dd RTCF: Real-time clock format (see APPENDIX C). HH:mm:ss:zzz" Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters ("UID" and "HID" parameter):
|RTC UID:rtc1 HID:rtc\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing hardware component, it must be referenced using the value of "UID" parameter:
@rtc1 RTCF:"HH:mm:ss" RTCR:2.0\r\n
Other applicable parameters can be chained to the above command in any order.
On real-time clock report When the real-time clock reports the date / time value, the following info is sent (the format is based on "RTCF" parameter):
138 GUI-O Team
@rtc1 2018/10/8 21:17:10:345\r\n
139 GUI-O Team
Position sensor (GPS) Parameters Parameter Description Default value header POS Component identifier Mandatory UID: Unique identifier. parameters HID: Must be set to "pos" (without quotes). Sensor report rate in Hz. Maximum report rate depends on the SRAT: device. Setting the value to zero (0) will 0.1 report position updates as often as necessary. Sensor enabled: SEN: 0 – Not enabled 1 1 – Enabled Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters ("UID" and "HID" parameter):
|POS UID:pos1 HID:pos\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing hardware component, it must be referenced using the value of "UID" parameter:
@pos1 SRAT:0\r\n
Other applicable parameters can be chained to the above command in any order.
140 GUI-O Team
On position report When the sensor reports the position (using mobile data or GPS or both), the following info is sent:
@pos1 p0,p1,p2,p3,p4,p5,p6,p7,p8,p9\r\n where p0 - position timestamp in ISO8601 format (local time) p1 – latitude in decimal degrees p2 – longitude in decimal degrees p3 – altitude in meters above sea level p4 – direction in degrees clockwise from true north to the direction of travel p5 – ground speed in m/s p6 – vertical speed in m/s p7 – magnetic declination p8 – horizontal accuracy of latitude-longitude in meters p9 – vertical accuracy of altitude in meters
NOTE: If any value from 'p3' to 'p9' is unavailable, it is replaced with "n/a" string. If latitude ('p1') or longitude ('p2') values are unavailable, no position data is sent.
141 GUI-O Team
Vibrator Parameters Parameter Description Default value header VIB Component identifier Mandatory UID: Unique identifier. parameters HID: Must be set to "vib" (without quotes). Duration of vibration in msec. EDUR: 500 Maximum duration limited to 5000 msec. Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters ("UID" and "HID" parameter):
|VIB UID:vib1 HID:vib\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing hardware component, it must be referenced using the value of "UID" parameter:
@vib1 EDUR:1000\r\n
Other applicable parameters can be chained to the above command in any order.
Activate vibrator In order to activate the vibrator instance with the set parameters, it needs to be referenced by the "UID" parameter:
@vib1 1\r\n
142 GUI-O Team
Camera capture NOTE: Camera capture requests should not be generated too often (requests during an active capture are silently discarded). Keep in mind that before each capture, the camera needs to be opened and closed afterwards. All captures are performed with maximum available resolution.
Parameters Parameter Description Default value header CAP Component identifier Mandatory UID: Unique identifier. parameters HID: Must be set to "cap" (without quotes). Camera mode: CAM: 0 – Front camera 1 1 – Back camera Camera action: 0 – No action CAA: 0 1 – Capture image in selected camera mode Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters ("UID" and "HID" parameter):
|CAP UID:cap1 HID:cap\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing hardware component, it must be referenced using the value of "UID" parameter:
@cap1 CAM:1\r\n
143 GUI-O Team
Other applicable parameters can be chained to the above command in any order.
Capture image In order to capture an image using the selected camera mode ("CAM"), the camera action parameter must be set ("CAA") :
@cap1 CAA:1\r\n
144 GUI-O Team
File I/O NOTES: File names must be unique, i.e., duplicate file names are not allowed. Up to five (5) files can be active simultaneously. If hardware components are cleared using the @cls command (see COMMUNICATION PROTOCOL), all opened files are flushed (buffered data is written) and closed.
The following file formats are supported: txt, csv, xml, htm, html, php. All saved files are located in the GUI-O application specific storage within the files folder (e.g., /Android/data/com.guio.guioapp/files/).
A note on file operations:
1. File open - open the file for read / write operations. When the file instance is created, the file is automatically opened. Every file can be opened and closed dynamically.
2. File write - when writing to a file, FAC:1 must be specified along with the payload data (FP). Every write is followed by new line internally.
3. File read - when reading from a file, FAC:2 must be specified along with the FP parameter which denotes the line index to read. For example, FP:"1" reads the first line, FP:"2" reads the second line and so on. Specifying FP:"-1" reads entire file content, line-by-line. If the requested line index is out of bounds, payload 'EOF' preceded by the unique identifier is returned. If the file is empty, payload 'EMPTY' preceded by the unique identifier is returned.
4. File close - flush any buffered data and close opened file.
5. Show file content - shows file content using external application. Requires the user to select the external application if more than one compatible application is available. NOTE: After this action, the file needs to be re-opened for read and write operations.
6. Clear file content - clears all content of the opened file, effectively making the file empty. NOTE: After this action, the file needs to be re-opened for read and write operations.
7. Share file - shares the file using external application. Requires the user to select the external application if more than one compatible application is
145 GUI-O Team
available. NOTE: After this action, the file needs to be re-opened for read and write operations.
Parameters Parameter Description Default value header EXTF Component identifier Mandatory UID: Unique identifier. parameters HID: Must be set to "extf" (without quotes). File name. Must be set when creating the FNA: "extf_def.txt" file instance. File action: 0 – Open 1 – Write 2 – Read FAC: 3 – Close 0 4 – Delete 5 – Show content (external application) 6 – Clear content 7 – Share file (external application) Payload data: • data to write when using write operations • line index to read when using read FP: operations ("1" ... "N" to read the not set corresponding line or "-1" to read all contents of the file) Applicable only when component is already created. Prepended date time format. This is prepended to every payload. [yyyy-MM-dd DTF: See APPENDIX C for possible formats. If HH:mm:ss] empty string is set (i.e., ""), nothing is prepended. Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
146 GUI-O Team
Create command Minimal command requires only mandatory parameters ("UID" and "HID" parameter):
|EXTF UID:extf1 HID:extf\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator. Note that if "FNA" parameter is not specified, the default will be used. It is therefore recommended to also specify this parameter.
Write command To write payload to an existing file instance, it must be referenced using the value of "UID" parameter:
@extf1 FAC:1 FP:"GUI-O finishes on the first line."\r\n
Read command To read from an existing file instance, it must be referenced using the value of "UID" parameter:
@extf1 FAC:2 FP:"3"\r\n
With respect to the command above, the application responds with:
@extf1 3 %1\r\n where %1 denotes the content on the third (3) line in file, if available.
147 GUI-O Team
Screen orientation NOTE: The GUI-O application always starts in locked portrait orientation mode.
Parameters Parameter Description Default value header SORI Component identifier Mandatory UID: Unique identifier. parameters HID: Must be set to "sori" (without quotes). Screen orientation setting: -1 – Unspecified 0 – Portrait 1 – Inverted portrait ORI: 0 2 – Landscape 3 – Inverted landscape 4 – System controlled 5 – Sensor controlled Screen orientation reporting: SEN: 0 – Not enabled 0 1 – Enabled Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters ("UID" and "HID" parameter):
|SORI UID:sori1 HID:sori\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing hardware component, it must be referenced using the value of "UID" parameter:
@sori1 SEN:1\r\n
148 GUI-O Team
Other applicable parameters can be chained to the above command in any order.
Orientation change To change the orientation (e.g. to landscape) and receive notification when the orientation changes, the following command should be used:
@sori1 SEN:1 ORI:2\r\n
If parameter "SEN" is already set to report the orientation changes, it can be omitted. With respect to the command above, when the orientation changes, the application responds with:
@sori1 2\r\n
149 GUI-O Team
Battery status Parameters Parameter Description Default value header BAT Component identifier Mandatory UID: Unique identifier parameters HID: Must be set to "bat" (without quotes). Sensor report rate in Hz. Valid range 0.01 – SRAT: 0.1 0.2 Hz. Sensor enabled: SEN: 0 – Not enabled 1 1 – Enabled Comma delimited publish topics for remote devices. If this parameter is set, PUB: not set the command is redirected to the MQTT broker.
Create command Minimal command requires only mandatory parameters ("UID" and "HID" parameter):
|BAT UID:bat1 HID:bat\r\n
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing hardware component, it must be referenced using the value of "UID" parameter:
@bat1 SRAT:0\r\n
Other applicable parameters can be chained to the above command in any order.
On battery status report The battery status report includes two values delimited by the comma character
(2Chex): (i) current battery percentage (0 - 100%) and (ii) current charging state of the device (0 - not charging, 1 - charging). On report, the following info is sent:
150 GUI-O Team
@bat1 60,1\r\n
The info above can be interpreted as (i) battery level at 60% and (ii) currently charging.
151 GUI-O Team
Device sensors Parameters HID Hardware device acc Accelerometer alt Altimeter als Ambient light sensor ats Ambient temperature sensor com Compass dss Distance sensor gyr Gyroscope hls Holster sensor hms Humidity sensor iprs IR Proximity sensor lds Lid sensor ls Light sensor mag Magnetometer ors Orientation sensor prs Pressure sensor prx Proximity sensor rts Rotation sensor tps Tap sensor tis Tilt sensor Table 1. Device sensors HID parameters.
Parameter Description Default value header SE Component identifier Mandatory UID: Unique identifier. parameters HID: See Table 1. Sensor report rate in Hz. Valid range 0.01 – SRAT: 1.0 10.0 Hz. Sensor enabled: SEN: 0 – Not enabled 1 1 – Enabled Comma delimited publish topics for remote devices. If this parameter is set, the PUB: not set command is redirected to the MQTT broker.
152 GUI-O Team
Create command Minimal command requires only mandatory parameters ("UID" and "HID" parameter):
|SE UID:se1 HID:%1\r\n where %1 denotes the "HID" parameter from Table 1.
Other applicable parameters can be chained to the above command in any order using space or comma character (20hex and 2Chex, respectively) as a separator.
Update command To update an existing hardware component, it must be referenced using the value of "UID" parameter:
@se1 SRAT:5.0\r\n
Other applicable parameters can be chained to the above command in any order.
On sensor reading report When the referenced sensor reports its reading, the following format is used:
@se1 %1,%2,...\r\n
The number of parameters (%1,%2,...) can vary based on the sensor type, but multiple values are always delimited by a comma character (2Chex).
153 GUI-O Team
DEVELOPER MODE This is a special feature that can be used during development phase to enable some extra features such as:
• Keep screen on
If this is enabled, the screen will always remain when application is running in the foreground (i.e., visible to the user). If this is disabled, the screen will turn off after user inactivity for the specified amount of time (determined by the system).
• Protocol warnings
This enables or disables warnings for the ASCII protocol, such as missing or invalid parameters.
• UI reset button
If enabled, this overlays a reset button over the main UI. Pressing the button clears all created widgets and active hardware objects.
• Log incoming messages
Enables logging of all incoming messages. The messages are logged into a file under the following path:
/Android/data/com.guio.guioapp/files/in_messages.log
The file contents persists for current session only. This means that the contents of the file are removed on each application start. If the GUI-O application is exited, the file contents remain unchanged (until next start).
• Log outgoing messages
Enables logging of all outgoing messages. The messages are logged into a file under the following path:
/Android/data/com.guio.guioapp/files/out_messages.log
The file contents persists for current session only. This means that the contents of the file are removed on each application start. If the GUI-O application is exited, the file contents remain unchanged (until next start).
154 GUI-O Team
• Display properties
Shows the display properties of the current device. The width (DPW) and height (DPH) are specified in dip (device independent pixel) values. The aspect ratio DPW (ASR) is specified as , regardless of the device orientation. DPH
Developer mode can be enabled from the settings menu under 'Info' by tapping on 'Application version' 10 times. A notification is displayed when developer mode is enabled and a new menu entry named 'Developer mode' appears at the bottom. Developer mode can be disabled at any time from within the developer mode menu.
155 GUI-O Team
KNOWN ISSUES i. screen orientation reporting is not triggered when direct rotation from portrait to inverted portrait is requested (and vice versa). The same issue applies for landscape to inverted landscape rotation (and vice versa).
156 GUI-O Team
APPENDIX A Supported USB devices The following chipsets are supported:
0x0403 / 0x6001: FTDI FT232R UART vendor-id="1027" product-id="24577" 0x1A86 / 0x7523: QinHeng HL-340 vendor-id="6790" product-id="29987" 0x0403 / 0x6015: FTDI FT231X vendor-id="1027" product-id="24597" 0x2341 / Arduino device vendor-id="9025" 0x16C0 / 0x0483: Teensyduino vendor-id="5824" product-id="1155" 0x10C4 / 0xEA60: CP210x UART Bridge vendor-id="4292" product-id="60000" 0x067B / 0x2303: Prolific PL2303 vendor-id="1659" product-id="8963" 0x1B4F / 0x0008: IOIO OTG vendor-id="6991" product-id="8" 0x0557 / 0x2008: Aten UC232-A vendor-id="1367" product-id="8200"
157 GUI-O Team
APPENDIX B Supported application fonts The following font types are supported:
Font family ("FFA") Font name Example
"font0" Open Sans
"font1" Caviar Dreams
"font2" Digital Dream
"font3" Balqis
"font4" Sacramento
"font5" Quicksand
"font6" Simplifica
"font7" Khand
"font8" LCD Dot
"font9" c39hrp24dhtt
158 GUI-O Team
APPENDIX C Supported date and time formats The following date and time format options are available:
Date formatting d the day as number without a leading zero (1 to 31) dd the day as number with a leading zero (01 to 31) ddd the abbreviated localized day name (e.g., 'Mon' to 'Sun') dddd the long localized day name (e.g., 'Monday' to 'Sunday') M the month as number without a leading zero (1 to 12) MM the month as number with a leading zero (01 to 12) MMM the abbreviated localized month name (e.g., 'Jan' to 'Dec') MMMM the long localized month name (e.g., 'January' to 'December') yy the year as two digit number (00 to 99) yyyy the year as four digit number. If the year is negative, a minus sign is prepended in addition.
Time formatting h the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display) hh the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display) H the hour without a leading zero (0 to 23, even with AM/PM display) HH the hour with a leading zero (00 to 23, even with AM/PM display) m the minute without a leading zero (0 to 59) mm the minute with a leading zero (00 to 59) s the whole second, without any leading zero (0 to 59) ss the whole second, with a leading zero where applicable (00 to 59) z the fractional part of the second, to go after a decimal point, without trailing zeroes (0 to 999). Thus "s.z" reports the seconds to full available (millisecond) precision without trailing zeroes.
159 GUI-O Team
Time formatting zzz the fractional part of the second, to millisecond precision, including trailing zeroes where applicable (000 to 999). AP or A use AM/PM display ap or a use am/pm display t the timezone (for example "CEST")
160 GUI-O Team
APPENDIX D External URL handling The GUI-O application can load local resource files as well as parse external http or https requests which enables dynamically downloading files from online resources. If external request is made, the application first checks the standard local paths; if the resource is already present on the device due to previous download (based on exact location and name match), the resource can be loaded locally. If no local resource is found, the external request is passed to the application's download manager. Resources can be downloaded using either Wi-Fi or Mobile data (in the latter case, the user must grant Mobile data permissions via the 'General Settings → Network usage' menu). Downloaded files are located on the standard paths on internal or external (SD card) memory or application specific location. Starting from root location (i.e., '/'), the default paths are as follows:
• Picture (image) files location
/Android/data/com.guio.guioapp/files/Pictures/
• Video (movie) files location
/Android/data/com.guio.guioapp/files/Movies/
• Audio files location
/Android/data/com.guio.guioapp/files/Music/
161 GUI-O Team
APPENDIX E Humidity and temperature monitor /* show load screen - hide GUI, clear widgets and hardware instances and set display settings */ @sls @cls @clh // set ASR parameter of the "development" device @guis BGC:#000000 ASR:0.5652
// create widgets |LB UID:lb1x X:50 Y:4 ROT:0 SHE:0 FGC:#F7DC6F FSZ:3 FFA:"font1" TXT:"Humidity Temperature Measurement"
|CB UID:cb3 X:25 Y:90 W:35 ROT:0 SHE:0 BGC:#454546 FGC:#278DB9 VAL:66 LVAL:0 HVAL:100 STA:225 ENA:-45 BTH:5.5 HAW:5 HAH:5 NT:3 CE:0 SHT:0 XTC:10 YTC:5 RCA:1 VIS:1 UD:0 FSZ:1.5 SHN:0
|CB UID:cb4 X:75 Y:90 W:35 ROT:0 SHE:0 BGC:#454546 FGC:#9C3B29 VAL:25 LVAL:0 HVAL:100 STA:225 ENA:-45 BTH:5.5 HAW:5 HAH:5 NT:3 CE:0 SHT:0 XTC:10 YTC:5 RCA:1 VIS:1 UD:0 FSZ:1.5 SHN:0
|CB UID:cb2 X:50 Y:70 W:25 ROT:0 SHE:0 BGC:#454546 FGC:#ABEBC6 VAL:10 LVAL:-20 HVAL:60 STA:225 ENA:-45 BTH:4 HAW:1 HAH:1 NT:0.3 CE:0 SHT:1 TXTC:#FFFFFF XTC:5 YTC:5 RCA:1 VIS:1 UD:0 FSZ:1.5 SHN:1
|LB UID:lbH X:25 Y:88 W:0 ROT:0 SHE:0 ALP:0 FGC:#278DB9 FSZ:3 ALP:0 TXT:"66"
|LB UID:lbT X:75 Y:88 W:0 ROT:0 SHE:0 ALP:0 FGC:#9C3B29 FSZ:3 ALP:0 TXT:"25"
|LB UID:lbT2 X:50 Y:75 W:0 ROT:0 SHE:0 ALP:0 FGC:#ABEBC6 FSZ:2 ALP:0 TXT:"10"
|LB UID:lbHt X:25 Y:92 ROT:0 SHE:0 ALP:0 FGC:#278DB9 FSZ:3 ALP:0 TXT:"Hum"
|LB UID:lbTt X:75 Y:92 ROT:0 SHE:0 ALP:0 FGC:#9C3B29 FSZ:3 ALP:0 TXT:"Temp"
|LB UID:lbtT2 X:50 Y:72 ROT:0 SHE:0 ALP:0 FGC:#ABEBC6 FSZ:2 ALP:0 TXT:"Temp"
162 GUI-O Team
|CH UID:ch1 X:50 Y:32 W:90 H:40 VIS:1 ROT:0 OPA:1 BGC:#454546 FGC:#FFFFFF DRA:1 DRAT:0.2 CHT:0 SHE:0 FSZ:1.4 RAD:1 BTH:0 AT:0.1 LT:0.2 YLO:20 YHI:40 XTC:5 YTC:10 XMA:5 YMA:5 SHG:1 CHN:""
|LB UID:lbHx X:13 Y:9 W:0 ROT:0 SHE:0 ALP:1 FGC:#FFFFFF FSZ:1.3 FFA:"font0" TXT:"Humidity [%]"
|LB UID:lbTx X:72 Y:9 W:0 ROT:0 SHE:0 ALP:1 FGC:#FFFFFF FSZ:1.3 FFA:"font0" TXT:"Temperature [C]"
|LB UID:lbrnd X:45 Y:9 W:0 ROT:0 SHE:0 ALP:1 FGC:#FFFFFF FSZ:1.3 FFA:"font0" TXT:"Temp Out [C]"
|BSL UID:bslh X:7 Y:9 SHE:0 LEN:5 BTH:2 FGC:#278DB9
|BSL UID:bslt X:65 Y:9 SHE:0 LEN:5 BTH:2 FGC:#9C3B29
|BSL UID:bslr X:38 Y:9 SHE:0 LEN:5 BTH:2 FGC:#ABEBC6
|LB UID:lbdate X:75 Y:14 W:0 ROT:0 SHE:0 ALP:1 FGC:#FFFFFF FSZ:1.8 FFA:"font0" TXT:"25.12.2020"
|LB UID:lbair X:8 Y:56 W:0 ROT:0 SHE:0 ALP:1 FGC:#FFFFFF FSZ:2.4 FFA:"font0" TXT:"STATUS"
|LB UID:lbaih X:32 Y:56 W:0 ROT:0 SHE:0 ALP:1 FGC:#FFFFFF FSZ:2 FFA:"font0" TXT:"Heating"
|LB UID:lbaiv X:67 Y:56 W:0 ROT:0 SHE:0 ALP:1 FGC:#FFFFFF FSZ:2 FFA:"font0" TXT:"Ventilation"
|BT UID:bt1 X:75 Y:92 W:10 H:5 ROT:0 RAD:4 BGC:#00454546 FGC:#00FFFFFF BTH:3 SVAL:"1"
|SI UID:si1 X:50 Y:56 W:6 VIS:1 SHE:0 BGC:#B0C4DE FGC:#990000 EN:1
|SI UID:si2 X:90 Y:56 W:6 VIS:1 SHE:0 BGC:#B0C4DE FGC:#3498DB EN:1
|BT UID:btu X:86 Y:65 W:15 H:4 ROT:0 SHE:0 RAD:1 BTH:0.2 BGC:#454546 FGC:#FFFFFF SVAL:"1" TXT:""
|BT UID:btd X:86 Y:70 W:15 H:4 ROT:0 SHE:0 RAD:1 BTH:0.2 BGC:#454546 FGC:#FFFFFF SVAL:"1" TXT:""
|LB UID:lbzp X:86 Y:65 W:10 ROT:0 SHE:0 ALP:0 FGC:#FFFFFF FSZ:2 FFA:"font0" TXT:"Int +"
|LB UID:lbzm X:86 Y:70 W:10 ROT:0 SHE:0 ALP:0 FGC:#FFFFFF FSZ:2 FFA:"font0" TXT:"Int -"
163 GUI-O Team
|BT UID:btf X:25 Y:87 W:100 H:50 ROT:0 RAD:4 BGC:#00454546 FGC:#00FFFFFF BTH:3 SVAL:"1"
// hide load screen (show GUI) @hls 200
// plot data @ch1 PLI:"pl1,pl2,pl3" PLC:"#278DB9,#9C3B29,#ABEBC6" YP:"78,22,15" @ch1 PLI:"pl1,pl2,pl3" PLC:"#278DB9,#9C3B29,#ABEBC6" YP:"79,23,17" @ch1 PLI:"pl1,pl2,pl3" PLC:"#278DB9,#9C3B29,#ABEBC6" YP:"82,24,19" @ch1 PLI:"pl1,pl2,pl3" PLC:"#278DB9,#9C3B29,#ABEBC6" YP:"86,23,18" @ch1 PLI:"pl1,pl2,pl3" PLC:"#278DB9,#9C3B29,#ABEBC6" YP:"90,22,16" @ch1 PLI:"pl1,pl2,pl3" PLC:"#278DB9,#9C3B29,#ABEBC6" YP:"88,22,15" @ch1 PLI:"pl1,pl2,pl3" PLC:"#278DB9,#9C3B29,#ABEBC6" YP:"81,23,14" @ch1 PLI:"pl1,pl2,pl3" PLC:"#278DB9,#9C3B29,#ABEBC6" YP:"71,24,12" @ch1 PLI:"pl1,pl2,pl3" PLC:"#278DB9,#9C3B29,#ABEBC6" YP:"66,25,10"
164