# Heatmap Widget

## Introduction

The Heatmap Widget is a newly released feature for the Datacake IoT platform. It is available for both **device dashboards** and **workspace dashboards** and provides a visual representation of data over time using color gradients. This document outlines how to set up and configure the Heatmap Widget.

### Video

What is better than 1000 words? Correct, a video!

{% embed url="<https://www.loom.com/share/29dd97084a014e9e9160448c985f6ca0>" %}

***

## Adding the Heatmap Widget

To add the Heatmap Widget to your dashboard:

1. **Enable Edit Mode**: Open your dashboard and activate the edit mode.
2. **Add a New Widget**: Click on **"Add Widget"**.
3. **Select Heatmap Widget**: Scroll down and select the **"Heatmap"** widget.
4. **Configure Basic Settings**:
   * Enter a **Title** for the widget.
   * Provide **translations** (optional).

***

## Configuring Data Sources

1. **Select Data Source Mode - Static Devices**:
   * Choose the device fields to display.
   * Example: Select **Temperature**, **Max Temperature**, and **Min Temperature**.
2. **Select Data Source Mode - Semantics:**
   1. Choose a semantic field to display
   2. Example: select CO2, then further filter the devices that report on CO2 by tag
3. **Save Configuration** to apply the changes.

***

## Timeframe&#x20;

1. Open the widget **Configuration**.
2. Click on **"Timeframe"**.
3. Choose between:
   * **Hourly**: Each cell represents an **hour**.
   * **Daily**: Each cell represents a **day**.

***

## Appearance Settings

1. **Cell Size**:
   * **Small**: Ideal for large datasets.
   * **Normal**: Displays numeric values inside the cells.
2. **Adjust the number of cells:**
   * Example: Set to **14 days** to show the last 14 days of data.
   * If data storage is limited (e.g., 7 days), older cells will appear empty.
3. **Custom Colorization**:
   * Define specific thresholds for color mapping.
   * Example:
     * **-10°C** = Blue (Cold)
     * **15°C** = Green (Moderate)
     * **35°C** = Red (Hot)
   * Adjust values as needed to improve readability.

#### Mark stale data

By default, every cell in the heatmap shows the most recent measurement that falls inside its bucket. When a device stops reporting, for example because it goes offline, runs out of battery, or loses connectivity, Datacake will keep filling the cells with the last known value so the heatmap remains continuous. Visually this can look identical to a device that is reporting steadily, even though no new data has arrived in hours or days.

Enable **Mark stale data** to make those forward-filled cells stand out:

* Cells that contain a fresh measurement render normally.
* Cells that simply repeat the last known value are drawn with a diagonal hatched overlay and a slightly dimmed value label.
* Hovering a stale cell shows an additional tooltip line ("No new measurement in this period") so you can tell at a glance which periods are real and which are filled forward.

This is especially useful for:

* Spotting offline devices on dashboards that compare many sensors side by side, a stretch of hatched cells on the right edge of a row immediately signals "this device stopped reporting".
* Investigating gaps in long timeframes (e.g. a 30-day temperature heatmap) where missing readings would otherwise blend into the surrounding values.
* SLA / uptime reviews, where the difference between "the value is stable" and "the device hasn't checked in" matters.

The toggle defaults to off, so existing dashboards keep their current look until you opt in. You can switch it on per heatmap widget under the Appearance tab in the widget settings.

{% hint style="info" %}
Cells with no value at all (for example, when no forward-fill is available) stay blank. The stale indicator only applies to cells that do show a value but that value is repeated from an earlier reading. The widget's "Last update" timestamp in the header continues to reflect the most recent real measurement received from any of the selected devices.
{% endhint %}

***

## Workspace Dashboard Configuration

The Heatmap Widget can also be used in **Workspace Dashboards**:

1. **Navigate to a Workspace Dashboard**.
2. **Add the Heatmap Widget** following the same steps as for device dashboards.
3. **Add Multiple Devices**:
   * Example: Weather stations from different cities (Athens, Barcelona, Berlin, Milan, Seville, Marrakesh, etc.).
   * Each row represents a location with its respective temperature data.
4. **Configure Timeframe and Appearance**:
   * Example: Set to **7 days**, **normal cell size**, and **daily timeframe**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.datacake.de/dashboards/widgets/heatmap-widget.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.