mDash Quick Start Guide

This guide outlines a full implementation of a commercial IoT product.

mDash Smart Light Diagram

The objective of the below project is an implementation of an IoT smart light. For this project, we are going to use an ESP32 development board with LED. Once the devboard is shipped to the customer, they can download the mobile app, register, and provision a device. You, as a vendor, have full control over all shipped products, including device dashboard with OTA firmware updates, remote management, customer activity, etc.

Step-by-step guide


1. Setup ESP32 device

For this project, you will need an ESP32 board. If your board does not have a built-in LED, attach it to one of the IO pins. Connect your ESP32 device to your workstation via a USB cable.

2. Clone Smart Light repository

The Smart Light repository can be downloaded from here: https://github.com/cesanta/mdash-smart-light. Clone it to your computer with the following command:

git clone https://github.com/cesanta/mdash-smart-light.git

2. Build and flash firmware

This reference project contains firmware sources suitable for different build environments. You can select the one that suits you best.

  • Using Arduino IDE
    • Download and install Arduino IDE
    • Install ESP32 support in Arduino IDE
    • Install mDash library:
      • Select "Sketch" → "Include Library" → "Manage Libraries"
      • In the search field, type "mDash" and press Enter
      • Click on "Install" to install the library
    • Select "Tools" → "Board" → "ESP32 Dev Module"
    • Select "Tools" → "Partitioning Scheme" → "Minimal SPIFFS"
    • Select "Tools" → "Port" → your serial port
    • Open file firmware/arduino/SmartLight.ino in Arduino IDE
    • Press on "Upload" button to build and upload the sketch to your device
  • Using ESP-IDF
    • Install ESP32 support in Arduino IDE to setup a correct cross-compiler toolchain
    • Install a stable release of ESP-IDF:
      mkdir -p ~/esp
      cd ~/esp
      git clone --single-branch --branch v3.2 https://github.com/espressif/esp-idf
      cd esp-idf
      git submodule update --init --recursive
      export IDF_PATH=~/esp/esp-idf
    • Find path to the Arduino's ESP32 GCC toolchain - i.e. a directory where xtensa-esp32-elf-gcc compiler binary lives. For example, on MacOS it could be ~/Library/Arduino15/packages/esp32/tools/xtensa-esp32-elf-gcc/1.22.0-80-g6c4433a-5.2.0/bin. On your system, it could be different. Add this path to the $PATH environment variable:
      # Note this will reset the PATH, to make sure we're using the correct one
      export PATH=/bin:/usr/bin:/usr/local/bin:PATH_TO_TOOLCHAIN_BIN_DIR
    • Now build and flash the firmware:
      $ cd PATH/TO/mdash-smart-light/firmware/esp-idf
      $ rm -rf sdkconfig sdkconfig.old build mDash
      $ make mdash defconfig flash ESPPORT=SERIAL_PORT

The firmware code does not contain WiFi or cloud credentials. This means you can OTA multiple devices with the same firmware. WiFi and cloud credentials will be stored in the configuration file mdash.cfg. WiFi name/password will be set up by the end-customer via the mobile app. The cloud credentials (device password) should be set up by the device vendor (you!) before shipping the device to a customer - see the next section.

4. Setup device credentials

There are two types of credentials stored on a device:

  • WiFi network name and password to get on the Internet
  • Cloud credentials (device password) to connect to mDash

The Cloud credentials are going to be set up right now via Serial console. Each device we ship to a customer has a unique device password. The WiFi credentials will be set up later via the mobile app (this is the end-customer part).

Both WiFi and cloud credentials are stored in the mdash.cfg configuration file. Mobile app and serial console are just different methods of setting up values in mdash.cfg. If you decide to implement any other custom method, e.g. via the NFC tag, just save the result using mDashConfigSet API call.

Login to https://mdash.net and register a new device. Click on Device Settings icon to see device token (password):

Now, start serial console:

  • In Arduino IDE, press the Serial Monitor button in the top right corner
  • If you use ESP-IDF, start any terminal emulator, like
    $ cu -h -s 115200 -l SERIAL_PORT
    or,
    miniterm.py -e SERIAL_PORT 115200

