Integration Guide

Integrating ESP-DASH in your existing code is pretty simple. This guide assumes that you already have a simple webserver code prepared and you just need to inject the following lines in your existing code:

Include Dependencies

We have used conditional compilation in this part therefore the code will work for ESP8266, ESP32 or RP2040+W.

#include <Arduino.h>
#if defined(ESP8266)
  /* ESP8266 Dependencies */
  #include <ESP8266WiFi.h>
  #include <ESPAsyncTCP.h>
  #include <ESPAsyncWebServer.h>
#elif defined(ESP32)
  /* ESP32 Dependencies */
  #include <WiFi.h>
  #include <AsyncTCP.h>
  #include <ESPAsyncWebServer.h>
#elif defined(TARGET_RP2040)
  /* RP2040 Dependencies */
  #include <WiFi.h>
  #include <AsyncTCP_RP2040W.h>
  #include <ESPAsyncWebServer.h>
#endif
 
#include <ESPDash.h>

Create AsyncWebServer Instance

Create an AsyncWebServer instance on default “80” port.

/* Start Webserver */
AsyncWebServer server(80);

💡

Note: You are not restricted to a single dashboard. You can host as many dashboards as you want on multiple ports.

Attach ESP-DASH Instance

Pass the AsyncWebServer instance to ESPDash’s instance. Internally the ESPDash will hook to AsyncWebServer for handling all the networking tasks.

/* Attach ESP-DASH to AsyncWebServer */
ESPDash dashboard(&server);

💡

You can still use the same AsyncWebServer instance for other tasks.

Create Widgets

In this step, we will be creating ESP-DASH widgets and passing our dasboard instance as a first argument so that they can add / remove themselves.

After we are done with this guide, Please take a look at Cards section to know more about the types of cards available to us.

/* 
  Dashboard Cards 
  Format - (Dashboard Instance, Card Type, Card Name, Card Symbol(optional) )
*/
Card temperature(&dashboard, TEMPERATURE_CARD, "Temperature", "°C");
 
Card humidity(&dashboard, HUMIDITY_CARD, "Humidity", "%");

Setup Block

In our setup block, we will be adding the usual WiFi connectivity stuff and then start our AsyncWebServer with server.begin();.

void setup() {
  Serial.begin(115200);
 
  /* Connect WiFi */
  WiFi.mode(WIFI_STA);
  WiFi.begin("ssid", "password");
  if (WiFi.waitForConnectResult() != WL_CONNECTED) {
      Serial.printf("WiFi Failed!\n");
      return;
  }
  Serial.print("IP Address: ");
  Serial.println(WiFi.localIP());
 
  /* Start AsyncWebServer */
  server.begin();
}

Loop Block

In our loop block, we will be doing 2 things:

Updating card values
Sending updates to our dashboard

Technically speaking, You can call these functions anywhere in your sketch, but for demonstration purposes we have called them in our loop block.

void loop() {
  /* Update Card Values */
  temperature.update((int)random(0, 50));
  humidity.update((int)random(0, 100));
 
  /* Send Updates to our Dashboard (realtime) */
  dashboard.sendUpdates();
 
  /* 
    Delay is just for demonstration purposes in this example,
    Replace this code with 'millis interval' in your final project.
  */
  delay(3000);
}

Final Code

That’s it! Now we can just upload this sketch to our MCU and access the dashboard via it’s IP address. ( Make sure to change the ssid and password in our sketch according to your Access Point )

/*
  -----------------------
  ESPDASH - Basic Example
  -----------------------
 
  Skill Level: Intermediate
 
  In this example we will be creating a basic dashboard which consists 
  of some cards and then update them in realtime ( at 3s interval ).
 
  Github: https://github.com/ayushsharma82/ESP-DASH
  Documentation: https://docs.espdash.pro
 
  Works with ESP8266, ESP32 and RP2040+W
*/
 
#include <Arduino.h>
#if defined(ESP8266)
  /* ESP8266 Dependencies */
  #include <ESP8266WiFi.h>
  #include <ESPAsyncTCP.h>
  #include <ESPAsyncWebServer.h>
#elif defined(ESP32)
  /* ESP32 Dependencies */
  #include <WiFi.h>
  #include <AsyncTCP.h>
  #include <ESPAsyncWebServer.h>
#elif defined(TARGET_RP2040)
  /* RP2040 Dependencies */
  #include <WiFi.h>
  #include <AsyncTCP_RP2040W.h>
  #include <ESPAsyncWebServer.h>
#endif
 
#include <ESPDash.h>
 
 
/* Your WiFi Credentials */
const char* ssid = ""; // SSID
const char* password = ""; // Password
 
/* Start Webserver */
AsyncWebServer server(80);
 
/* Attach ESP-DASH to AsyncWebServer */
ESPDash dashboard(&server); 
 
/* 
  Dashboard Cards 
  Format - (Dashboard Instance, Card Type, Card Name, Card Symbol(optional) )
*/
Card temperature(&dashboard, TEMPERATURE_CARD, "Temperature", "°C");
Card humidity(&dashboard, HUMIDITY_CARD, "Humidity", "%");
 
 
void setup() {
  Serial.begin(115200);
 
  /* Connect WiFi */
  WiFi.mode(WIFI_STA);
  WiFi.begin(ssid, password);
  if (WiFi.waitForConnectResult() != WL_CONNECTED) {
      Serial.printf("WiFi Failed!\n");
      return;
  }
  Serial.print("IP Address: ");
  Serial.println(WiFi.localIP());
 
  /* Start AsyncWebServer */
  server.begin();
}
 
void loop() {
  /* Update Card Values */
  temperature.update((int)random(0, 50));
  humidity.update((int)random(0, 100));
 
  /* Send Updates to our Dashboard (realtime) */
  dashboard.sendUpdates();
 
  /* 
    Delay is just for demonstration purposes in this example,
    Replace this code with 'millis interval' in your final project.
  */
  delay(3000);
}

Installation Examples