Contents

Arduino C++ Controls Messaging

MessageData Class

The MessageData class provides the message processing for incoming messages and stores the results. It is an attribute of each connection and is available as a parameter in the incoming message callback that you must setup for each connection (BLE, TCP or MQTT) and takes the form:

void processIncomingMessage(MessageData *messageData) {
    switch (messageData->control) {
    case status:
      processStatus(messageData->connectionType);
      break;
    case config:
      processConfig(messageData->connectionType);
      break;
    case button:
      processButton(messageData);
      break;
    case slider:
      processSlider(messageData);
      break;

      // etc
      // etc
      // etc

    default:
      break;
    }
}

The important attributes of the MessageData are:

  • connectionType - Set at instantiation of the class and use to define the type of connection: enum {BLE_CONN, TCP_CONN, MQTT_CONN}. The MessageData must be instantiated with the connectionType as an attribute.
  • control - Contains the Control_Type of the received message: enum {deviceView, label, button, menu, buttonGroup, eventLog, slider, knob, dial, direction, textBox, selector, graph, timeGraph, mapper, colorPicker, audioVisual}.
  • idStr - Contains the control_ID of the received message.
  • payloadStr - Contains the primary payload field of the received message.
  • payloadStr2 - Contains the. secondary payload field of the received message.

Messageing Principles

Controls within an IoT device may send an receive messages at any time the IoT device is connected.

  • Receiving a message allows the IoT device to take action according to the contents of the message received from the DashIO app.
  • Sending a message allows the IoT device to send information or provide feedback to the user of the DashIO app.
  • It is good practice to reply to a received control message. This is to provide feedback to the user of the DashIO app that an action has taken place, or not.

Incoming messages are received in the incoming message callback, which includes the MessageData as a parameter. The contents of the incoming message are contained within the MessageData class as described above.

Use the control (Control_Type) and ideStr (ControlID) to address the control the MessageData is referring to. Then, use payloadStr and payloadStr2 to access the contents of the message.

For example, consider when a button message is received from the DashIO app. The received message tells tha IoT device that the particular button, addressed by the control and idStr, has been tapped on the DashIO app and needs to be toggled in the IoT device. The payloadStr or payloadStr2 message components are not used in this case:

void processIncomingMessage(MessageData *messageData) { // callback
    switch (messageData->control) {
    case button: // Process Button
        if (messageData->idStr == "BUTTON_ID") {
            buttonValue = !buttonValue;
        }
    default:
        break;
    }
}

where buttonValue is a boolean representing whether the button should be display as on (true) or off (false) on the DashIO app.

A button control reply message may be created in the IoT device and returned to a connection (in this example both BLE or MQTT) as follows:

void processIncomingMessage(MessageData *messageData) { // callback
    switch (messageData->control) {
    case button: // Process Button
        if (messageData->idStr == "BUTTON_ID") {
            buttonValue = !buttonValue;
            String message = dashioDevice.getButtonMessage("BUTTON_ID", buttonValue);
            if (messageData->connectionType == BLE_CONN) {
                ble_con.sendMessage(message);
            } else if (messageData->connectionType == MQTT_CONN) {
                mqtt_con.sendMessage(message);
            }
        }
    default:
        break;
    }
}

An instance of DashioDevice is used to create the button message by using the function dashioDevice.getButtonMessage("BUTTON_ID", buttonValue)

All Controls

In the following sub-sections, controlID is the control identifier and message is a String containing the contents of a message the may be sent to the DashIO app through a connection (BLE, TCP or MQTT).

All time infomration is sent and received as an IOS 8601 format String representing the UTC time i.e. "yyyy-MM-dd’T’HH:mm:ssZ".

All color information is a String with the color name (as used in the DashIO app, e.g. "blue", or a hex color, e.g. "#RRGGBB")

Button

Incoming Messages

An incoming Button control message indicates that the Button control on the DashIO app has been tapped and the state on the Button control in the IoT device should be toggled.

MessageData Payload

  • Payload: unused
  • Payload2: unused

Outgoing Messages

Button outgoing messages can send the button state, which only changes the button's color on the DashIO app, or it can also specify the icon and text to be displayed.

message = dashioDevice.getButtonMessage(controlID, on);
message = dashioDevice.getButtonMessage(controlID, on, iconName);
message = dashioDevice.getButtonMessage(controlID, on, iconName, text);

Parameters

  • on: bool indicating if the button is on (true) or off
  • iconName: String parameter containing the name of the icon to display on the button. If blank (""), the icon on the button is NOT changed.
  • text: String parameter containing the text to display on the button. If blank, (""), the text on the button is NOT changed. If text is NOT blank, setting the iconName to blank will remove the icon from the button.

Event Log

Incoming Messages

There are no incoming messages for the Event Log

Outgoing Messages

EventLog outgoing messages contain event data.