In the serial console, type in the following command to save the device token (password) and press enter:

set device.pass DEVICE_PASSWORD

NOTE: device settings are saved in the mdash.cfg configuration file on a device's filesystem. Once a device boots up, it will look for WiFi and cloud credentials in that file. While the binary firmware on all of your devices stays the same, the configuration files will be different.

In order to factory-reset a device, call mDashConfigReset() API function. That function simply deletes the mdash.cfg file. The SmartLight firmware will call mDashConfigReset() on a long (more than 3 seconds) button press.

Now it is time to configure device ACL to define what a customer can do with the device, and what cannot do. Click on the device settings icon, choose "ACL" tab, and modify the shadow_read and shadow_write values:

{
  "shadow_read": "^.state.reported.(online|on|name)",
  "shadow_write": "^.state.desired.(on|name)",
  "rpc": "",
  "public_key": "DO NOT MODIFY THIS!",
  "publish_data": false
}

Click Save. We have just granted our mobile app some restricted permissions to access our device.

5. Mobile app overview

Now cloud credentials are set up, and your device is ready to be shipped to a customer. A customer gets a physical device and a mobile app to set up and control the device.

The mobile app in this reference project is built with PWA technology, It is written using Bootstrap and Preact. The Preact code is written in plain ES3 JavaScript, without JSX or any similar layer, to avoid an extra build step.

Open mdash-smart-light/mobile-app/index.html file in your browser to see how it looks like. An app logic resides in mdash-smart-light/mobile-app/js/app.js file. You can modify it as you wish.

Zip the mdash-smart-light/mobile-app directory. On the mDash UI, go to "WebApp" tab and upload the .zip file. mDash will assign a unique URL to your app, and start serving it:

If you wish to go with a native mobile application for Android / iPhone, take a look at the mdash-smart-light/mobile-app/js/app.js logic on how the device setup process works, and replicate it into a native app.

For production, modify this PWA according your project specs, upload to mDash or your own website and share the URL / QR code with your customers.

6. Install mobile app

Here we are acting as a customer. Open mDash "WebApp" tab. You should see your uploaded app and a QR code:

Open the WebApp on your mobile phone.

  • On iPhone
    • Open the Camera app
    • Hold your phone so the QR code appears on the camera view
    • Click on the "Open in Safari" popup
  • On Android
    • Scan the QR code in any QR code scanning application
    • Click to open in a browser

Follow the customer registration steps:

  • Send invitation email
  • Open invitation email in your inbox, click on the registration URL
  • Login using your customer email and generated password

7. WiFi setup

Initially, there are no devices in the list. Click on "Add device":

Then follow the instructions to add a device. That involves temporarily changing the phone's WiFi network to communicate directly with the device (you will need to scan for the device Access Point using phone's options in Settings). Once back in the app you'll scan for the device and then enter your WLAN's network name (SSID) and the password.

During that procedure, the app will:

  • Download the access key from the device. Later on, the app will use that key to fetch the device info from mDash and control the device
  • Send WiFi credentials to the device. The device will then join the customer's WiFi network, and connect to mDash.

8. Device control

Once the device provisioning procedure is complete, you should be able to see the added device as online:

Use the toggle button to turn the device on and off. The LED on the board should switch on and off accordingly. If the LED does not react, it means you have a wrong LED_PIN value in your firmware. Update the correct IO pin value, rebuild the firmware, and then OTA via mDash.

When done, the board should react to the toggle actions as expected. When you toggle the LED, notice how the shadow changes. Firstly, the mobile app sets state.desired.on. Then mDash sends a delta value to the device. Then the device sets the LED and updates the shadow, changing state.reported.on:

9. Next steps

Now you have an end-to-end working IoT product implementation in front of you, that you can amend to your own needs. You can now start implementing your own product, launch and sell it to your customers.

We advise you to concentrate on the most important parts of your product: the physical device itself, and an end-user interface. If you have any questions, drop us an email at support@cesanta.com, or simply use the online chat button below.

Let's launch great products together. Good luck!