IrisControlsAPI4 Overview

From Wiki.IrisDynamics.com
Jump to navigation Jump to search

Contents

Iris Controls 4 Embedded Library

Iris Controls 4 (IC4) is a flexible application that allows users to operate and monitor Iris Dynamics devices from a Windows PC using over USB. The IC4 embedded library simplifies building GUIs to suit a wide variety of use cases by providing an object-based implementation of the IC4 serial API.

General Description

Iris Controls 4 is a Windows based application that displays a single main window in which a variety of different elements can be placed. The main window contains a grid of 20px by 20px squares. The number of rows and columns is set by the user. Elements are assigned a position using an origin row and column where (0,0) is the top left corner of the main window. They are given a size by assigning a row-span and column-span. For example, an element added with row = 3, column = 3, rowSpan = 2, columnSpan = 4 will occupy rows 3 and 4 between columns 3 and 6. Elements have a minimum size and if they are not assigned adequate row or column spans the elements will not be added.

Device Support

  • "Eagle" controllers (ARM Cortex M4)
  • "SuperEagle" controllers (Zynq7000)
  • "Orca600" embedded motor drives (ARM Cortex M4)

Data Flow

Except for the initial handshake, data transactions are initiated by the device, and a response is sent from the GUI. In other words, the device will update the GUI with data, and will poll the GUI for changes to any of the interactive elements.

Handshaking

IC4 is configured to communicate with a single COM port (i.e. a single USB Serial device connected to the PC). When connection is enabled on IC4 and a valid COM port is selected, IC4 will periodically send a "ping" message and wait for a response. When a device running an IC4 server receives that ping, it will respond with its device ID, the IC4 serial API version, the IC4 server name, and some other information. IC4 responds with an acknowledgement when a compatible API version is detected. A CRC is completed to ensure the handshake's data is not corrupted in transmission. At this point, the handshaking is considered complete and the device is free to start the data flow.

Initial Challenge

Iris Controls periodically sends \x02\x06\r to the device.

Initial Challenge Response

After receiving the initial challenge, the device will transmit \x02\x06 COMMUNICATIONS_PROTOCOL DEVICE_ID IC_SERIAL_API_VERSION SERVER_NAME which includes:

  • COMMUNICATIONS_PROTOCOL - The communications protocol in use, half or full duplex.
  • DEVICE_ID - The device id located in the config.h file of the device firmware.
  • IC_SERIAL_API_VERSION - The version of the Iris Controls Serial API in use.
  • SERVER_NAME - The Iris Controls server name.
  • TIME_STAMP - A time stamp used in data plotting to record accurate data capture times.
  • TIMEOUT_TIMER - The timeout timer duration in ms.

Connection Established

Upon successful reception of the response, Iris Controls will send \x02\x01\r which indicates to the device that it can begin normal communications. At this stage, if in half duplex communication mode, Iris Controls will not transmit again until receiving an end of transmission token from the device.

Iris Controls will also generate (or add to if already generated) a connection log file and record the device parameters as passed in the handshake.

General Operation

The device will issue a stream of serial data, which could include element data updates (e.g. moving sliders), new elements, removing elements, log file entries, etc. Periodically, the device will also issue a "clear to send" token (\x02\x04\r) followed by silence, which indicates to IC4 that it should send a response. The response from IC4 may be an acknowledgement alone, or may contain information about user interaction with relevant GUI elements (e.g. they pressed a button). Even when no interaction is detected since the last message, IC must respond as the device is checking for an active connection as well as monitoring user interaction.

Disconnection

When in half-duplex mode, IC4 must wait until issued a "clear to send" command before sending the "disconnect" command to the device.

Connection Status

The connection status of Iris Controls can be queried by calling any of the following functions.

is_connected();

is_disconnected();

is_timed_out();

New Connection

A new connection can be detected by calling new_connection(); which returns true upon first establishing connection.

This can be used to trigger a setup loop in an application.

Connection Timeout

At handshake, the device transmits the timeout duration. Iris Controls and the device will both run timers of this duration. If the timer on either end expires, a timeout condition will be entered.

Iris Controls Timeout Condition

Iris Controls disables input to all I/O elements (except the console) during a timeout condition. Output elements (e.g. plots, labels, and sliders) remain in place with their last output displayed. Iris Controls adds an opacity mask to help notify the user that a timeout condition has been entered. This state persists until the Connect/Disconnect button in the console is pressed at which time the GUI returns to its boot state.

Device Timeout Condition

The timeout behaviour of a given device varies with different device firmware.

Handling Timeout Conditions

In order to execute any re-connection functions, an application can call restored_connection(); which returns true if the previous connection was interrupted.

The function set_disconnected(); can be called to set the connection status of the device to disconnected.

Disconnected

When the connection state is disconnected, bytes must be received at intervals of no more than 50ms. If an interval greater than 50ms occurs in the middle of a message, the receive buffer is reset to ensure that spurious signals are not stored in the receive buffer between sessions.

Device State

A cyclic redundancy check method has been implemented to check that the device and Iris Controls 4 are synchronous with respect to the state of the various GUI elements being displayed to the user. This check can be user initiated by using the console command crc or the device can initiate it by calling device_state_check();. The result of the CRC is displayed in the console.

Configuration Files

Some devices make use of console commands to setup various parameters within their firmware. Iris Controls can load configuration files which can contain many console commands. These files can be loaded in three ways:

  1. The settings dialog via a Windows file browser.
  2. The "load" console command.
  3. The device requesting it via the API command below.

Once loaded, the commands within the configuration file are sent to the device as console messages one line at a time with a 250ms pause between each one.

Configuration File Format

Iris Controls will ignore all content in a configuration file until it encounters a line containing only START after which every line (except for wait commands) is transmitted through the console. To add a longer delay between console messages, a wait command can be included in the configuration file. Including wait(delay) will cause the delay at that point in the file to be 250 + delay in milliseconds.

API Commands

A connected device may call for a configuration file to be loaded.

Configuration File
Name Syntax Notes
arg type argument description
Load Config File Loads a configuration file with the filename.
load_config_file(filename); filename const char * The file name of the config file (e.g. "config_file.txt")

General GUI Management

Each Iris Controls 4 GUI is a collection of elements that are placed on a grid of rows and columns. Each row/column is 20px tall/wide. At launch, the GUI contains and is only large enough to contain, the console. The device GUI must send a set_grid(rows, columns) command to set the number of rows and columns before placing any further elements.

  • Ensure that the number of rows and columns requested will fit on the display in use. The Inject Delay command can be used to smooth GUI view/page change operations.
  • Consider whether or not Windows is using other than 100% scaling on the display in use as Windows scaling will cause the fonts used in element labels to change but the size of the element itself will not. This may cause the label of, for example, A Flex Button to overflow its boundaries. If commanded to create a button with an oversized label, Iris Controls 4 will reject that request.
  • Limit GUI element quantity to fewer than 9000 elements. Using more elements than this may result in undefined behaviour.

API Commands

General GUI Commands
Name Syntax Notes
arg type argument description
Set Grid Sets the number of rows and columns of the grid
gui_set_grid(rows, columns); rows u16 The number of rows to set. (1)
columns u16 The number of columns to set.
Query Max Grid Sends a query to IrisControls which returns the max allowable number of rows and columns
gui_query_max_grid();
Set Max Grid Sets the GUI to the maximum valid number of rows and columns
gui_set_max_grid();
Inject Delay Injects a delay into the serial communications thread in Iris Controls 4
delay(delay_length); delay_length u16 The length of the delay in ms. (2)
Disconnect Initiates a disconnect
disconnect();
Set Element Default Colour Sets the default colour of an aspect of the specified Flex Element
set_default_colour(element_type, element_aspect, r, g, b, a); element_type u16 The type of Flex Element. (3)(4)
element_aspect u16 The aspect of the element to change (e.g. text colour, or border colour).
r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
Restore Default Colours Restores all element colours to their default value.
restore_default_colours();
Assign Keyboard Shortcut Connects a shortcut keyboard key to a target FlexElement.
assign_keyboard_shortcut(key, target_id); key int The keyboard key that will initiate the shortcut. (5)
target_id u16 The id of the element to be activated when the key is pressed.
Set Main Window Title Sets the title in the top left corner of the main window of Iris Controls.
set_main_window_title(title); title const char* The new title. (6)

Notes:

  1. The display in use must be large enough to allow for a each row/column to be at least 20px tall/wide.
  2. Maximum delay time is 100ms.
  3. See table below for allowed element types.
  4. See table in Set Colour for available options.
  5. See here for a list of permissible key values.
  6. There is a 100 character limit.
