Z2M - Aqara Rotary Knob H1 – Adjustable Brightness & Color Temperature (Z2M)

kkqq9320 · February 3, 2025, 7:52pm

It supports brightness control, pressed-rotation color-temperature control, custom Single/Double/Hold actions, optional Hold repeating, and a separate Release Action.

Breaking changes — read before updating

Home Assistant Core 2025.4 or newer is required.
Target Light now accepts one light entity selected in the UI. Existing templates and entity lists are no longer supported.
Brightness sensitivity now uses a direct 1-100 %/tick value. The default is 2 %/tick.
Pressed-rotation color-temperature sensitivity now uses a direct 1-10000 K/tick value. The default is 100 K/tick.
The unused translate_friendly_name input has been removed.
Hold Repeat Maximum Duration now defaults to 11 seconds and cannot be set higher.

After re-importing, open every automation created from this Blueprint, review the changed inputs, and save it again. Existing template/list targets must be replaced with one light or light-group entity.

Import Blueprint

If the Blueprint is already installed, use Settings > Automations & scenes > Blueprints > ⋮ > Re-import blueprint. Re-importing overwrites the installed Blueprint with the current version.

Supported device

Aqara Rotary Knob H1 (wireless) ZNXNKG02LM
Zigbee2MQTT 2.0.0 and later; older versions may also work but are not guaranteed

Requirements

Home Assistant Core 2025.4 or newer
Zigbee2MQTT
Home Assistant MQTT integration
The knob’s Zigbee2MQTT operation mode set to event
One target light entity with brightness support
Kelvin color-temperature support for pressed rotation

The Blueprint reads each JSON action directly from the knob’s Zigbee2MQTT device topic. It does not use generated Home Assistant action sensor entity IDs. Renaming those sensor entity IDs does not affect this version.

The legacy_action_sensor setting can be either enabled or disabled; it does not affect this Blueprint because the Blueprint does not use legacy action sensor entities.

Configuration

Import or re-import the Blueprint.
Enter the Zigbee2MQTT base topic. Keep zigbee2mqtt if you did not change it.
Enter the knob’s exact Zigbee2MQTT friendly name. This forms the device topic together with the base topic, for example zigbee2mqtt/knob.
Select one target light or light-group entity.
Configure Single, Double, and Hold actions as needed.
Expand Hold Repeat & Release only if repeat or release behavior is needed.
Adjust brightness, color temperature, transition, and limit settings.

Controlling multiple lights

Target Light accepts one entity. To control multiple lights, select a single group entity created with either:

Direct entity lists and templates are not supported.

Knob controls

Turn right: Increase brightness
Turn left: Decrease brightness
Press and turn right: Increase color temperature
Press and turn left: Decrease color temperature
Single / Double / Hold: Run the configured action
Release: Run Release Action when configured

One 12-degree rotation is one tick. For example, with the default brightness value of 2 %/tick, five ticks change brightness by 10%. With the default color-temperature value of 100 K/tick, five pressed-rotation ticks change the target by 500 K.

The Blueprint uses the cumulative angle from one rotation gesture and clamps the result to the configured light limits. High per-tick values are safe: the result stops at the selected minimum or maximum instead of exceeding it.

Restore Brightness

Disabled by default: turning right while the target is off starts from the configured minimum brightness and applies the rotation.
Enabled: turning right while the target is off first restores the previous brightness when the light supports it, then later movement continues adjustment.

Hold Repeat & Release

The Press Action section contains only Single Action, Double Action, and Hold Action. Repeat and release settings are in the separate, collapsed Hold Repeat & Release section.

Do not repeat: Run Hold Action once.
Repeat Hold Action: Run Hold Action once, then repeat it.
Hold once, then repeat a separate action: Run Hold Action once, then repeat Hold Repeat Action.

Repeating stops when release, another knob action, or the maximum duration is reached. Release Action runs once when a release event is received, independently of the selected Hold Repeat Mode.

LEAVE RELEASE ACTION EMPTY unless an action is specifically needed when the knob is released.

Hold Repeat Maximum Duration is a software fallback for a lost release event. It cannot prevent the knob’s hardware behavior.

RELEASE THE PHYSICAL BUTTON BEFORE 10 SECONDS. Holding it for 10 seconds can place the knob into networking mode, interrupt its Zigbee connection, and require pairing again.

Updating

Home Assistant supports updating an installed Blueprint by re-importing it. Review the Breaking Changes section first, re-import the Blueprint, then review and save each existing automation that uses it.

Official Home Assistant guide: Using automation blueprints

yong · February 4, 2025, 4:20am

I know him
He is a great musician

buriburida · February 4, 2025, 4:22am

wow, very very thank you.
So sexy brain man.

davidr · December 7, 2025, 10:48pm

This is working great! thanks so much.

Just a q.q. is there any way to set a minimum brightness to avoid turn off the light when reducing brighness?

kkqq9320 · December 17, 2025, 1:51am

Of course, it’s possible through the blueprint. If I have a chance to revisit this blueprint soon, I’ll try updating it.

Drolkan · February 20, 2026, 1:04am

Thanks for your effort, i must probably be doing something wrong as the “hold + rotate” is not changing the color temperature.

Also been trying to change the blueprint minimum brightness to avoid turn off without any luck.

Drolkan · March 7, 2026, 12:34am

Did the new update 2026.3.0 broke the automation? Double and Hold action seem broke.

djcurley89 · March 19, 2026, 4:01pm

Yeah I believe this is now broken, possibly due to these changes in Home Assistant core

Using color_temp (in mireds) to set a lights color temperature is no longer supported. Use

color_temp_kelvin instead.

Additionally, the color_temp,

kelvin, min_mireds, and max_mireds light entity state attributes have been removed. Use

color_temp_kelvin,

