> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperwisor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gauge

> A circular gauge that displays a live value with arcs and thresholds — settings and firmware.

<Info>
  **Category:** Display · **Sends commands:** via triggers · **Reads data:** yes
</Info>

## Mental model

A **Gauge is a speedometer.** It *shows* a single number as a needle on an arc — it's
a read-only display, driven by data pushed to its widget ID. (It can also fire
`threshold` triggers when the value crosses a line — a display that can also act.)

## When to use it

* Show one live value at a glance: temperature, speed, battery, pressure
* Trigger an action when a value crosses a threshold

## Settings

### General

* **Widget Title / ID** — firmware pushes the value to this ID
* **Value range** (min / max)

### Style

* **Arc start / end** · **arc width** — the gauge sweep
* **Add threshold** — colored bands at value ranges
* **Animation duration / easing / delay** — needle motion
* Common background / shadow / filter controls

### Data

Bind the Gauge to a device value or **field path** in the
[Data tab](/dashboard/binding-data) — or push to its widget ID from firmware.

### Triggers

| Event         | Fires when                                                |
| ------------- | --------------------------------------------------------- |
| `threshold`   | The value crosses a configured threshold                  |
| `min` / `max` | The value hits the range ends                             |
| `change`      | The value changes                                         |
| *(common)*    | `load`, `ready`, `destroy`, `update`, `visible`, `hidden` |

## Example — drive the gauge from firmware

Push a reading to the Gauge's widget ID (`tempGauge`):

```cpp theme={null}
void loop() {
  device.loop();
  float temperature = readTemperature();
  device.updateWidget(targetId, "tempGauge", temperature);   // needle moves live
  delay(2000);
}
```

The Gauge updates in real time — no refresh, no polling.

## Example — act on a threshold

A `threshold` trigger turns something off when the value is too high:

```
WHEN     threshold
SEND TO  Current Device
EXECUTE  Operate
Action   OFF   params: {}
```

## Script API example

The same interactions from a [dashboard script](/script/overview):

```js theme={null}
widget.on('tempGauge', 'change', (t) => {
  widget.setConfig('tempGauge', 'color', t > 80 ? '#ef4444' : '#22c55e');
});
widget.on('tempGauge', 'threshold', (d) => {
  console.warn('Crossed threshold:', d.value, '>', d.threshold);
});
```

<CardGroup cols={2}>
  <Card title="Binding data" icon="diagram-project" href="/dashboard/binding-data">
    Connect the gauge to device data.
  </Card>

  <Card title="Chart" icon="chart-line" href="/dashboard/widgets/display">
    To show a value *over time*.
  </Card>
</CardGroup>