message = dashioDevice.getEventLogMessage(controlID, timeStr, color, textArr, numTextRows);
message = dashioDevice.getEventLogMessage(controlID, eventsArr, numEvents);

Parameters

  • timeStr: Event time. If the timeStr is left blank (""), the current time will be inserted by either the dash server or DashIO app when the message is received.
  • color: color of the event.
  • textArr: array of row of text to display on th event.
  • numTextRows: number of elements in the textArr.
  • eventsArr: array of Event struct (see below).
  • numEvents: umber of elements in the eventsArr
struct Event {
    String time;    // Event time
    String color;   // Color of the event.
    String *lines;  // Lines of text
    int numLines;   // Number of lines of text
};

Slider

Incoming Messages

An incoming Slider control message indicates that the Slider control on the DashIO app has been moved.

MessageData Payload

  • Payload: Value of the new position of the slider.
  • Payload2: unused

Outgoing Messages

message = dashioDevice.getSliderMessage(controlID, value);
message = dashioDevice.getSingleBarMessage(controlID, value);
message = dashioDevice.getDoubleBarMessage(controlID, value1, value2);

The slider outgoing messages are of three different types:

  • getSliderMessage: set the position of the knob on the slider (float or int).
  • getSingleBarMessage: set the position of a singe bar under the slider (float or int).
  • getDoubleBarMessage: set the position of two bars under the slider (float or int).

Parameters

  • value, value1, value2: position of the knob or bar. The minimum and maximum values of the slider are specified in the slider's configuration data.

Knob

Incoming Messages

An incoming Knob control message indicates that the Knob control on the DashIO app has been rotated.

MessageData Payload

  • Payload: New value of the Knob position.
  • Payload2: unused

Outgoing Messages

message = dashioDevice.getKnobMessage(controlID, value);
message = dashioDevice.getKnobDialMessage(controlID, value);

The knob messages are of two different types:

  • getKnobMessage: set the position of the knob (float or int).
  • getKnobDialMessage: set the position of a dial surrounding the knob (float or int).

Parameters

  • value: position of the knob or dial. The minimum and maximum values of the knob are specified in the knob's configuration data.

Dial

Incoming Messages

There are no incoming messages for the Dial control.

Outgoing Messages

Dial control outgoing messages contain the position of the dial.

message = dashioDevice.getDialMessage(controlID, value);

Parameters

  • value: position of the dial (float or int). The minimum and maximum values of the dial are specified in the dial's configuration data.

Direction

Incoming Messages

There are no incoming messages for the Direction control.

Outgoing Messages

Direction control outgoing messages contain the position of the direction indicator.

message = dashioDevice.getDirectionMessage(controlID, direction);
message = dashioDevice.getDirectionMessage(controlID, direction, speed);

Parameters

  • direction: direction in decimal degrees (float or int).
  • speed: speed where the units are specified in the direction control's configuration data.

Text Box

Incoming Messages

There are no incoming messages for the Text Box control.

Outgoing Messages

Text Box control outgoing messages contain the text to display on the Text Box on the DashIO app.

message = dashioDevice.getTextBoxMessage(controlID, text);

Parameters

  • text: String to be displayed in the text box.

Selector

Incoming Messages

An incoming Selector control message indicates that the Selector control on the DashIO app has had a selection made.

MessageData Payload

  • Payload: Index of the snew election.
  • Payload2: unused

Outgoing Messages

Text Selector control outgoing messages contain the current selection index, and optionally, the selection items.

message = dashioDevice.getSelectorMessage(controlID, index);
message = dashioDevice.getSelectorMessage(controlID, index, selectionItems, numItems);

Parameters

  • index: index to the currently selected item.
  • selectionItems: array of String where eack element in the arrray is a selection item.
  • numItems: number of selection items.

Menu

Incoming Messages

An incoming Menu control message indicates that the Menu control on the DashIO app has been tapped.

MessageData Payload

  • Payload: unused
  • Payload2: unused

Other incoming messages are handled by the Menu's sub-controls.

Outgoing Messages

There are no outgoing messages available for the Menu control. All outgoing messages are handled by the Menu's sub-controls.

Button Group

Incoming Messages

An incoming Button Group control message indicates that the Button Group control on the DashIO app has been tapped.

MessageData Payload

  • Payload: unused
  • Payload2: unused

Other incoming messages are handled by the Button Group's sub-controls.

Outgoing Messages

There are no outgoing messages available for the Button Group control. All outgoing messages are handled by the Button Group's sub-controls.

Graph

Incoming Messages

There are no incoming messages for the Graph control.

Outgoing Messages

Graph control outgoing messages contain the information for a single line to display on the Graph on the DashIO app.

message = dashioDevice.getGraphLineInts(controlID, graphLineID, lineName, lineType, color, lineData, dataLength);
message = dashioDevice.getGraphLineFloats(controlID, graphLineID, lineName, lineType, color, lineData, dataLength);

