Bar Chart

A bar chart compares quantities across categories or discrete intervals, such as daily energy consumption or event counts per hour. In ESP-DASH v5, bar charts are created with the dash::BarChart<X, Y> class template, where X and Y define the data types of the two axes.

ConstructorCopy Anchor Link

dash::BarChart<X, Y> chart(ESPDash& dashboard, const char* name);
dash::BarChart<X, Y> chart(const char* name);

The first form creates the chart and adds it to dashboard. The second form creates the chart without adding it to a dashboard; add it later with dashboard.add(chart).

Template parametersCopy Anchor Link

dash::string is an alias for Arduino String, or for std::string when DASH_USE_STL_STRING is defined. Any other type for X or Y fails to compile.

Constructor parametersCopy Anchor Link

// Category labels on the X-axis, integer values on the Y-axis
dash::BarChart<const char*, int> sales(dashboard, "Sales by Day");

// Numeric X-axis, floating-point Y-axis
dash::BarChart<int, float> production(dashboard, "Production");

MethodsCopy Anchor Link

setXCopy Anchor Link

bool setX(X arr_x[], size_t x_size);

Sets the X-axis data. The element type of arr_x must match the template parameter X. The chart stores a pointer to the array and marks the X-axis as changed; the data is sent on the next call to dashboard.sendUpdates(). Always returns true.

const char* days[] = {"Mon", "Tue", "Wed", "Thu", "Fri"};
sales.setX(days, 5);

setYCopy Anchor Link

bool setY(Y arr_y[], size_t y_size);

Sets the Y-axis data. The element type of arr_y must match the template parameter Y. The chart stores a pointer to the array and marks the Y-axis as changed; the data is sent on the next call to dashboard.sendUpdates(). Always returns true.

int totals[] = {10, 20, 15, 30, 25};
sales.setY(totals, 5);

x and yCopy Anchor Link

const X* x() const;
const Y* y() const;

Return a pointer to the current X-axis or Y-axis array, or nullptr if the axis has not been set.

const int* current = sales.y();

xSize and ySizeCopy Anchor Link

size_t xSize() const;
size_t ySize() const;

Return the number of elements passed to the last setX() or setY() call, or 0 if the axis has not been set.

setNameCopy Anchor Link

bool setName(const char* name);

Changes the chart title. Returns false if the new title is identical to the current one; otherwise marks the title as changed and returns true. As with the constructor, the pointer is stored and must remain valid.

ExampleCopy Anchor Link

#include <Arduino.h>
#include <WiFi.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>
#include <ESPDash.h>

const char* ssid = "";
const char* password = "";

AsyncWebServer server(80);
ESPDash dashboard(server);

// Chart data must outlive the chart, so it is declared at global scope
const char* XAxis[] = {"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"};
int YAxis[] = {0, 0, 0, 0, 0, 0, 0};

dash::BarChart<const char*, int> power(dashboard, "Power Usage (kWh)");

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

  WiFi.mode(WIFI_STA);
  WiFi.begin(ssid, password);
  if (WiFi.waitForConnectResult() != WL_CONNECTED) {
    Serial.println("WiFi connection failed");
    return;
  }
  Serial.println(WiFi.localIP());

  // The X-axis does not change in this example, so it is set once
  power.setX(XAxis, 7);
  power.setY(YAxis, 7);

  server.begin();
}

void loop() {
  static unsigned long lastUpdate = 0;
  if (millis() - lastUpdate >= 3000) {
    lastUpdate = millis();

    for (int i = 0; i < 7; i++) {
      YAxis[i] = (int)random(0, 200);
    }

    // Mark the Y-axis as changed, then push the update to all clients
    power.setY(YAxis, 7);
    dashboard.sendUpdates();
  }
}

NotesCopy Anchor Link

• Data lifetime. Charts do not copy axis data. setX() and setY() store a pointer to your array, and the array is read each time the chart is serialized for a client. Declare the arrays at global scope or as static, never as local variables of the function that calls setX() or setY().
• Array constness. setX() and setY() take a non-const pointer, so the array elements themselves cannot be const (for example, const int values[] does not compile as a Y-axis). An array of const char* labels is valid because the elements are pointers.
• Matching sizes. Pass the same number of elements to setX() and setY() so that each value has a corresponding label.
• Shared API. All v5 chart types (Line, Area, Pie and Doughnut) derive from the same base class and expose the same constructor signatures and methods as dash::BarChart.
• Layout options. In ESP-DASH Pro, charts also support setSize(), setIndex(), setDisplay() and assignment to tabs.