1KEY Developers
Reference

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.
  • contact is true when closed: its two parts are in contact.
  • Temperatures are °C, decimal.
  • power is negative while a device exports.
  • button and alarm are events: they have a last event, not a current value, and arrive as channel.observed each time.