Adding DashIO to your product is simple, low cost to develop and easy distribute. The lightweight DashIO Protocol adds very little overhead to your product. We build customized and branded versions of the DashIO Dashboard app and DashIO Cloud Services for you and your customers’ exclusive only. Contact us to discuss your requirements.
DashIO works just as well for one-off projects as it does for mass production. Because hardware specific libraries are not required, DashIO is very flexible. The lightweight DashIO Protocol allows you to easily add DashIO to the majority of the off-the shelf micro-controller and development boards that are available, from simple Arduinos through to ESPs, Raspberry Pis, and PCs and Macs.
The DashIO app can connect directly to your IoT device with Bluetooth BLE or TCP connections. For remote IoT devices, an MQTT broker, such as the dash MQTT broker is required to make the connection. A single IoT device may be connected with a one or more connection types (BLE, TCP or MQTT ), to allow rapid and direct connection when the user is close to the IoT device and remote connection connections via the MQTT broker when the user and the IoT device are separated.
The DashIO Protocol is used to send and receive messages between controls (buttons, knobs, graphs etc.) on the DashIO dashboard app and their counterparts in the IoT device. It operates over all connection types (BLE, TCP and MQTT).
DashIO Protocol Features
- ASCII text messages (Human readable).
- Easy to generate and parse.
- Designed to be transported by any network.
- Variable length messages.
- Asynchronous communication.
- Open for anyone to use.
Messages containing information about the values of controls are transfered between the DashIO Dashboard and your IoT device. These messages are defined in the DashIO Protocol, as are messages that allow for Push Notifications (alarms or events), device discovery and configuration. Configuration messages enable IoT devices to send the control designs and their layout onto the DashIO app.
DashIO Key Concepts
Connections: The method of communication. The available
connection types are BLE (Bluetooth Light), TCP or MQTT. There may be one of each connection type per device. Connections are used to transfer messages between the IoT devices and the controls on the DashIO Dashboard. Messages include the controlID and deviceID to enable correct addressing of the message information.
Devices: Your IoT devices properties mapped into the DashIO Dashboard. Device instances within the DashIO Dashboard are the primary source of information for the IoT devices that the DashIO Dashboard is working with. Each Device instance contains a unique
identifier, the deviceID.
Device Views: The highest level graphics objects for each IoT device. Each Device View is displayed on the DashIO Dashboard and the Controls for the IoT device are displayed on the Device Views. Each device must have at lease one Device View. Each Device View is identified with a controlID.
Controls: The buttons, knobs, graphs, sliders etc. that your IoT device requires. Controls are functional graphics object that provide user input and output for each IoT device. The controls communicate through the connections to an IoT device. Controls are displayed in one of their IoT device’s Device Views or, in some cases, on other controls (e.g. Menu or Button Group controls). Controls are identified with a controlID.
For a detailed description of the DashIO Protocol, please download the DashIO Protocol specification. However, an in depth knowledge of the DashIO Protocol is not necessary to get started and set up your device to connect with the DashIO app.
Setup your iot device
1. Select the hardware for your IoT device.
2. Include the DashIO library into your project or start with one of the example projects.
3. Create the functionality for you project using the DashIO library.
The hardware you choose must have a suitable communications peripheral. Some off-the-shelf boards, like the Arduino Uno
will need a TCP, Wi-Fi or BLE Shield to communicate, while others are already communication-enabled; like the ESP8266, ESP32, Raspberri Pi with WiFi dongle, Particle Photon or the many low cost Linux boards. Because there are BLE, TCP and WiFi shields and breakout boards that can be added to any microcontroller, there is almost no limit to the hardware that the DashIO Dashboard can connect and communicate with. The DashIO Dashboard can even be used to communicate with other mobile phones and tablets.
Include DashIO Library
The DashIO library is an open source, lightweight message processor that encodes and decodes messages for sending and receiving over a BLE, TCP or MQTT connections. It provides the following services:
- Decodes incoming messages into the message/control type, identifier and data fields, proving all the information required by the IoT device.
- Encodes messages to send to the IoT Dashboard, given the message/control type, identifier and data.
- Encodes configuration information for each control into JSON strings for sending in the data field of configuration messages.
- Device and connection classes for managing messages.
- Control configuration structures and helper functions to simplify control configuration messages.
- Arduino C++
Create Your IoT Device
Design and build your IoT device. The software development guides show how to use the DashIO library and the example projects are a great way to start your project.
Each IoT device may communicate with the DashIO Dashboard with one or more of the three connection types available; Bluetooth LE (BLE), TCP, and MQTT. If more than one connection is enabled and actively communicating between the DashIO app and IoT device, the messages are only transmitted through the connection with the highest priority. The priority order, from highest to lowest is 1) BLE, 2) TCP, 3 MQTT.
The DashIO protocol operates over all connection types, with only minor differences required for device discovery.
A BLE IoT device connection can be easily setup to operate with the DashIO Protocol. Device discovery is achieved with the DashIO app scanning for BLE enabled IoT devices which must be setup as follows:
- The IoT device is setup as a BLE peripheral.
- The peripheral (local name) should be set to the device type. Do NOT set the peripheral name to the device name because the device name can be changed via the DashIO protocol, but changing the peripheral name can cause significant confusion as it is usually cached in the BLE Central (client).
- The Service UUID must be advertised and the peripheral must be connectable. No additional or secondary advertised data is required. Some BLE peripherals advertise the Service UUID by default, while others must be specifically setup to advertise the Service UUID.
- The advertised service must have notify and write characteristics. It may be a single characteristic containing both notify and write properties.
- The DashIO Protocol must be operating.
Device discovery is not complete until a DashIO Protocol WHO request message is written to the discovered device, and receipt of the WHO response message is received from the IoT device and validated. Secure (encrypted) BLE connections may be used. Please note that BLE libraries can be resource intense, such as ESP32 BLE libraries.
TCP connections require an IP address and port. The DashIO app will always attempt to connect to TCP communicating IoT devices over the local network that the DashIO app is operating on. Therefore, if the IoT device is not on the same local network as the dashboard, they will not be able to connect.
Device discovery is achieved with mDNS. Using mDNS allows the DashIO Dashboard to discover IoT devices on any port on the local network having the mDNS service “_DashIO._tcp.“. A DashIO Protocol WHO request message is written to the discovered device. Receipt of the WHO response message from the IoT device validates that the discovered device is available to be used with the DashIO Protocol. No additional service text messages are required.
MQTT connections can be made using any MQTT broker, using the publish and subscribe topics defined in the DashIO Protocol. However, device discovery can ONLY occur when the DashIO Cloud Services MQTT broker is used.
Device discovery is an integral part of the DashIO Cloud Services and is initiated by the IoT device sending a DashIO Protocol WHO message to the announce MQTT topic. The WHO message contains the device identifier, device type and device name which are retrieved by the DashIO MQTT broker and stored as an available device for the particular user. The DashIO app retrieves the available IoT devices from the DashIO Cloud Services database.
Push notifications (events or alarms) can created with DashIO Cloud Services. The IoT device can send a notification message to the alarm topic which contains the notification information. This information is retrieved by the MQTT broker and sent to the push notification server, which sends the notification to your mobile device.
The DashIO Cloud Services MQTT broker connection must use SSL.
The DashIO app contains a list of virtual Devices that have been loaded into the Dashboard. The DashIO app allows each device to be selected to show information including the device name, device type and which connections are being used. Each connections can be selected from the virtual device to view and edit the connection details and to view the incoming and outgoing messages.
For IoT devices connected through the DashIO Cloud MQTT broker, if the device within the DashIO app is selected, the user can view and manage alarms and sharing of the device.
All controls for IoT devices are presented on the DashIO app in Device Views. A Device View contains the theme (i.e. layout information and general colors) for all the controls present on the Device View.
Device View Size
The DashIO app is always displayed in portrait style on a phone and landscape style on a tablet.
Device Views are presented in a column format so the user can scroll horizontally between the columns and device views. One column is the width of a phone in portrait style. Tablets are 3 columns wide. The default Device View height is the height of the screen the Device View is being presented on.
Device Views are scaled according to the device they are presented on and can be one of three sizes with differing widths, but having the same default height. The width is defined by the number of columns of the device view and may be 1, 2 or 3 columns wide. The width to height ratio of a single column Device View is very approximately 1 to 2.
For phones, single column device views generally look better than multiple column Device Views. However, for complex layouts that are mainly for use on tablets, wider Devices Views may provide a better solution. Note that the IoT device can configure different Device Views for phones and tablets.
Controls are used on the DashIO app as a means of sending actions to the IoT device and displaying information from the IoT device. They may be setup anywhere on a Device View on the DashIO app and configured to meet your design requirements. They can be easily resized, colored and have their behavior adjusted as needed. Each control transfers information with its virtual counterpart in the IoT device.
The IoT device may send information to controls in the DashIO app at any time. Even controls that send actions to the IoT device (e.g. buttons) are also capable of receiving information from their counterparts in the IoT device and displaying the data. When the user causes an action through a control on the DashIO app, the IoT device should respond to indicate that the actions has occurred. The response is then shown on the control on the dashboard, therefore ensuring feedback is provided to the user of the DashIO app.
For a detailed description of how each control works, please download the DashIO Controls document.
A Button allow the user to send a simple action, informing the IoT device that the button has been pressed. The button state (on or off color) is not changed by tapping the button. After the IoT device receives a message containing the action, it sends a message back to the control in the dashboard to set the button state.
A Button control behaves as both as a momentary push button for user input and as a status indicator to provide feedback from the IoT device.
A Sliders allow the user to send a numerical values to the IoT device when the user drags the slider to a new position. The slider also includes bar graph that can be set by the IoT device. The bar graphs can be controlled independently of the slider or can be used to provide feedback to the user from the IoT Device.
The IoT device may send messages to update both the bar graph and the slider knob positions. The bar graph may set to have two bars.
The knob of the slider may be disabled so that the slider becomes a simple bar graph indicator.
A Knob allow the user to send numerical values to the IoT device when the user drags the knob to a new position. A Knob control contains a user adjustable knob surrounded by a simple dial indicator. The dial can be controlled independently of the knob or can be used to provide feedback to the user from the IoT Device.
The IoT device may send messages to update both the dial and knob positions.
A Dial display is used to present a numerical value in a graphical circular dial. The Dial display receives messages from the IoT device to set the dial position.
A Direction display is used to graphically present a decimal direction value from 0 to 360 degrees. The Direction display receives messages from the IoT device to set the direction indicator position.
A Text Box control receives simple line text messages from the IoT device to display on the DashIO Dashboard. The text may optionally be plain text, reformatted as a number or, when the text is ISO8601 date/time, it may be formatted to a date/time that is easy to read.
The Text Box may also allow the user to input text. Touching the control will present the user with a keyboard where the user can enter text. When the Send button on the keyboard is pressed, the message will be sent to the IoT device.
A Graph display is used to present graphical data on the DashIO Dashboard, where the data is a series of vertical (Y) axis data. The data is evenly spaced on the horizontal (X) axis. The IoT device sends a message for each line in the graph. The data may be shown as lines, bars or peak values.
Each line can be independently added, deleted or changed by the IoT device. Multiple IoT devices can add lines to a single Graph control.
Each line can be independently added, deleted or changed by the IoT device. Multiple IoT devices can add lines to a single Time Graph control.
Graph data is stored in the dashboard.
A Selector control is used to present a popup list of options that the user can select from. When a Selector is tapped, the DashIO Dashboard presents the list of text options to the user to make their selection from. The user can tap on an option to select is and the index of the selected option will be sent to the IoT device.
Feedback to the user of the dashboard is achieved when the IoT device responds to the selection message. The dashboard updates the Selector control check box with this value.
A Menu control is used to present a popup table of user adjustable controls and is ideal for presenting a list of IoT device setup parameters. The Menu does not receive messages directly, but presents a list of other controls (sub-controls) that send and receive messages of their own.
Controls that can be included in a Menu control are Text Boxes, Sliders, Selectors and Buttons.
A Button Group control is used to present a popup grid or table of Button controls. The Button Group does not receive messages directly, but presents Button controls that send and receive messages.
An Event Log display is used to present time stamped events or alarms from IoT devices. The most recent event is shown on the control and a scrollable list of events is presented when the Event Log is tapped by the user.
Each event contains the time of the event, the color to display the event and the text to display.
Multiple IoT devices can be shown on a single Event Log control.
A Map display is used to plot positions on a map. The Map display receives messages from the IoT Device that contain latitude and longitude to mark the position. Additional data, such as speed and altitude may also be included and shown on the Map display.
Multiple IoT devices can be shown on a single Map.
A Label is a simple control to add structure to your layout on the dashboard. They do not transfer information with IoT devices.
Setting up your IoT device for automated configuration allows the IoT device to send all the required information for the layout of the controls and connections onto the DashIO app. If you are going to share access to your device to others, or distribute a product, then automated configuration is essential for your users to simplify setting up their DashIO app.
- Each Connection
- The Device
- Each Device View
- Each Control
- Develop your IoT device to a point where you can establish a connections with the DashIO app.
- On your DashIO app, discover and your IoT device and connect to it through all connection types you wish to use.
- On your DashIO app, manually add device views, and controls and set their positions, colors and other parameters to your requirements. Make sure you set a Control ID for each control.
- Select your device from the Devices menu and press the Share Config button. This will allow you to email the configuration information in JSON format; showing the key : value pairs for all parameters for all controls in your IoT device.
- Enter the key : value pair information into configuration objects into your IoT device code. When a CONFIG message is received by your IoT device, send the configuration objects to the DashIO app. See the DashIO Protocol specification for more details.
dashio dashboard OVerview
The DashIO app contains a set of device views with controls located on them. The buttons at the top left and top right and at the bottom of the screen are all that is required to use the DashIO app.
Context sensitive help is available in menu of the menus. Simply tap the “?” button at the top right of the menu.
The navigation buttons allow the user to move Left or Right through the device views or to jump to a specific device view from the Device Views menu.
Tap the Devices button to bring up a list of all IoT devices that are known to the DashIO app. From the devices menu you can perform the following device related functions:
- Find and attach new devices
- Delete the device
- View the connections and a live stream of the connection messages
- Perform device setup (device name, passwords etc)
- Download the configuration (layout and controls) for the device
- Manage alarms
- Manage device sharing
- Retrieve the device layout configuration data
Tap the DashIO account button to setup and edit your account settings. Although an account isn’t necessary to use the DashIO Dashboard, it provides the following benefits:
- MQTT broker for MQTT connections
- Push notifications (events or alarms)
- Sharing of IoT devices to other users
- Saving and loading of the DashIO controls and layout
- Reviewing and deleting DashIO dashboards apps attached to the account
- Reviewing and deleting IoT devices attached to the account
Tap the Settings menu button to:
- Adjust DashIO app settings such as units and toolbar behavior.
- View product information
- View help menus
- Review credit usage and in-app purchases
- Contact information
A Device View can be set to edit mode to allow the user to changes the layout of the controls, adjust the behavior of the controls and add or delete controls. Tap the Edit button to enter edit mode and a grid will be shown behind the controls. When you have finished editing, tap the Edit button again to exit edit mode.
Use edit mode to design the controls and layout for your IoT device. Once your design is complete, you can export your design in JSON format and use this information to setup the config messages in your IoT device. This will allow any dashboard that connects to your IoT device to be able to automatically configure the dashboard for the controls and layout specific to your IoT device.
Tap anywhere on the grid where there are no controls to edit the details of the device view that is being edited..
Edit Device View
When a Device View is in edit mode, you can tap on the Edit Device View button to edit the device view parameters and theme for the controls.