MQTTfy
Back to Resources

Mastering IoT Visualization with Interactive Floorplan Widgets

November 21, 2025

From Data Points to Smart Spaces: Using the Floorplan Widget

In the world of the Internet of Things (IoT), context is everything. Knowing a sensor's temperature is useful, but knowing that the sensor in the upstairs bedroom is reporting a high temperature is actionable intelligence. The Floorplan Widget in MQTTfy is designed to provide exactly this kind of spatial context, allowing you to transform a static image—like a building blueprint, a factory layout, or a network diagram—into a living, breathing, real-time dashboard.

This article will walk you through the powerful features of the Floorplan Widget, from uploading your custom background to placing and configuring interactive "hotspots" that react to live data from your IoT devices via MQTT, API, or Bluetooth.

A floorplan of a smart home with interactive hotspots glowing on it

Why Use a Floorplan Widget?

A floorplan visualization bridges the gap between raw data and the physical world it represents. Instead of scanning a list of sensor names, you can instantly see the status of your entire space at a glance.

  • Smart Home Management: See which lights are on, which windows are open, or which rooms have motion detected, all overlaid on your home's layout.
  • Industrial Monitoring: Visualize the status of machinery on a factory floor. A green hotspot could mean "Operating Normally," yellow could indicate a warning, and red could signal an immediate fault, allowing maintenance teams to pinpoint the exact machine needing attention.
  • Office and Building Management: Monitor room occupancy, air quality, or temperature across different zones of an office building to optimize energy usage and ensure comfort.
  • Network and System Diagrams: Use a network topology diagram as your background and place hotspots on servers or routers to visualize their online/offline status or network traffic levels.

The possibilities are limited only by your imagination and the data you can collect.

Key Features of the Floorplan Widget

  • Custom Backgrounds: Upload any image (JPG, PNG, SVG) to serve as the canvas for your visualization. This can be anything from a simple hand-drawn sketch to a professional architectural blueprint.
  • Interactive Hotspots: Place clickable, color-changing dots anywhere on your image. Each hotspot is an independent entity that represents a specific sensor or device.
  • Flexible Data Binding: Connect each hotspot to a unique data source, whether it's an MQTT topic, an API endpoint, or a Bluetooth characteristic.
  • State-Based Coloring: Define "ON" and "OFF" values for each hotspot. The widget will automatically change the hotspot's color based on the data it receives. For example, a motion sensor could send 1 for motion detected (turning the hotspot red) and 0 for no motion (turning it gray).
  • Customizable Appearance: Configure the size, shape, and color for both the ON and OFF states of each hotspot to create a clear and intuitive visual language for your dashboard.

Step-by-Step Guide: Creating a Smart Home Floorplan

Let's build a simple smart home dashboard. Assume we have the following IoT devices publishing their status to an MQTT broker:

  • Living Room Lamp: Topic home/livingroom/light, payload ON or OFF.
  • Bedroom Window Sensor: Topic home/bedroom/window, payload OPEN or CLOSED.
  • Thermostat: Topic home/hvac/temperature, payload is a number (e.g., 21.5).

Step 1: Add the Floorplan Widget

  1. From your MQTTfy dashboard, click "Add Widget" and select the Floorplan widget.
  2. In the configuration sheet that appears, under "Widget Specifics," click "Upload Floorplan" and select the image file of your home's layout. You will see a preview of the image appear directly in the configuration panel.

Step 2: Place Your First Hotspot (Living Room Lamp)

  1. Click the "Add Hotspot" button. A message will appear instructing you to click on the preview image to place the hotspot.
  2. Click on the location of the lamp in your living room on the floorplan preview. A new hotspot configuration block will appear, pre-filled with the X and Y coordinates of your click.
  3. Configure the Hotspot:
    • Label: "Living Room Lamp"
    • Topic: home/livingroom/light
    • ON Value: ON
    • OFF Value: OFF
    • ON Color: Choose a bright yellow.
    • OFF Color: Choose a dark gray.

Step 3: Place and Configure More Hotspots

Repeat the process for the other devices.

Bedroom Window Sensor:

  1. Click "Add Hotspot" again.
  2. Click on the bedroom window in the preview image.
  3. Configure the Hotspot:
    • Label: "Bedroom Window"
    • Topic: home/bedroom/window
    • ON Value: OPEN (We'll define "open" as the "ON" state)
    • OFF Value: CLOSED
    • ON Color: A warning red (e.g., #FF4136)
    • OFF Color: A reassuring green (e.g., #2ECC40)

Thermostat with Alerting: The hotspot is binary (ON/OFF), but our thermostat provides a number. We can use a Data Transformation to convert this numeric data into a state.

  1. Add a new hotspot for the thermostat's location.
  2. Configure the Hotspot:
    • Label: "Thermostat"
    • Topic: home/hvac/temperature
    • ON Value: ALERT (This is a custom value we will generate).
    • ON Color: Red.
  3. Set up the Data Transformation: Go to the main "Data Transformation" section for the entire widget. Enter the following JavaScript function: (payload) => (parseFloat(payload) > 25) ? 'ALERT' : 'OK'
  4. This function checks if the temperature is above 25. If it is, it returns the string ALERT, which matches our hotspot's "ON Value," turning it red. If not, it returns OK, which doesn't match, so the hotspot will be in its default OFF state (gray).

Step 4: Save and Observe

Save the widget configuration. You will now see your floorplan on the dashboard with the hotspots overlaid. As your devices publish new data to their MQTT topics, the hotspots will change color in real time, giving you an instant, intuitive overview of your smart home's status.

Conclusion

The Floorplan Widget elevates your IoT dashboard from a simple collection of data points to a true command center with spatial awareness. It provides an immediate, intuitive way to understand the state of your environment, whether it's a home, a factory, or a complex network. By combining your custom layouts with real-time data from any source, you can create powerful, context-rich visualizations that were previously only possible with expensive, custom-built software.