Arduino C++ Devices & Connections

6 January 2023

All Arduino C++ libraries include the core library files DashIO.h and DashIO.cpp. The Dash library is important for developing your projects for two main reasons:

  • The header file provides all the information you will need to create your device, connections and controls (using methods and attributes).
  • To enable you to create your own libraries for whatever project you can imagine.

The Dash library contains the DashioDevice object that you need to instantiate.

Dashio Device

DashioDevice is the workhorse class, providing much of the functionality for messaging. It holds important attributes for the IoT device:

  • deviceID - the unique identifier of the IoT device. A UUID may be used for the deviceID, or the mac address from the comms peripheral is also suitable.
  • type - human readable text to describe the IoT device. This can be whatever you choose and may be a manufaturer product designator. Once this is assigned to the dashioDevice it cannot be changed.
  • name - human readable name for the IoT device. This can be changed by through the Dash protocol.
  • mqttSubscrberTopic - the dashioDevice also creates and stores the mqttSubscrberTopic for MQTT connections.
  • configC64Str - pointer program memory containing the layout configuration text for the IoT device. The C64 string is compressed and encoded into Base64 for transmitting within text messages.

The dashioDevice contains all the methods for creating the correctly formatted messages that are sent through the BLE, TCP and MQTT connections. This data includes messages for each control and their configuration messages. Please refer to the file DashIO.h for details.

You must create an instance of DashioDevice class as follows:

DashioDevice dashioDevice(Device_Type);

where Device_Type is a user defined String that describes the device and which is presented to the user during device discovery.

The deviceID, and optionally the device_name, are setup with through one of the following methods, which should be called from within the Arduino setup() function:

dashioDevice.setup(deviceID, device_name);

The deviceID is typically set to the mac address from a comms peripheral and may be a String or an array of 6 bytes. The device_name is a String.

DashioDevice contains all the methods for creating messages that the IoT device can send through a connection. For example:

String message = dashioDevice.getSelectorMessage("SELECTOR_ID", menuSelectorIndex, selection, 3);
message += dashioDevice.getButtonMessage("BUTTON_ID", menuButtonValue);
message += dashioDevice.getTextBoxMessage("TEXTBOX_ID", String(menuTextBoxValue));
message += dashioDevice.getSliderMessage("SLIDER_ID", menuSliderValue);


Instantiating Connection Objects (& WiFi for TCP & MQTT)

The instantiation of connections differs very slightly depending on the specific hardware being used and is therefore not discussed in this document. Please refer to the software guides for specific hardware for details. Below are examples of instantiating connections for different processors. These examples use the folllowing parameters:

  • tcpPort: TCP port of your choice.
  • printMessages: boolean to choose to print messages to the Serial Monitor
  • mqttBufferSize: MQTT connection buffer size. 2048 is a reasonable value.
  • sendRebootAlarm: boolean to choose to send a push notification when the IoT device reboots.

ESP32 & ESP8266 Example

DashioWiFi wifi;
DashioTCP  tcp_con(&dashioDevice, tcpPort, printMessages);
DashioMQTT mqtt_con(&dashioDevice, mqttBufferSize, sendRebootAlarm, printMessages);
DashioBLE  ble_con(&dashioDevice, printMessages);

Arduino NANO 33 IoT & MKR 1010 Example

DashioWiFi wifi;
DashioTCP  tcp_con(&dashioDevice, tcpPort, printMessages);
DashioMQTT mqtt_con(&dashioDevice, sendRebootAlarm, printMessages);
DashioBLE  ble_con(&dashioDevice, printMessages);

Arduino Nano 33 Example

DashioBLE ble_con(&dashioDevice, printMessages);

Arduino Bluefruit Example

DashioBluefruit_BLE ble_con(&dashioDevice, printMessages);

Arduino Bluno Example

DashioBluno ble_con(&dashioDevice);

Connection Setup and Receiving Messages

The following is an example of how to setup and start wifi and all connections, including the processIncomingMessage callback, which is used to process incoming messages:

void processIncomingMessage(MessageData *messageData) {
    switch (messageData->control) {
    case status:
    // etc.

void setup() {
    // Setup DashioDevice
    dashioDevice.setup(wifi.macAddress()); // Get unique deviceID

    // Setup & start BLE connection

    // Setup MQTT connection
    mqtt_con.setup(mqttUser, mqttPassword);

    // Setup TCP connection

    // Start WiFi, which will also start TCP and MQTT if attached
    wifi.begin(dashioProvision.wifiSSID, dashioProvision.wifiPassword);

Typically most Arduino processors are only capable of managing a maximum of two connections running simultaniously. For best performance, it is highly recommended that the IoT device is setup with either a physical switch or other method to swap between connecting types.

A Soft AP connection is also available for ESP devices. Please review the header file "DashioESP.h" for details.

WiFi Connection Callback

You can also setup a callback that is executed when the WiFI is connected:

void onWiFiConnectCallback(void) {
    // Do something useful when the WiFi connects

void setup() {
    // etc.

Running the Connections

To make sure the connections run and the callbacks are executed, the connections must be "run" from within the main loop.

void loop() {;;

The; manages running TCP and MQTT connections.


As discussed above, incoming messages are recived from the Dash IoT Dashboard through the processIncomingMessage callback.

To send a message to the Dash dashboard, a formatted message must first be created.

Processing incoming messages and creating messages for each control type is discussed in the following document: