{"id":6317,"date":"2026-09-01T14:05:56","date_gmt":"2026-09-01T14:05:56","guid":{"rendered":"https:\/\/netguide.io\/smart-home\/aqara-h2-eu-light-switch-zha-custom-quirk-decoupled-mode\/"},"modified":"2026-09-01T14:27:02","modified_gmt":"2026-09-01T14:27:02","slug":"aqara-h2-eu-light-switch-zha-custom-quirk-decoupled-mode","status":"publish","type":"post","link":"https:\/\/netguide.io\/smart-home\/en\/aqara-h2-eu-light-switch-zha-custom-quirk-decoupled-mode\/","title":{"rendered":"Aqara Light Switch H2 EU in ZHA: Enable Decoupled Mode with a Custom Quirk"},"content":{"rendered":"<div id=\"netgu-1071320904\" class=\"netgu-before-content netgu-entity-placement\"><script async src=\"\/\/pagead2.googlesyndication.com\/pagead\/js\/adsbygoogle.js?client=ca-pub-6258556257245998\" crossorigin=\"anonymous\"><\/script><ins class=\"adsbygoogle\" style=\"display:block;\" data-ad-client=\"ca-pub-6258556257245998\" \ndata-ad-slot=\"3494115342\" \ndata-ad-format=\"auto\"><\/ins>\n<script> \n(adsbygoogle = window.adsbygoogle || []).push({}); \n<\/script>\n<\/div>\n<p class=\"wp-block-paragraph\"><strong>The Aqara Light Switch H2 EU (Zigbee model <code>lumi.switch.agl009<\/code>) only works in a rudimentary way under <a href=\"https:\/\/netguide.io\/smart-home\/category\/home-assistant\/\" data-internallinksmanager029f6b8e52c=\"2\" title=\"Home Assistant\">Home Assistant<\/a>\u2019s ZHA integration: a switch entity, power and energy readings, and little else. No decoupled mode, no click events, no LED or power-on control. A custom quirk brings back the full feature set \u2013 without switching to Zigbee2MQTT. This guide walks you through it step by step; it was carried out and verified on six switches on 1 September 2026.<\/strong><\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"#problem\">Why the H2 only half-works under ZHA<\/a><\/li>\n\n<li><a href=\"#requirements\">Requirements<\/a><\/li>\n\n<li><a href=\"#step1\">Step 1: Create the quirk folder and add it to the YAML<\/a><\/li>\n\n<li><a href=\"#step2\">Step 2: Install the quirk file<\/a><\/li>\n\n<li><a href=\"#step3\">Step 3: Restart and verify<\/a><\/li>\n\n<li><a href=\"#entities\">The new entities you get<\/a><\/li>\n\n<li><a href=\"#decoupled\">Enabling Decoupled Mode safely<\/a><\/li>\n\n<li><a href=\"#events\">Using click events in automations<\/a><\/li>\n\n<li><a href=\"#limits\">Limits and pitfalls<\/a><\/li>\n\n<li><a href=\"#faq\">FAQ<\/a><\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"problem\">Why the H2 only half-works under ZHA<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Pair the H2 in ZHA and you get a <code>switch<\/code> entity, power, an energy meter, LQI\/RSSI, Identify and firmware info \u2013 nothing more. For comparison: the exact same device is fully supported under Zigbee2MQTT. The reason shows up in the device diagnostics. Download them (Settings \u2192 Devices \u2192 the device \u2192 menu \u2192 \u201cDownload diagnostics\u201d) and you will see:<\/p>\n\n\n\n<div class=\"wp-block-kevinbatdorf-code-block-pro\" data-code-block-pro-font-family=\"Code-Pro-JetBrains-Mono\" style=\"font-size:.875rem;font-family:Code-Pro-JetBrains-Mono,ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;line-height:1.25rem;--cbp-tab-width:2;tab-size:var(--cbp-tab-width, 2)\"><span style=\"display:block;padding:16px 0 0 16px;margin-bottom:-1px;width:100%;text-align:left;background-color:#24292e\"><svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" width=\"54\" height=\"14\" viewBox=\"0 0 54 14\"><g fill=\"none\" fill-rule=\"evenodd\" transform=\"translate(1 1)\"><circle cx=\"6\" cy=\"6\" r=\"6\" fill=\"#FF5F56\" stroke=\"#E0443E\" stroke-width=\".5\"><\/circle><circle cx=\"26\" cy=\"6\" r=\"6\" fill=\"#FFBD2E\" stroke=\"#DEA123\" stroke-width=\".5\"><\/circle><circle cx=\"46\" cy=\"6\" r=\"6\" fill=\"#27C93F\" stroke=\"#1AAB29\" stroke-width=\".5\"><\/circle><\/g><\/svg><\/span><span role=\"button\" tabindex=\"0\" style=\"color:#e1e4e8;display:none\" aria-label=\"Copy\" class=\"code-block-pro-copy-button\"><pre class=\"code-block-pro-copy-button-pre\" aria-hidden=\"true\"><textarea class=\"code-block-pro-copy-button-textarea\" tabindex=\"-1\" aria-hidden=\"true\" readonly>\"quirk_applied\": false,\n\"quirk_class\": \"zigpy.device.Device\"<\/textarea><\/pre><svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" style=\"width:24px;height:24px\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\"><path class=\"with-check\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4\"><\/path><path class=\"without-check\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2\"><\/path><\/svg><\/span><pre class=\"shiki github-dark\" style=\"background-color: #24292e\" tabindex=\"0\"><code><span class=\"line\"><span style=\"color:#e1e4e8\">\"quirk_applied\": false,<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">\"quirk_class\": \"zigpy.device.Device\"<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">So no quirk applies at all \u2013 zigpy only parses the raw ZCL profile. The manufacturer-specific cluster <code>0xFCC0<\/code> is present on several endpoints, but its attribute list is empty. Yet that is exactly where decoupled mode, LED control, power-on behaviour, relay lock and multi-click live. On top of that, the <code>multistate_input<\/code> clusters stay silent, so no button-press events are generated. Without a matching quirk, ZHA simply cannot know these attributes. If you first want to sort out the fundamental differences between the two Zigbee paths, see our comparison <a href=\"https:\/\/netguide.io\/smart-home\/en\/zigbee2mqtt-vs-zha\/\">Zigbee2MQTT vs. ZHA<\/a>.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"requirements\">Requirements<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/netguide.io\/smart-home\/category\/home-assistant\/\" data-internallinksmanager029f6b8e52c=\"2\" title=\"Home Assistant\">Home Assistant<\/a> 2026.8 or newer (tested with 2026.8.3 on HA OS 18.2)<\/li>\n\n<li>An active ZHA integration (tested with <code>zha 2.1.0<\/code> \/ <code>zha-quirks 2.2.0<\/code>)<\/li>\n\n<li>Access to the <code>\/config<\/code> directory, e.g. via the \u201cAdvanced SSH &amp; Web Terminal\u201d or \u201cFile editor\u201d add-on<\/li>\n\n<li>The H2 EU as <code>lumi.switch.agl009<\/code> (2 buttons\/1 channel) \u2013 the quirk also covers <code>agl010<\/code>, <code>agl004<\/code>, <code>agl005<\/code> and <code>agl006<\/code><\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">The finished quirk comes from the still-open pull request <a href=\"https:\/\/github.com\/zigpy\/zha-device-handlers\/pull\/4141\" target=\"_blank\" rel=\"noopener\">zigpy\/zha-device-handlers #4141<\/a> (\u201cAdd Aqara H2 switches (EU+US)\u201d). Because it is not yet part of <code>zha-quirks 2.2.0<\/code>, we add it as a local custom quirk.<\/p>\n\n\n\n<div class=\"wp-block-group aqara-buybox is-layout-constrained wp-container-core-group-is-layout-037d570b wp-block-group-is-layout-constrained\" style=\"border:1px solid #d7dde5;border-radius:12px;padding:20px\">\n<h3 class=\"wp-block-heading\">Matching device: Aqara Light Switch H2 EU<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Exactly the model used in this guide: 2-in-1 (with\/without neutral), 2 buttons \/ 1 channel, Thread &amp; Matter, Zigbee model <code>lumi.switch.agl009<\/code>.<\/p>\n\n\n\n<div class=\"wp-block-buttons is-layout-flex wp-block-buttons-is-layout-flex\">\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-color has-background wp-element-button\" style=\"color:#111111;background-color:#ff9900\" href=\"https:\/\/www.amazon.de\/dp\/B0DT68HB41?tag=netguideio-21\" target=\"_blank\" rel=\"sponsored nofollow noopener\">View on Amazon.de<\/a><\/div>\n<\/div>\n\n\n\n<p class=\"has-small-font-size wp-block-paragraph\"><em>Affiliate link \u2013 buying through it supports netguide.io at no extra cost to you.<\/em><\/p>\n<\/div>\n\n\n\n<div id=\"netgu-2060186414\" class=\"netgu-content netgu-entity-placement\"><aside class=\"deals-top deals-top--compact\">\r\n\r\n\t\t\t<h3 class=\"deals-top__title\">Smart Home Deals<\/h3>\r\n\t\r\n\t\t\t<ul class=\"deals-top__list\">\r\n\t\t\t\t\t\t\t<li class=\"deals-top__item\">\r\n\t\t\t\t\t<a class=\"deals-top__link\" href=\"https:\/\/netguide.io\/deals\/de\/deals\/philips-hue-white-ambiance-e27-3er-starter-set-inkl-smart-button-dimmbar-alle-weissschattierungen-steuerbar-via-app-kompatibel-mit-amazon-alexa-echo-echo\/\">\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t<img class=\"deals-top__image\" src=\"https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/15\/2026\/09\/61pZ0xD9KGL._AC_SL1500_-150x150.jpg\" alt=\"\" width=\"52\" height=\"52\" loading=\"lazy\" \/>\r\n\t\t\t\t\t\t\r\n\t\t\t\t\t\t<span class=\"deals-top__body\">\r\n\t\t\t\t\t\t\t<span class=\"deals-top__name\">Philips Hue White Ambiance E27 3er Starter Set inkl. Smart Button, dimmbar, alle Wei\u00dfschattierungen, steuerbar via App, kompatibel mit Amazon Alexa (Echo, Echo\u2026<\/span>\r\n\r\n\t\t\t\t\t\t\t<span class=\"deals-top__meta\">\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<span class=\"deals-top__price\">77.99 \u20ac<\/span>\r\n\t\t\t\t\t\t\t\t\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<s>129.99 \u20ac<\/s>\r\n\t\t\t\t\t\t\t\t\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<span class=\"deals-discount\">-40%<\/span>\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<\/span>\r\n\t\t\t\t\t\t<\/span>\r\n\r\n\t\t\t\t\t\t<span class=\"deals-top__temperature\">\r\n\t\t\t\t\t\t\t0\u00b0\r\n\t\t\t\t\t\t<\/span>\r\n\t\t\t\t\t<\/a>\r\n\t\t\t\t<\/li>\r\n\t\t\t\t\t\t\t<li class=\"deals-top__item\">\r\n\t\t\t\t\t<a class=\"deals-top__link\" href=\"https:\/\/netguide.io\/deals\/de\/deals\/philips-hue-e27-filament-grosse-edison-lampe-white-ambiance-alle-weisstoene-550-lm-dimmbar-leuchtmittel-fuer-das-hue-lichtsystem-app-und-sprachsteuerung-s\/\">\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t<img class=\"deals-top__image\" src=\"https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/15\/2026\/09\/61UiXJLhChL._AC_SL1500_-150x150.jpg\" alt=\"\" width=\"52\" height=\"52\" loading=\"lazy\" \/>\r\n\t\t\t\t\t\t\r\n\t\t\t\t\t\t<span class=\"deals-top__body\">\r\n\t\t\t\t\t\t\t<span class=\"deals-top__name\">Philips Hue E27 Filament Gro\u00dfe Edison Lampe | White Ambiance, Alle Wei\u00dft\u00f6ne, 550 lm, Dimmbar, Leuchtmittel f\u00fcr das Hue Lichtsystem, App- und Sprachsteuerung, S\u2026<\/span>\r\n\r\n\t\t\t\t\t\t\t<span class=\"deals-top__meta\">\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<span class=\"deals-top__price\">29.99 \u20ac<\/span>\r\n\t\t\t\t\t\t\t\t\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<s>39.90 \u20ac<\/s>\r\n\t\t\t\t\t\t\t\t\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<span class=\"deals-discount\">-25%<\/span>\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<\/span>\r\n\t\t\t\t\t\t<\/span>\r\n\r\n\t\t\t\t\t\t<span class=\"deals-top__temperature\">\r\n\t\t\t\t\t\t\t0\u00b0\r\n\t\t\t\t\t\t<\/span>\r\n\t\t\t\t\t<\/a>\r\n\t\t\t\t<\/li>\r\n\t\t\t\t\t\t\t<li class=\"deals-top__item\">\r\n\t\t\t\t\t<a class=\"deals-top__link\" href=\"https:\/\/netguide.io\/deals\/de\/deals\/bosch-smart-home-heizkoerper-thermostat-ii-m-smartes-heizkoerperthermostat-intelligentes-heizen-energiesparen-matter-app-steuerung-apple-home-google-h\/\">\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t<img class=\"deals-top__image\" src=\"https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/15\/2026\/09\/512mj3mE3VL-150x150.jpg\" alt=\"\" width=\"52\" height=\"52\" loading=\"lazy\" \/>\r\n\t\t\t\t\t\t\r\n\t\t\t\t\t\t<span class=\"deals-top__body\">\r\n\t\t\t\t\t\t\t<span class=\"deals-top__name\">Bosch Smart Home Heizk\u00f6rper-Thermostat II [+M], smartes Heizk\u00f6rperthermostat, intelligentes Heizen &amp; Energiesparen, Matter, App-Steuerung, Apple Home, Google H\u2026<\/span>\r\n\r\n\t\t\t\t\t\t\t<span class=\"deals-top__meta\">\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<span class=\"deals-top__price\">49.89 \u20ac<\/span>\r\n\t\t\t\t\t\t\t\t\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<s>58.76 \u20ac<\/s>\r\n\t\t\t\t\t\t\t\t\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<span class=\"deals-discount\">-15%<\/span>\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<\/span>\r\n\t\t\t\t\t\t<\/span>\r\n\r\n\t\t\t\t\t\t<span class=\"deals-top__temperature\">\r\n\t\t\t\t\t\t\t0\u00b0\r\n\t\t\t\t\t\t<\/span>\r\n\t\t\t\t\t<\/a>\r\n\t\t\t\t<\/li>\r\n\t\t\t\t\t\t\t<li class=\"deals-top__item\">\r\n\t\t\t\t\t<a class=\"deals-top__link\" href=\"https:\/\/netguide.io\/deals\/de\/deals\/amazon-fire-tv-stick-hd-neueste-generation-mit-alexa-sprachfernbedienung-free-live-tv-einfache-einrichtung-stromversorgung-ueber-tv\/\">\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t<img class=\"deals-top__image\" src=\"https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/15\/2026\/09\/61p8EZV0P2L._AC_SL1500_-150x150.jpg\" alt=\"\" width=\"52\" height=\"52\" loading=\"lazy\" \/>\r\n\t\t\t\t\t\t\r\n\t\t\t\t\t\t<span class=\"deals-top__body\">\r\n\t\t\t\t\t\t\t<span class=\"deals-top__name\">Amazon Fire TV Stick HD (neueste Generation) mit Alexa-Sprachfernbedienung, Free- &amp; Live-TV, einfache Einrichtung, Stromversorgung \u00fcber TV<\/span>\r\n\r\n\t\t\t\t\t\t\t<span class=\"deals-top__meta\">\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<span class=\"deals-top__price\">26.99 \u20ac<\/span>\r\n\t\t\t\t\t\t\t\t\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<s>64.99 \u20ac<\/s>\r\n\t\t\t\t\t\t\t\t\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<span class=\"deals-discount\">-58%<\/span>\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<\/span>\r\n\t\t\t\t\t\t<\/span>\r\n\r\n\t\t\t\t\t\t<span class=\"deals-top__temperature\">\r\n\t\t\t\t\t\t\t0\u00b0\r\n\t\t\t\t\t\t<\/span>\r\n\t\t\t\t\t<\/a>\r\n\t\t\t\t<\/li>\r\n\t\t\t\t\t<\/ul>\r\n\r\n\t\t\t\t\t<p class=\"deals-top__more\">\r\n\t\t\t\t<a href=\"https:\/\/netguide.io\/deals\/\">Alle Deals ansehen \u2192<\/a>\r\n\t\t\t<\/p>\r\n\t\t\t<\/aside>\r\n<\/div><h2 class=\"wp-block-heading\" id=\"step1\">Step 1: Create the quirk folder and add it to the YAML<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">ZHA loads custom quirks from a directory you define in <code>configuration.yaml<\/code>:<\/p>\n\n\n\n<div class=\"wp-block-kevinbatdorf-code-block-pro\" data-code-block-pro-font-family=\"Code-Pro-JetBrains-Mono\" style=\"font-size:.875rem;font-family:Code-Pro-JetBrains-Mono,ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;line-height:1.25rem;--cbp-tab-width:2;tab-size:var(--cbp-tab-width, 2)\"><span style=\"display:block;padding:16px 0 0 16px;margin-bottom:-1px;width:100%;text-align:left;background-color:#24292e\"><svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" width=\"54\" height=\"14\" viewBox=\"0 0 54 14\"><g fill=\"none\" fill-rule=\"evenodd\" transform=\"translate(1 1)\"><circle cx=\"6\" cy=\"6\" r=\"6\" fill=\"#FF5F56\" stroke=\"#E0443E\" stroke-width=\".5\"><\/circle><circle cx=\"26\" cy=\"6\" r=\"6\" fill=\"#FFBD2E\" stroke=\"#DEA123\" stroke-width=\".5\"><\/circle><circle cx=\"46\" cy=\"6\" r=\"6\" fill=\"#27C93F\" stroke=\"#1AAB29\" stroke-width=\".5\"><\/circle><\/g><\/svg><\/span><span role=\"button\" tabindex=\"0\" style=\"color:#e1e4e8;display:none\" aria-label=\"Copy\" class=\"code-block-pro-copy-button\"><pre class=\"code-block-pro-copy-button-pre\" aria-hidden=\"true\"><textarea class=\"code-block-pro-copy-button-textarea\" tabindex=\"-1\" aria-hidden=\"true\" readonly>zha:\n  enable_quirks: true\n  custom_quirks_path: \/config\/zha_quirks\/<\/textarea><\/pre><svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" style=\"width:24px;height:24px\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\"><path class=\"with-check\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4\"><\/path><path class=\"without-check\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2\"><\/path><\/svg><\/span><pre class=\"shiki github-dark\" style=\"background-color: #24292e\" tabindex=\"0\"><code><span class=\"line\"><span style=\"color:#e1e4e8\">zha:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">  enable_quirks: true<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">  custom_quirks_path: \/config\/zha_quirks\/<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n<div class=\"wp-block-group has-luminous-vivid-amber-background-color has-background is-layout-constrained wp-container-core-group-is-layout-4667ddc0 wp-block-group-is-layout-constrained\" style=\"border-left-color:#f0b429;border-left-width:4px;padding-top:12px;padding-right:16px;padding-bottom:12px;padding-left:16px\">\n<p class=\"wp-block-paragraph\"><strong>Mind the order:<\/strong> <a href=\"https:\/\/netguide.io\/smart-home\/category\/home-assistant\/\" data-internallinksmanager029f6b8e52c=\"2\" title=\"Home Assistant\">Home Assistant<\/a> validates the path at startup with <code>cv.isdir<\/code>. If the folder does not exist yet, the config check fails. So create the <code>\/config\/zha_quirks\/<\/code> directory first and add the YAML <em>afterwards<\/em>. There is no field for this in the integration\u2019s options dialog \u2013 it is YAML-only configuration.<\/p>\n<\/div>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"step2\">Step 2: Install the quirk file<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The most robust approach is to download the file pinned to a fixed commit \u2013 that way its contents will not change while the PR keeps evolving. In the HA terminal:<\/p>\n\n\n\n<div class=\"wp-block-kevinbatdorf-code-block-pro\" data-code-block-pro-font-family=\"Code-Pro-JetBrains-Mono\" style=\"font-size:.875rem;font-family:Code-Pro-JetBrains-Mono,ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;line-height:1.25rem;--cbp-tab-width:2;tab-size:var(--cbp-tab-width, 2)\"><span style=\"display:block;padding:16px 0 0 16px;margin-bottom:-1px;width:100%;text-align:left;background-color:#24292e\"><svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" width=\"54\" height=\"14\" viewBox=\"0 0 54 14\"><g fill=\"none\" fill-rule=\"evenodd\" transform=\"translate(1 1)\"><circle cx=\"6\" cy=\"6\" r=\"6\" fill=\"#FF5F56\" stroke=\"#E0443E\" stroke-width=\".5\"><\/circle><circle cx=\"26\" cy=\"6\" r=\"6\" fill=\"#FFBD2E\" stroke=\"#DEA123\" stroke-width=\".5\"><\/circle><circle cx=\"46\" cy=\"6\" r=\"6\" fill=\"#27C93F\" stroke=\"#1AAB29\" stroke-width=\".5\"><\/circle><\/g><\/svg><\/span><span role=\"button\" tabindex=\"0\" style=\"color:#e1e4e8;display:none\" aria-label=\"Copy\" class=\"code-block-pro-copy-button\"><pre class=\"code-block-pro-copy-button-pre\" aria-hidden=\"true\"><textarea class=\"code-block-pro-copy-button-textarea\" tabindex=\"-1\" aria-hidden=\"true\" readonly>wget -O \/config\/zha_quirks\/switch_h2.py \\\n  https:\/\/raw.githubusercontent.com\/lonevvolf\/zha-device-handlers\/c06083b1d655c1787f5c0c2f56edd84b970328d4\/zhaquirks\/xiaomi\/aqara\/switch_h2.py\n\n# verify integrity (optional but recommended)\nsha256sum \/config\/zha_quirks\/switch_h2.py\n# fc846cbd24a37a51964196d999d46bc6516662d937227b9b1b2e1ed1410e017a  (19761 bytes, 575 lines)\n\nha core restart<\/textarea><\/pre><svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" style=\"width:24px;height:24px\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\"><path class=\"with-check\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4\"><\/path><path class=\"without-check\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2\"><\/path><\/svg><\/span><pre class=\"shiki github-dark\" style=\"background-color: #24292e\" tabindex=\"0\"><code><span class=\"line\"><span style=\"color:#e1e4e8\">wget -O \/config\/zha_quirks\/switch_h2.py \\<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">  https:\/\/raw.githubusercontent.com\/lonevvolf\/zha-device-handlers\/c06083b1d655c1787f5c0c2f56edd84b970328d4\/zhaquirks\/xiaomi\/aqara\/switch_h2.py<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\"><\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\"># verify integrity (optional but recommended)<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">sha256sum \/config\/zha_quirks\/switch_h2.py<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\"># fc846cbd24a37a51964196d999d46bc6516662d937227b9b1b2e1ed1410e017a  (19761 bytes, 575 lines)<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\"><\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">ha core restart<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">The checksum matches commit <code>c06083b<\/code> from 27 August 2026. If it matches on your side, you have exactly the same file as in this guide.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"step3\">Step 3: Restart and verify<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">After the restart, download the diagnostics for the same device again. It should now read:<\/p>\n\n\n\n<div class=\"wp-block-kevinbatdorf-code-block-pro\" data-code-block-pro-font-family=\"Code-Pro-JetBrains-Mono\" style=\"font-size:.875rem;font-family:Code-Pro-JetBrains-Mono,ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;line-height:1.25rem;--cbp-tab-width:2;tab-size:var(--cbp-tab-width, 2)\"><span style=\"display:block;padding:16px 0 0 16px;margin-bottom:-1px;width:100%;text-align:left;background-color:#24292e\"><svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" width=\"54\" height=\"14\" viewBox=\"0 0 54 14\"><g fill=\"none\" fill-rule=\"evenodd\" transform=\"translate(1 1)\"><circle cx=\"6\" cy=\"6\" r=\"6\" fill=\"#FF5F56\" stroke=\"#E0443E\" stroke-width=\".5\"><\/circle><circle cx=\"26\" cy=\"6\" r=\"6\" fill=\"#FFBD2E\" stroke=\"#DEA123\" stroke-width=\".5\"><\/circle><circle cx=\"46\" cy=\"6\" r=\"6\" fill=\"#27C93F\" stroke=\"#1AAB29\" stroke-width=\".5\"><\/circle><\/g><\/svg><\/span><span role=\"button\" tabindex=\"0\" style=\"color:#e1e4e8;display:none\" aria-label=\"Copy\" class=\"code-block-pro-copy-button\"><pre class=\"code-block-pro-copy-button-pre\" aria-hidden=\"true\"><textarea class=\"code-block-pro-copy-button-textarea\" tabindex=\"-1\" aria-hidden=\"true\" readonly>\"quirk_applied\": true,\n\"quirk_class\": \"switch_h2:(Aqara \/ lumi.switch.agl009)\"<\/textarea><\/pre><svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" style=\"width:24px;height:24px\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\"><path class=\"with-check\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4\"><\/path><path class=\"without-check\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2\"><\/path><\/svg><\/span><pre class=\"shiki github-dark\" style=\"background-color: #24292e\" tabindex=\"0\"><code><span class=\"line\"><span style=\"color:#e1e4e8\">\"quirk_applied\": true,<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">\"quirk_class\": \"switch_h2:(Aqara \/ lumi.switch.agl009)\"<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n<div class=\"wp-block-group has-luminous-vivid-amber-background-color has-background is-layout-constrained wp-container-core-group-is-layout-4667ddc0 wp-block-group-is-layout-constrained\" style=\"border-left-color:#f0b429;border-left-width:4px;padding-top:12px;padding-right:16px;padding-bottom:12px;padding-left:16px\">\n<p class=\"wp-block-paragraph\">The system log shows the message <code>zhaquirks: Loaded custom quirks. Please contribute them to \u2026<\/code> at WARNING level. This is <strong>not an error<\/strong> \u2013 it is a normal notice that a custom quirk is active.<\/p>\n<\/div>\n\n\n\n<p class=\"wp-block-paragraph\">The result is visible right on the device: instead of 7, each switch now exposes 13 entities. The new \u201cConfiguration\u201d card looks like this:<\/p>\n\n\n\n<figure class=\"wp-block-image size-large\"><img loading=\"lazy\" decoding=\"async\" width=\"428\" height=\"522\" src=\"https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/3\/2026\/09\/aqara-h2-eu-decoupled-mode-zha.png\" alt=\"Home Assistant configuration card of the Aqara H2 EU with operating mode Decoupled, LED indicator, Lock relay, Multi click and Power on mode\" class=\"wp-image-6315\" srcset=\"https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/3\/2026\/09\/aqara-h2-eu-decoupled-mode-zha.png 428w, https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/3\/2026\/09\/aqara-h2-eu-decoupled-mode-zha-246x300.png 246w\" sizes=\"auto, (max-width: 428px) 100vw, 428px\" \/><figcaption class=\"wp-block-image__caption\">After the quirk, ZHA shows operating mode (Decoupled), LED indicator, Flip LED indicator, Lock relay, Multi click and Power on mode \u2013 the values are read live from the device.<\/figcaption><\/figure>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"entities\">The new entities you get<\/h2>\n\n\n\n<figure class=\"wp-block-table is-style-stripes\"><table><thead><tr><th>Entity<\/th><th>Type<\/th><th>Function<\/th><\/tr><\/thead><tbody><tr><td>Operating mode<\/td><td>Select<\/td><td>Switch between <code>Decoupled<\/code> and <code>Relay<\/code><\/td><\/tr><tr><td>Power on mode<\/td><td>Select<\/td><td>Behaviour after power returns: <code>On<\/code>, <code>Previous<\/code>, <code>Off<\/code>, <code>Inverted<\/code><\/td><\/tr><tr><td>LED indicator<\/td><td>Switch<\/td><td>Turn the status LED on\/off<\/td><\/tr><tr><td>Flip LED indicator<\/td><td>Switch<\/td><td>Invert the LED logic<\/td><\/tr><tr><td>Lock relay<\/td><td>Switch<\/td><td>Freeze the relay in its current state<\/td><\/tr><tr><td>Multi click<\/td><td>Switch<\/td><td>Enable multi-click detection<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">The values are not just created but actually read from the device \u2013 in our test the operating mode came back as <code>Relay<\/code> and the power-on mode as <code>Previous<\/code>.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"decoupled\">Enabling Decoupled Mode safely<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">In decoupled mode the rocker is decoupled from the relay: the physical switch no longer cuts power, it only reports the button press to <a href=\"https:\/\/netguide.io\/smart-home\/category\/home-assistant\/\" data-internallinksmanager029f6b8e52c=\"2\" title=\"Home Assistant\">Home Assistant<\/a>. That is exactly what you want when <strong>smart bulbs<\/strong> sit behind the switch and need permanent power. So that the bulbs are never left without power, follow this order:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>First<\/strong> turn on the <code>switch<\/code> entity (relay closed, the bulbs have constant power).<\/li>\n\n<li><strong>Then<\/strong> set the operating mode to <code>Decoupled<\/code> (the rocker can no longer cut power).<\/li>\n\n<li><strong>Optionally<\/strong> enable <code>Lock relay<\/code> so no accidental automation opens the relay either.<\/li>\n<\/ul>\n\n\n\n<div class=\"wp-block-group has-luminous-vivid-amber-background-color has-background is-layout-constrained wp-container-core-group-is-layout-4667ddc0 wp-block-group-is-layout-constrained\" style=\"border-left-color:#f0b429;border-left-width:4px;padding-top:12px;padding-right:16px;padding-bottom:12px;padding-left:16px\">\n<p class=\"wp-block-paragraph\"><strong>Important:<\/strong> In decoupled mode the light switch depends on Home Assistant being available. If HA is down, the rocker does nothing. If an ordinary (non-smart) lamp sits behind the switch, you do not need decoupled mode at all \u2013 the rocker then switches directly as usual.<\/p>\n<\/div>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"events\">Using click events in automations<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The quirk makes the buttons fire the <code>zha_event<\/code>. The event <code>command<\/code> is composed of endpoint and press type. For the <code>agl009<\/code>:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Button 1: <code>1_single<\/code>, <code>1_double<\/code>, <code>1_hold<\/code>, <code>1_release<\/code><\/li>\n\n<li>Button 2: <code>4_single<\/code>, <code>4_double<\/code>, <code>4_hold<\/code>, <code>4_release<\/code><\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">Because ZHA does not create <code>event.*<\/code> entities for these switches, you trigger on the <code>zha_event<\/code> directly. Use <code>device_ieee<\/code> instead of <code>device_id<\/code> \u2013 the IEEE address survives re-pairing the device. Branch via trigger IDs and <code>choose<\/code>:<\/p>\n\n\n\n<div class=\"wp-block-kevinbatdorf-code-block-pro\" data-code-block-pro-font-family=\"Code-Pro-JetBrains-Mono\" style=\"font-size:.875rem;font-family:Code-Pro-JetBrains-Mono,ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;line-height:1.25rem;--cbp-tab-width:2;tab-size:var(--cbp-tab-width, 2)\"><span style=\"display:block;padding:16px 0 0 16px;margin-bottom:-1px;width:100%;text-align:left;background-color:#24292e\"><svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" width=\"54\" height=\"14\" viewBox=\"0 0 54 14\"><g fill=\"none\" fill-rule=\"evenodd\" transform=\"translate(1 1)\"><circle cx=\"6\" cy=\"6\" r=\"6\" fill=\"#FF5F56\" stroke=\"#E0443E\" stroke-width=\".5\"><\/circle><circle cx=\"26\" cy=\"6\" r=\"6\" fill=\"#FFBD2E\" stroke=\"#DEA123\" stroke-width=\".5\"><\/circle><circle cx=\"46\" cy=\"6\" r=\"6\" fill=\"#27C93F\" stroke=\"#1AAB29\" stroke-width=\".5\"><\/circle><\/g><\/svg><\/span><span role=\"button\" tabindex=\"0\" style=\"color:#e1e4e8;display:none\" aria-label=\"Copy\" class=\"code-block-pro-copy-button\"><pre class=\"code-block-pro-copy-button-pre\" aria-hidden=\"true\"><textarea class=\"code-block-pro-copy-button-textarea\" tabindex=\"-1\" aria-hidden=\"true\" readonly>alias: Kitchen \u2013 wall switch (decoupled)\ntriggers:\n  - trigger: event\n    event_type: zha_event\n    event_data:\n      device_ieee: \"AA:BB:CC:DD:EE:FF:00:11\"\n      command: \"1_single\"\n    id: toggle\n  - trigger: event\n    event_type: zha_event\n    event_data:\n      device_ieee: \"AA:BB:CC:DD:EE:FF:00:11\"\n      command: \"1_double\"\n    id: bright\nconditions: []\nactions:\n  - choose:\n      - conditions:\n          - condition: trigger\n            id: toggle\n        sequence:\n          - action: light.toggle\n            target:\n              entity_id: light.kitchen\n      - conditions:\n          - condition: trigger\n            id: bright\n        sequence:\n          - action: light.turn_on\n            target:\n              entity_id: light.kitchen\n            data:\n              brightness_pct: 100\nmode: queued\nmax: 10<\/textarea><\/pre><svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" style=\"width:24px;height:24px\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\"><path class=\"with-check\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4\"><\/path><path class=\"without-check\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2\"><\/path><\/svg><\/span><pre class=\"shiki github-dark\" style=\"background-color: #24292e\" tabindex=\"0\"><code><span class=\"line\"><span style=\"color:#e1e4e8\">alias: Kitchen \u2013 wall switch (decoupled)<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">triggers:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">  - trigger: event<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">    event_type: zha_event<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">    event_data:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">      device_ieee: \"AA:BB:CC:DD:EE:FF:00:11\"<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">      command: \"1_single\"<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">    id: toggle<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">  - trigger: event<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">    event_type: zha_event<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">    event_data:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">      device_ieee: \"AA:BB:CC:DD:EE:FF:00:11\"<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">      command: \"1_double\"<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">    id: bright<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">conditions: []<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">actions:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">  - choose:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">      - conditions:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">          - condition: trigger<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">            id: toggle<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">        sequence:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">          - action: light.toggle<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">            target:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">              entity_id: light.kitchen<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">      - conditions:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">          - condition: trigger<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">            id: bright<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">        sequence:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">          - action: light.turn_on<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">            target:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">              entity_id: light.kitchen<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">            data:<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">              brightness_pct: 100<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">mode: queued<\/span><\/span>\n<span class=\"line\"><span style=\"color:#e1e4e8\">max: 10<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\"><code>mode: queued<\/code> is deliberate so that quick button sequences are not dropped. The quirk maps the press types as follows: <code>0 = hold<\/code>, <code>1 = single<\/code>, <code>2 = double<\/code>, <code>3 = triple<\/code>, <code>255 = release<\/code>.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"limits\">Limits and pitfalls<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>No direct Zigbee binding to lamps.<\/strong> EP 1 only exposes Time and OTA as out-clusters \u2013 no OnOff client. So the switch sends no Zigbee switching commands; it reports presses as attribute reports. Zigbee \u201cbinding\u201d and groups are therefore out; everything runs through Home Assistant automations.<\/li>\n\n<li><strong>Writes can fail over Zigbee.<\/strong> The H2 report themselves as an <code>EndDevice<\/code> with \u201cBattery or Unknown\u201d, even though they are mains-powered. ZHA then treats them like sleeping devices at times, and a switch acknowledges with <code>ZIGBEE_DELIVERY_FAILED<\/code>. Fix: press the rocker once to wake the device, then write again.<\/li>\n\n<li><strong>LED indicator may have no effect on EU variants.<\/strong> Testers report that LED control has no effect on EU models, while it works on US\/AU. Decoupled mode and click events are unaffected.<\/li>\n\n<li><strong>Delete the local copy after the merge.<\/strong> Custom quirks take precedence over built-in ones. Once the PR is merged and part of <code>zha-quirks<\/code>, remove <code>switch_h2.py<\/code> from <code>\/config\/zha_quirks\/<\/code> \u2013 otherwise the frozen file permanently overrides the maintained upstream quirk.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"faq\">FAQ<\/h2>\n\n\n\n<h4 class=\"wp-block-heading\">What exactly is decoupled mode?<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">It decouples the physical rocker from the internal relay. The switch no longer cuts power itself; it only reports the button press \u2013 ideal for smart bulbs that need constant power.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">Do I need the quirk with an ordinary lamp too?<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">No. If a regular, non-smart lamp sits behind the switch, the rocker works directly and reliably in the default mode (Relay) \u2013 even without Home Assistant. Decoupled mode only makes sense with smart bulbs.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">What happens when the pull request is merged?<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">The quirk will eventually become a fixed part of <code>zha-quirks<\/code>. Delete your local <code>switch_h2.py<\/code> so the updated upstream version is used instead of your frozen copy.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">Why doesn\u2019t my LED indicator respond?<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">On EU variants several users report that LED control has no effect. This is known and affects neither decoupled mode nor the click events.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">Can I bind the switch directly to a Zigbee lamp?<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">No. The switch lacks the required OnOff client cluster. You connect the button press to the lamp through a Home Assistant automation (see above).<\/p>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\"\/>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Sources:<\/strong> <a href=\"https:\/\/github.com\/zigpy\/zha-device-handlers\/pull\/4141\" target=\"_blank\" rel=\"noopener\">Pull request #4141 (zha-device-handlers)<\/a> \u00b7 <a href=\"https:\/\/github.com\/zigpy\/zha-device-handlers\/issues\/3957\" target=\"_blank\" rel=\"noopener\">Device support request H2 EU<\/a> \u00b7 <a href=\"https:\/\/github.com\/Koenkk\/zigbee-herdsman-converters\/blob\/master\/src\/lib\/lumi.ts\" target=\"_blank\" rel=\"noopener\">Zigbee2MQTT converter (attribute semantics)<\/a>. Note: the H2 EU dimmer (<code>lumi.switch.agl011<\/code>) is <em>not<\/em> covered by this quirk.<\/p>\n<div id=\"netgu-463090975\" class=\"netgu-after-content netgu-entity-placement\"><script async src=\"\/\/pagead2.googlesyndication.com\/pagead\/js\/adsbygoogle.js?client=ca-pub-6258556257245998\" crossorigin=\"anonymous\"><\/script><ins class=\"adsbygoogle\" style=\"display:block;\" data-ad-client=\"ca-pub-6258556257245998\" \ndata-ad-slot=\"4559785002\" \ndata-ad-format=\"auto\"><\/ins>\n<script> \n(adsbygoogle = window.adsbygoogle || []).push({}); \n<\/script>\n<\/div>","protected":false},"excerpt":{"rendered":"<p>How to unlock decoupled mode, click events and LED control on the Aqara H2 EU (lumi.switch.agl009) under Home Assistant ZHA with a custom quirk \u2013 step by step.<\/p>\n","protected":false},"author":1,"featured_media":6315,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_uag_custom_page_level_css":"","site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"default","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","ast-disable-related-posts":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":""},"categories":[],"tags":[],"class_list":["post-6317","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry"],"uagb_featured_image_src":{"full":["https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/3\/2026\/09\/aqara-h2-eu-decoupled-mode-zha.png",428,522,false],"thumbnail":["https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/3\/2026\/09\/aqara-h2-eu-decoupled-mode-zha-150x150.png",150,150,true],"medium":["https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/3\/2026\/09\/aqara-h2-eu-decoupled-mode-zha-246x300.png",246,300,true],"medium_large":["https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/3\/2026\/09\/aqara-h2-eu-decoupled-mode-zha.png",428,522,false],"large":["https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/3\/2026\/09\/aqara-h2-eu-decoupled-mode-zha.png",428,522,false],"1536x1536":["https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/3\/2026\/09\/aqara-h2-eu-decoupled-mode-zha.png",428,522,false],"2048x2048":["https:\/\/netguide.io\/smart-home\/wp-content\/uploads\/sites\/3\/2026\/09\/aqara-h2-eu-decoupled-mode-zha.png",428,522,false]},"uagb_author_info":{"display_name":"Tobias","author_link":"https:\/\/netguide.io\/smart-home\/author\/tobias-pries\/"},"uagb_comment_info":0,"uagb_excerpt":"How to unlock decoupled mode, click events and LED control on the Aqara H2 EU (lumi.switch.agl009) under Home Assistant ZHA with a custom quirk \u2013 step by step.","brizy_media":[],"_links":{"self":[{"href":"https:\/\/netguide.io\/smart-home\/wp-json\/wp\/v2\/posts\/6317","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/netguide.io\/smart-home\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/netguide.io\/smart-home\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/netguide.io\/smart-home\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/netguide.io\/smart-home\/wp-json\/wp\/v2\/comments?post=6317"}],"version-history":[{"count":1,"href":"https:\/\/netguide.io\/smart-home\/wp-json\/wp\/v2\/posts\/6317\/revisions"}],"predecessor-version":[{"id":6325,"href":"https:\/\/netguide.io\/smart-home\/wp-json\/wp\/v2\/posts\/6317\/revisions\/6325"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/netguide.io\/smart-home\/wp-json\/wp\/v2\/media\/6315"}],"wp:attachment":[{"href":"https:\/\/netguide.io\/smart-home\/wp-json\/wp\/v2\/media?parent=6317"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/netguide.io\/smart-home\/wp-json\/wp\/v2\/categories?post=6317"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/netguide.io\/smart-home\/wp-json\/wp\/v2\/tags?post=6317"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}