Element Types
Flex Element Value
Flex Button FlexElement::FLEXBUTTON
Flex Slider FlexElement::FLEXSLIDER
Flex Label FlexElement::FLEXLABEL
Flex Data FlexElement::FLEXDATA
Flex Plot FlexElement::FLEXPLOT

The Console

The Console is the only element visible upon launching IrisControls. It is located at the origin (0,0) and occupies 20 rows and 10 columns. The Console provides user feedback on IrisControls and motor operations as well as handling the USB connection. Upon establishing the USB connection, the console can be moved and/or resized.

Constructor

The Console is automatically constructed by the GUI.

API Commands

Console Commands
Name Syntax Notes
arg type argument description
Hide Hides the Console
console.hide();
Show Reveals the Console
console.show();
Move Moves the Console to a new position
console.move(row, column); row u16 The new row. (1)
column u16 The new column.
Resize Resizes the Console
console.resize(rowSpan, columnSpan); rowSpan u16 The new row span.
columnSpan u16 The new column span.
Set Colour Sets the colour of the specified aspect of the Console.
console.set_colour(config, r, g, b, a); config Console::COLOUR_SET_FLAG A flag to indicated which aspect of the Console to colour.
r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
Reset to Default Colours Resets any colour changes that were made.
console.reset_default_colours();


GUI Page

The GUI Page class is used to group elements into pages or views. They help simplify changing pages by reducing the source code and the serial connection bandwidth required to accomplish this. A call of a GUI Pages's show or hide method will show or hide all child elements of that GUI Page.

NOTE: You can assign a GUI page to an element when making that element's add call. Doing so means there is no need to use the GUI_Page::add_element method defined below.

Constructor

No arguments need to be passed in a GUI Page constructor.

Example:

GUI_Page gui_page();

API Commands

Instance Methods
Name Syntax Notes
arg type argument description
Add a GUI Page Adds the GUI page. (1)
gui_page.add();
Remove a GUI Page Removes the GUI page.
gui_page.remove();
Add element to GUI Page Adds a Flex Element to the GUI Page.
gui_page.add_element(flex_element); flex_element FlexElement* A pointer to the Flex Element to add.
Remove element from GUI Page Removes a Flex Element from the GUI Page.
gui_page.remove_element(flex_element); flex_element FlexElement* A pointer to the Flex Element to remove.
Show GUI Page Shows all child elements of the GUI Page.
gui_page.show();
Hide GUI Page Hides all child elements of the GUI Page.
gui_page.hide();
  1. This must be called before adding any element that has gui_page as a parent.



Flex Element

Inherited by Flex Button, Flex Slider, Flex Label, Flex Data, and Flex Plot.

Constructor

There is no need to construct Flex Elements directly.

API Commands

The following API commands are common to all Flex Elements.

Instance Methods
Name Syntax Notes
arg type argument description
Show Element Reveals the element
flexelement.show();
Hide Element Hides the element
flexelement.hide();
Move Element Moves the element
flexelement.move(row, column); row u16 The new row. (1)
column u16 The new column.
Resize Element Resizes the element
flexelement.resize(rowSpan, columnSpan); rowSpan u16 The new row span.
columnSpan u16 The new column span.
Rename Element Changes the visible label of the element
flexelement.rename(name); name string The new name.
Delete Element Deletes the element
flexelement.remove();
Disable/Enable Element Disables/Enables the element
flexelement.disable(status); status bool True = disable, False = enable
Set Colour Sets the colour of the Flex Element
flexelement.set_colour(config, r, g, b, a); config COLOUR_SET_FLAG A flag to indicated which aspect of the element to colour. (2)
r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
Set Font Size Sets the font size of the selected sub-element of the element.
set_font_size(sub_element, font_size); sub_element FlexElement::SUBELEMENT_TYPE The sub-element to be altered (e.g. Label, Values, Units...)
font_size u16 The new point size of the font.
  1. The new position must be valid (i.e. not already occupied by a non-hidden element and not wholly or partially out of bounds). If the position is not valid the element will stay in its original position. Hidden elements can be moved on top of other elements but must remain in bounds.
  2. See the configuration table below.


Static Methods
Name Syntax Notes
arg type argument description
Reset All Default Colours Resets all element default colours.
FlexElement::reset_all_default_colours();



Colour Change API

Flex Button

FlexButton annotated2.png

Description Config Value
Changes colour of the button's default text. FlexButton::TEXT
Changes colour of the button's default background. FlexButton::BACKGROUND
Changes colour of the button's default border. FlexButton::BORDER
Changes colour of the button's checked text. FlexButton::CHECKED_TEXT
Changes colour of the button's checked background. FlexButton::CHECKED_BACKGROUND
Changes colour of the button's checked border. FlexButton::CHECKED_BORDER
Changes colour of the button's pressed text. FlexButton::PRESSED_TEXT
Changes colour of the button's pressed background. FlexButton::PRESSED_BACKGROUND
Changes colour of the button's pressed border. FlexButton::PRESSED_BORDER
Changes colour of the button's hover text. FlexButton::HOVER_TEXT
Changes colour of the button's hover background while unchecked. FlexButton::HOVER_BACKGROUND_NORMAL
Changes colour of the button's hover background while checked. FlexButton::HOVER_BACKGROUND_CHECKED
Changes colour of the button's hover border. FlexButton::HOVER_BORDER
Changes colour of the button's text while disabled. FlexButton::DISABLED_TEXT
Changes colour of the button's background while unchecked and disabled. FlexButton::DISABLED_BACKGROUND_NORMAL
Changes colour of the button's background while checked and disabled. FlexButton::DISABLED_BACKGROUND_CHECKED
Changes colour of the button's border while disabled. FlexButton::DISABLED_BORDER
Flex Slider

FlexSlider annotated.png

Description Config Value
Changes colour of the label's text. FlexSlider::LABEL_TEXT
Changes colour of the label's background. FlexSlider::LABEL_BACKGROUND
Changes colour of the slider's background. FlexSlider::SLIDER_BACKGROUND
Changes colour of the slider's groove left of the handle. FlexSlider::SLIDER_SUBPAGE
Changes colour of the slider's groove right of the handle. FlexSlider::SLIDER_ADDPAGE
Changes colour of the slider's handle. FlexSlider::HANDLE_COLOUR
Changes colour of the slider's handle while the mouse is hovering over it. FlexSlider::HANDLE_HOVER
Changes colour of the slider's handle while it is pressed by the mouse. FlexSlider::HANDLE_PRESSED
Changes colour of the slider's handle when it is disabled (output only). FlexSlider::HANDLE_DISABLED
Changes colour of the value's text. FlexSlider::VALUE_TEXT
Changes colour of the value's background. FlexSlider::VALUE_BACKGROUND
Changes colour of the units' text. FlexSlider::UNITS_TEXT
Changes colour of the units' background. FlexSlider::UNITS_BACKGROUND
Flex Label

FlexLabel annotated1.png

Description Config Value
Changes the text colour. FlexLabel::TEXT
Changes the background colour. FlexLabel::BACKGROUND
Flex Data

FlexData annotated.png

Description Config Value
Changes the label's text colour. FlexData::LABEL_TEXT
Changes the label's background colour. FlexData::LABEL_BACKGROUND
Changes the value's text colour. FlexData::VALUE_TEXT
Changes the value's background colour. FlexData::VALUE_BACKGROUND
Changes the units' text colour. FlexData::UNITS_TEXT
Changes the units' background colour. FlexData::UNITS_BACKGROUND
Flex Plot

FlexPlot annotated.png

