2 * Copyright (c) 2010-2024 Contributors to the openHAB project
4 * See the NOTICE file(s) distributed with this work for additional
7 * This program and the accompanying materials are made available under the
8 * terms of the Eclipse Public License 2.0 which is available at
9 * http://www.eclipse.org/legal/epl-2.0
11 * SPDX-License-Identifier: EPL-2.0
13 package org.openhab.io.homekit.internal;
15 import java.lang.reflect.InvocationTargetException;
16 import java.time.Clock;
17 import java.time.Duration;
18 import java.util.ArrayList;
19 import java.util.Collection;
20 import java.util.HashMap;
21 import java.util.HashSet;
22 import java.util.List;
24 import java.util.Map.Entry;
25 import java.util.Optional;
27 import java.util.concurrent.ExecutionException;
28 import java.util.concurrent.ScheduledExecutorService;
29 import java.util.stream.Collectors;
31 import org.eclipse.jdt.annotation.NonNullByDefault;
32 import org.eclipse.jdt.annotation.Nullable;
33 import org.openhab.core.common.ThreadPoolManager;
34 import org.openhab.core.common.registry.RegistryChangeListener;
35 import org.openhab.core.items.GroupItem;
36 import org.openhab.core.items.Item;
37 import org.openhab.core.items.ItemNotFoundException;
38 import org.openhab.core.items.ItemRegistry;
39 import org.openhab.core.items.ItemRegistryChangeListener;
40 import org.openhab.core.items.Metadata;
41 import org.openhab.core.items.MetadataKey;
42 import org.openhab.core.items.MetadataRegistry;
43 import org.openhab.core.storage.Storage;
44 import org.openhab.io.homekit.internal.accessories.AbstractHomekitAccessoryImpl;
45 import org.openhab.io.homekit.internal.accessories.DummyHomekitAccessory;
46 import org.openhab.io.homekit.internal.accessories.HomekitAccessoryFactory;
47 import org.slf4j.Logger;
48 import org.slf4j.LoggerFactory;
50 import io.github.hapjava.accessories.HomekitAccessory;
51 import io.github.hapjava.characteristics.impl.common.NameCharacteristic;
52 import io.github.hapjava.server.impl.HomekitRoot;
55 * Listens for changes to the item and metadata registry. When changes are detected, check
56 * for HomeKit tags and, if present, add the items to the HomekitAccessoryRegistry.
58 * @author Andy Lintner - Initial contribution
61 public class HomekitChangeListener implements ItemRegistryChangeListener {
62 private final Logger logger = LoggerFactory.getLogger(HomekitChangeListener.class);
63 private static final String REVISION_CONFIG = "revision";
64 private static final String ACCESSORY_COUNT = "accessory_count";
65 private static final String KNOWN_ACCESSORIES = "known_accessories";
66 private final ItemRegistry itemRegistry;
67 private final HomekitAccessoryRegistry accessoryRegistry = new HomekitAccessoryRegistry();
68 private final MetadataRegistry metadataRegistry;
69 private final Storage<Object> storage;
70 private final RegistryChangeListener<Metadata> metadataChangeListener;
71 private HomekitAccessoryUpdater updater = new HomekitAccessoryUpdater();
72 private HomekitSettings settings;
73 private int lastAccessoryCount;
74 private Map<String, String> knownAccessories = new HashMap<>();
76 private List<String> priorDummies = new ArrayList<>();
78 private final Set<String> pendingUpdates = new HashSet<>();
80 private final ScheduledExecutorService scheduler = ThreadPoolManager
81 .getScheduledPool(ThreadPoolManager.THREAD_POOL_NAME_COMMON);
84 * Rather than reacting to item added/removed/modified changes directly, we mark them as dirty (and the groups to
87 * We wait for a second to pass until no more items are changed. This allows us to add a group of items all at once,
88 * rather than for each update at a time, preventing us from showing an error message with each addition until the
91 private final Debouncer applyUpdatesDebouncer;
93 HomekitChangeListener(ItemRegistry itemRegistry, HomekitSettings settings, MetadataRegistry metadataRegistry,
94 Storage<Object> storage, int instance) {
95 this.itemRegistry = itemRegistry;
96 this.settings = settings;
97 this.metadataRegistry = metadataRegistry;
98 this.storage = storage;
99 this.instance = instance;
100 this.applyUpdatesDebouncer = new Debouncer("update-homekit-devices-" + instance, scheduler,
101 Duration.ofMillis(1000), Clock.systemUTC(), this::applyUpdates);
102 metadataChangeListener = new RegistryChangeListener<>() {
104 public void added(final Metadata metadata) {
105 final MetadataKey uid = metadata.getUID();
106 if (HomekitAccessoryFactory.METADATA_KEY.equalsIgnoreCase(uid.getNamespace())) {
108 markDirty(itemRegistry.getItem(uid.getItemName()));
109 } catch (ItemNotFoundException e) {
110 logger.trace("Could not find item for metadata {}", metadata);
116 public void removed(final Metadata metadata) {
117 final MetadataKey uid = metadata.getUID();
118 if (HomekitAccessoryFactory.METADATA_KEY.equalsIgnoreCase(uid.getNamespace())) {
120 markDirty(itemRegistry.getItem(uid.getItemName()));
121 } catch (ItemNotFoundException e) {
122 logger.trace("Could not find item for metadata {}", metadata);
128 public void updated(final Metadata oldMetadata, final Metadata newMetadata) {
129 final MetadataKey oldUid = oldMetadata.getUID();
130 final MetadataKey newUid = newMetadata.getUID();
131 if (HomekitAccessoryFactory.METADATA_KEY.equalsIgnoreCase(oldUid.getNamespace())
132 || HomekitAccessoryFactory.METADATA_KEY.equalsIgnoreCase(newUid.getNamespace())) {
134 // the item name is same in old and new metadata, so we can take any.
135 markDirty(itemRegistry.getItem(oldUid.getItemName()));
136 } catch (ItemNotFoundException e) {
137 logger.debug("Could not find item for metadata {}", oldMetadata);
142 itemRegistry.addRegistryChangeListener(this);
143 metadataRegistry.addRegistryChangeListener(metadataChangeListener);
144 initialiseRevision();
145 boolean changed = false;
146 for (var i : itemRegistry.getItems()) {
147 String oldValue = knownAccessories.get(i.getName());
148 createRootAccessories(i);
149 if (accessoryChanged(i.getName(), oldValue)) {
150 logger.debug("Accessory {} changed:\n{}\n{}", i.getName(), oldValue, knownAccessories.get(i.getName()));
154 // order of this conditional is important - checkMissingAccessories has side effects that need to always happen
155 if (checkMissingAccessories() || changed) {
156 makeNewConfigurationRevision();
158 logger.info("Created {} HomeKit items in instance {} (no change from prior configuration).",
159 accessoryRegistry.getAllAccessories().size(), instance);
160 if (settings.useDummyAccessories) {
161 checkForDummyAccessories();
166 private void initialiseRevision() {
169 String revisionString = (String) storage.get(REVISION_CONFIG);
170 if (revisionString == null) {
171 throw new NumberFormatException();
173 revision = Integer.parseInt(revisionString);
174 } catch (NumberFormatException e) {
176 accessoryRegistry.setConfigurationRevision(revision);
178 lastAccessoryCount = 0;
179 var localKnownAccessories = (Map<String, String>) storage.get(KNOWN_ACCESSORIES);
180 if (localKnownAccessories == null) {
181 knownAccessories = new HashMap<>();
184 String accessoryCountString = (String) storage.get(ACCESSORY_COUNT);
185 if (accessoryCountString == null) {
186 throw new NumberFormatException();
188 lastAccessoryCount = Integer.parseInt(accessoryCountString);
189 } catch (NumberFormatException e) {
192 knownAccessories = localKnownAccessories;
193 lastAccessoryCount = knownAccessories.size();
197 private boolean hasHomeKitMetadata(Item item) {
198 return metadataRegistry.get(new MetadataKey(HomekitAccessoryFactory.METADATA_KEY, item.getUID())) != null;
202 public synchronized void added(Item item) {
203 if (hasHomeKitMetadata(item)) {
209 public void allItemsChanged(Collection<String> oldItemNames) {
214 * Mark an item as dirty, plus any accessory groups to which it pertains, so that after a debounce period the
215 * accessory update can be applied.
217 * @param item The item that has been changed or removed.
219 private synchronized void markDirty(Item item) {
220 logger.trace("Mark dirty item {}", item.getName());
221 pendingUpdates.add(item.getName());
223 * If findMyAccessoryGroups fails because the accessory group has already been deleted, then we can count on a
224 * later update telling us that the accessory group was removed.
226 for (Item accessoryGroup : HomekitAccessoryFactory.getAccessoryGroups(item, itemRegistry, metadataRegistry)) {
227 pendingUpdates.add(accessoryGroup.getName());
231 * if metadata of a group item was changed, mark all group member as dirty.
233 if (item instanceof GroupItem itemAsGroupItem) {
234 itemAsGroupItem.getMembers().forEach(groupMember -> pendingUpdates.add(groupMember.getName()));
236 applyUpdatesDebouncer.call();
240 public synchronized void removed(Item item) {
241 if (hasHomeKitMetadata(item)) {
246 private Optional<Item> getItemOptional(String name) {
248 return Optional.of(itemRegistry.getItem(name));
249 } catch (ItemNotFoundException e) {
250 return Optional.empty();
254 public void makeNewConfigurationRevision() {
255 final int newRevision = accessoryRegistry.makeNewConfigurationRevision();
256 lastAccessoryCount = accessoryRegistry.getAllAccessories().size();
257 logger.info("Created {} HomeKit items in instance {}.", accessoryRegistry.getAllAccessories().size(), instance);
258 logger.trace("Making new configuration revision {}", newRevision);
259 storage.put(REVISION_CONFIG, "" + newRevision);
260 storage.put(KNOWN_ACCESSORIES, knownAccessories);
263 public synchronized void pruneDummyAccessories() {
264 boolean removed = false;
265 for (HomekitAccessory accessory : accessoryRegistry.getAllAccessories().values()
266 .toArray(new HomekitAccessory[0])) {
267 if (accessory instanceof DummyHomekitAccessory) {
269 String name = accessory.getName().get();
270 logger.info("Pruning dummy accessory {}.", name);
271 knownAccessories.remove(name);
272 accessoryRegistry.remove(name);
274 } catch (ExecutionException | InterruptedException e) {
275 // will never happen; it's a always completed future
280 makeNewConfigurationRevision();
284 private synchronized void applyUpdates() {
285 logger.trace("Apply updates");
287 HomekitRoot bridge = accessoryRegistry.getBridge();
288 if (bridge != null) {
289 bridge.batchUpdate();
293 boolean changed = false;
294 for (final String name : pendingUpdates) {
295 String oldValue = knownAccessories.get(name);
296 accessoryRegistry.remove(name);
297 logger.trace(" Add items {}", name);
298 getItemOptional(name).ifPresent(this::createRootAccessories);
299 if (accessoryChanged(name, oldValue)) {
303 pendingUpdates.clear();
304 if (checkMissingAccessories() || changed) {
305 makeNewConfigurationRevision();
307 checkForDummyAccessories();
309 if (bridge != null) {
310 bridge.completeUpdateBatch();
315 private boolean accessoryChanged(String name, @Nullable String oldValue) {
316 String newValue = knownAccessories.get(name);
317 if (oldValue == null && newValue == null) {
320 return oldValue == null && newValue != null || oldValue != null && newValue == null
321 || !oldValue.equals(newValue);
325 public void updated(Item oldElement, Item element) {
326 markDirty(oldElement);
330 public int getLastAccessoryCount() {
331 return lastAccessoryCount;
334 public synchronized void clearAccessories() {
335 accessoryRegistry.clear();
338 public synchronized void setBridge(HomekitRoot bridge) {
339 accessoryRegistry.setBridge(bridge);
342 public void setUpdater(HomekitAccessoryUpdater updater) {
343 this.updater = updater;
346 public void updateSettings(HomekitSettings settings) {
347 boolean wasUsingDummyAccessories = this.settings.useDummyAccessories;
348 this.settings = settings;
349 // If they turned off dummy accessories, immediately prune them
350 if (wasUsingDummyAccessories && !settings.useDummyAccessories) {
351 pruneDummyAccessories();
355 public synchronized void stop() {
356 this.itemRegistry.removeRegistryChangeListener(this);
357 this.metadataRegistry.removeRegistryChangeListener(metadataChangeListener);
358 applyUpdatesDebouncer.stop();
359 accessoryRegistry.unsetBridge();
362 public Map<String, HomekitAccessory> getAccessories() {
363 return this.accessoryRegistry.getAllAccessories();
366 public int getConfigurationRevision() {
367 return this.accessoryRegistry.getConfigurationRevision();
371 * select primary accessory type from list of types.
373 * - if accessory has only one type, it is the primary type
374 * - if accessory has no primary type defined per configuration, then the first type on the list is the primary type
375 * - if accessory has primary type defined per configuration and this type is on the list of types, then it is the
377 * - if accessory has primary type defined per configuration and this type is NOT on the list of types, then the
378 * first type on the list is the primary type
380 * @param item openhab item
381 * @param accessoryTypes list of accessory type attached to the item
382 * @return primary accessory type
384 private HomekitAccessoryType getPrimaryAccessoryType(Item item,
385 List<Entry<HomekitAccessoryType, HomekitCharacteristicType>> accessoryTypes,
386 @Nullable Map<String, Object> configuration) {
387 if (accessoryTypes.size() > 1 && configuration != null) {
388 final @Nullable Object value = configuration.get(HomekitTaggedItem.PRIMARY_SERVICE);
389 if (value instanceof String valueAsString) {
390 return accessoryTypes.stream().filter(aType -> valueAsString.equalsIgnoreCase(aType.getKey().getTag()))
391 .findAny().orElse(accessoryTypes.get(0)).getKey();
394 // no primary accessory found or there is only one type, so return the first type from the list
395 return accessoryTypes.get(0).getKey();
399 * creates one or more HomeKit items for given openhab item.
400 * one OpenHAB item can be linked to several HomeKit accessories.
401 * OpenHAB item is a good candidate for a HomeKit accessory
403 * - it has HomeKit accessory types defined using HomeKit accessory metadata
404 * - AND is not part of a group with HomeKit metadata
406 * Switch light "Light" {homekit="Lighting"}
407 * Group gLight "Light Group" {homekit="Lighting"}
410 * - it has HomeKit accessory types defined using HomeKit accessory metadata
411 * - AND is part of groups with HomeKit metadata, but all groups have baseItem
413 * Group:Switch:OR(ON,OFF) gLight "Light Group " {homekit="Lighting"}
414 * Switch light "Light" (gLight) {homekit="Lighting.OnState"}
417 * In contrast, items which are part of groups without BaseItem are additional HomeKit characteristics of the
418 * accessory defined by that group and don't need to be created as accessory here.
420 * Group gLight "Light Group " {homekit="Lighting"}
421 * Switch light "Light" (gLight) {homekit="Lighting.OnState"}
422 * is not the root accessory but only a characteristic "OnState"
425 * // Single line HomeKit Accessory
426 * Switch light "Light" {homekit="Lighting"}
428 * // One HomeKit accessory defined using group
429 * Group gLight "Light Group" {homekit="Lighting"}
430 * Switch light "Light" (gLight) {homekit="Lighting.OnState"}
432 * // 2 HomeKit accessories: one is switch attached to group, another one a single switch
433 * Group:Switch:OR(ON,OFF) gLight "Light Group " {homekit="Lighting"}
434 * Switch light "Light" (gLight) {homekit="Lighting.OnState"}
436 * @param item openHAB item
438 private void createRootAccessories(Item item) {
439 final List<Entry<HomekitAccessoryType, HomekitCharacteristicType>> accessoryTypes = HomekitAccessoryFactory
440 .getAccessoryTypes(item, metadataRegistry);
441 if (accessoryTypes.isEmpty()) {
445 final List<GroupItem> groups = HomekitAccessoryFactory.getAccessoryGroups(item, itemRegistry, metadataRegistry);
446 // Don't create accessories that are sub-accessories of other accessories
447 if (groups.stream().anyMatch(g -> !HomekitAccessoryFactory.getAccessoryTypes(g, metadataRegistry).isEmpty())) {
451 final @Nullable Map<String, Object> itemConfiguration = HomekitAccessoryFactory.getItemConfiguration(item,
453 if (!itemIsForThisBridge(item, itemConfiguration)) {
457 final HomekitAccessoryType primaryAccessoryType = getPrimaryAccessoryType(item, accessoryTypes,
459 logger.trace("Item {} is a HomeKit accessory of types {}. Primary type is {}", item.getName(), accessoryTypes,
460 primaryAccessoryType);
461 final HomekitOHItemProxy itemProxy = new HomekitOHItemProxy(item);
462 final HomekitTaggedItem taggedItem = new HomekitTaggedItem(itemProxy, primaryAccessoryType, itemConfiguration);
464 final AbstractHomekitAccessoryImpl accessory = HomekitAccessoryFactory.create(taggedItem, metadataRegistry,
466 if (accessory.isLinkedServiceOnly()) {
467 logger.warn("Item '{}' is a '{}' which must be nested another another accessory.", taggedItem.getName(),
468 primaryAccessoryType);
472 accessoryTypes.stream().filter(aType -> !primaryAccessoryType.equals(aType.getKey()))
473 .forEach(additionalAccessoryType -> {
474 final HomekitTaggedItem additionalTaggedItem = new HomekitTaggedItem(itemProxy,
475 additionalAccessoryType.getKey(), itemConfiguration);
477 final AbstractHomekitAccessoryImpl additionalAccessory = HomekitAccessoryFactory
478 .create(additionalTaggedItem, metadataRegistry, updater, settings);
479 // Secondary accessories that don't explicitly specify a name will implicitly
480 // get a name characteristic based on the item's name
481 if (!additionalAccessory.getCharacteristic(HomekitCharacteristicType.NAME).isPresent()) {
483 additionalAccessory.addCharacteristic(
484 new NameCharacteristic(() -> additionalAccessory.getName()));
485 } catch (NoSuchMethodException | IllegalAccessException | InvocationTargetException e) {
486 // This should never happen; all services should support NameCharacteristic as an
487 // optional Characteristic.
488 // If HAP-Java defined a service that doesn't support
489 // addOptionalCharacteristic(NameCharacteristic), then it's a bug there, and we're
490 // just going to ignore the exception here.
493 accessory.getServices().add(additionalAccessory.getPrimaryService());
494 } catch (HomekitException e) {
495 logger.warn("Cannot create additional accessory {}", additionalTaggedItem);
498 knownAccessories.put(taggedItem.getName(), accessory.toJson());
499 accessoryRegistry.addRootAccessory(taggedItem.getName(), accessory);
500 } catch (HomekitException e) {
501 logger.warn("Cannot create accessory {}", taggedItem);
505 private boolean itemIsForThisBridge(Item item, @Nullable Map<String, Object> configuration) {
506 // non-tagged accessories belong to the first instance
507 if (configuration == null) {
508 return (instance == 1);
511 final @Nullable Object value = configuration.get(HomekitTaggedItem.INSTANCE);
513 return (instance == 1);
515 if (value instanceof Number valueAsNumber) {
516 return (instance == valueAsNumber.intValue());
518 logger.warn("Unrecognized instance tag {} ({}) for item {}; assigning to default instance.", value,
519 value.getClass(), item.getName());
520 return (instance == 1);
524 * Check for any missing accessories.
526 * If there are, return true so we know to increment the config version. UNLESS
527 * we're configured to use dummy accessories, in which case backfill it with a dummy.
529 * @return if we need to increment the configuration version
531 private boolean checkMissingAccessories() {
532 List<String> toRemove = new ArrayList<>();
533 for (Map.Entry<String, String> accessory : knownAccessories.entrySet()) {
534 if (!accessoryRegistry.getAllAccessories().containsKey(accessory.getKey())) {
535 if (settings.useDummyAccessories) {
536 logger.debug("Creating dummy accessory for missing item {}.", accessory.getKey());
537 accessoryRegistry.addRootAccessory(accessory.getKey(),
538 new DummyHomekitAccessory(accessory.getKey(), accessory.getValue()));
540 toRemove.add(accessory.getKey());
545 toRemove.forEach(k -> knownAccessories.remove(k));
546 return !toRemove.isEmpty();
549 private void checkForDummyAccessories() {
550 List<String> currentDummies = accessoryRegistry.getAllAccessories().values().stream()
551 .filter(a -> a instanceof DummyHomekitAccessory).map(a -> {
553 return a.getSerialNumber().get();
554 } catch (InterruptedException | ExecutionException e) {
557 }).collect(Collectors.toList());
559 List<String> resolvedDummies = new ArrayList(priorDummies);
560 resolvedDummies.removeAll(currentDummies);
561 List<String> newDummies = new ArrayList(currentDummies);
562 newDummies.removeAll(priorDummies);
564 if (resolvedDummies.size() <= 5) {
565 for (String item : resolvedDummies) {
566 logger.info("{} has been resolved to an actual accessory, and is no longer a dummy.", item);
568 } else if (currentDummies.isEmpty() && !resolvedDummies.isEmpty()) {
569 logger.info("All dummy accessories have been resolved to actual accessories.");
570 } else if (!resolvedDummies.isEmpty()) {
571 logger.info("{} dummy accessories have been resolved to actual accessories.", resolvedDummies.size());
574 if (newDummies.size() <= 5) {
575 for (String item : newDummies) {
577 "{} has been replaced with a dummy. See https://www.openhab.org/addons/integrations/homekit/#dummy-accessories for more information.",
580 } else if (!newDummies.isEmpty()) {
582 "{} accessories have been replaced with dummies. See https://www.openhab.org/addons/integrations/homekit/#dummy-accessories for more information.",
584 } else if (!currentDummies.isEmpty()) {
586 "{} accessories are still dummies. See https://www.openhab.org/addons/integrations/homekit/#dummy-accessories for more information.",
587 currentDummies.size());
589 priorDummies.clear();
590 priorDummies.addAll(currentDummies);