min_color_temp_kelvin, and max_color_temp_kelvin instead.```

djcurley89 · March 19, 2026, 5:14pm

I just udpated the blueprint in my setup and got back the press and hold color temp functionality by upating all the “color_temp” to “color_temp_kelvin”, including all the “color_temp_[min/max]” to “[min/max]_color_temp_kelvin”.

I also updated “color_temp_base” to “base_color_temp_kelvin” and “color_temp_stepsize” to “color_temp_kelvin_stepsize” but not sure those 2 are correct yet as HA documentation doesn’t mention them, I have to do more testing to make sure they’re the correct syntax but at least I’m able to change the light temps with the knob again.

StudlySpud · April 10, 2026, 3:26am

Hi, happy to find your automation as I have just bought a few of these knobs!
I set up the automation blueprint and the press action works to toggle the light, but there is no dimming control.

I’ve been attempting to diagnose but the HA trace tool is not easy to follow, however I think I’ve found it is exiting in the step where it’s choosing condition STATES_PRESSED == ‘released’ or ‘pressed’, however the input for STATES_PRESSED is ‘unknown’.
Interestingly, all the exposed states change to null/unknown after I press the button, and they are all restored if I just use the knob. There is still an “action” available.
Did you experience this with your aqara knobs?

ShadowFist · April 10, 2026, 8:57am

What you’re seeing is standard Z2M behaviour. All actions revert to null after a few milliseconds, so that duplicate consecutive actions can be detected successfully.

Eg. Say you were unlucky enough to send 2 consecutive action_rotation_speed events with a value of exactly 168, minutes or hours apart from each other.
HA’s state engine would see the state going from 168 > 168 and not log any change. If you used action_rotation_speed as a trigger in an automation, it would not trigger the second time.
With Z2M setting the value to null, HA’s state engine would see 168 > null > 168, so HA would pick this up as a state change & your automation would trigger.

kkqq9320 · April 27, 2026, 4:18pm

That’s correct. It wasn’t working because kelvin was changed to color_temp_kelvin in the ha-core 2026.3 update. I’ve fixed it, so please check version 4.0.0!

Note: Most of the color_temp_* variables in the blueprint are custom names I defined myself. The same goes for stepsize. You don’t need to worry too much about them!

kkqq9320 · April 27, 2026, 4:20pm

I’ve added the feature you wanted, so please give 4.0.0 a try. If you run into any problems, feel free to open an issue!

kkqq9320 · April 27, 2026, 4:22pm

4.0.0

Double and hold continue to work without any issues.

thorstenfrank1978 · June 28, 2026, 4:56pm

Changing the color temp with press+rotate does not work for me. I'm new to HA, so might have done something wrong:

Aqara H2 Dimmer as friendly name "Dimmer Esstisch-Lampe"
** is set to "multi-press button: yes"
Group of innr zb bulbs: "light.esstisch_lampe"
After basic BP setup with names above (no single/double/hold actions defined):
** Rotate knob: Works
** Knob pressed + rotate: Nothing or it dims normally
** Single tap: Nothing (as expected)
** Double tap: Nothing (as expected)
Set single tap action explicitely to switch power state:
** Single tap: Works
** Double tap: Works
All other config values: Default

PS: blueprint is installed from github, so it should be the newest version (I do see that color_temp_kelvin is used in the code).

kkqq9320 · July 7, 2026, 6:44pm

I’m not sure what “multi-press button: yes” means. Please show me which option this is using an image.
Please check whether legacy_action_sensor is disabled.
After turning the knob a few times, please go back a few traces from the Trace button in the top-right of the blueprint, and capture the trace from when it rotated.

thorstenfrank1978 · July 11, 2026, 1:59pm

I don’t see anything called legacy_sensor_action in Z2M’s expose tab, nor in the device config window that opens when I click on the device in Z2M. Here is a screenshot of this window, showing only part of the contents. I can screenshot the rest, but I think the status output further down shows it all as well in text from, right?

The status info shown in Z2M:

{
    "brightness": 254,
    "consumption": 0.07390067726373672,
    "current": 0,
    "device_temperature": 35,
    "energy": 0.07,
    "flip_indicator_light": "ON",
    "led_disabled_night": true,
    "led_indicator": "ON",
    "level_config": {
        "off_transition_time": 0.5,
        "on_transition_time": 0.5
    },
    "linkquality": 142,
    "max_brightness": 100,
    "min_brightness": 65,
    "multi_click": true,
    "operation_mode": "decoupled",
    "phase": "forward",
    "power": 0.27,
    "power_on_behavior": "inverted",
    "power_outage_count": 4,
    "sensitivity": "medium",
    "state": "ON",
    "update": {
        "installed_version": 4120,
        "latest_release_notes": null,
        "latest_source": null,
        "latest_version": 4120,
        "state": "idle"
    },
    "voltage": 230.64,
    "action_rotation_angle": null,
    "action_rotation_angle_speed": null,
    "action_rotation_button_state": null,
    "action_rotation_percent": null,
    "action_rotation_percent_speed": null,
    "action_rotation_time": null,
    "effect": null
}

thorstenfrank1978 · July 11, 2026, 2:38pm

Not sure what you mean by “capture the trace”, sorry. I did find the rotate event in the trace window, i.e. a trace for an event that happened a few seconds ago, when I turned the knob. Which of the various tabs would help you to understand my situation? The most verbose seems to be the “changed variables” one:

base_topic: zigbee2mqtt
knob: Dimmer Esstischlampe
translate_friendly_name: ''
this:
  entity_id: automation.sync_dimmer_esstisch
  state: 'on'
  attributes:
    id: '1782769067669'
    last_triggered: '2026-07-11T14:25:30.358225+00:00'
    mode: parallel
    current: 0
    max: 100
    friendly_name: Esstischlampe an/aus/dimmen
  last_changed: '2026-07-11T14:16:24.766015+00:00'
  last_reported: '2026-07-11T14:25:30.384012+00:00'
  last_updated: '2026-07-11T14:25:30.384012+00:00'
  context:
    id: 01KX8S3C7NE8NQ0T22AFKQE7CH
    parent_id: null
    user_id: null
trigger:
  id: '0'
  idx: '0'
  alias: null
  platform: mqtt
  topic: zigbee2mqtt/Dimmer Esstischlampe/action
  payload: rotation
  qos: 0
  description: mqtt topic zigbee2mqtt/Dimmer Esstischlampe/action

Or maybe the flowchart for this event?

PS: Thank you so much for taking the time to help me here! If any logs on a system level would be helpful, I wouldn’t mind ssh’ing onto the machine or using the Terminal in HA itself to dig around if you tell me what to look for.

ShadowFist · July 11, 2026, 3:54pm

It’s in the Z2M Settings page, under Home assistant Integration tab

thorstenfrank1978 · July 12, 2026, 4:00pm

Found it, thank you! It’s indeed disabled.