Description Config Value
Changes colour of all text including the legend, graph name, and tick labels. FlexPlot::TEXT
Changes the background colour of the plot and legend. FlexPlot::BACKGROUND
Changes the colour of the frame and tick marks. FlexPlot::FRAME
Changes the colour of button text. FlexPlot::BUTTON_TEXT
Changes the background colour of buttons. FlexPlot::BUTTON_BACKGROUND
Changes the border colour of buttons. FlexPlot::BUTTON_BORDER
Changes the text colour of buttons while checked. FlexPlot::BUTTON_CHECKED_TEXT
Changes the background colour of buttons while checked. FlexPlot::BUTTON_CHECKED_BACKGROUND
Changes the border colour of buttons while checked. FlexPlot::BUTTON_CHECKED_BORDER
Changes the text colour of buttons while pressed. FlexPlot::BUTTON_PRESSED_TEXT
Changes the background colour of buttons while pressed. FlexPlot::BUTTON_PRESSED_BACKGROUND
Changes the border colour of buttons while pressed. FlexPlot::BUTTON_PRESSED_BORDER
Changes the text colour of buttons while being hovered. FlexPlot::BUTTON_HOVER_TEXT
Changes the background colour of unchecked buttons while being hovered. FlexPlot::BUTTON_HOVER_BACKGROUND_NORMAL
Changes the background colour of checked buttons while being hovered. FlexPlot::BUTTON_HOVER_BACKGROUND_CHECKED
Changes the border colour of buttons while being hovered. FlexPlot::BUTTON_HOVER_BORDER
Changes the text colour of comboboxes. FlexPlot::COMBOBOX_TEXT_COLOUR
Changes the background colour of comboboxes. FlexPlot::COMBOBOX_BACKGROUND_COLOUR
Changes the border colour of comboboxes. FlexPlot::COMBOBOX_BORDER_COLOUR
Changes the background colour of checked comboboxes. FlexPlot::COMBOBOX_CHECKED_BACKGROUND
Changes the border colour of comboboxes while being hovered. FlexPlot::COMBOBOX_HOVER_BORDER
Changes the colour of the grid pattern on the plot. FlexPlot::GRID
Console

File:Console annotated.png

Description Config Value
Changes the colour of the title text. CONSOLE::TITLE_TEXT
Changes the colour of the title background. CONSOLE::TITLE_BACKGROUND
Changes the colour of the output field text. CONSOLE::OUTPUT_TEXT
Changes the colour of the output field background. CONSOLE::OUTPUT_BACKGROUND
Changes the colour of the input field text. CONSOLE::INPUT_TEXT
Changes the colour of the input field background. CONSOLE::INPUT_BACKGROUND
Changes the colour of the control button text (Settings Dialog button, Info button, and Clear button). CONSOLE::CONTROL_BUTTON_TEXT
Changes the colour of the control button background (Settings Dialog button, Info button, and Clear button). CONSOLE::CONTROL_BUTTON_BACKGROUND
Changes the colour of the control button border (Settings Dialog button, Info button, and Clear button). CONSOLE::CONTROL_BUTTON_BORDER
Changes the colour of the control button text while being pressed (Settings Dialog button, Info button, and Clear button). CONSOLE::CONTROL_BUTTON_PRESSED_TEXT
Changes the colour of the control button background while being pressed (Settings Dialog button, Info button, and Clear button). CONSOLE::CONTROL_BUTTON_PRESSED_BACKGROUND
Changes the colour of the control button border while being pressed (Settings Dialog button, Info button, and Clear button). CONSOLE::CONTROL_BUTTON_PRESSED_BORDER
Changes the colour of the control button text while being hovered (Settings Dialog button, Info button, and Clear button). CONSOLE::CONTROL_BUTTON_HOVER_TEXT
Changes the colour of the control button background while being hovered (Settings Dialog button, Info button, and Clear button). CONSOLE::CONTROL_BUTTON_HOVER_BACKGROUND
Changes the colour of the control button border while being hovered (Settings Dialog button, Info button, and Clear button). CONSOLE::CONTROL_BUTTON_HOVER_BORDER
Changes the colour of the connect button text. CONSOLE::CONNECT_BUTTON_TEXT
Changes the colour of the connect button background. CONSOLE::CONNECT_BUTTON_BACKGROUND
Changes the colour of the connect button border. CONSOLE::CONNECT_BUTTON_BORDER
Changes the colour of the connect button text when the button is checked. CONSOLE::CONNECT_BUTTON_CHECKED_TEXT
Changes the colour of the connect button background when the button is checked. CONSOLE::CONNECT_BUTTON_CHECKED_BACKGROUND
Changes the colour of the connect button border when the button is checked. CONSOLE::CONNECT_BUTTON_CHECKED_BORDER
Changes the colour of the connect button text when the button is pressed. CONSOLE::CONNECT_BUTTON_PRESSED_TEXT
Changes the colour of the connect button background when the button is pressed. CONSOLE::CONNECT_BUTTON_PRESSED_BACKGROUND
Changes the colour of the connect button border when the button is pressed. CONSOLE::CONNECT_BUTTON_PRESSED_BORDER
Changes the colour of the connect button text when the button is hovered. CONSOLE::CONNECT_BUTTON_HOVER_TEXT
Changes the colour of the connect button background when the button is hovered and not checked. CONSOLE::CONNECT_BUTTON_HOVER_BACKGROUND_NORMAL
Changes the colour of the connect button background when the button is hovered and checked. CONSOLE::CONNECT_BUTTON_HOVER_BACKGROUND_CHECKED
Changes the colour of the connect button border when the button is hovered. CONSOLE::CONNECT_BUTTON_HOVER_BORDER
Changes the colour of the COM select menu text. CONSOLE::COM_SELECT_TEXT_COLOUR
Changes the colour of the traffic display's plain text. CONSOLE::TRAFFIC_PLAIN_TEXT
Changes the colour of the traffic display's up text and plot. CONSOLE::TRAFFIC_UP
Changes the colour of the traffic display's down text and plot. CONSOLE::TRAFFIC_DOWN
Changes the colour of the traffic display's fps text and plot. CONSOLE::TRAFFIC_FPS
Changes the colour of the traffic display's background. CONSOLE::TRAFFIC_BACKGROUND

User Interaction with Elements

Users will interact with GUI elements in many ways including clicking a button or dragging a slider to a new value. In order to improve GUI frame efficiency, the GUI's run loop can query whether or not an element has been updated since the last time it was checked. If it has not, the GUI need not check each individual element for updates.

It is also possible to query individual elements to see if they have been updated since the last check.


Flex Elements
Name Syntax Notes
argument description
Check For Element Updates Returns true when any element has changed since the last check.
check_for_element_updates();
Check For Element Click Updates Returns true when any element has been pressed or toggled since the last check.
is_button_updated();
Check For Value Updates Returns true when any element has had a change in value since the last check.
is_value_updated();
Check Element For Value Updates Returns true when the element has had a change in value since the last check.
flex_element.new_value_received(); flex_element IO_thing The element to be queried for changes. (1)
  1. All FlexElements with values are IO_things.


Special Character Parsing

Iris Controls can parse keywords into special symbols. For example, when naming an element or setting the units of a slider, the following keywords will be parsed as symbols:

Keyword Parsing
Keyword Parses To
*deg* °
*degC* °C
*alpha* α
*c* ©
*mu* µ
*ohm* Ω

Flex Button

FlexButton.png

Inherits: Flex Element

Flex Buttons are push buttons that the user can press or toggle. Toggling a button is like checking a box, the button has two states: toggled and not toggled.

Constructor

No arguments need to be passed in a Flex Button constructor.

Example:

FlexButton flexbutton();

API Commands

Instance Methods
Name Syntax Notes
arg type argument description
Add Flex Button Adds a new Flex Button
flexbutton.add(name, initValue, row, column, rowSpan, columnSpan);
or

flexbutton.add(parent, name, initValue, row, column, rowSpan, columnSpan);
parent GUI_Page* A pointer to the parent GUI Page.
name const char* The name and display text of the button.
initValue int The initial value of the button. 1 = toggled, 0 = not toggled, -1 = not toggleable.
row u16 The row the button is to be placed in.
column u16 The column the button is to be placed in.
rowSpan u16 The number of rows the button will span.
columnSpan u16 The number of columns the button will span.
Set Toggle Changes the button's toggled state
flexbutton.set_toggle(status); status int 1 = toggled, 0 = not toggled
Reset Colours Resets this instance's colours to defaults.
flexbutton.reset_this_flexbutton_default_colours();
Static Methods
Name Syntax Notes
arg type argument description
Set Default Colour Sets the Default Colour of an Aspect of the Element
FlexButton::set_default_colour(flag, r, g, b, a); flag FlexButton::COLOUR_SET_FLAG The aspect of the element to change. (1)
r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
Reset All FlexButton Default Colours Resets all FlexButton default colours.
FlexButton::reset_all_flexbutton_default_colours();
  1. See table for allowed element aspects.


Feedback

Users can interact with Flex Buttons in two ways: pressing and toggling. There are three ways to check the state of a Flex Button.

Flex Buttons
Name Syntax Notes
arg type argument description
Get Returns the current value of the button. A toggled button's value is 1. An un-toggled button's value is 0.
flexbutton.get();
Pressed Returns true (1) if the button was pressed since the last time this function was called. Returns false (0) otherwise.
flexbutton.pressed();
Toggled Returns true (1) if the button was toggled since the last time this function was called. Returns false (0) otherwise.
flexbutton.toggled();


