Contents

DashIO IoT Guide (Adafruit Bluefruit SPI Friend)

7 Septembet 2022

So, what is DashIO? It is a quick effortless way to connect your IoT device to your phone, tablet or iPad. It allows easy setup of controls such as Dials, Text Boxes, Maps, Graphs, Notifications..., from your IoT device. You can define the look and layout of the controls on your phone from your IoT device. There are three methods to connect to your phone; Bluetooth Low Energy (BLE), TCP or MQTT. What's Dash then? Dash is a mqtt server with extra bits added in to allow you to store data, send notifications, share your devices, and save your DashIO app setup.

This guide demonstractes how to make a BLE connection with an Adafruit Bluefruit SPI friend using the Arduino IDE.

Getting Started

For the big picture on DashIO, take a look at our website: dashio.io

For the DashIO arduino library: github.com/dashio-connect/arduino-dashio

Requirements

Grab an development board, Adafruit Bluefruit SPI friend, Arduino IDE and follow this guide.

You will need to install the DashIO app on your pobile phone or tablet. And if you'd like to connect to one IoT device for free, setup a free DashIO account from within the DashIO app.

Install

DashIO

You will need to add the DashIO library into your project. Download the DashIO library from GitHub with the following link: https://github.com/dashio-connect/arduino-dashio

You will need to copy the following files from the arduino-dashio library into your project directory:

  • DashioBluefruitSPI.h
  • DashioBluefruitSPI.cpp
  • bluefruitConfig.g

BLE

You will need to install the Adafruit library for the Bluefruit SPI friend, which are available in the Arduino IDE Library Manager. Search for the library "Adafruit BluefruitLE nRF51" and install.

Guide

BLE Basics

Lets start with a simple BLE connection.

#include "DashioBluefruitSPI.h"

#define DEVICE_TYPE "BF_SPI_BLE_Type"
#define DEVICE_NAME "Jill Name"

DashioDevice dashioDevice(DEVICE_TYPE);
DashioBluefruit_BLE  ble_con(&dashioDevice, true);

void setup() {
    Serial.begin(115200);

    dashioDevice.name = DEVICE_NAME;
    ble_con.begin(true);
}

void loop() {
    ble_con.run();
}

This is about the fewest number of lines of code necessary to get talking to the DashIO app. There is a lot happening under the hood to make this work. After the #include "DashioBluefruitSPI.h" we create a device with the device_type as its only attribute. We also create a BLE connection, with the newly created device being an attribute to the connection. The second attribute of the BLE connection enables the received and transmitted messages to be printed to the serial monitor to make debugging easier.

In the setup() function we assign the device name to the device and start the BLE connection ble_con.begin(true);. The device_ID is automagically obtained from the macAddress of the Bluefruit SPI Friend.

The "true" attribute of the ble_conn.begin(true); causes the Bluefruit SPI friend to perform a factory reset to make sure everything is in a known state. This can be set to "false" when you have finished your code.

This device is discoverable by the DashIO app. You can also discover your IoT device using a thiry party BLE scanner (e.g. BlueCap or "nRF Connect"). The BLE advertised name of your IoT device will be a concatentation of "DashIO_" and the device_type.

Setup the Arduino IDE serial monitor with 115200 baud and run the above code. Then run the DashIO app on your mobile device and you will see connection "WHO" messages on the Arduino serial monitor as the DashIO app detects and communicates with your IoT device.

Troubleshooting: Occasionally, the DashIO app is unable to discover a BLE connection to the IoT device. If this occurs, try deleting the the IoT device from the Bluetooth Settings of your phone or tablet.

If you like, you can assign your own device_ID by changing the BLE connection begin function call with the following:

dashioDevice.deviceID = "myUniqueDevieID";
ble_con.begin(true, false);

Lets add Dial control messages that are sent to the DashIO app every second. To do this we create a new task to provide a 1 second time tick and then send a Dial value message from the loop every second.

#include "DashioBluefruitSPI.h"

#define DEVICE_TYPE "BF_SPI_BLE_Type"
#define DEVICE_NAME "Jill Name"

DashioDevice dashioDevice(DEVICE_TYPE);
DashioBluefruit_BLE  ble_con(&dashioDevice, true);

