Migration of Things between old and new bridge API versions

AndrewFG · February 11, 2023, 3:05pm

I am adding support for the new Hue CLIP 2 API v2 to the existing binding, and I need some ideas from developers about migrating existing user’s Things to the new API.

In the old API v1 there are fourteen different types of Thing (seven varieties of light, plus seven varieties of sensor). Whereas in the new CLIP 2 API v2 there is a single Thing type (a ‘device’) which dynamically has different Channels according to its particular capabilities.

I am wondering if there is some way that, if the user has existing Thing’s defined, then (for example) the binding discovery process can parse the list of existing API v1 things, and create respective matching, but new, API v2 things in the Inbox, taking over as many as possible of the attributes of the old existing Things. At minimum it would be great to take over the existing Thing labels, locations, and maybe some properties. (note: insofar as a match exists).

Also, I am wondering if there is some similar way of migrating existing Items from being connected to the old API Thing Channels to the respective matching new Thing Channels. (note: insofar as a match exists).

AndrewFG · February 15, 2023, 6:16pm

I figured out a way to do it, using the ThingRegistry. If anyone is interested in the details, please let me know.

ssalonen · February 15, 2023, 9:14pm

I am similar approach for modbus 4.0 version would be most useful

AndrewFG · February 15, 2023, 9:41pm

Following are two code links…

Discovery code that searches for existing legacy things, and if found, adds information from the legacy thing to the newly discovered thing, in form of a property.
Thing handler code that when the newly discovered thing is instantiated, reads the property from the legacy thing, and applies it to the new thing itself.

github.com