Flex Slider

A FlexSlider with units

Inherits: Flex Element

Flex Sliders are objects made up of a label, a horizontal slider, and an input/output text box. They can be created as either input/output devices or strictly output ones. As input devices, users can drag the slider with a mouse, or type a value into the text box. Either method of entry will update the other and report the new value over the USB connection.

Denominators

Principles

A denominator can be applied to the output value of the Flex Slider in order to accomplish a unit conversion. In essence, all values sent to the slider will be divided by the denominator while all values coming from the slider will be multiplied by the denominator.

For example, if you wish to display a frequency value that is expressed in Hz, a denominator of 1000 can be applied to an output slider to display frequency in kHz. flexslider.update(1000); will display on the slider as 1. In this case, when adding the slider, use "kHz" for the units field.

Building the Slider

When choosing minimum and maximum values for a slider with a denominator, choose values that have already had the denominator applied. For example, if a slider with denominator 1000 should accept values between -20,000 and +20,000, the apparent minimum and maximum values will be -20,000/1000 = -20 and 20,000/1000 = 20 respectively.

The initial value and all subsequent updates will have the denominated applied to them, so to see an initial value of 10, the initial value should be 10,000 when using a denominator of 1000.

Transfer of Data

When updating a slider by calling flexslider.update(value);, the value displayed will always be value/denominator.

When retrieving a slider's data by calling flexslider.get(); the value returned will be the slider's apparent value times the denominator.

For example, a slider with denominator 1000 has flexslider.update(2000); called. It will show as 2. If flexslider.get(); is called for that same slider, it will return 2000.

Constructor

No arguments need to be passed in a Flex Slider constructor.

Example:

FlexSlider flexslider();

API Commands

Instance Methods
Name Syntax Notes
arg type argument description
Add Flex Slider Adds a new Flex Slider

flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, config);


or

flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, config);


or

flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator);


or

flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator);

parent GUI_Page* A pointer to the parent GUI Page. (1)
name const char* The name and visible label of the slider.
row u16 The row the slider is to be placed in.
column u16 The row the slider is to be placed in.
rowSpan u16 The number of rows the slider will span.
columnSpan u16 The number of columns the slider will span.
min int / double The minimum value the slider can display.
max int / double The maximum value the slider can display.
initValue int / double The initial value the slider will hold.
denominator u16 The factor by which values are divided before being displayed (e.g. if denominator = 100 then flexslider.update(1000); displays 10.)
config u16 A configuration flag. See the configuration section below. (optional)
Add Flex Slider Adds a new Flex Slider With Units

flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units, config);


or

flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units, config);


or

flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units);


or

flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units);

parent GUI_Page* A pointer to the parent GUI Page. (1)
name const char* The name and visible label of the slider.
row u16 The row the slider is to be placed in.
column u16 The row the slider is to be placed in.
rowSpan u16 The number of rows the slider will span.
columnSpan u16 The number of columns the slider will span.
min int / double The minimum value the slider can display.
max int / double The maximum value the slider can display.
initValue int / double The initial value the slider will hold.
denominator u16 The factor by which values are divided before being displayed (e.g. if denominator = 100 then flexslider.update(1000); displays 10.)
units string Display name of the units field. Must not contain whitespaces; underscores are converted to whitespace.
config u16 A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Slider Re-Configure Flex Slider
flexslider.config(configuration); configuration u16 The new configuration flag.
Update Flex Slider Sets the slider to a new value
flexslider.update(int value);
flexslider.update(u16 value);
flexslider.update(u32 value);
flexslider.update(s32 value);
flexslider.update(float value);
value int
u16
u32
s32
float
The new value of the slider.
Set Slider Range Sets the minimum and maximum values the slider can display
flexslider.set_range(min, max); min s32 The minimum value the slider can display. (2)
max s32 The maximum value the slider can display.
Reset Colours Resets this instance's colours to defaults.
flexslider.reset_this_flexslider_default_colours();
  1. Note: min, maximum, and initValue may be all integers or all doubles but no combination of types is accepted.
  2. Sliders may be updated with values outside their range. In this case, the written value will reflect the actual value while the slider handle remains at its minimum/maximum limit.
Static Methods
Name Syntax Notes
arg type argument description
Set Default Colour Sets the Default Colour of an Aspect of the Element
FlexSlider::set_default_colour(flag, r, g, b, a); flag FlexSlider::COLOUR_SET_FLAG The aspect of the element to change. (1)
r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
Reset All FlexSlider Default Colours Resets all FlexSlider default colours.
FlexSlider::reset_all_flexslider_default_colours();
  1. See table for allowed element aspects.


Configuration

Flex Sliders have a variety of configuration options.

Configuration
Configuration Element Description Config Value
Input Allows the Flex Slider to be used as an input device. (1) FlexSlider::ALLOW_INPUT
Not Tracking Prevents the slider from sending updates as it is dragged. If this is selected, it only update the device when the user stops dragging with the mouse. It will not update when using the keyboard or mouse wheel to adjust the slider value. FlexSlider::NOT_TRACKING
Units Field Adds a text field to the right of the slider's value that can display units or other useful data. FlexSlider::UNITS
Frame Draws a frame around the value box. FlexSlider::FRAME
Digits of Precision Sets the number of decimal places for the slider where X is an int between 1 and 7. FlexSlider::PRECISION_X
Mirrored Horizontally mirrors the slider. FlexSlider::MIRRORED
Size of Value Sets the number of digits the value can hold where X is an int (1-8, 10, 12, 14, 18, 22, 26, 30, or 34). The default is 7 digits. FlexSlider::DIGITS_X
Binary Numerical System Sets the numerical system to binary. Output is shown in binary format. FlexSlider::BINARY
Hexadecimal Numerical System Sets the numerical system to hexadecimal. Output is shown in hexadecimal format. FlexSlider::HEXADECIMAL
Unsigned Decimal System Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer. FlexSlider::UNSIGNED_DECIMAL
Value Field Alignment Decimal System Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer. FlexSlider::UNSIGNED_DECIMAL
Align Value Left Aligns the value characters left. FlexSlider::VALUE_ALIGN_LEFT
Align Value Center Aligns the value characters center. FlexSlider::VALUE_ALIGN_CENTER
Align Value Right Aligns the value characters right. FlexSlider::VALUE_ALIGN_RIGHT

Example: To make the slider an input element with a frame around the value box use config = 1 + 8 = 9 or config = FlexSlider::INPUT + FlexSlider::FRAME

  1. When a FlexSlider is NOT an input slider, the handle cannot be dragged. To make colour changes to this type of slider use disabled flags like the FlexSlider::HANDLE_DISABLED flag.

Feedback

Flex Sliders will send any changed values to the device as soon as those changes are made. To retrieve the new value, call one of the following functions:

Flex Sliders
Name Syntax Notes
arg type argument description
Get Integer Value Returns the integer value of the slider. (1)
flexslider.get();
Get Float Value Returns the float value of the slider.
flexslider.get_f();
Pressed Returns true (1) if the element was clicked since the last time this function was called. Returns false (0) otherwise.
flexslider.pressed();
  1. The integer value is the float value multiplied by the total factor which is the multiple of 10 required to express the float value as an int without losing any data.


Numerical Systems

By default, Flex Sliders use the decimal system to express their value in the text field. If user input is enabled, the text field will only accept integers between -999999 and 999999. Any other character will cause the entry to be rejected.

If the config option FlexSlider::BINARY or FlexSlider::HEXADECIMAL or FlexSlider::UNSIGNED_DECIMAL is used, the value of the slider will always be expressed in the chosen numerical system. If user input is enabled, the text field will accept entries in any of the formats (decimal, binary, or hexadecimal). The entered figure will be translated into the chosen numerical system. For example, if the hexadecimal numerical system is set, and the user enters 100, the text field will display 0x64. If the user enters 0b100, the text field will display 0x4.

To input a value in binary format, the following syntax must be used: 0b[number] where number is a value in binary.

To input a value in hexadecimal format, the following syntax must be used: 0x[number] where number is a value in hexadecimal.

Basic Flex Slider

A FlexSlider with units

Inherits: Flex Element

Basic Flex Sliders are objects made up of a label, a horizontal slider, and an input/output text box. They can be created as either input/output devices or strictly output ones. As input devices, users can drag the slider with a mouse, or type a value into the text box. Either method of entry will update the other and report the new value over the USB connection.

Constructor

No arguments need to be passed in a Basic Flex Slider constructor.

Example:

