feat(hass): support Zigbee2MQTT off-state updates via MQTT publish

Author: subha0319

src/main/java/at/sv/hue/HueScheduler.java

@@ -261,6 +261,13 @@ public final class HueScheduler implements Runnable {
             description = "Disables certificate validation for older bridges using self-signed certificates." +
                           " Default: ${DEFAULT-VALUE}")
     private boolean insecure;
+
+    @Option(names = "--z2m-base-topic", paramLabel = "<topic>",
+            defaultValue = "${env:Z2M_BASE_TOPIC}",
+            description = "The base topic for Zigbee2MQTT to enable silent updates for off lights. " +
+                          "If provided, Home Assistant will route off-state updates via MQTT. Example: zigbee2mqtt")
+    String z2mBaseTopic;
+
     private HueApi api;
     private StateScheduler stateScheduler;
     private final ManualOverrideTracker manualOverrideTracker;
@@ -398,7 +405,7 @@ private void setupHassApi() {
         HassAreaRegistry areaRegistry = new HassAreaRegistryImpl(
                 new HassWebSocketClientImpl(websocketOrigin, accessToken, httpClient, 5));
         HassAvailabilityListener availabilityListener = new HassAvailabilityListener(this::clearCachesAndReSyncScenes);
-        api = new HassApiImpl(apiHost, new HttpResourceProviderImpl(httpClient, maxConcurrentRequests), areaRegistry, availabilityListener, rateLimiter);
+        api = new HassApiImpl(apiHost, new HttpResourceProviderImpl(httpClient, maxConcurrentRequests), areaRegistry, availabilityListener, rateLimiter, this.z2mBaseTopic);
         lightEventListener = createLightEventListener();
         sceneEventListener = new SceneEventListenerImpl(api, Ticker.systemTicker(),
                 sceneActivationIgnoreWindowInSeconds,

src/main/java/at/sv/hue/api/hass/HassApiImpl.java

@@ -55,6 +55,7 @@ public class HassApiImpl implements HueApi {
     private final HassAvailabilityListener availabilityListener;
     private final ObjectMapper mapper;
     private final String baseUrl;
+    private final String z2mBaseTopic;
 
     private final Object lightMapLock = new Object();
     private Map<String, State> availableStates;
@@ -63,12 +64,13 @@ public class HassApiImpl implements HueApi {
     private boolean nameToStatesMapInvalidated;
 
     public HassApiImpl(String origin, HttpResourceProvider httpResourceProvider, HassAreaRegistry hassAreaRegistry,
-                       HassAvailabilityListener availabilityListener, RateLimiter rateLimiter) {
+                       HassAvailabilityListener availabilityListener, RateLimiter rateLimiter, String z2mBaseTopic) {
         baseUrl = origin + "/api";
         this.httpResourceProvider = httpResourceProvider;
         this.hassAreaRegistry = hassAreaRegistry;
         this.availabilityListener = availabilityListener;
         this.rateLimiter = rateLimiter;
+        this.z2mBaseTopic = z2mBaseTopic;
         mapper = new ObjectMapper();
         mapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
         mapper.setDefaultPropertyInclusion(JsonInclude.Include.NON_NULL);
@@ -167,11 +169,61 @@ public void allowFastSceneUpdate(String groupId) {
     private void putStateInternal(PutCall putCall) {
         String id = putCall.getId();
         assertSupportedStateType(id);
+
+        // Determine if this is a silent attribute update (light is off, and we aren't explicitly turning it on)
+        boolean isOffUpdate = (putCall.getOn() == null && isLightOff(id)) || Boolean.FALSE.equals(putCall.getOn());
+        boolean hasAttributesToUpdate = putCall.getBri() != null || putCall.getCt() != null || (putCall.getX() != null && putCall.getY() != null);
+
+        if (isOffUpdate && hasAttributesToUpdate && this.z2mBaseTopic != null) {
+            State state = getAndAssertLightExists(id);
+            String friendlyName = state.getAttributes().getFriendly_name();
+            
+            if (friendlyName != null) {
+                publishZ2mMqttUpdate(putCall, friendlyName);
+                
+                // If on is null, we only wanted a silent update. We can safely return.
+                if (putCall.getOn() == null) {
+                    return; 
+                }
+                // If putCall.getOn() == false, we fall through to let HA run the actual turn_off service
+            }
+        }
+
         ChangeState changeState = getChangeState(putCall);
         changeState.setEntity_id(id);
         httpResourceProvider.postResource(getUpdateUrl(putCall), getBody(changeState));
     }
 
+    private void publishZ2mMqttUpdate(PutCall putCall, String friendlyName) {
+        List<String> payloadParts = new ArrayList<>();
+        
+        // Hardcode the null state to bypass JSON serializer dropping it
+        payloadParts.add("\"state\":null");
+        
+        if (putCall.getBri() != null) {
+            payloadParts.add("\"brightness\":" + hueToHassBrightness(putCall.getBri()));
+        }
+        if (putCall.getCt() != null) {
+            payloadParts.add("\"color_temp\":" + miredsToKelvin(putCall.getCt()));
+        }
+        if (putCall.getX() != null && putCall.getY() != null) {
+            Double[] xy = getXyColor(putCall);
+            payloadParts.add("\"color\":{\"x\":" + xy[0] + ",\"y\":" + xy[1] + "}");
+        }
+        if (putCall.getTransitionTime() != null) {
+            payloadParts.add("\"transition\":" + convertToSeconds(putCall.getTransitionTime()));
+        }
+
+        // Combine the parts into a raw JSON string
+        String rawZ2mPayload = "{" + String.join(",", payloadParts) + "}";
+
+        MqttPublish publish = new MqttPublish();
+        publish.setTopic(this.z2mBaseTopic + "/" + friendlyName + "/set");
+        publish.setPayload(rawZ2mPayload);
+
+        httpResourceProvider.postResource(createUrl("/services/mqtt/publish"), getBody(publish));
+    }
+
     private ChangeState getChangeState(PutCall putCall) {
         ChangeState changeState = new ChangeState();
         changeState.setBrightness(hueToHassBrightness(putCall.getBri()));
@@ -641,4 +693,10 @@ private static final class CreateScene {
         String scene_id;
         Map<String, ChangeState> entities;
     }
+
+    @Data
+    private static final class MqttPublish {
+        String topic;
+        String payload;
+    }
 }

src/test/java/at/sv/hue/api/hass/HassApiTest.java

@@ -21,6 +21,7 @@
 import org.intellij.lang.annotations.Language;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
 import org.mockito.Mockito;
 
 import java.net.MalformedURLException;
@@ -31,7 +32,9 @@
 import java.util.List;
 
 import static org.assertj.core.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
@@ -55,7 +58,7 @@ private void setupApi(String origin) {
         HassAvailabilityListener availabilityListener = new HassAvailabilityListener(() -> {
         });
         api = new HassApiImpl(origin, http, areaRegistry, availabilityListener, permits -> {
-        });
+        }, null);
         baseUrl = origin + "/api";
     }
 
@@ -2770,6 +2773,50 @@ void putState_turnOn_fan_usesCorrectService() {
                 "{\"entity_id\":\"fan.test_fan\"}");
     }
 
+    @Test
+    void testZ2mMqttPublish_whenLightIsOff_andAttributesChanged() {
+        // 1. Re-initialize the API for this specific test to include the "zigbee2mqtt" topic.
+        // We reuse 'http' and 'areaRegistry' mocks that are automatically created in @BeforeEach.
+        HassAvailabilityListener availabilityListener = new HassAvailabilityListener(() -> {});
+        api = new HassApiImpl("http://localhost:8123", http, areaRegistry, availabilityListener, permits -> {}, "zigbee2mqtt");
+        
+        // 2. Use the existing test helper method to mock the state of the light as "off"
+        setGetResponse("/states", """
+            [
+              {
+                "entity_id": "light.my_z2m_bulb",
+                "state": "off",
+                "attributes": {
+                  "friendly_name": "My Bulb",
+                  "supported_features": 44
+                }
+              }
+            ]
+            """);
+
+        // 3. Create a PutCall that updates brightness/color but DOES NOT turn the light on (on=null)
+        PutCall silentUpdate = PutCall.builder()
+                .id("light.my_z2m_bulb")
+                .bri(150)
+                .ct(300)
+                .build();
+
+        // 4. Trigger the putState call
+        api.putState(silentUpdate);
+
+        // 5. Verify the correct MQTT publish payload was sent (uses getUrl() to match the URL object)
+        org.mockito.ArgumentCaptor<String> bodyCaptor = org.mockito.ArgumentCaptor.forClass(String.class);
+        verify(http).postResource(eq(getUrl("/services/mqtt/publish")), bodyCaptor.capture());
+
+        // 6. Assert the JSON payload matches the required Z2M structure
+        String payload = bodyCaptor.getValue();
+        assertThat(payload).contains("\"topic\":\"zigbee2mqtt/My Bulb/set\"");
+        
+        // Add extra slashes to account for the escaped nested JSON string
+        assertThat(payload).contains("\\\"state\\\":null");
+        assertThat(payload).contains("\\\"brightness\\\":");
+    }
+
     @Test
     void unsupportedType_exception() {
         assertThatThrownBy(() -> getLightState("sensor.sun_next_setting")).isInstanceOf(UnsupportedStateException.class);