> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/dashboards/adding-widgets/digital-building-twin/binding-sensors-and-colors.md).
# How to Bind Sensors to a Digital Building Twin
Bind sensors to Digital Building Twin objects and define color rules — turn a 3D drawing into a live operational view.
This is the step that makes a Digital Building Twin worth building. Up to now the model is a 3D drawing of a facility. Binding sensors turns it into a live operational view: a sensor reads "occupied" and the desk it's bound to turns red; a probe reports 14°C and the cold store it's bound to turns from green to amber.
A **binding** connects one sensor reading to one or more objects in the model, plus a set of color rules that decide what color those objects show at any given value. This page covers building that connection.
## How do I open the Sensors panel?
On the bottom toolbar, click **Sensors**. The Sensors panel opens, headed **Source**. This is where every binding is configured.
## How do I add a data source?
A data source is a device.
1. Click **Add datasource**. A new data-source card appears.
2. Click **Choose device** and pick the device whose readings you want to use.
3. The card now shows the device name. Add as many data sources as you need — one per device.
## How do I add a metric?
Each data source exposes the device's individual sensor readings as **metrics**.
1. On the data-source card, click **Add metric**.
2. In the **Device metric** dropdown, choose the reading you want — temperature, occupancy, fill level, status, and so on.
3. Repeat to add more metrics from the same device.
Each metric is one binding. A device with a temperature sensor and an occupancy sensor gives you two metrics, and you bind each to different objects.
## How do I bind a metric to objects?
1. On the metric, click **Configure**. The metric enters binding mode and its editor expands.
2. The editor shows the prompt **Click objects on the scene to bind them**.
3. Click any object in the 3D model — a desk, a parking spot, an AC unit, a wall, a whole floor zone. Each object you click is added to this metric, and appears in the editor's **Bound** list.
4. Bind as many objects as the reading should drive. To unbind one, remove it from the Bound list.
5. When you're done, click **Done**.
One metric can drive several objects at once — bind a single zone-temperature sensor to every desk in that zone and they all recolor together. The metric's **Bound** count shows how many objects it currently drives.
## How do I define sensor colors?
A binding's editor carries the color rules. Two things control what an object shows:
* **Unit** — a text field at the top of the binding editor (for example `°C` or `%`). Whatever you type is appended to the value, with no space added, on pins and in the test readout, so `13.4` with unit `°C` reads `13.4°C`.
* **Default color** — the color used when no condition matches. Set it with the **Default** color picker beside the **Unit** field.
* **Conditions** — the rules that map readings to colors. Click the **+** (**Add condition**) button next to the **Conditions** heading to create one; it adds a red condition named **Rule** covering 0 to 100, which you then edit. Each condition has:
* a **color**,
* a **Name** (a label like "Occupied," "Breach," "Warning"),
* a **Data type** — **Number**, **String**, or **Boolean**,
* and a value test that depends on the type:
* **Number** — a **From** / **To** range. The condition matches when the reading falls inside it.
* **String** — a single **Value**. The condition matches when the reading equals it exactly.
* **Boolean** — a **True** / **False** setting. The condition matches when the reading matches it.
Conditions are evaluated in order, and the **first one that matches wins**. If none match, the object shows the default color. This is the same conditional-color system used by the Last Data, Chart, and Image widgets — see [Conditions](/dashboards/adding-widgets/conditions.md) for the full reference.
## How do I test sensor colors?
A binding's editor includes a **Value** slider, a fixed 0 to 100 scale with the current value and unit shown beside it. It appears only while the bound sensor isn't sending live data. Drag the slider and watch the bound objects recolor in real time — it's the fastest way to confirm your conditions before the model goes on a dashboard. Once the device is reporting, the binding shows the real **Current value**, rounded to at most two decimals for readability, and the model reflects live readings.
## What can I do with sensor bindings?
**Parking availability.** Bind an occupancy sensor's status metric to a parking spot. Add two String conditions: `occupied` → red, `vacant` → green. The bay shows its real-time state; a lot full of these reads at a glance.
**Cold-chain compliance.** Bind a temperature probe to the cold-store zone. Add Number conditions: 2–8°C green ("Compliant"), 8–12°C amber ("Warning"), set the default color red for anything above. A supervisor sees compliance status without opening a single device page.
**Equipment and HVAC fault visibility.** Bind a status sensor to an AC unit or a pump. A Boolean condition — fault `true` → red — turns the equipment red in the model the moment it faults, so the failure is located as well as flagged.
**Facility occupancy.** Bind motion or occupancy sensors to the desks or zones of an office floor. Occupied desks shade one color, free desks another — space utilization becomes a picture instead of a report.
These four are a small sample of what binding makes possible. Any sensor in your deployment can drive any element of the model — if you can describe what a reading means for a place, you can make the twin show it. Let your own deployment suggest the rest.
## What are the best tips for binding sensors?
* Name objects clearly in the **Scene** panel before you bind — clicking the right desk is much easier when it's called "Rack B7."
* Bind one metric to many objects when they share a reading; bind separate metrics when each object has its own sensor.
* Use the test slider to prove every condition before you save.
* Keep conditions few and meaningful — three bands (good / warning / critical) usually communicate more clearly than ten.
## See also
* [Conditions](/dashboards/adding-widgets/conditions.md) — The full conditional-color reference
* [Drop-pins and live values](/dashboards/adding-widgets/digital-building-twin/drop-pins-and-live-values.md) — Show the numeric value in the scene
* [Placing objects](/dashboards/adding-widgets/digital-building-twin/placing-objects.md) — Add the objects sensors bind to
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.kiloiot.io/dashboards/adding-widgets/digital-building-twin/binding-sensors-and-colors.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