Parameters

  • graphLineID: String identifier of the graph line.
  • lineName: Name of the graph line
  • lineType: Enumerator for the style or type of line (see LineType below).
  • color: color of the line.
  • lineData: array or int or float.
  • dataLength: number of elements in the lineData array.
enum LineType {
    line,    // Line betwen each point
    bar,     // Bar graph
    segBar,  // Bargraph with segmented bars (not available in Time Graphs)
    peakBar, // Bar graph with a howizontal line at the top or peak.  (not available in Time Graphs) instead of a filles or segmented bar. (not available in Time Graphs)
    bln,     // Shades an area of the graph (only available in TimeGraphs)
};

Time Graph

Incoming Messages

An incoming Time Graph control message indicates that DashIO app require an update of the line data for the Time Graph.

MessageData Payload

  • Payload: UTC time String from which the Time Graph on the DashIO requires line data.
  • Payload2: unused

Outgoing Messages

Time Graph control outgoing line messages contain the information for a single line to display on the Time Graph on the DashIO app.

TimeGraph line messages may contain all the metadata (name, color etc.) and line data, or just the metadata. TimeGraph point messages are a short format messages for just sending a single point on the graph line.

message = dashioDevice.getTimeGraphLineFloats(controlID, graphLineID, lineName, lineType, color, String times, lineData, dataLength);
message = dashioDevice.getTimeGraphLineFloats(controlID, graphLineID, lineName, lineType, color, String times, lineData, dataLength, breakLine);
message = dashioDevice.getTimeGraphLineBools(controlID, graphLineID, lineName, lineType, color, String times, lineData, dataLength);
message = dashioDevice.getTimeGraphLine(controlID, graphLineID, lineName, lineType, color);
message = dashioDevice.getTimeGraphPoint(controlID, graphLineID, value);
message = dashioDevice.getTimeGraphPoint(controlID, graphLineID, time, value);

Parameters

  • graphLineID: String identifier of the graph line.
  • lineName: Name of the graph line
  • lineType: Enumerator for the style or type of line (see LineType in Graph control above).
  • color: color of the line.
  • times array of time Strings.
  • lineData: array of float or bool where each element matches the correcponding time in the times parameter.
  • breakline: Optional. When true, creates a break in the line data toseperate widely dispersed points.
  • dataLength: number of elements in the lineData array.
  • time: Time of the graph line point. If the time is not used, the current time will be inserted by either the dash server or DashIO app when the message is received. optional
  • value: float value of a single point.

Map

Incoming Messages

An incoming Map control message indicates that DashIO app require an update of the asset or track data for the Map control.

MessageData Payload

  • Payload: UTC time String from which the Time Graph on the DashIO requires line data.
  • Payload2: unused

Outgoing Messages

Map control outgoing messages contain the information for a single asset or track to display on the Map on the DashIO app.

Map outgoing messages provide GPS data to the map control. The message can be either a single waypoint or many waypoints that form part of a track.

message = dashioDevice.getMapWaypointMessage(controlID, trackID, latitude, longitude);
message = dashioDevice.getMapTrackMessage(controlID, trackID, text, colour, waypoints, numWaypoints);
message = dashioDevice.getMapTrackMessage(controlID, trackID, text, colour);

Parameters

  • trackID: String identifier of the map track.
  • latitude: Latitude decimal degrees as a String.
  • longitude: Longitude decimal as a String.
  • text: Test that is displayed on the asset pin.
  • color: Colour of the track and asset pin.
  • waypoints: Array or GPS Waypoint data (see below). Fields that are not required may be left blank ("").
  • numWaypoints: Number of waypoints in the waypoint array.
struct Waypoint {
    String time;        // Time of the waypoint
    String latitude;    // Latitude in decimal degrees
    String longitude;   // Longitude in decimal degrees
    String avgeSpeed;   // Average speed since the last message in meters/second
    String peakSpeed;   // Maximum speed since the last message in meters/second
    String course;      // Course direction in decimal degrees. A negative value indicates an unknown heading
    String altitude;    // Altitude in meters
    String distance;    // Accumulated distance since the last message in meters
};

Color Picker

Incoming Messages

An incoming Color Picker control message indicates that a new color has been chosen from the Color Picker control on the DashIO app.

MessageData Payload

  • Payload: New color String.
  • Payload2: unused

Outgoing Messages

message = dashioDevice.getColorMessage(controlID, color);

Parameters

  • color: Current colour of the colorPicker control.

Audio Visual

Incoming Messages

There are no incoming messages for the Audio Visual control.

Outgoing Messages

message = dashioDevice.getAudioVisualMessage(controlID, url);

Parameters

  • url: Set the URL of the audioVisual control.

Label

The Label control does not receive or send messages.

Configuration

Configuration of all controls is discussed in the following document:

https://dashio.io/dashio-arduino-config/