andrewfg/openhab-addons/blob/e245cf79509bb0510c2d6365712d6084d30e1162/bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/discovery/Clip2ThingDiscoveryService.java#L78


      
          @Override
          public void deactivate() {
              super.deactivate();
              Clip2BridgeHandler bridgeHandler = this.bridgeHandler;
              if (Objects.nonNull(bridgeHandler)) {
                  bridgeHandler.registerDiscoveryService(null);
                  removeOlderResults(new Date().getTime(), bridgeHandler.getThing().getBridgeUID());
              }
          }
          
          /**
           * If the bridge is online, then query it to get all resource types within it, which are allowed to be instantiated
           * as OH things, and announce those respective things by calling the core 'thingDiscovered()' method.
           */
          private synchronized void discoverDevices() {
              Clip2BridgeHandler bridgeHandler = this.bridgeHandler;
              if (Objects.nonNull(bridgeHandler) && bridgeHandler.getThing().getStatus() == ThingStatus.ONLINE) {
                  try {
                      ThingUID bridgeUID = bridgeHandler.getThing().getUID();
                      for (Resource resource : bridgeHandler
                              .getResources(new ResourceReference().setType(ResourceType.DEVICE)).getResources()) {

github.com

andrewfg/openhab-addons/blob/e245cf79509bb0510c2d6365712d6084d30e1162/bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/handler/DeviceThingHandler.java#L540


      
              logger.debug("updateState() channelID:{}, state:{}, fullUpdate:{}", channelID, state, fullUpdate);
              boolean isDefined = state != UnDefType.UNDEF;
              if (fullUpdate || isDefined) {
                  updateState(channelID, state);
              }
              if (fullUpdate && isDefined) {
                  supportedChannelIds.add(channelID);
              }
          }
          
          /**
           * Check if the discovery process found a thing location property, and if so apply it to the thing itself.
           */
          private void updateThingLocation() {
              Map<String, String> properties = thing.getProperties();
              String location = properties.get(HueBindingConstants.PROPERTY_LOCATION);
              if (Objects.nonNull(location) && !location.isBlank()) {
                  Map<String, String> newProperties = new HashMap<>(properties);
                  newProperties.remove(HueBindingConstants.PROPERTY_LOCATION);
                  updateThing(editThing().withLocation(location).withProperties(newProperties).build());
              }

AndrewFG · February 17, 2023, 11:01pm

@ssalonen in a second iteration, I added code to search the ItemChannelLinkRegistry to find items that are linked to the legacy thing’s channels, and replicate those links between the respective items and the new thing’s equivalent channels.

github.com

openhab/openhab-addons/blob/b2627c7c1f8dae5572dc801b316399d166d12ed9/bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/discovery/Clip2ThingDiscoveryService.java#L82


      
              if (Objects.nonNull(bridgeHandler)) {
                  bridgeHandler.registerDiscoveryService(null);
                  removeOlderResults(new Date().getTime(), bridgeHandler.getThing().getBridgeUID());
              }
          }
          
          
/**
           * If the bridge is online, then query it to get all resource types within it, which are allowed to be instantiated
           * as OH things, and announce those respective things by calling the core 'thingDiscovered()' method.
           */
          private synchronized void discoverDevices() {
              Clip2BridgeHandler bridgeHandler = this.bridgeHandler;
              if (Objects.nonNull(bridgeHandler) && bridgeHandler.getThing().getStatus() == ThingStatus.ONLINE) {
                  try {
                      ThingUID bridgeUID = bridgeHandler.getThing().getUID();
                      for (Resource resource : bridgeHandler
                              .getResources(new ResourceReference().setType(ResourceType.DEVICE)).getResources()) {
          
          
                MetaData metaData = resource.getMetaData();
                          if (Objects.nonNull(metaData)) {
                              if (metaData.getArchetype() == Archetype.BRIDGE_V2) {

github.com

openhab/openhab-addons/blob/24345fc217a68c4be1a2204bb4e335a063591167/bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/handler/DeviceThingHandler.java#L602


      
          if (Objects.nonNull(legacyThingUID)) {
              Thing legacyThing = thingRegistry.get(new ThingUID(legacyThingUID));
              if (Objects.nonNull(legacyThing)) {
                  ThingBuilder editBuilder = editThing();
          
          
        String location = legacyThing.getLocation();
                  if (Objects.nonNull(location) && !location.isBlank()) {
                      editBuilder = editBuilder.withLocation(location);
                  }
          
          
        // save list of legacyLinkedChannelUIDs for use after channel list is initialised
                  synchronized (legacyLinkedChannelUIDs) {
                      legacyLinkedChannelUIDs.clear();
                      legacyLinkedChannelUIDs.addAll(legacyThing.getChannels().stream().map(Channel::getUID)
                              .filter(legacyChannelUID -> HueBindingConstants.EQUIVALENT_CHANNEL_ID_MAP.containsKey(
                                      legacyChannelUID.getId()) && itemChannelLinkRegistry.isLinked(legacyChannelUID))
                              .toList());
                  }
          
          
        Map<String, String> newProperties = new HashMap<>(properties);
                  newProperties.remove(HueBindingConstants.PROPERTY_LEGACY_THING_UID);

github.com

openhab/openhab-addons/blob/24345fc217a68c4be1a2204bb4e335a063591167/bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/handler/DeviceThingHandler.java#L301


      
                      }
                  }
              }
          }
          
          
/**
           * If this v2 thing has a matching v1 legacy thing in the system, then for each channel in the v1 thing that
           * corresponds to an equivalent channel in this v2 thing, and for all items that are linked to the v1 channel,
           * create a new channel/item link between that item and the respective v2 channel in this thing.
           */
          private void updateChannelItemLinksFromLegacy() {
              if (!disposing) {
                  synchronized (legacyLinkedChannelUIDs) {
                      legacyLinkedChannelUIDs.forEach(legacyLinkedChannelUID -> {
                          String targetChannelId = HueBindingConstants.EQUIVALENT_CHANNEL_ID_MAP
                                  .get(legacyLinkedChannelUID.getId());
                          if (Objects.nonNull(targetChannelId)) {
                              Channel targetChannel = thing.getChannel(targetChannelId);
                              if (Objects.nonNull(targetChannel)) {
                                  ChannelUID targetChannelUID = targetChannel.getUID();
                                  itemChannelLinkRegistry.getLinkedItems(legacyLinkedChannelUID).forEach(linkedItem -> {