Basic_FlexSlider flexslider();

API Commands

Instance Methods
Name Syntax Notes
arg type argument description
Add Flex Slider Adds a new Flex Slider

flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, config);


or

flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, config);


or
flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator);

or
flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator);
parent GUI_Page* A pointer to the parent GUI Page.
name const char* The name and visible label of the slider.
row u16 The row the slider is to be placed in.
column u16 The row the slider is to be placed in.
rowSpan u16 The number of rows the slider will span.
columnSpan u16 The number of columns the slider will span.
min int The minimum value the slider can display.
max int The maximum value the slider can display.
initValue int The initial value the slider will hold.
denominator u16 The factor by which values are divided before being displayed (e.g. if denominator = 100 then flexslider.update(1000); displays 10.)
config u16 A configuration flag. See the configuration section below. (optional)
Add Flex Slider Adds a new Flex Slider With Units
flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units, config);
or
flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units);
name string The name and visible label of the slider.
row u16 The row the slider is to be placed in.
column u16 The row the slider is to be placed in.
rowSpan u16 The number of rows the slider will span.
columnSpan u16 The number of columns the slider will span.
min int The minimum value the slider can display.
max int The maximum value the slider can display.
initValue int The initial value the slider will hold.
denominator u16 The factor by which values are divided before being displayed (e.g. if denominator = 100 then flexslider.update(1000); displays 10.)
units string Display name of the units field. Must not contain whitespaces; underscores are converted to whitespace.
config u16 A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Slider Re-Configure Flex Slider
flexslider.config(configuration); configuration u16 The new configuration flag.
Update Flex Slider Sets the slider to a new value
flexslider.update(int value);
flexslider.update(u16 value);
flexslider.update(u32 value);
flexslider.update(s32 value);
value int
u16
u32
s32
float
The new value of the slider.
Set Slider Range Sets the minimum and maximum values the slider can display
flexslider.set_range(min, max); min s32 The minimum value the slider can display. (1)
max s32 The maximum value the slider can display.
Reset Colours Resets this instance's colours to defaults.
flexslider.reset_this_flexslider_default_colours();
  1. Sliders may be updated with values outside their range. In this case, the written value will reflect the actual value while the slider handle remains at its minimum/maximum limit.
Static Methods
Name Syntax Notes
arg type argument description
Set Default Colour Sets the Default Colour of an Aspect of the Element
FlexSlider::set_default_colour(flag, r, g, b, a); flag FlexSlider::COLOUR_SET_FLAG The aspect of the element to change. (1)
r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
  1. See table for allowed element aspects.


Configuration

Flex Sliders have a variety of configuration options.

Configuration
Configuration Element Description Config Value
Input Allows the Flex Slider to be used as an input device. (1) FlexSlider::ALLOW_INPUT
Not Tracking Prevents the slider from sending updates as it is dragged. If this is selected, it only update the device when the user stops dragging with the mouse. It will not update when using the keyboard or mouse wheel to adjust the slider value. FlexSlider::NOT_TRACKING
Units Field Adds a text field to the right of the slider's value that can display units or other useful data. FlexSlider::UNITS
Frame Draws a frame around the value box. FlexSlider::FRAME
Digits of Precision Sets the number of decimal places for the slider where X is an int between 1 and 7. FlexSlider::PRECISION_X
Mirrored Horizontally mirrors the slider. FlexSlider::MIRRORED
Size of Value Sets the number of digits the value can hold where X is an int (1-8, 10, 12, 14, 18, 22, 26, 30, or 34). The default is 7 digits. FlexSlider::DIGITS_X
Binary Numerical System Sets the numerical system to binary. Output is shown in binary format. FlexSlider::BINARY
Hexadecimal Numerical System Sets the numerical system to hexadecimal. Output is shown in hexadecimal format. FlexSlider::HEXADECIMAL
Unsigned Decimal System Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer. FlexSlider::UNSIGNED_DECIMAL
Value Field Alignment Decimal System Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer. FlexSlider::UNSIGNED_DECIMAL
Align Value Left Aligns the value characters left. FlexSlider::VALUE_ALIGN_LEFT
Align Value Center Aligns the value characters center. FlexSlider::VALUE_ALIGN_CENTER
Align Value Right Aligns the value characters right. FlexSlider::VALUE_ALIGN_RIGHT

Example: To make the slider an input element with a frame around the value box use config = 1 + 8 = 9 or config = FlexSlider::INPUT + FlexSlider::FRAME

  1. When a FlexSlider is NOT an input slider, the handle cannot be dragged. To make colour changes to this type of slider use disabled flags like the FlexSlider::HANDLE_DISABLED flag.

Feedback

Flex Sliders will send any changed values to the device as soon as those changes are made. To retrieve the new value, call one of the following functions:

Flex Sliders
Name Syntax Notes
arg type argument description
Get Integer Value Returns the integer value of the slider. (1)
flexslider.get();
Pressed Returns true (1) if the element was clicked since the last time this function was called. Returns false (0) otherwise.
flexslider.pressed();


Numerical Systems

By default, Flex Sliders use the decimal system to express their value in the text field. If user input is enabled, the text field will only accept integers between -999999 and 999999. Any other character will cause the entry to be rejected.

If the config option FlexSlider::BINARY or FlexSlider::HEXADECIMAL or FlexSlider::UNSIGNED_DECIMAL is used, the value of the slider will always be expressed in the chosen numerical system. If user input is enabled, the text field will accept entries in any of the formats (decimal, binary, or hexadecimal). The entered figure will be translated into the chosen numerical system. For example, if the hexadecimal numerical system is set, and the user enters 100, the text field will display 0x64. If the user enters 0b100, the text field will display 0x4.

To input a value in binary format, the following syntax must be used: 0b[number] where number is a value in binary.

To input a value in hexadecimal format, the following syntax must be used: 0x[number] where number is a value in hexadecimal.

Flex Label

FlexLabel.png

Inherits: Flex Element

Flex Labels are simple text fields. They are output only elements.

Constructor

The Flex Label constructor takes no arguments.

Example: FlexLabel flexlabel();

API Commands

Instance Methods
Name Syntax Notes
arg type argument description
Add Flex Label Adds a new Flex Label

flexlabel.add(name, row, column, rowSpan, columnSpan, config);


or

flexlabel.add(parent, name, row, column, rowSpan, columnSpan, config);


or

flexlabel.add(name, row, column, rowSpan, columnSpan);


or

flexlabel.add(parent, name, row, column, rowSpan, columnSpan);

parent GUI_Page* A pointer to the parent GUI Page.
name const char* The name and visible text of the label.
row u16 The row the label is to be placed in.
column u16 The column the label is to be placed in.
rowSpan u16 The number of rows the label will span.
columnSpan u16 The number of columns the label will span.
config u16 A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Label Re-Configure Flex Label
flexlabel.config(config); config u16 The new configuration flag. See the configuration section below.
Reset Colours Resets this instance's colours to defaults.
flexlabel.reset_this_flexlabel_default_colours();
Static Methods
Name Syntax Notes
arg type argument description
Set Default Colour Sets the Default Colour of an Aaspect of the Element
FlexLabel::set_default_colour(flag, r, g, b, a); flag FlexLabel::COLOUR_SET_FLAG The aspect of the element to change. (1)
r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
Reset All FlexLabel Default Colours Resets all FlexLabel default colours.
FlexLabel::reset_all_flexlabel_default_colours();
  1. See table for allowed element aspects.


Configuration

Flex Label elements have a variety of configuration options.

Configuration
Configuration Element Description Config Value
Name Decimal
Align Center Sets the text alignment of the label. FlexLabel::ALIGN_CENTER 1
Align Right Sets the text alignment of the label. FlexLabel::ALIGN_RIGHT 2

Clickable Flex Label

FlexLabel.png

Inherits: Flex Element

Clickable Flex Labels are Flex Labels that report user clicks to the device.

Constructor

The Clickable Flex Label constructor takes no arguments.

Example: C_FlexLabel flexlabel();

API Commands

Instance Methods
Name Syntax Notes
arg type argument description
Add Flex Label Adds a new Flex Label

flexlabel.add(name, row, column, rowSpan, columnSpan, config);


or

flexlabel.add(parent, name, row, column, rowSpan, columnSpan, config);


or

flexlabel.add(name, row, column, rowSpan, columnSpan);


or

flexlabel.add(parent, name, row, column, rowSpan, columnSpan);

