IoT Dash Documentation

Platform guide for version 0.4.1-beta — Device-first real-time IoT dashboard

Overview

IoT Dash is a real-time IoT dashboard platform that connects to MQTT brokers to visualize sensor data with gauges, time-series charts, and interactive maps — and control IoT devices with buttons, toggles, and sliders. Everything runs in the browser via WebSocket MQTT.

Key features:

Device-first architecture — organize sensors, controls, and map pins under devices
Multi-app system — up to 5 independent dashboards per account
Real-time gauges & charts — SVG arc gauges and Recharts time-series
Interactive map — Leaflet map with live GPS pins from MQTT topics
Control widgets — buttons, toggles, and sliders that publish to MQTT
Drag-and-drop layout — fully customizable grid with persistent positions
ESP32 code generator — download a ready-to-flash Arduino sketch
Built-in simulator — test your dashboard without hardware
Cloud sync — all data saved to Firestore, cached locally for instant loads

Dashboard UI — visual overview

☰

🌤️ Weather Station

🔓 Lock + Sensor + Control 🗺️ Map + Device 📖 Docs

📡 Roof Sensors 3 💡 Living Room 2 🔧 Garage Unit 1

Connected — emqx.iotdash.app:8084

Disconnect ▶ Simulator ⚙️ ⬇ ESP32

🌡️ Temperature ✏️ 🗑️

23.5 °C

050

💧 Humidity ✏️ 🗑️

62 %

0100

🌀 Pressure ✏️ 🗑️

1013 hPa

9001100

🌡️ Temperature — time series

💧 Humidity — time series

📋 MQTT Data Log

Time	Topic	Value
14:32:05	weather/roof/temp	23.5
14:32:05	weather/roof/humidity	62
14:32:04	weather/roof/pressure	1013

Quick Start

Get your first dashboard running in under two minutes:

Sign up & verify email

Create an account at www.iotdash.app. Check your inbox for a verification email and click the link.

Create an app

Click + New App in the sidebar. Give it a name or pick a template (e.g., "Weather Station", "Smart Home").

Add your first device

Click + Device in the header. Name your device (e.g., "ESP32 Living Room"), choose an icon and color. The topic prefix auto-generates from the name.

Add sensors & controls

With a device tab active, click + Sensor or + Control to create widgets. They are automatically assigned to the active device.

Connect & test

Click Connect in the connection bar. Use the built-in Simulator to generate demo data, or connect real hardware.

Account & Login

IoT Dash uses Firebase Authentication with email/password. After signing up, you must verify your email before accessing the dashboard.

ℹ️ Email Verification

If you don't see the verification email, check your spam folder. You can request a new one from the verification page.

Your data is stored per-user in Cloud Firestore and cached in localStorage for instant loading on return visits.

Apps

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

Creating an App

Click + New App in the sidebar. You can:

Enter a custom name
Select a template to pre-populate sensors and controls

Switching Apps

Click any app in the sidebar to switch. The dashboard fully re-mounts on app switch, loading the selected app's data.

Managing Apps

Rename: Right-click or use the edit button on an app in the sidebar
Delete: Remove an app and all its data permanently

Devices

In v0.4.1, devices are the primary organizational unit. All sensors, controls, and map pins belong to a device. You must create at least one device before adding any widgets.

💡 Device-First Architecture

Think of a device as a physical piece of hardware (e.g., an ESP32 board, a Raspberry Pi, a PLC). Widgets are grouped under the device they report from or control.

Creating a Device

Click + Device in the dashboard header. Configure:

Field	Description
Name	Human-readable device name (e.g., "Weather Station Roof")
Icon	Emoji icon displayed on the device tab (📡 🖥️ 💡 🌡️ etc.)
Color	Accent color for the device tab border
Topic Prefix	Auto-generated from name. Pre-fills MQTT topics when adding widgets (e.g., `weather/station/`)

Device Tabs

Each device appears as a tab below the header. Click a tab to view only that device's widgets. The active tab determines which device new widgets are assigned to.

Device Tabs — active tab highlighted

📡 Roof Sensors 3 💡 Living Room 2 🔧 Garage Unit 1 🌱 Garden 4

