> ## 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.

# How It Works

> The widget/command loop that connects firmware to dashboards.

There is one idea at the center of Hyperwisor. Once it clicks, everything else
follows: **firmware and dashboard widgets are linked by a shared widget ID.**

## The core loop

A dashboard widget has an ID. Your firmware pushes a value to that ID, and the
widget updates. The widget sends a command, and your firmware receives it. That's
the whole loop.

```mermaid theme={null}
flowchart LR
  subgraph Device [Firmware]
    A["device.updateWidget(<br/>targetId, widgetId, value)"]
    B["setUserCommandHandler(cb)"]
  end
  subgraph Dashboard
    C["Widget bound to<br/>the same widgetId"]
    D["Switch / Button"]
  end
  A -- "value flows up" --> C
  D -- "command flows down" --> B
```

### Pushing a value up

In firmware you call `updateWidget` with a target, the widget's ID, and a value:

```cpp theme={null}
// Arduino
device.updateWidget(targetId, "tempGauge", 27.4);
```

On the dashboard, a Gauge whose widget ID is `tempGauge` now reads `27.4`. No
polling — the value arrives over the realtime channel and the widget re-renders.

### Sending a command down

When a user flips a Switch or presses a Button, the dashboard sends a command.
Your firmware receives it through the command handler you registered:

```cpp theme={null}
// Arduino
device.setUserCommandHandler([](JsonObject &msg) {
  // inspect the command and act on it (drive a GPIO, toggle a relay, ...)
});
```

## What the SDK handles for you

You never deal with the transport yourself. The firmware libraries wrap all of
it behind simple calls:

<CardGroup cols={2}>
  <Card title="Connection" icon="plug">
    Wi-Fi provisioning, the realtime connection, and reconnection are managed by
    the library. You call <code>begin()</code> / <code>loop()</code> and it stays connected.
  </Card>

  <Card title="Identity" icon="id-card">
    The device's ID and the user it belongs to are stored on the device and used
    to route messages — set once during provisioning.
  </Card>

  <Card title="Widgets" icon="gauge">
    <code>updateWidget()</code> and its typed overloads push values; specialized
    helpers exist for charts, 3D models, heatmaps, and more.
  </Card>

  <Card title="Commands" icon="bolt">
    Incoming commands are parsed and delivered to your handler as structured
    JSON; helper functions find commands, actions, and params for you.
  </Card>
</CardGroup>

## The data is yours to shape

The platform makes no assumptions about what your device measures or controls.
You decide the widget IDs, the values, and the command vocabulary. A thermostat,
a soil sensor, and a drone all run on the same loop — only the IDs and payloads
differ.

<Card title="Next: Core concepts" icon="cubes" href="/learn/concepts">
  Product, device, user, and dashboard — and how they relate.
</Card>