Statistics

Statistics display key values on a dedicated Statistics page of the dashboard. Use them for device information, sensor readings or any other single data point you want to highlight.

TypesCopy Anchor Link

ESP-DASH provides two statistic classes:

• dash::StatisticValue: displays a value that you set from your sketch.
• dash::StatisticProvider: displays a value returned by a function that ESP-DASH calls when it generates an update.

ConstructorCopy Anchor Link

Declare statistics in global scope. Both classes take the dashboard instance and a name, which is shown as the label of the statistic on the dashboard.

dash::StatisticValue<const char*> hardwareStat(dashboard, "Hardware");
dash::StatisticValue<uint32_t> freeHeapStat(dashboard, "Free Heap");

dash::StatisticProvider<uint32_t> heapProvider(dashboard, "Free Heap (SRAM)");

Template parameters:

MethodsCopy Anchor Link

setValueCopy Anchor Link

Available on dash::StatisticValue. Sets the value of the statistic and returns true if the value changed, or false if it is identical to the current value.

hardwareStat.setValue("ESP32");
freeHeapStat.setValue(ESP.getFreeHeap());

setProviderCopy Anchor Link

Available on dash::StatisticProvider. Registers a function that returns the current value. ESP-DASH calls the provider whenever it generates the dashboard layout or an update, so you do not need to set the value yourself.

heapProvider.setProvider([]() {
  return ESP.getFreeHeap();
});

The provider must return a value of type T.

ExampleCopy Anchor Link

The following sketch uses both statistic classes. Default statistics are disabled because they already use the names "Hardware", "SDK Version" and "Free Heap (SRAM)"; see Disable Statistics.

// ...

/* Disable the default statistics */
ESPDash dashboard(server, false);

// Statistic Value
dash::StatisticValue<const char*> hardware(dashboard, "Hardware");
dash::StatisticValue<dash::string> sdkVersion(dashboard, "SDK Version");

// Statistic Provider
dash::StatisticProvider<uint32_t> freeHeap(dashboard, "Free Heap (SRAM)");

void setup() {
  // ...

  // Set values for Statistic Value
  hardware.setValue("my-custom-hardware");
  sdkVersion.setValue(ESP.getSdkVersion());

  // Set provider for Statistic Provider
  freeHeap.setProvider([]() {
    return ESP.getFreeHeap();
  });
}

void loop() {
  // StatisticProvider values are read automatically when the dashboard updates.
  // StatisticValue values must be set whenever the data changes, for example:
  // if (some_condition) {
  //   hardware.setValue("New Hardware Value");
  //   dashboard.sendUpdates();
  // }
}

NotesCopy Anchor Link

• By default, ESP-DASH adds the following system statistics: Hardware, SDK Version, Free Heap (SRAM), WiFi Mode and WiFi Signal. To remove them, see Disable Statistics.
• ESP.getFreeHeap() and ESP.getSdkVersion() are available on ESP32. On RP2040 and RP2350, use rp2040.getFreeHeap() to read the free heap.
• Updated values reach connected clients when you call dashboard.sendUpdates(); this also applies to values returned by a provider.