Click a tab to switch to that device
Right-click a tab to edit the device
Widget count is shown as a badge on each tab

Deleting a Device

⚠️ Destructive Action

Deleting a device permanently removes all its sensors, controls, and map pins. This cannot be undone.

Limits

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

Sensors

Sensors are read-only widgets that subscribe to an MQTT topic and display incoming values. Each sensor renders as a gauge card and (for numeric types) an accompanying time-series chart.

Adding a Sensor

With a device tab active, click + Sensor. Configure:

Field	Description	Required
Name	Display label (e.g., "Room Temperature")	✅
MQTT Topic	Topic to subscribe to. Topic prefix auto-fills from device. (e.g., `home/bedroom/temp`)	✅
Unit	Display unit (°C, %, hPa, lux, etc.)
Data Type	`number`, `integer`, `boolean`, or `string`
Min / Max	Gauge range (numeric types only)
Warning Low / High	Threshold values that trigger visual warnings on the gauge
Decimals	Decimal places for display (0–5)
Icon	Emoji icon for the gauge card
Color	Accent color for gauge arc and chart line

Data Types

Type	Gauge	Chart	Example MQTT Payload
`number`	Arc gauge with min/max	✅ Line chart	`23.5`
`integer`	Arc gauge with min/max	✅ Line chart	`42`
`boolean`	ON/OFF indicator	—	`1` or `0`
`string`	Raw text display	—	`OK`

Editing & Deleting

Hover over a gauge card to reveal the edit (✏️) and delete (🗑️) buttons in the top-right corner.

Gauge Cards — sensor widgets

🌡️ Temperature ✏️ 🗑️

23.5 °C

050

🚪 Door Sensor ✏️ 🗑️

🟢

OPEN boolean

📊 Status ✏️ 🗑️

📋

Running OK string

Controls

Controls are write widgets that publish MQTT messages when the user interacts with them. Use them to switch relays, set thresholds, or send commands to your devices.

Control Types

Type	UI Element	Publishes
Button	Click button	A fixed payload string (e.g., `1`) on each click
Toggle	ON/OFF switch	Alternates between ON payload and OFF payload (e.g., `1` / `0`)
Slider	Range slider	The current slider value (e.g., `75`) with configurable min, max, step, and unit

Adding a Control

With a device tab active, click + Control. Configure the label, MQTT topic, widget type, and type-specific settings (payloads, labels, slider range).

Control Fields

Field	Applies To	Description
Label	All	Display name
MQTT Topic	All	Topic to publish to
Payload	Button	Message to publish on click
Button Text	Button	Label on the button (default: "Send")
ON / OFF Payload	Toggle	Values sent for each state
ON / OFF Label	Toggle	Text displayed in each state
Min / Max / Step	Slider	Slider range configuration
Default Value	Slider	Initial slider position
Unit	Slider	Unit displayed next to the slider value

Control Widgets — button, toggle, slider

🔔 Ring Alarm

🔔 Ring Now → home/alarm/ring

💡 Room Light

ON → home/light/switch

🌀 Fan Speed

75 %

→ home/fan/speed

Map Pins

Map pins display real-time GPS positions on an interactive Leaflet map. Each pin subscribes to separate MQTT topics for latitude and longitude, enabling live tracking of vehicles, drones, or mobile sensors.

Adding a Map Pin

With a device tab active, click 🗺️ Map. Configure:

Field	Description
Pin Name	Label shown on the map marker
Latitude Topic	MQTT topic publishing latitude (e.g., `device/gps/lat`)
Longitude Topic	MQTT topic publishing longitude (e.g., `device/gps/lng`)
Icon	Map marker emoji
Marker Color	Color of the map marker

ℹ️ Topic-Based GPS

Map pins use MQTT topics, not static coordinates. Your device publishes its GPS position as separate lat and lng values, and the map updates in real time. The topic prefix from the device auto-fills.

Expected MQTT Payloads

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

Payloads should be plain numeric strings (decimal degrees).

MQTT Broker

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

⚠️ WebSocket Required

Browsers cannot use raw TCP MQTT. Your broker must support WebSocket connections. Most modern brokers (EMQX, Mosquitto, HiveMQ) have this enabled by default on a separate port.

