Contents
Arduino C++ Configuration Objects
9 February 2022
Control configuration objects are only required for configuration messages that enable an IoT device to configure its layout in the DashIO app.
Configuration Process
The process of creating and sending a configuration message is:
- Only send configuration messages once the IoT device has received a configuration request message.
- Create a controlCfg object and set any attributes that you want to change from the default values.
- From the dashioDevice, call a method to create the configuration message
getConfigMessage
with controlCfg as an attribute - Send the configuration message through the appropriate comms library. For example, if the configuration request message is received via BLE, the configuration message should be sent back throught BLE.
The example below shows the creation of button control confguration message:
ButtonCfg aButton("BUTTON_ID", "DEV_VIEW_ID", "Button", {0.5, 0.788, 0.2, 0.121});
aButton.iconName = "bell";
aButton.offColor = "blue";
aButton.onColor = "black";
String message = dashioDevice.getConfigMessage(aButton);
An instance of DashioDevice is used to create the configuration message by using the function dashioDevice.getConfigMessage(aButton)
All controls are instantiated with the same set of attributes as in the example above. In order, they are:
- controlID - Identifier of the control. Must be unique to the IoT device.
- parentID - Identifier of the control that is the parent control to this control. May be a device view, menu, or button group.
- title - Title or name of the control to be displayed on the DashIO app.
- coordinates - Position and size of the control on the device view, where 0 is the top or left side and 1 is right or the right side. The four coordinates, in order, are {control left side position, control top position, control width, control height}.
In the above example code the iconName, offColor, and onColor are also set for the button. There are many attributes than can be set for each control. Please refer to the file DashIO.h for details or all alltribtes for all controls.
Configuration Enumerators
The enumerator types shown below are used when setting up Configuration Objects:
LineType
Value |
Description |
---|---|
line | Solid line |
bar | Solid bar (not available in Time Graphs) |
segBar | Bar broken into segments (not available in Time Graphs) |
peakBar | Small bar or dash at the data value (not available in Time Graphs) |
bln | Shades an area of the graph (only available in TimeGraphs) |
ButtonMultiState
Value |
Description |
---|---|
off | OFF state |
on | ON state |
MQTTTopicType
Value |
Description |
---|---|
data_topic | Topic or IoT device to transmit data on |
control_topic | Topic for IoT device to receive commands on |
alarm_topic | Topic for IoT device to send alarm messages on |
announce_topic | Topic for IoT device to announce that it is available to be connected to |
will_topic | LWT topic |
TitlePosition
Value |
Description |
---|---|
titleOff | No title |
titleTop | Title at the top of the control |
titleBottom | Title at the bottom of the control |
LabelStyle
Value |
Description |
---|---|
basic | Simple text label |
border | Text label with a border |
group | Label use to surround a group of controls |
KnobPresentationStyle
Value |
Description |
---|---|
knobNormal | Standard style knob |
knobPan | Knob the behaves as a stereo pan control |
DialNumberPosition
Value |
Description |
---|---|
numberOff | Value not shown as a number |
numberLeft | Value number shown on the left side of the dial |
numberRight | Value number shown on the right side of the dial |
numberCenter | Value number shown on the center of the dial |
DialPresentationStyle
Value |
Description |
---|---|
dialPie | Dial presented as a curved bar |
dialPieInverted | Dial presented in a pie form, rotating clockwise from right to left |
dialBar | Dial presented in a pie form, rotating clockwise from left to right |
DirectionPresentationStyle
Value |
Description |
---|---|
dirNSEW | North, South, East, and West symbols |
dirDeg | Degrees |
dirDegPS | Degrees to port and starboard |
TextFormat
Value |
Description |
---|---|
numFmt | Attempt to format the text as a number |
dateTimeFmt | Attempt to short format the text as date and time |
dateTimeLongFmt | Attempt to long format the text as dat and time |
intvlFmt | Attempt to format the text as a time interval |
noFmt | Do not format the text, just display it as it is received |
KeyboardType
Value |
Description |
---|---|
hexKbd | Hexidecimal characters |
allKbd | All characters |
numKbd | Real numbers |
intKbd | Integer numbers |
dateKbd | Date |
timeKbd | Time |
dateTimeKbd | Date and Time |
intvlKbd | Time Interval |
noKbd | No keyboard - text entry is disabled |
TextAlign
Value |
Description |
---|---|
textLeft | Left |
textCenter | Center |
textRight | Right |
BarStyle
Value |
Description |
---|---|
segmentedBar | Segmented bar |
solidBar | Solid bar |
XAxisLabelsStyle
Value |
Description |
---|---|
labelsOnLines | Draw value labels directly beneath the vertical lines |
labelsBetweenLines | Draw value labels in the spaces between the vertical lines |
Configuration Objects
Configuration Objects are used to create configuration messages that are required to configure the IoT device on the DashIO app. After a DashIODevice object has been created, it can be use to create the configuration message:
DashioDevice dashioDevice("My Device Type");
String cfgMsg = dashioDevice.getConfigMessage(ConfigurationObject);
The tables below show all the Configuration bjects that are available:
BLEConnCfg
For configuring BLE connections.
Attribute Name | Type | Default | Description |
---|---|---|---|
serviceUUID | String | empty | BLE Service UUID |
readUUID | String | empty | BLE read characteristic UUID |
writeUUID | String | empty | BLE write characteristic UUID |
TCPConnCfg
For configuring TCP connections.
Attribute Name | Type | Default | Description |
---|---|---|---|
ipAddress | String | empty | current IP address of the connection |
port | int | 5650 | TCP port for the connection |
MQTTConnCfg
For configuring MQTT connections.
Attribute Name | Type | Default | Description |
---|---|---|---|
userName | String | empty | Username for the MQTT host |
hostURL | String | empty | URL of the MQTT host |
AlarmCfg
For configuring Alarm (push notification) sounds.
Attribute Name | Type | Default | Description |
---|---|---|---|
controlID | String | empty | Identifier of the alarm/notification |
description | String | empty | Displayed in the notification title |
soundName | String | empty | Displayed in the notification body |
DeviceCfg
For configuring the Device.
Attribute Name | Type | Default | Description |
---|---|---|---|
numDeviceViews | int | 0 | Number of Device Views available for the device |
deviceSetup | String | empty | Device provisioning text options* |
*Device provisioning setup text contains comma separated device setup options: “name, wifi, tcp, dashio, mqtt”:
- “name" = can change change the device name
- “wifi” = can change the wifi Country Code, SSID and password
- “tcp” = can change the TCP port
- “dashio” = can change the DashIO server MQTT username and password
- “mqtt”= can change the MQTT URL, port, SSL (enabled), username, and password
DeviceViewCfg
For configuring Device Views.
Attribute Name | Type | Default | Description |
---|---|---|---|
controlID | String | empty | Unique identifier of the Device View |
title | String | empty | Device View Name |
iconName | String | empty | Name of the icon from the icons in DashIO app. Displayed on the menu |
color | String | "black" | Device View background color. Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
shareColumn | bool | true | When true, allows device views to share a column if their height is small enough |
numColumns | int | 1 | Number of columns wide the deviceView is (1 to 3) |
ctrlMaxFontSize | int | 30 | The maximum size of the text font for all controls. The font size will never be larger than this value |
ctrlBorderOn | bool | true | Hide or show border on all controls |
ctrlBorderColor | String | "white" | Default color of the border and title box text for all controls. Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
ctrlColor | String | "white" | Default color of the border and title box text for all controls. Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
ctrlBkgndColor | String | "blue" | Default color of the background of all controls. Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
ctrlBkgndTransparency | int | 0 | Default transparency of the background of all controls (range = 0 to 100) |
ctrlTitleFontSize | int | 18 | Font size for the title box of al controls (range = 8 to 30) |
ctrlTitleBoxColor | String | "blue" | Color of the title box of all controls. Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
ctrlTitleBoxTransparency | int | 0 | Default transparency of the title box of all controls (range = 0 to 100) |
Rect
The Rect is a Struct that is used for defining the position and size of all the displayed controls below.
Attribute Name | Type | Default | Description |
---|---|---|---|
xPositionRatio | float | 0 | Position of the left side of the control as a ratio of the screen width (range = 0 to 1) |
yPositionRatio | float | 0 | Position of the top side of the control as a ratio of the screen height (range = 0 to 1) |
widthRatio | float | 0 | Width of the control as a ratio of the screen width (range = 0 to 1) |
heightRatio | float | 0 | Height of the control as a ratio of the screen height (range = 0 to 1) |
CommonControl
All displayed control listed below inherit from the Common Control.
Attribute Name | Type | Default | Description |
---|---|---|---|
controlID | String | empty | Identifier of the control |
parentID | String | empty | Identifier of the parent control |
title | String | empty | Text to be displayed in the title box of the control |
titlePosition | TitlePosition | titleTop | Default position of title box |
graphicsRect | Rect | Position and size of the control |
LabelCfg : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
style | LabelStyle | group | Layout style of the label |
color | String | "white" | Color of the text |
ButtonCfg : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
buttonEnabled | bool | true | Enable the control as a button. If not enable, control only behaves as a display indocator |
iconName | String | empty | Name of the icon from the icons in DashIO app. Displayed on the button |
text | String | empty | Text displayed on the button |
offColor | String | "dark gray" | Color of text or icon when the button is in the OFF state. Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
onColor | String | "white" | Color of text or icon when the button is in the ON state. Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
MenuCfg : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
iconName | String | "menu" | Name of the icon from the icons in DashIO app. Displayed on the menu control |
text | String | empty | Text displayed on the menu control |
ButtonGroupCfg : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
iconName | String | "group" | Name of the icon from the icons in DashIO app. Displayed on the button group control |
text | String | empty | Text displayed on the button group control |
gridView | bool | true | If true, show as a grid of buttons, otherwise show as a vertical menu of buttons |
EventLogCfg : CommonControl
No other attributes
KnobCfg : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
min | float | 0 | Minimum value of the dial behind the knob |
max | float | 100 | Maximum value of the dial behind the knob |
redValue | float | 70 | When the dial value is above this number it will be colored red |
showMinMax | bool | true | Show the maximum and minimum values on the dial |
style | KnobPresentationStyle | knobNormal | Presentation style of the dial |
knobColor | String | "red" | Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
sendOnlyOnRelease | bool | true | Send message only when the the knob is released by the user |
dialFollowsKnob | bool | true | The dial behind the knob shows the same value as the knob |
dialColor | String | "yellow" | Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
DialCfg : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
min | float | 0 | Minimum value of the dial |
max | float | 100 | Maximum value of the dial |
redValue | float | 70 | When the dial value is above this number it will be colored red |
dialFillColor | String | "green" | Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
pointerColor | String | "yellow" | Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
numberPosition | DialNumberPosition | numberCenter | Position on the display of the dial value |
showMinMax | bool | true | Show the maximum and minimum values on the dial |
style | DialPresentationStyle | dialBar | Presentation style of the dial |
units | String | empty | Displayed after the value on the dial |
precision | int | 3 | Numeric precision - number of charactes excluding the decimal point from 1 to 6. Any other value = off |
DirectionCfg : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
pointerColor | String | "yellow" | Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
style | DirectionPresentationStyle | dirNSEW | Presentation style of the dial |
calAngle | int | 0 | Correction offset in degrees for the direction pointer |
units | String | empty | To be displayed below the text |
precision | int | 3 | Numeric precision - number of charactes excluding the decimal point from 1 to 6. Any other value = off |
TextBoxCfg : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
format | TextFormat | noFmt | Presentation format for the text |
textAlign | TextAlign | textCenter | Text alignment |
units | String | empty | To be displayed after the text |
precision | int | 0 | Numeric precision - number of charactes excluding the decimal point from 1 to 6. Any other value = off |
kbdType | KeyboardType | allKbd | Type of keyboard that appears when the Text Box is tapped |
closeKbdOnSend | bool | true | Hide the keyboard once the message has been sent |
SelectorCfg : CommonControl
No other attributes
SliderCfg : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
min | float | 0 | Minimum value of the slider and bar |
max | float | 100 | Maximum value of the slider and bar |
redValue | float | 70 | When the bar value is above this number it will be colored red |
showMinMax | bool | true | Show the maximum and minimum values on the bar and slider |
sliderEnabled | bool | true | Hide or show the slider knob. When disabled, only the bar is shown |
knobColor | String | "white" | Color of the knob of the slider. Color from colors in DashIO app .e.g. "blue" or "#RRGGBB" |
sendOnlyOnRelease | bool | true | Send message only when the the knob is released by the user |
barFollowsSlider | bool | true | The bar behind the slider shows the same value as the knob |
barColor | String | "green" | Color name from colors in DashIO app e.g. "blue" or "#RRGGBB" |
barStyle | BarStyle | segmentedBar | Style of the bar |
GraphCfg : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
xAxisLabel | String | empty | Title of the horizontal axis |
xAxisMin | float | 0 | Value of the horizontal axis left hand side |
xAxisMax | float | 100 | Value of the horizontal axis right hand side |
xAxisNumBars | int | 6 | Number of grid lines crossing the horizontal axis, including the left and right axes |
xAxisLabelsStyle | XAxisLabelsStyle | labelsOnLines | Style of the value labels on th horizontal axis |
yAxisLabel | String | empty | Title of the vertical axis |
yAxisMin | float | 0 | Value of the vertical axis bottom |
yAxisMax | float | 100 | Value of the vertical axis top |
yAxisNumBars | int | 6 | Number of grid lines crossinz the vertical axis, including the top and bottom axes |
TimeGraphCfg : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
yAxisLabel | String | empty | Title of the vertical axis |
yAxisMin | float | 0 | Value of the vertical axis bottom |
yAxisMax | float | 100 | Value of the vertical axis top |
yAxisNumBars | int | 6 | Number of grid lines crossinz the vertical axis, including the top and bottom axes |
MapCfg : CommonControl
No other attributes
ColorPicker : CommonControl
Attribute Name | Type | Default | Description |
---|---|---|---|
pickerStyle | String | wheel | "wheel" for wheel or “spec" spectrum |
sendOnlyOnRelease | bool | true | Send message only when the the color picker is released by the user |
AudioVisual : CommonControl
No other attributes