parent GUI_Page* A pointer to the parent GUI Page.
name const char* The name and visible text of the label.
row u16 The row the label is to be placed in.
column u16 The column the label is to be placed in.
rowSpan u16 The number of rows the label will span.
columnSpan u16 The number of columns the label will span.
config u16 A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Label Re-Configure Flex Label
flexlabel.config(config); config u16 The new configuration flag. See the configuration section below.
Reset Colours Resets this instance's colours to defaults.
flexlabel.reset_this_flexlabel_default_colours();
Static Methods
Name Syntax Notes
arg type argument description
Set Default Colour Sets the Default Colour of an Aaspect of the Element
FlexLabel::set_default_colour(flag, r, g, b, a); flag FlexLabel::COLOUR_SET_FLAG The aspect of the element to change. (1)
r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
  1. See table for allowed element aspects.


Configuration

Flex Label elements have a variety of configuration options.

Configuration
Configuration Element Description Config Value
Name Decimal
Align Center Sets the text alignment of the label. FlexLabel::ALIGN_CENTER 1
Align Right Sets the text alignment of the label. FlexLabel::ALIGN_RIGHT 2

Feedback

Clickable Flex Label
Name Syntax Notes
arg type argument description
Pressed Returns true (1) if the element was clicked since the last time this function was called. Returns false (0) otherwise.
flexlabel.pressed();

Flex Data

FlexData.png

Inherits: Flex Element

The Flex Data element consists of a label and a data field. The data field accepts/displays numerical data and can be configured to be an input/output or output only. The colour of the text in the Flex Data is configurable.

Denominators

Principles

A denominator can be applied to the output value of the Flex Data in order to accomplish a unit conversion. In essence, all values sent to the element will be divided by the denominator while all values coming from the element will be multiplied by the denominator.

For example, if you wish to display a frequency value that is expressed in Hz, a denominator of 1000 can be applied to display frequency in kHz. flexdata.update(1000); will display on the Flex Data as 1. In this case, when adding the element, use "kHz" for the units field.

Building the Slider

The initial value and all subsequent updates will have the denominator applied to them so to see an initial value of 10 with a denominator of 100, use initial value 10,000.

Transfer of Data

When updating a Flex Data by calling flexdata.update(value);, the value displayed will always be value/denominator.

When retrieving data by calling flexdata.get(); the value returned will be the element's apparent value times the denominator.

For example, a Flex Data with denominator 1000 has flexdata.update(2000); called. It will show as 2. If flexdata.get(); is called for that same element, it will return 2000.

Constructor

No arguments need to be passed in a Flex Data constructor.

Example:

FlexData flexdata();

API Commands

Instance Methods
Name Syntax Notes
arg type argument description
Add Flex Data Adds a new Flex Data

flexdata.add(name, row, column, rowSpan, columnSpan, initValue, denominator, config);


or

flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, denominator, config);


or

flexdata.add(name, row, column, rowSpan, columnSpan, initValue, denominator);


or

flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, denominator);

parent GUI_Page* A pointer to the parent GUI Page.
name const char* The name and visible label of the element.
row u16 The row the element is to be placed in.
column u16 The row the element is to be placed in.
rowSpan u16 The number of rows the element will span.
columnSpan u16 The number of columns the element will span.
initValue float The initial value the element will hold.
denominator u16 The factor by which to multiply the value of the Data to get a whole number. (e.g. for two digits of precision, denominator = 100)
config u16 A configuration flag. See the configuration section below. (optional)
Add Flex Data Adds a new Flex Data With Units

flexdata.add(name, row, column, rowSpan, columnSpan, initValue, denominator, units, config);


or

flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, denominator, units, config);


or

flexdata.add(name, row, column, rowSpan, columnSpan, initValue, denominator, units);


or

flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, denominator, units);

parent GUI_Page* A pointer to the parent GUI Page.
name const char* The name and visible label of the element.
row u16 The row the element is to be placed in.
column u16 The row the element is to be placed in.
rowSpan u16 The number of rows the element will span.
columnSpan u16 The number of columns the element will span.
initValue float The initial value the element will hold.
denominator u16 The factor by which to multiply the value of the Data to get a whole number. (e.g. for two digits of precision, denominator = 100)
units string Display name of the units field. Must not contain whitespaces; underscores are converted to whitespace.
config u16 A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Data Re-Configure Flex Data
flexdata.config(configuration); configuration u16 The new configuration flag.
Update Flex Data Sets the Data to a new value.
flexdata.update(int value);
flexdata.update(u16 value);
flexdata.update(u32 value);
flexdata.update(s32 value);
flexdata.update(float value);
value int
u16
u32
s32
float
The new value of the slider.
Reset Colours Resets this instance's colours to defaults.
flexdata.reset_this_flexdata_default_colours();
Static Methods
Name Syntax Notes
arg type argument description
Set Default Colour Sets the Default Colour of an Aspect of the Element
FlexData::set_default_colour(flag, r, g, b, a); flag FlexData::COLOUR_SET_FLAG The aspect of the element to change. (1)
r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
Reset All FlexData Default Colours Resets all FlexData default colours.
FlexData::reset_all_flexdata_default_colours();
  1. See table for allowed element aspects.


Configuration

Flex Data elements have a variety of configuration options.

Configuration
Configuration Element Description Config Value
Input Allows the Flex Data to be used as an input element. FlexData::ALLOW_INPUT
Frame Draws a frame around the value box. FlexData::FRAME
Units Field Adds a text field to the right of the element's value that can display units or other useful data. FlexData::UNITS
Digits of Precision Sets the number of decimal places for the element where X is an int between 1 and 7. FlexData::PRECISION_X
Mirrored Horizontally mirrors the element. FlexData::MIRRORED
Size of Value Sets the number of digits the value can hold where X is an int (1-8, 10, 12, 14, 18, 22, 26, 30, or 34). The default is 7 digits. FlexData::DIGITS_X
Binary Numerical System Sets the numerical system to binary. Output is shown in binary format. FlexData::BINARY
Hexadecimal Numerical System Sets the numerical system to hexadecimal. Output is shown in hexadecimal format. FlexData::HEXADECIMAL
Unsigned Decimal System Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer. FlexData::UNSIGNED_DECIMAL
Align Label Left Aligns the label characters left. FlexData::LABEL_ALIGN_LEFT
Align Label Center Aligns the label characters center. FlexData::LABEL_ALIGN_CENTER
Align Label Right Aligns the label characters right. FlexData::LABEL_ALIGN_RIGHT
Align Value Left Aligns the value characters left. FlexData::VALUE_ALIGN_LEFT
Align Value Center Aligns the value characters center. FlexData::VALUE_ALIGN_CENTER
Align Value Right Aligns the value characters right. FlexData::VALUE_ALIGN_RIGHT
Align Units Left Aligns the units characters left. FlexData::UNITS_ALIGN_LEFT
Align Units Center Aligns the units characters center. FlexData::UNITS_ALIGN_CENTER
Align Units Right Aligns the units characters right. FlexData::UNITS_ALIGN_RIGHT

Example: To make the element an input element with a frame around the value box use config = 1 + 2 = 3 or config = FlexData::INPUT + FlexData::FRAME

Feedback

Flex Data
Name Syntax Notes
arg type argument description
Get Integer Value Returns the integer value of the Data. (1)
flexdata.get();
Get Float Value Returns the float value of the Data.
flexdata.get_f();
Pressed Returns true (1) if the element was clicked since the last time this function was called. Returns false (0) otherwise.
flexdata.pressed();
  1. The integer value is the float value multiplied by the total factor which is the multiple of 10 required to express the float value as an int without losing any data.


Numerical Systems

By default, Flex Datas use the decimal system to express their value in the text field. If user input is enabled, the text field will only accept integers between -999999 and 999999. Any other character will cause the entry to be rejected.

If the config option FlexData::BINARY or FlexData::HEXADECIMAL or FlexData::UNSIGNED_DECIMAL is used, the value of the Flex Data will always be expressed in the chosen numerical system. If user input is enabled, the text field will accept entries in any of the formats (decimal, binary, or hexadecimal). The entered figure will be translated into the chosen numerical system. For example, if the hexadecimal numerical system is set, and the user enters 100, the text field will display 0x64. If the user enters 0b100, the text field will display 0x4.

To input a value in binary format, the following syntax must be used: 0b[number] where number is a value in binary.

To input a value in hexadecimal format, the following syntax must be used: 0x[number] where number is a value in hexadecimal.

Basic Flex Data

FlexData.png

Inherits: Flex Element

The Basic Flex Data element consists of a label and a data field. The data field accepts/displays numerical data and can be configured to be an input/output or output only. The colour of the text in the Basic Flex Data is configurable.