void setup() {
    Serial.begin(115200);

    dashioDevice.name = DEVICE_NAME;
    ble_con.begin(true);
}

void loop() {
    ble_con.run();
    ble_con.sendMessage(dashioDevice.getDialMessage("D01", int(random(0, 100))));
    delay(1000);
}

The line dashioDevice.getDialMessage("D01", int(random(0, 100))) creates the message with two parameters. The first parameter is the control_ID which identifies the specific Dial control in the DashIO app and the second parameter is simply the Dial value.

Once again, run the above code and the DashIO app. This time, a new "DIAL" messages will be seen on the serial monitor every second.

The next step is to show the dial values from the messages on a control on the DashIO app.

In the DashIO app, tap the All Devices button, followed by the Find New Device button. Then select the BLE Scan option to show a list of new IoT devices that are BLE enabled. Your IoT device shpuld be shown in the list. Select your device and from the next menu select Create Device View. This will create an empty Device View for your new IoT deivce. You can now add controls to the Device View:

  • Start Editing: Tap the Edit button (it not already in editing mode).
  • Add Dial Control: Tap the Add Control button and select the Dial control from the list.
  • Edit Controls: Tap the Dial control to select it. The Control Settings Menu button will appear in the middle of the Control. The Control can then be dragged and resized (pinch). Tapping the button allows you to edit the Control settings where you can setup the style, colors and other characteristics of your Control. Make sure the Control_ID is set to the same value that is used in the dial messages (in this case it should be set to "D01").
  • Quit editing: Tap the Edit button again.

The Dial on the DashIO app will now show the random Dial values as they arrive.

The next piece of the puzzle to consider is how your IoT device can receive data from the DashIO app. Lets add a Knob and connect it to the Dial.

In the DashIO app you will need to add a Knob control onto your Device View, next to your Dial control. Edit the Knob to make sure the Control ID of the knob matches what you have used in your knob messages (in this case it should be "KB01"), then quit edit mode.

Next, in the Arduino code we need to respond to messages coming in from a Knob control that we just added to the DashIO app. To make the changes to your IoT device we add a callback, processIncomingMessage, into the BLE connection with the setCallback function.

#include "DashioBluefruitSPI.h"

#define DEVICE_TYPE "BF_SPI_BLE_Type"
#define DEVICE_NAME "Jill Name"

DashioDevice dashioDevice(DEVICE_TYPE);
DashioBluefruit_BLE  ble_con(&dashioDevice, true);

void processIncomingMessage(MessageData *messageData) {
    switch (messageData->control) {
    case knob:
        if (messageData->idStr == "KB01") {
            String message = dashioDevice.getDialMessage("D01", (int)messageData->payloadStr.toFloat());
            ble_con.sendMessage(message);
        }
        break;
    }
}

void setup() {
    Serial.begin(115200);

    dashioDevice.name = DEVICE_NAME;
    ble_con.setCallback(&processIncomingMessage);
    ble_con.begin(true);
}

void loop() {
    ble_con.run();
}

We obtain the Knob value from the message data payload that we receive in the processIncomingMessage function. We then create a Dial message with the value from the knob and send this back to the DashIO app. And remember to remove the timer and the horrible delay from the loop:

When you adjust the Knob on the DashIO app, a message with the knob value is sent your IoT device, which returns the knob value into the dial control, which you will see on the DashIO app.

Finally, we should respond to the STATUS message from the DashIO app. STATUS messages allows the IoT device to send initial conditions for each control to the DashIO app as soon as a connection becomes active. Once again, we do this from the processIncomingMessage function and our complete code looks like this:

#include "DashioBluefruitSPI.h"

#define DEVICE_TYPE "BF_SPI_BLE_Type"
#define DEVICE_NAME "Jill Name"

DashioDevice dashioDevice(DEVICE_TYPE);
DashioBluefruit_BLE  ble_con(&dashioDevice, true);

int dialValue = 0;

void processStatus(ConnectionType connectionType) {
    String message((char *)0);
    message.reserve(1024);

    message = dashioDevice.getKnobMessage("KB01", dialValue);
    message += dashioDevice.getDialMessage("D01", dialValue);

    ble_con.sendMessage(message);
}

