Mẫu Gauge

Một mẫu dựa trên khoảng để giám sát các giá trị số. Hiển thị giá trị hiện tại kèm đơn vị, và hiển thị nhãn min/max ở hai đầu thanh tiến trình. Tiến trình được máy chủ tự động tính toán.

Fields

Field	Type	Description
`template`	string	Required. Must be `"gauge"`
`value`	float	Required. Current value within the range
`min_value`	float	Required. Minimum value of the range
`max_value`	float	Required. Maximum value of the range. Must be greater than `min_value`
`unit`	string	Unit label displayed after the value (e.g. "°C", "%", "rpm"). Max 32 characters
`state`	string	Status text (e.g. "Heating", "Ready")
`icon`	string	SF Symbol name (e.g. `"thermometer.medium"`) or MDI icon with `mdi:` prefix
`subtitle`	string	Secondary descriptive text
`accent_color`	string	Named color or hex. Default: `orange`
`background_color`	string	Background color override
`text_color`	string	Text color override

ℹ Thông tin

The progress field is auto-calculated by the server from (value - min_value) / (max_value - min_value). You do not need to send it.

Example: Oven Preheating

Cập nhật gauge

{
  "state": "ongoing",
  "content": {
    "template": "gauge",
    "value": 125,
    "min_value": 0,
    "max_value": 250,
    "unit": "°C",
    "state": "Heating",
    "icon": "thermometer.medium",
    "accent_color": "orange"
  }
}

Example: Target Reached

Gauge hoàn thành

{
  "state": "ended",
  "content": {
    "template": "gauge",
    "value": 250,
    "min_value": 0,
    "max_value": 250,
    "unit": "°C",
    "state": "Ready",
    "icon": "checkmark.circle.fill",
    "accent_color": "green"
  }
}

Typical Flow

Start monitoring (ended -> ongoing): Set initial value, min/max range, and unit
Update value (ongoing -> ongoing): Send updated value — server recalculates progress automatically
Target reached (ongoing -> ended): Final value with completion state

💡 Mẹo

The gauge template is ideal for any value that changes within a known range: temperature, humidity, battery level, disk usage, download speed, etc.

Buttons & tap targets

The circular Dynamic Island variant has no inline buttons; tap_action is the most useful field there. On Lock Screen surfaces, url_action and secondary_url_action render as buttons. See Tap actions for the action object shape.

Use Cases

Smart home — oven temperature, thermostat setpoint, humidity sensors
3D printing — hotend/bed temperature reaching target
Infrastructure — CPU temperature, disk fill percentage, memory usage
IoT — tank level, battery charge, signal strength