IoT Dash Documentation

Complete platform guide for v0.9.2-beta — Real-time IoT Dashboard with 15 widget types & light/dark theme

Overview

IoT Dash is a real-time IoT dashboard platform that connects to MQTT brokers to visualize sensor data, control IoT devices, and track GPS locations — all from your browser via WebSocket MQTT.

The platform organizes widgets into three categories:

• Display Widgets (9 types) — Gauge, Digital Display, 7-Segment, Stat Card, Status Card, LED Indicator, Progress Bar, Terminal Log, Image Card
• Control Widgets (5 types) — Button, Toggle, Slider, Number Input, RGB Color
• Location Widget (1 type) — Map Pin with real-time GPS tracking

Plus automatic Time-Series Charts for gauge widgets and a live Data Table for all MQTT messages.

Quick Start — Manual Setup

Build your first dashboard from scratch in under 3 minutes:

Quick Start — AI Generator

The fastest way to build a dashboard. Describe your IoT setup in plain English and AI creates everything for you.

"I have an ESP32 monitoring a greenhouse with temperature,
humidity, soil moisture sensors and a water pump relay.
Also a GPS tracker on my delivery van."

Quick Start — From Template

Templates create a pre-configured dashboard with mixed widget types in one click.

See the full App Templates reference for what each template includes.

Account & Login

IoT Dash uses Firebase Authentication with email/password.

• After signing up, you must verify your email before accessing the dashboard
• All data is stored per-user in Cloud Firestore and cached in localStorage for instant loading
• Sessions persist — you stay logged in until you explicitly sign out

Apps

An app is an independent dashboard workspace. Each app has its own devices, widgets, layout, and broker configuration. You can create up to 5 apps per account.

Creating an App

Click + New App in the sidebar. Options:

• Blank — empty canvas, build from scratch
• Template — pre-configured sensors and controls (see Templates)
• AI Generate — describe your setup in words (see AI Generator)

Switching & Managing Apps

• Click any app in the sidebar to switch (dashboard fully remounts)
• Rename: right-click or use the edit button on an app
• Delete: removes the app and all its data permanently

Devices

Devices are the primary organizational unit. All widgets (sensors, controls, map pins) belong to a device. You must create at least one device before adding widgets.

Creating a Device

Device Profiles

Save a device's complete widget set as a reusable profile. Apply saved profiles when creating new devices to instantly set up all sensors, controls, and map pins. See Device Profiles.

Limits

Up to 20 devices per app. The "+ Device" button is disabled at the limit.

Widget Categories

IoT Dash organizes its 15 widget types into three categories. When you click + Add Widget, the dropdown shows all types grouped:

Gauge

The classic SVG arc gauge — a semicircular dial that fills proportionally between min and max. Best for real-time numeric values like temperature, pressure, or speed. Gauge widgets also automatically generate a time-series chart below them.

Configuration Fields

Best For

Temperature, pressure, speed, RPM, voltage — any value with a known range where you want to see "how full" the reading is.

Digital Display

A clean, large numeric readout — like a digital multimeter. Shows the value prominently in a monospace font with an optional thin bar indicating position within its range and a last-updated timestamp. Perfect when a gauge arc is overkill and you just need a big, readable number.

Features

• Monospace font — gives a clean digital-meter aesthetic
• Thin range bar — subtle position indicator (only for numeric data types)
• Last updated timestamp — shows when the last reading arrived
• Warning state — border glows red when value exceeds warning thresholds
• Multiple data types — also works for boolean (ON/OFF) and string payloads

Gauge vs Digital Display

Best For

Cumulative values (kWh, total count), high-precision readings, fast-changing values where a gauge arc would be distracting, or when you simply want the cleanest possible number display.

7-Segment Display

A retro-style seven-segment LED display — the classic look from industrial panels, digital clocks, and multimeters. Each digit is rendered as SVG segments with inactive segments faintly visible, giving that authentic hardware feel. The widget always keeps a dark panel background even in light theme for maximum realism.

Features

• SVG seven-segment digits — each segment individually rendered, inactive segments dimly visible
• Dark panel background — keeps the authentic LED panel look even in light theme
• Accent color segments — active segments glow in your chosen sensor color
• Warning state — segments turn red when value exceeds thresholds
• Supports decimals, negatives, and text — renders dots, minus signs, and basic characters

Best For

RPM, voltage, frequency, counters — any value where you want that classic industrial hardware panel aesthetic. Especially effective on dark dashboards for monitoring environments.

Stat Card

Shows the current value prominently with a trend arrow (↑ rising, ↓ falling, → stable) and min / avg / max from recent history. Great for at-a-glance monitoring.

Best For

