Contents

Arduino C++ Devices & Connections

1 September 2022

All Arduino C++ libraries include the core library files DashIO.h and DashIO.cpp. The DashIO 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 DashIO library contains the DashioDevice object that you need to instantiatre.

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 DashIo 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);
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);

Connections

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 bugger 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

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

void processIncomingMessage(MessageData *messageData) {
    switch (messageData->control) {
    case status:
      processStatus(messageData->connectionType);
      break;
      
    // etc.
    
    default:
      break;
    }
}

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

    // Setup & start BLE connection
    ble_con.setCallback(&processIncomingMessage);
    ble_con.begin();

    // Setup MQTT connection
    mqtt_con.setup(mqttUser, mqttPassword);
    mqtt_con.setCallback(&processIncomingMessage);
    wifi.attachConnection(&mqtt_con);

    // Setup TCP connection
    tcp_con.setCallback(&processIncomingMessage);
    wifi.attachConnection(&tcp_con);

    // 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.

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() {
    wifi.setOnConnectCallback(&onWiFiConnectCallback);
    
    // 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() {
    ble_con.run();
    wifi.run();
}

The wifi.run(); manages running TCP and MQTT connections.

Sending Messages

Messages are sent through connections and are typically, but not always, sent as a reply through the connection where an incoming message arrived. Below is an example a method to send a message to a specific connection:

void sendMessage(ConnectionType connectionType, const String& message) {
    if (connectionType == TCP_CONN) {
        tcp_con.sendMessage(message);
    } else if (connectionType == BLE_CONN) {
        ble_con.sendMessage(message);
    } else {
        mqtt_con.sendMessage(message);
    }
}

Creating Messages

Creating messages is discussed in the following document:

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