Configuring the Broker

Click the ⚙️ gear icon in the connection bar to open Broker Settings. Options:

Connection Bar — broker status & controls

Connected — IoT Dash Cloud (EMQX) · emqx.iotdash.app:8084

Disconnect ▶ Simulator ⚙️ ⬇ ESP32

Disconnected — tap Connect to start

Connect ▶ Simulator ⚙️ ⬇ ESP32

Field	Description	Default
Broker URL	Full WebSocket URL	`wss://test.mosquitto.org:8081/mqtt`
Username	MQTT auth username (optional)	—
Password	MQTT auth password (optional)	—
Client ID	Unique client ID (auto-generated if blank)	Auto
Keep-alive	Ping interval in seconds	60
Clean Session	Start with no prior subscriptions	true
Reconnect Period	Reconnect delay in ms	5000
Connect Timeout	Connection timeout in ms	10000

Connection Status

The connection bar shows the current MQTT state:

Status	Meaning
🟢 Connected	Actively receiving messages
🟡 Connecting	Establishing connection
🔴 Disconnected	Not connected — click "Connect"
🔴 Error	Connection failed — check broker URL and credentials

Broker Presets

IoT Dash includes pre-configured broker presets for quick setup:

Preset	Provider	Auth	Notes
⚡ IoT Dash Cloud	EMQX Cloud	Pre-filled	Built-in broker, ready to use out of the box
🦟 Mosquitto (Public)	Eclipse Foundation	None	Public test broker — anyone can see your data
🐝 HiveMQ (Public)	HiveMQ	None	Public test broker
🔧 Custom Broker	Your own	Your config	Enter any WebSocket-enabled MQTT broker

💡 Recommended for Testing

Use the IoT Dash Cloud preset for the easiest experience. It comes pre-configured with authentication and works immediately with the simulator and ESP32 code generator.

Simulator

The built-in simulator publishes random demo data to all your configured sensor topics without needing any hardware. It also simulates GPS coordinates for map pins.

Using the Simulator

Ensure you're connected to an MQTT broker
Click ▶ Simulate in the connection bar
Watch your gauges, charts, and map update with randomized values
Click ⏹ Stop to stop the simulator

The simulator publishes values within each sensor's configured min/max range and random GPS coordinates near a base location (New Delhi by default for the ESP32, but map pins use their own topic subscriptions).

Grid Layout

The dashboard uses a responsive drag-and-drop grid powered by react-grid-layout. Widgets auto-arrange but their positions can be customized.

Editing Layout

Click the 🔒 button to unlock the layout (changes to 🔓 Editing)
Drag widgets by the ⠿ handle that appears in the top-left
Resize widgets by dragging the bottom-right corner
Click 🔓 Editing to lock and save

Layout changes are auto-saved with an 800ms debounce — you don't need to manually save.

Responsive Breakpoints

Breakpoint	Width	Grid Columns
Large (lg)	> 900px	12
Medium (md)	600–900px	8
Small (sm)	< 600px	4

Widget Types

Each device's dashboard can contain the following widget types:

Gauge Card

An SVG arc gauge showing the current sensor value. Displays the sensor icon, name, value, unit, and a colored arc that fills proportionally between min and max. Warning zones are highlighted when values exceed thresholds.

Time-Series Chart

A Recharts line chart that appears automatically for number and integer data types. Shows the recent history of values over time with the sensor's accent color.

Control Card

Interactive widget for buttons, toggles, and sliders. Each publishes to its configured MQTT topic when the user interacts.

Map Widget

A Leaflet map showing all the active device's map pins as markers. Positions update in real time from MQTT. The map appears automatically when at least one map pin exists.

Data Table

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

ESP32 Code Generator

IoT Dash can generate a ready-to-upload Arduino sketch (.ino file) pre-configured with your app's sensors, controls, map pins, and broker settings.

Downloading the Sketch