void processIncomingMessage(MessageData *messageData) {
    switch (messageData->control) {
    case status:
        processStatus(messageData->connectionType);
        break;
    case knob:
        if (messageData->idStr == "KB01") {
              dialValue = messageData->payloadStr.toFloat();
            String message = dashioDevice.getDialMessage("D01", dialValue);
            ble_con.sendMessage(message);
        }
        break;
    }
}

void setup() {
    Serial.begin(115200);

    dashioDevice.name = DEVICE_NAME;
    ble_con.setCallback(&processIncomingMessage);
    ble_con.begin(true);
}

void loop() {
    ble_con.run();
}

This is just the beginning and there is a lot more we can do. Take a look at the examples in the library to see more details.

Layout Configuration

Layout configuration allows the IoT device to hold a copy of the complete layout of the device as it should appear on the DashIO app. It includes all infomration for the device, controls (size, colour, style etc.), device views and connections.

When the DashIO app discovers a new IoT device, it will download the Layout Configuration from the IoT device to display the device controls they way they have been designed by the developer. This is particularly useful developing commercial products and distributing your IoT devices to other users.

To include the Layout Configuration in your IoT device, simply follow these steps:

  • Design your layout in the DashIO app and include all controls and connections that you need in your layout.
  • Export the layout: Tap on the Device button, then tap the Export Layout button.
  • Select the provisioning setup that you want (see below for provisioning details) and tap the Export button. The Layout Configuration will be emailed to you.
  • Copy and paste the C64 configuration text from the email into your Arduino code, assigning it to a pointer to store the text in program memory. Your C64 configuration text will be different to that shown below.
  • Add the pointer to the C64 configuration text (configC64Str) as a second attribute to the DashioDevice object.
  • Add the Layout Config Revision integer (CONFIG_REV) as a third attribute to the DashioDevice object.
const char configC64Str[] PROGMEM =
"lVRNb+IwEP0rlQ97SlYJCZRyIyGpVv2gopTVatWDSWbBqmNHjlNgEf99x/kqLVTa3uyZefNm3ni8JxmIsiCj388W4XQJvDlr2OpA"
"bqG5ZjRvTstSaymulSzfW5rLStF83To4hFIISDSTgoz2RAFNn55+TMiIBFHQ94deZHuDyLX9wXBoB5dx347GzqU3cIPeYDwkFilA"
"vbIEGpAfj+Ow57i2Gwd92+9fRfYwDkM77IdXoee5V64fIGijmIav8Bws8iLk0pS9J4XecUDk/XR2N77FdIkUWklepbsJHLcqS6RT"
"wXdTMQMOtMB4rUowOm3JyHUci+RUgdAVaLKoQArSBeUlxl6iXzNd0dwgMTrXwFZrPaMoFRk533uDJuJBFqyWj8ynD4Z6LTd3TNwZ"
"oppz18Z0aL9XNxRKLhUiZ5AiMmWUx5JzuSkq0gZuzG3gLzBuIyFL9brL1/ctsj1h6aE1Y1iZc3iu09QC5goSVlQ1e1YnZzCefdBy"
"UqnydcUmyHResapDxrt2rhWAIJ8peaqbix3lkgkN6kQRUWZLUEdJwuh+Hs3OTuR/1SsF06gZIcdCJshcqmaFKKcqa1eSZXB9tF4p"
"mNXADfvDVma76vsj6DLHnIJmUJc9qewLBhsEuocW2BhwYIlWHKuPcTaP7C9K7DmmKxwHqlBmom0Lc9UGk+fDLOuBmUzBy0qkrXyB"
"mV5jlyoFNe2yvdna4J9r3Nsm+sTWJaTJC3n/GC6+XTRb1PHPFRVF9aCSHepae+YGg5/ameJa1+e4N3XcoUUYNn9vFB6Rp5yYsRX4"
"ESRatoMrOMPO2kkxVX+C7VTLlMkFK0rafrfwik//Vq6q6+Ef";

DashioDevice    dashioDevice(DEVICE_TYPE, configC64Str, CONFIG_REV);

Jump In and Build Your Own IoT Device

When you are ready to create your own IoT device, the following links will provide you with more details about what you need to know.

Devices & Connections

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

Messaging for All Controls

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