Values where trend direction matters more than a gauge position — barometric pressure, vibration, pH, current draw. Also ideal when you want min/avg/max at a glance.

Status Card

A large, bold ON / OFF text display with a color glow. Designed for binary status indicators where you need instant, unmistakable visual clarity at a glance.

How It Works

Boolean data type: payloads 1, true, ON, open display as ON (glowing). Everything else displays as OFF (dim).

Best For

Door open/closed, machine running/stopped, alarm active/clear — any binary state where visibility from across the room matters.

LED Indicator

A simple colored glowing dot — mimics a physical LED on a circuit board. Compact and perfect for dense dashboards with many binary indicators.

LED vs Status Card

Best For

Motion detected, rain sensor, fault alerts, pump active, relay status — compact binary indicators when you have many on one dashboard.

Progress Bar

A horizontal bar that fills proportionally between min and max. Shows a percentage value alongside. Changes color when entering warning zones.

Best For

Tank levels, fill percentages, battery level, soil moisture, humidity, power consumption — any value naturally expressed as "how full" a horizontal bar is.

Terminal Log

A scrollable monospace log that displays every MQTT message received on the sensor's topic. Auto-scrolls to the latest message. Styled like a serial monitor terminal.

Image Card

Displays an image from a URL published to its MQTT topic. The payload must be a valid URL (http://, https://, or data: URI). Click the image to open it full-size.

https://cam.example.com/snap.jpg

data:image/jpeg;base64,/9j/4AAQ...

Time-Series Chart

A Recharts line chart that automatically appears for every Gauge widget with a numeric data type. Shows the recent history of values plotted over time.

Control widgets publish MQTT messages when the user interacts with them. Use them to switch relays, set thresholds, trigger actions, or send commands to your devices.

Button

A simple click-to-publish button. Each click sends a fixed payload to the configured topic.

Toggle

An ON/OFF switch that alternates between two payloads. Visually shows the current state with a sliding knob.

Slider

A range slider that publishes the current value when adjusted. Configure min, max, step, and unit.

Number Input

A text field + send button for typing an exact numeric value and publishing it. Supports min/max validation and step constraints. Press Enter or click ▶ to publish.

Slider vs Number Input

RGB Color

A Blynk-style color picker for controlling RGB LEDs, light strips, or any color-based actuator. Includes a glowing preview circle, HTML5 color picker, and individual R / G / B sliders. Similar to the RGB widget in Blynk, but with three publish format options.

Configuration

Publish Formats Comparison

ESP32 Example (CSV format)

// Subscribe to RGB topic
mqttClient.subscribe("home/led/color");

// In message callback:
void onMessage(String topic, String payload) {
  int r, g, b;
  sscanf(payload.c_str(), "%d,%d,%d", &r, &g, &b);
  analogWrite(RED_PIN, r);
  analogWrite(GREEN_PIN, g);
  analogWrite(BLUE_PIN, b);
}

Map Pin

Displays real-time GPS positions on an interactive Leaflet map. Each pin subscribes to separate MQTT topics for latitude and longitude. The map widget appears automatically when at least one map pin exists.

Configuration

Expected MQTT Payloads

topic: device/gps/lat   →  payload: 28.6139
topic: device/gps/lng   →  payload: 77.2090

Payloads must be plain numeric strings in decimal degrees.

MQTT Broker

IoT Dash connects to MQTT brokers over WebSocket (ws:// or wss://). Each app has its own broker configuration.

Broker Settings

Connection Status

Broker Presets

Simulator

The built-in simulator publishes random demo data to all your sensor topics without any hardware.

1. Ensure you're connected to an MQTT broker
2. Click ▶ Simulate in the connection bar
3. Watch all widgets update with randomized values within their configured ranges
4. Click ⏹ Stop to stop

The simulator publishes values within each sensor's configured min/max range, and random GPS coordinates for map pins.

Grid Layout

The dashboard uses a drag-and-drop grid powered by react-grid-layout v2.

Editing Layout

1. Click 🔒 to unlock the layout (changes to 🔓 Editing)
2. Drag widgets by the ⠿ handle in the top-left
3. Resize by dragging the bottom-right corner
4. Click 🔓 Editing to lock and save

Layout auto-saves with 800ms debounce.

Responsive Breakpoints

Default Widget Sizes

Data Table

A raw MQTT message log at the bottom of every dashboard. Shows recent incoming and outgoing messages with timestamps, topics, and payloads. Always present.

AI Dashboard Generator

Describe your IoT setup in plain English and the AI creates a complete dashboard with devices, sensors (automatically choosing appropriate widget types), controls, and map pins.

How It Works

1. Click 🤖 AI Generate in the sidebar
2. Describe your project (devices, sensors, what they measure, controls needed)
3. Click Generate — AI analyzes your description and creates a blueprint
4. Preview the generated devices, sensors, and controls
5. Click Create Dashboard to apply it

Tips for Better Results

• Be specific: "ESP32 with DHT22 (temperature + humidity) and BMP280 (pressure)"
• Mention controls: "relay for water pump", "slider for fan speed"
• Mention locations: "GPS tracker on delivery van"
• Specify quantities: "4 room temperature sensors, 1 outdoor weather station"

Theme (Light / Dark)

IoT Dash supports both dark and light themes. Switch using the theme toggle button in the sidebar footer.

How to Switch

1. Open the sidebar (expand it if collapsed)
2. At the bottom, click ☀️ Light Mode or 🌙 Dark Mode
3. The theme switches instantly — all widgets, modals, charts, and maps adapt

Persistence

Your theme preference is saved to localStorage and persists across sessions. The theme is applied before React loads (via an inline script in index.html) so there's no flash of the wrong theme on page load.

CSS Variable System

The theme system uses CSS custom properties on the :root / [data-theme] selectors. All background colors, text colors, borders, shadows, and accent transparencies are driven by these variables:

ESP32 Code Generator

Click 📥 ESP32 in the connection bar to download a ready-to-flash Arduino sketch.

What's Included

• WiFi connection code (set your SSID/password)
• All broker presets as selectable blocks
• Sensor publish code — simulated values within your min/max ranges
• Control subscribe code — callbacks for each control topic
• Map pin GPS simulation — lat/lng near a base coordinate
• Auto-reconnect with configurable interval

Flashing Steps

Requirements

App Templates

Templates create pre-configured dashboards with mixed widget types in one click:

All template widgets can be edited, deleted, or added to after creation.

Device Profiles

Device profiles let you save and reuse a device's complete widget configuration.

Built-in Profiles

Custom Profiles

• Set up a device with all the widgets you want
• Right-click the device tab → Save as Profile
• When creating new devices, pick your saved profile from the profile picker
• Custom profiles can be deleted from the profile picker

Limits & Quotas

Tips & Shortcuts

FAQ

Why can't I add widgets? The button is disabled.

You need a device first. Click + Device to create one, then widgets become available.

My widgets show "—" instead of a value.

No MQTT message has been received on that topic yet. Check that:

• You're connected to the broker (green status indicator)
• Your device publishes to the exact same topic string
• The broker allows the subscription (check ACLs if using authentication)

Can I use my own MQTT broker?

Yes! Choose "Custom Broker" in broker settings and enter your WebSocket URL (ws:// or wss://). Raw TCP (mqtt://) is not supported in browsers.

Why does my ESP32 use port 1883 but the dashboard uses 8084?

Browsers use WebSocket MQTT (port 8084 for WSS on EMQX). ESP32 uses raw TCP MQTT (port 1883). Both connect to the same broker through different protocol listeners.

What's the difference between Gauge and Stat Card?

Gauge shows a visual arc dial (like a speedometer) + generates a time-series chart. Stat Card shows a big number with trend arrow + min/avg/max — no chart. Choose Gauge when the arc visualization and chart history are valuable; choose Stat when trend direction and statistics matter more.

When should I use LED vs Status Card?

LED is compact (small dot) — best for dense dashboards with many indicators. Status Card is large with bold text — visible from across the room, best for critical statuses.

When should I use Slider vs Number Input?

Slider for approximate values in small ranges (volume, fan speed 0–100). Number Input for exact values or large ranges (setpoints, addresses, thresholds 0–10000).

How does the RGB Color widget publish data?

You choose the format when creating the widget: CSV (255,128,0), JSON ({"r":255,"g":128,"b":0}), or HEX (#FF8000). With auto-send enabled, every slider or picker change publishes immediately.

Can I switch between light and dark mode?

Yes! Click the ☀️ / 🌙 toggle in the sidebar footer. Your preference is saved automatically.

Is my data private?

Your dashboard config is stored in Firebase under your account. MQTT messages pass through the broker you choose — public brokers mean anyone can see your topics. Use IoT Dash Cloud or your own private broker for security.

What happens when I delete a device?

All sensors, controls, and map pins belonging to that device are permanently deleted.

Can I export data?

The Data Table shows raw messages during the session but they're not persisted. The ESP32 generator exports your configuration as an Arduino sketch. Data export is not currently supported.

What browsers are supported?

Chrome, Firefox, Edge, Safari — any modern browser with WebSocket support.

How does the AI Generator work?

It sends your description to GPT-4o-mini (via Netlify serverless function) which returns a structured JSON with devices, sensors, controls, and map pins. The app then creates all of them in one shot. Requires GITHUB_TOKEN environment variable in Netlify.