Click the ESP32 download button in the connection bar. A .ino file is downloaded with a unique ID in the filename (so multiple downloads don't overwrite each other).

What's Included

WiFi connection code (enter your SSID/password)
All broker presets as selectable blocks (first preset uncommented by default)
Sensor publish code — publishes random values within your configured min/max ranges
Control subscribe code — subscribes to control topics with callback handlers
Map pin GPS simulation — publishes randomized lat/lng near a base coordinate
MQTT connection with auto-reconnect
3-second publish interval (configurable)

Requirements

Item	Details
Board	Any ESP32 board (ESP32, ESP32-S3, etc.)
IDE	Arduino IDE 2.x
Library	PubSubClient by Nick O'Leary (install from Library Manager)
Connection	Plain MQTT over TCP (port 1883) — no TLS

Flashing Steps

Open the .ino file in Arduino IDE

Install PubSubClient library (Sketch → Include Library → Manage Libraries)

Set WIFI_SSID and WIFI_PASSWORD at the top of the file

Choose a broker preset (first one is active by default) or enter custom broker details

Select your ESP32 board and port, then click Upload

Open Serial Monitor at 115200 baud to see connection status and published data

ℹ️ Demo Data Only

The generated sketch publishes random simulated values. Replace the publishSensorData() function body with real sensor readings from your hardware (DHT22, BMP280, GPS module, etc.).

App Templates

When creating a new app, you can choose from pre-built templates that include pre-configured sensors and controls:

Template	Sensors	Description
📄 Blank	0	Start from scratch
🌤️ Weather Station	4	Temperature, humidity, pressure, wind speed
🏠 Smart Home	3 sensors + 3 controls	Room temp, humidity, light + LED, fan, thermostat
🏭 Industrial	4	Motor RPM, tank level, pressure, vibration
🌱 Agriculture	4 sensors + 2 controls	Soil moisture, temp, rain, light + irrigation, fan
⚡ Energy Monitor	4	Voltage, current, power, energy consumption

Template sensors come with sensible defaults for min/max, warning thresholds, units, and icons. You can edit or delete any of them after creation.

Limits & Quotas

Resource	Limit
Apps per account	5
Devices per app	20
Sensors per app	No hard limit (practical: ~50)
Controls per app	No hard limit (practical: ~50)
Map pins per app	No hard limit (practical: ~20)
Message history	Kept in browser memory (cleared on page refresh)
Data persistence	Config persisted to Firestore; live sensor data is ephemeral

ℹ️ Data Storage

IoT Dash stores your configuration (devices, sensors, controls, layout, broker) in the cloud. Live sensor data (values, chart history, raw messages) are kept in browser memory only and are lost on page refresh. IoT Dash is a real-time visualization tool, not a data logger.

Tips & Shortcuts

Action	How
Edit a device	Right-click the device tab
Edit a sensor	Hover gauge → click ✏️
Delete a sensor	Hover gauge → click 🗑️
Edit a control	Hover control card → click ✏️
Edit a map pin	Click the pin on the map → click Edit
Unlock layout	Click 🔒 in the header
Drag a widget	Grab the ⠿ handle (layout must be unlocked)
Resize a widget	Drag the bottom-right corner (layout unlocked)
Open broker settings	Click ⚙️ in the connection bar
Toggle sidebar	Click ☰ in the header

FAQ

Why can't I add sensors? The buttons are hidden.

You need to create a device first. In v0.4.1, all widgets belong to a device. Click + Device to get started.

My gauges show "—" instead of a value.

This means no MQTT message has been received on that topic yet. Check that:

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

Can I use my own MQTT broker?

Yes! Choose "Custom Broker" in broker settings and enter your WebSocket URL (must be 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 but through different protocol listeners.

Is my data private?

Your dashboard configuration is stored in Firebase Firestore under your user account and is only accessible to you. However, MQTT messages pass through the broker you choose — if you use a public broker, anyone subscribed to the same topics can see your data. Use the IoT Dash Cloud preset or your own private broker for secure communication.

What happens when I delete a device?

All sensors, controls, and map pins belonging to that device are permanently deleted. The dashboard switches to the next available device tab.

Can I export my data?

Currently, IoT Dash does not support data export. The Data Table shows raw messages during the session, but they are not persisted. The ESP32 code generator exports your configuration as an Arduino sketch.

What browsers are supported?

IoT Dash works on all modern browsers: Chrome, Firefox, Edge, Safari. A WebSocket-capable browser is required for MQTT connectivity.