Channel reference
Channel reference
Every channel has one type and one unit, whatever the device or its protocol: the hub converts. The API refuses a command whose value doesn't fit its channel's type, and the device's own channel schema can narrow it further, such as a thermostat's setpoint range or the modes it has. GET /v1/channel-types returns these as JSON Schema.
| Key | Type | Unit | Values | Settable | Meaning |
|---|---|---|---|---|---|
switch |
boolean | yes | On (true) or off. |
||
level |
number | % | 0–100 | yes | Brightness or output, 0 off to 100 full. |
lift |
number | % closed | 0–100 | yes | A shade's or blind's height, 0 fully open to 100 fully closed. |
tilt |
number | % closed | 0–100 | yes | A blind's slat angle, 0 fully open to 100 fully closed. |
fan_speed |
number | % | 0–100 | yes | A fan's speed, 0 off to 100 full. |
color |
object | hue 0–360, saturation 0–100 |
yes | Colour as hue (degrees) and saturation (%). | |
color_temperature |
number | K | 1000–12000 | yes | White colour temperature. |
lock |
boolean | yes | Locked (true) or unlocked. |
||
lock_state |
enum | locked, unlocked, unlatched, not_fully_locked, unknown |
no | What the lock reports its bolt is doing. | |
door_state |
enum | open, closed, jammed, forced_open, ajar, error |
no | The door a lock is fitted to, from its door sensor. | |
lock_mode |
enum | normal, vacation, privacy, no_remote, passage |
yes | How the lock treats codes and remote commands. | |
barrier |
boolean | yes | A garage door or gate: open (true) or closed. |
||
barrier_state |
enum | closed, opening, open, closing, stopped, unknown |
no | Where a garage door or gate is, including while it moves. | |
mode |
enum | off, auto, cool, heat, emergency_heat, precooling, fan_only, dry, sleep |
yes | A thermostat's mode. | |
fan_mode |
enum | off, low, medium, high, on, auto, smart |
yes | A thermostat's or fan's fan mode. | |
operating_state |
enum | idle, heating, cooling, fan_only, pending_heat, pending_cool, vent |
no | What a thermostat is doing now. | |
fan_state |
enum | off, running, running_high, running_medium, circulation, humidity_circulation, right_left_circulation, up_down_circulation, quiet_circulation |
no | What a thermostat's fan is doing now. | |
heating_setpoint |
number | °C | 0–40 | yes | The temperature heating holds to. Its schema has this device's minimum, maximum and step, and the unit it shows (display_unit). |
cooling_setpoint |
number | °C | 0–40 | yes | The temperature cooling holds to. Its schema has this device's minimum, maximum and step, and the unit it shows (display_unit). |
temperature |
number | °C | no | Measured temperature. | |
water_temperature |
number | °C | no | Measured water temperature. | |
dew_point |
number | °C | no | Dew point. | |
humidity |
number | % | 0–100 | no | Relative humidity. |
absolute_humidity |
number | g/m³ | ≥ 0 | no | Absolute humidity. |
illuminance |
number | lx | ≥ 0 | no | Light level. |
light_level |
number | % | 0–100 | no | Light level from a sensor that reports no lux. |
pressure |
number | kPa | ≥ 0 | no | Air pressure. |
co2 |
number | ppm | ≥ 0 | no | Carbon dioxide. |
co_level |
number | ppm | ≥ 0 | no | Carbon monoxide level. |
voc |
number | ppm | ≥ 0 | no | Volatile organic compounds. |
pm25 |
number | µg/m³ | ≥ 0 | no | Fine particulates (PM2.5). |
uv_index |
number | ≥ 0 | no | UV index. | |
noise |
number | dB | ≥ 0 | no | Sound level. |
battery |
number | % | 0–100 | no | Battery charge. |
battery_low |
boolean | no | The device reports its battery as low. | ||
contact |
boolean | no | A door or window sensor: true when closed (its two parts in contact). |
||
motion |
boolean | no | true while motion is detected. |
||
leak |
boolean | no | true while water is detected. |
||
heat |
boolean | no | true while overheating is detected. |
||
binary |
boolean | no | A general-purpose sensor's state, from a device that doesn't say what it senses. | ||
valve |
boolean | yes | A water or gas valve: open (true) or closed. |
||
tamper |
boolean | no | true while the device reports tampering. |
||
smoke |
enum | normal, warning, critical |
no | Smoke alarm state. | |
co |
enum | normal, warning, critical |
no | Carbon monoxide alarm state. | |
power |
number | W | no | Power now; negative while exporting. | |
energy |
number | kWh | ≥ 0 | no | Energy imported, cumulative. |
energy_exported |
number | kWh | ≥ 0 | no | Energy exported, cumulative. |
voltage |
number | V | no | Voltage. | |
current |
number | A | no | Current. | |
gas |
number | m³ | ≥ 0 | no | Gas consumed, cumulative. |
water |
number | m³ | ≥ 0 | no | Water consumed, cumulative. |
color_components |
object | components 0–255 | yes | A colour device's raw components, each 0–255 (warm_white, cold_white, red, green, blue, amber, cyan, purple, index), every component named at once. Usually set color or color_temperature instead. |
|
credentials |
text | no | A lock that holds codes; its schema.slots is how many. Codes go through its users. |
||
local_protection |
boolean | yes | true while the device's own buttons are locked out. |
||
button |
event | initial_press, long_press, short_release, long_release, multi_press_complete |
no | Button presses: {button, event, count}. An event, not a state: multi_press_complete carries count. |
|
alarm |
event | no | Device alarms and notifications: {type, event, severity}, severity info, warning or critical. An event, not a state: event idle means that type's alarm cleared. Current state is in leak, smoke, co, motion, contact and tamper. |
Conventions
- Percentages run 0–100. Shades and blinds count % closed: 0 is fully open.
contactistruewhen closed: its two parts are in contact.- Temperatures are °C, decimal.
poweris negative while a device exports.buttonandalarmare events: they have a last event, not a current value, and arrive aschannel.observedeach time.