Constructor

No arguments need to be passed in a Basic Flex Data constructor.

Example:

Basic_FlexData flexdata();

API Commands

TITLE
Name Syntax Notes
arg type argument description
Add Flex Data Adds a new Flex Data

flexdata.add(name, row, column, rowSpan, columnSpan, initValue, config);


or

flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, config);


or

flexdata.add(name, row, column, rowSpan, columnSpan, initValue);


or

flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue);

parent GUI_Page* A pointer to the parent GUI Page.
name const char* The name and visible label of the element.
row u16 The row the element is to be placed in.
column u16 The row the element is to be placed in.
rowSpan u16 The number of rows the element will span.
columnSpan u16 The number of columns the element will span.
initValue int The initial value the element will hold.
config u16 A configuration flag. See the configuration section below. (optional)
Add Flex Data Adds a new Flex Data With Units

flexdata.add(name, row, column, rowSpan, columnSpan, initValue, units, config);


or

flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, units, config);


or

flexdata.add(name, row, column, rowSpan, columnSpan, initValue, units);


or

flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, units);

parent GUI_Page* A pointer to the parent GUI Page.
name const char* The name and visible label of the element.
row u16 The row the element is to be placed in.
column u16 The row the element is to be placed in.
rowSpan u16 The number of rows the element will span.
columnSpan u16 The number of columns the element will span.
initValue int The initial value the element will hold.
units string Display name of the units field. Must not contain whitespaces; underscores are converted to whitespace.
config u16 A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Data Re-Configure Flex Data
flexdata.config(configuration); configuration u16 The new configuration flag.
Update Flex Data Sets the Data to a new value.
flexdata.update(int value);
flexdata.update(u16 value);
flexdata.update(u32 value);
flexdata.update(s32 value);
value int
u16
u32
s32
The new value of the slider.
Reset Colours Resets this instance's colours to defaults.
flexdata.reset_this_flexdata_default_colours();
Static Methods
Name Syntax Notes
arg type argument description
Set Default Colour Sets the Default Colour of an Aspect of the Element
FlexData::set_default_colour(flag, r, g, b, a); flag FlexData::COLOUR_SET_FLAG The aspect of the element to change. (1)
r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
  1. See table for allowed element aspects.


Configuration

Flex Data elements have a variety of configuration options.

Configuration
Configuration Element Description Config Value
Input Allows the Flex Data to be used as an input element. FlexData::ALLOW_INPUT
Frame Draws a frame around the value box. FlexData::FRAME
Units Field Adds a text field to the right of the element's value that can display units or other useful data. FlexData::UNITS
Digits of Precision Sets the number of decimal places for the element where X is an int between 1 and 7. FlexData::PRECISION_X
Mirrored Horizontally mirrors the element. FlexData::MIRRORED
Size of Value Sets the number of digits the value can hold where X is an int (1-8, 10, 12, 14, 18, 22, 26, 30, or 34). The default is 7 digits. FlexData::DIGITS_X
Binary Numerical System Sets the numerical system to binary. Output is shown in binary format. FlexData::BINARY
Hexadecimal Numerical System Sets the numerical system to hexadecimal. Output is shown in hexadecimal format. FlexData::HEXADECIMAL
Unsigned Decimal System Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer. FlexData::UNSIGNED_DECIMAL
Align Label Left Aligns the label characters left. FlexData::LABEL_ALIGN_LEFT
Align Label Center Aligns the label characters center. FlexData::LABEL_ALIGN_CENTER
Align Label Right Aligns the label characters right. FlexData::LABEL_ALIGN_RIGHT
Align Value Left Aligns the value characters left. FlexData::VALUE_ALIGN_LEFT
Align Value Center Aligns the value characters center. FlexData::VALUE_ALIGN_CENTER
Align Value Right Aligns the value characters right. FlexData::VALUE_ALIGN_RIGHT
Align Units Left Aligns the units characters left. FlexData::UNITS_ALIGN_LEFT
Align Units Center Aligns the units characters center. FlexData::UNITS_ALIGN_CENTER
Align Units Right Aligns the units characters right. FlexData::UNITS_ALIGN_RIGHT

Example: To make the element an input element with a frame around the value box use config = 1 + 2 = 3 or config = FlexData::INPUT + FlexData::FRAME

Feedback

Flex Data
Name Syntax Notes
arg type argument description
Get Integer Value Returns the integer value of the Data. (1)
flexdata.get();
Pressed Returns true (1) if the element was clicked since the last time this function was called. Returns false (0) otherwise.
flexdata.pressed();


Numerical Systems

By default, Flex Datas use the decimal system to express their value in the text field. If user input is enabled, the text field will only accept integers between -999999 and 999999. Any other character will cause the entry to be rejected.

If the config option FlexData::BINARY or FlexData::HEXADECIMAL or FlexData::UNSIGNED_DECIMAL is used, the value of the Flex Data will always be expressed in the chosen numerical system. If user input is enabled, the text field will accept entries in any of the formats (decimal, binary, or hexadecimal). The entered figure will be translated into the chosen numerical system. For example, if the hexadecimal numerical system is set, and the user enters 100, the text field will display 0x64. If the user enters 0b100, the text field will display 0x4.

To input a value in binary format, the following syntax must be used: 0b[number] where number is a value in binary.

To input a value in hexadecimal format, the following syntax must be used: 0x[number] where number is a value in hexadecimal.

Plotting

IrisControls4 supports real-time plotting of data. In order to display data, a Flex Plot must first be added to the main window. Once displayed, data points can be saved as a text file by the user. If Iris Controls unexpectedly loses connection with the motor due to a crash or otherwise, all datasets are automatically saved to data files.

Flex Plot

FlexPlot.png

Inherits: Flex Element

The Flex Plot is the element that displays the data contained within datasets. It could be thought of as a blank piece of graphing paper. Flex Plots are Flex Elements and therefore can be moved, resized, hidden, shown, renamed, and deleted. Deleting a Flex Plot will cause any Datasets assigned that that Flex Plot to be unassigned. By default, Flex Plots have a grey background but there is an API to change that colour. Flex Plots can be configured to "walk" as new data is added, and the x-axis can be configured to display time in a clear readable format.

Constructor

FlexPlot flexplot();

API Commands

Instance Methods
Name Syntax Notes
arg type argument description
Add Flex Plot Adds the main plot element to the window

flexplot.add(name, row, column, rowSpan, columnSpan, min, max, config);


or

flexplot.add(parent, name, row, column, rowSpan, columnSpan, min, max, config);


or

flexplot.add(name, row, column, rowSpan, columnSpan, min, max);


or

flexplot.add(parent, name, row, column, rowSpan, columnSpan, min, max);

parent GUI_Page* A pointer to the parent GUI Page. (1)
name const char* The name of the plot.
row u16 The row the plot element is to be placed in.
column u16 The column the plot element is to be placed in.
rowSpan u16 The number of rows the plot element will span.
columnSpan u16 The number of columns the plot element will span.
min float Sets the lower bound of the range for the primary y-axis.
max float Sets the upper bound of the range for the primary y-axis.
config u16 The configuration value. See configuration section below. (optional)
Config Plot I/O Configures the available I/O elements for plotting.
flexplot.config(config); config u16 The configuration value. See configuration section below.
Set Primary Range Sets the range of the y-axis for the Flex Plot
flexplot.setRange(min, max); min float The lower bound of the range.
max float The upper bound of the range.
Set Secondary Range Sets the range of the secondary (right) y-axis for the Flex Plot
flexplot.set_secondary_range(min, max); min float The lower bound of the range.
max float The upper bound of the range.
Set Domain Sets the domain of the x-axis of the Flex Plot
flexplot.setDomain(min, max); min float The lower bound of the domain.
max float The upper bound of the domain.
Set Walking Domain Sets the domain of the x-axis of the Flex Plot for walking plots
flexplot.setDomain(domain); domain int The size of the domain in the x-axis units. For time plots, the units are seconds.
Set Max Number of Visible Datapoints Sets the maximum number of datapoints that will be displayed on the plot without user intervention
flexplot.setVisibleDatapoints(datapoints); datapoints u16 The max number of datapoints to display. (2)
Set Axes Labels Sets the axes labels of the Flex Plot to that of the Dataset specified
flexplot.setAxesLabels(&dataset) dataset Dataset* The Dataset from which the labels are to be used.
Reset Colours Resets this instance's colours to defaults.
flexplot.reset_this_flexplot_default_colours();
  1. The minimum size of the main plot element is 6x6 rows/columns.
  2. All datapoints (up to the maximum dataset size) are retained, they simply won't be visible unless the user uses mouse control to zoom and/or pan.


Static Methods
Name Syntax Notes
arg type argument description
Set Default Colour Sets the Default Colour of an Aspect of the Element
FlexPlot::set_default_colour(flag, r, g, b, a); flag FlexPlot::COLOUR_SET_FLAG The aspect of the element to change. (1)
r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
Reset All FlexPlot Default Colours Resets all FlexPlot default colours.
FlexPlot::reset_all_flexplot_default_colours();
  1. See table for allowed element aspects.

Configuration

Configuration
Configuration Element Description Config Value
Name Decimal
Legend A legend to show which plot line is from which Dataset. FlexPlot::LEGEND 1
Legend Toggle Button A push button that toggles the plot's legend on and off. FlexPlot::LEGEND_BUTTON 2
Mouse Control Toggle Button A push button that enables/disables mouse control. When enabled the user can drag the plot and use the mousewheel to zoom. When disabled, the plot automatically adjusts zoom to show all visible data. FlexPlot::MOUSE_BUTTON 4
Save Data Button A push button that saves all data points from all visible datasets to a text file. FlexPlot::SAVE_DATA_BUTTON 8
Dataset Select Menu A drop down menu that allows the user to select which datasets are displayed. FlexPlot::DATASET_SELECT_MENU 16
Axis Label Select Menu A drop down menu that allows the user to select which dataset's axes labels are displayed. FlexPlot::AXES_LABEL_MENU 32
Time Plot Assigns the x-axis of the Flex Plot to display time. FlexPlot::TIMEPLOT 64
Walking Plot Assigns the Flex Plot as a walking plot. FlexPlot::WALKING 128
Plot Label Prints the Flex Plot's label above the plot. FlexPlot::NAME_LABEL 256

Example: To include the Save Data Button and the Dataset Select Menu config = 8 + 16 = 24 or config = FlexPlot::SAVE_DATA_BUTTON + FlexPlot::DATASET_SELECT_MENU

Datasets

Datasets are containers for pairs of data points. Each Dataset is assigned to a FlexPlot upon which it can be displayed. Datasets are limited in the number of pairs of data they can contain. When a Dataset reaches its maximum size, the Dataset will function as a FIFO register. The limit is defined in the FlexPlot.h header file and is typically set to 100,000. The data contained in a Dataset can be saved to a text file (if it is currently visisble on its assigned FlexPlot) by clicking the Save Data button (if enabled by that FlexPlot's configuration). The colour of the plot line of a Dataset is automatically assigned but there is an API to select different colours. By default, plotted data points are marked with a cross and are connected by straight lines. Both these behaviours are adjustable using the configuration flag.

Constructor

Dataset dataset();

API Commands

DataSets
Name Syntax Notes
arg type argument description
Add Dataset Adds a new Dataset
dataset.add(flexplot, name, x_label, y_label, config); flexplot FlexPlot* The Flex Plot this Dataset will be initially assigned to.
name string The name of the Dataset. This will appear in the legend and on save files.
x_label string The label of the x-axis data.
y_label string The label of the y-axis data.
config u16 The configuration flag of the dataset.
Set Maximum Dataset Size Sets the maximum number of data points Iris Controls will save in the Dataset before deleting old data as new data is added. (Default is 100,000)
dataset.set_max_data_points(number_of_datapoints); number_of_datapoints u32 The maximum number of data points (pairs of x and y values).
Remove Dataset Deletes the Dataset and all its data
dataset.remove();
Hide Dataset Hides the Dataset's plot.
dataset.hide();
Show Dataset Reveals the Dataset's plot
dataset.show();
Add Data Adds data points to the Dataset
dataset.add_data(int xData, int yData);
dataset.add_data(u16 xData, u16 yData);
dataset.add_data(u32 xData, u32 yData);
dataset.add_data(s32 xData, s32 yData);
dataset.add_data(float xData, float yData);
xData int
u16
u32
s32
float
The x value.
yData int
u16
u32
s32
float
The y value.
Add Data Adds data points to the Dataset
dataset.add_data(int dataPairs, int xData[] int yData[]);
dataset.add_data(int dataPairs, int xData[] int yData[]);
dataPairs int The size of the xData and yData arrays.
xData[] int
float
An array of x values.
yData[] int
float
An array of y values.
Purge Dataset Purges the Dataset of all data.
dataset.purge()
Assign Dataset Assigns the Dataset to a Flex Plot
dataset.assign(FlexPlot* flexplot); flexplot FlexPlot* The Flex Plot the Dataset is to be assigned to. (1)
Un-Assign Dataset Disassociates the Dataset from all Flex Plots
dataset.unassign();
Set Colour Sets the colour of the Dataset
dataset.setColour(r, g, b, a); r u16 The "red" value.
g u16 The "green" value.
b u16 The "blue" value.
a u16 The "alpha" value.
  1. If the Dataset is already assigned to a Flex Plot, it will automatically be un-assigned before being re-assigned to the Flex Plot specified in this command.


Configuration

Configuration
Configuration Element Description Config Value
Name Decimal
Timeplot If set, the Dataset expects all data point x-values to be a time in microseconds since device boot. Iris Controls converts each value to local time. Dataset::TIMEPLOT 1
Secondary y-Axis If set, the Dataset will use the secondary (right side) y-Axis. Dataset::SECONDARY_Y_AXIS 2
Scatter Plot If set, the Dataset will not connect data points with lines when plotted. Dataset::SCATTER_PLOT 4
Data Point Shape: Circle* Data points will be marked by a circle. Dataset::CIRCLE 8
Data Point Shape: Diamond* Data points will be marked by a circle. Dataset::DIAMOND 16
Data Point Shape: None* Data points will not be marked. Dataset::NONE 24

Example: To make the Dataset a timeplot on the secondary y-axis use config = Dataset::TIMEPLOT + Dataset::SECONDARY_Y_AXIS

  • Up to ONE shape configuration can be selected per Dataset. The points are marked by a cross if none of these options are selected.

Logging

Iris Controls 4 can create and maintain data logging files. To access this, log.h must be included in the GUI application.

Constructor

DataLog datalog(name);

API Commands

DataSets
Name Syntax Notes
arg type argument description
Add DataLog Adds a new DataLog
datalog.add();
Write to DataLog Writes a string to the DataLog
datalog.write(data); data string The data to be written.


Automatic Logging

Iris Controls automatically generates some log files in the Logs folder.

Error Log

Any time an application function encounters an error, that error will be written to this log. Each new session of Iris Controls 4 generates a new log file to prevent runaway file sizes, but the previous session's log is also retained.

/Logs/Error Log.txt

Connection Log

This log records connection parameters on every successful connection and some disconnection information. Each new session of Iris Controls 4 generates a new log file to prevent runaway file sizes, but the previous session's log is also retained.

/Logs/Connection Log.txt

Serial Log

This log records raw serial communication data for use in troubleshooting.

/Logs/Serial Log.txt

IC4 Serial API

See this page for the IC4 serial API.

Development GUI

Iris Controls 4 Development GUI

Legacy Elements

The legacy elements are three frames (input, output, and button) that were used in older GUIs. Support for these has been retained to make IrisControls4 backwards compatible. Legacy frames are a fixed size.

Constructor

There is no constructor.

API Commands

Legacy Frames
Name Syntax Notes
arg type argument description
Add Legacy Frames Adds all three frames. (1)
add_legacy_frames(row, column);
Remove Legacy Frames gendescription
remove_legacy_frames();
Add Input Frame Adds the Input Frame.
add_input_frame(row, column); row u16 The row the frame is to be placed in. (2)
column u16 The column the frame is to be placed in.
Add Output Frame Adds the Output Frame.
add_output_frame(row, column); row u16 The row the frame is to be placed in. (2)
column u16 The column the frame is to be placed in.
Add Button Frame Adds the Button Frame.
add_button_frame(row, column); row u16 The row the frame is to be placed in. (3)
column u16 The column the frame is to be placed in.
Remove Input Frame Removes the Input Frame
remove_input_frame();
Remove Output Frame Removes the Output Frame
remove_output_frame();
Remove Button Frame Removes the Button Frame
remove_button_frame();
  1. The frames are added in this orientation:
    [ INPUT ][ OUTPUT ]
    [ BUTTON FRAME ]
  2. This frame has a rowSpan of 30 rows and a columnSpan of 30 columns.
  3. This frame has a rowSpan of 10 rows and a columnSpan of 50 columns.