git.basschouten.com Git - openhab-addons.git/blob

   1 /**
   2  * Copyright (c) 2010-2021 Contributors to the openHAB project
   3  *
   4  * See the NOTICE file(s) distributed with this work for additional
   5  * information.
   6  *
   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
  10  *
  11  * SPDX-License-Identifier: EPL-2.0
  12  */
  13 package org.openhab.binding.insteon.internal;
  14
  15 import java.io.IOException;
  16 import java.util.ArrayList;
  17 import java.util.Collections;
  18 import java.util.Comparator;
  19 import java.util.HashMap;
  20 import java.util.HashSet;
  21 import java.util.Iterator;
  22 import java.util.List;
  23 import java.util.Map;
  24 import java.util.Map.Entry;
  25 import java.util.Set;
  26 import java.util.concurrent.ConcurrentHashMap;
  27 import java.util.concurrent.ScheduledExecutorService;
  28
  29 import javax.xml.parsers.ParserConfigurationException;
  30
  31 import org.eclipse.jdt.annotation.NonNullByDefault;
  32 import org.eclipse.jdt.annotation.Nullable;
  33 import org.openhab.binding.insteon.internal.config.InsteonChannelConfiguration;
  34 import org.openhab.binding.insteon.internal.config.InsteonNetworkConfiguration;
  35 import org.openhab.binding.insteon.internal.device.DeviceFeature;
  36 import org.openhab.binding.insteon.internal.device.DeviceFeatureListener;
  37 import org.openhab.binding.insteon.internal.device.DeviceType;
  38 import org.openhab.binding.insteon.internal.device.DeviceTypeLoader;
  39 import org.openhab.binding.insteon.internal.device.InsteonAddress;
  40 import org.openhab.binding.insteon.internal.device.InsteonDevice;
  41 import org.openhab.binding.insteon.internal.device.InsteonDevice.DeviceStatus;
  42 import org.openhab.binding.insteon.internal.device.RequestQueueManager;
  43 import org.openhab.binding.insteon.internal.driver.Driver;
  44 import org.openhab.binding.insteon.internal.driver.DriverListener;
  45 import org.openhab.binding.insteon.internal.driver.ModemDBEntry;
  46 import org.openhab.binding.insteon.internal.driver.Poller;
  47 import org.openhab.binding.insteon.internal.driver.Port;
  48 import org.openhab.binding.insteon.internal.handler.InsteonDeviceHandler;
  49 import org.openhab.binding.insteon.internal.handler.InsteonNetworkHandler;
  50 import org.openhab.binding.insteon.internal.message.FieldException;
  51 import org.openhab.binding.insteon.internal.message.Msg;
  52 import org.openhab.binding.insteon.internal.message.MsgListener;
  53 import org.openhab.binding.insteon.internal.utils.Utils;
  54 import org.openhab.core.io.transport.serial.SerialPortManager;
  55 import org.openhab.core.thing.ChannelUID;
  56 import org.openhab.core.types.Command;
  57 import org.openhab.core.types.State;
  58 import org.slf4j.Logger;
  59 import org.slf4j.LoggerFactory;
  60 import org.xml.sax.SAXException;
  61
  62 /**
  63  * A majority of the code in this file is from the openHAB 1 binding
  64  * org.openhab.binding.insteonplm.InsteonPLMActiveBinding. Including the comments below.
  65  *
  66  * -----------------------------------------------------------------------------------------------
  67  *
  68  * This class represents the actual implementation of the binding, and controls the high level flow
  69  * of messages to and from the InsteonModem.
  70  *
  71  * Writing this binding has been an odyssey through the quirks of the Insteon protocol
  72  * and Insteon devices. A substantial redesign was necessary at some point along the way.
  73  * Here are some of the hard learned lessons that should be considered by anyone who wants
  74  * to re-architect the binding:
  75  *
  76  * 1) The entries of the link database of the modem are not reliable. The category/subcategory entries in
  77  * particular have junk data. Forget about using the modem database to generate a list of devices.
  78  * The database should only be used to verify that a device has been linked.
  79  *
  80  * 2) Querying devices for their product information does not work either. First of all, battery operated devices
  81  * (and there are a lot of those) have their radio switched off, and may generally not respond to product
  82  * queries. Even main stream hardwired devices sold presently (like the 2477s switch and the 2477d dimmer)
  83  * don't even have a product ID. Although supposedly part of the Insteon protocol, we have yet to
  84  * encounter a device that would cough up a product id when queried, even among very recent devices. They
  85  * simply return zeros as product id. Lesson: forget about querying devices to generate a device list.
  86  *
  87  * 3) Polling is a thorny issue: too much traffic on the network, and messages will be dropped left and right,
  88  * and not just the poll related ones, but others as well. In particular sending back-to-back messages
  89  * seemed to result in the second message simply never getting sent, without flow control back pressure
  90  * (NACK) from the modem. For now the work-around is to space out the messages upon sending, and
  91  * in general poll as infrequently as acceptable.
  92  *
  93  * 4) Instantiating and tracking devices when reported by the modem (either from the database, or when
  94  * messages are received) leads to complicated state management because there is no guarantee at what
  95  * point (if at all) the binding configuration will be available. It gets even more difficult when
  96  * items are created, destroyed, and modified while the binding runs.
  97  *
  98  * For the above reasons, devices are only instantiated when they are referenced by binding information.
  99  * As nice as it would be to discover devices and their properties dynamically, we have abandoned that
 100  * path because it had led to a complicated and fragile system which due to the technical limitations
 101  * above was inherently squirrely.
 102  *
 103  *
 104  * @author Bernd Pfrommer - Initial contribution
 105  * @author Daniel Pfrommer - openHAB 1 insteonplm binding
 106  * @author Rob Nielsen - Port to openHAB 2 insteon binding
 107  */
 108 @NonNullByDefault
 109 public class InsteonBinding {
 110     private static final int DEAD_DEVICE_COUNT = 10;
 111
 112     private final Logger logger = LoggerFactory.getLogger(InsteonBinding.class);
 113
 114     private Driver driver;
 115     private Map<InsteonAddress, InsteonDevice> devices = new ConcurrentHashMap<>();
 116     private Map<String, InsteonChannelConfiguration> bindingConfigs = new ConcurrentHashMap<>();
 117     private PortListener portListener = new PortListener();
 118     private int devicePollIntervalMilliseconds = 300000;
 119     private int deadDeviceTimeout = -1;
 120     private int messagesReceived = 0;
 121     private boolean isActive = false; // state of binding
 122     private int x10HouseUnit = -1;
 123     private InsteonNetworkHandler handler;
 124
 125     public InsteonBinding(InsteonNetworkHandler handler, InsteonNetworkConfiguration config,
 126             SerialPortManager serialPortManager, ScheduledExecutorService scheduler) {
 127         this.handler = handler;
 128
 129         String port = config.getPort();
 130         logger.debug("port = '{}'", Utils.redactPassword(port));
 131
 132         driver = new Driver(port, portListener, serialPortManager, scheduler);
 133         driver.addMsgListener(portListener);
 134
 135         Integer devicePollIntervalSeconds = config.getDevicePollIntervalSeconds();
 136         if (devicePollIntervalSeconds != null) {
 137             devicePollIntervalMilliseconds = devicePollIntervalSeconds * 1000;
 138         }
 139         logger.debug("device poll interval set to {} seconds", devicePollIntervalMilliseconds / 1000);
 140
 141         String additionalDevices = config.getAdditionalDevices();
 142         if (additionalDevices != null) {
 143             try {
 144                 DeviceTypeLoader instance = DeviceTypeLoader.instance();
 145                 if (instance != null) {
 146                     instance.loadDeviceTypesXML(additionalDevices);
 147                     logger.debug("read additional device definitions from {}", additionalDevices);
 148                 } else {
 149                     logger.warn("device type loader instance is null");
 150                 }
 151             } catch (ParserConfigurationException | SAXException | IOException e) {
 152                 logger.warn("error reading additional devices from {}", additionalDevices, e);
 153             }
 154         }
 155
 156         String additionalFeatures = config.getAdditionalFeatures();
 157         if (additionalFeatures != null) {
 158             logger.debug("reading additional feature templates from {}", additionalFeatures);
 159             DeviceFeature.readFeatureTemplates(additionalFeatures);
 160         }
 161
 162         deadDeviceTimeout = devicePollIntervalMilliseconds * DEAD_DEVICE_COUNT;
 163         logger.debug("dead device timeout set to {} seconds", deadDeviceTimeout / 1000);
 164     }
 165
 166     public Driver getDriver() {
 167         return driver;
 168     }
 169
 170     public boolean startPolling() {
 171         logger.debug("starting to poll {}", driver.getPortName());
 172         driver.start();
 173         return driver.isRunning();
 174     }
 175
 176     public void setIsActive(boolean isActive) {
 177         this.isActive = isActive;
 178     }
 179
 180     public void sendCommand(String channelName, Command command) {
 181         if (!isActive) {
 182             logger.debug("not ready to handle commands yet, returning.");
 183             return;
 184         }
 185
 186         InsteonChannelConfiguration bindingConfig = bindingConfigs.get(channelName);
 187         if (bindingConfig == null) {
 188             logger.warn("unable to find binding config for channel {}", channelName);
 189             return;
 190         }
 191
 192         InsteonDevice dev = getDevice(bindingConfig.getAddress());
 193         if (dev == null) {
 194             logger.warn("no device found with insteon address {}", bindingConfig.getAddress());
 195             return;
 196         }
 197
 198         dev.processCommand(driver, bindingConfig, command);
 199
 200         logger.debug("found binding config for channel {}", channelName);
 201     }
 202
 203     public void addFeatureListener(InsteonChannelConfiguration bindingConfig) {
 204         logger.debug("adding listener for channel {}", bindingConfig.getChannelName());
 205
 206         InsteonAddress address = bindingConfig.getAddress();
 207         InsteonDevice dev = getDevice(address);
 208         if (dev == null) {
 209             logger.warn("device for address {} is null", address);
 210             return;
 211         }
 212         @Nullable
 213         DeviceFeature f = dev.getFeature(bindingConfig.getFeature());
 214         if (f == null || f.isFeatureGroup()) {
 215             StringBuilder buf = new StringBuilder();
 216             ArrayList<String> names = new ArrayList<>(dev.getFeatures().keySet());
 217             Collections.sort(names);
 218             for (String name : names) {
 219                 DeviceFeature feature = dev.getFeature(name);
 220                 if (feature != null && !feature.isFeatureGroup()) {
 221                     if (buf.length() > 0) {
 222                         buf.append(", ");
 223                     }
 224                     buf.append(name);
 225                 }
 226             }
 227
 228             logger.warn("channel {} references unknown feature: {}, it will be ignored. Known features for {} are: {}.",
 229                     bindingConfig.getChannelName(), bindingConfig.getFeature(), bindingConfig.getProductKey(),
 230                     buf.toString());
 231             return;
 232         }
 233
 234         DeviceFeatureListener fl = new DeviceFeatureListener(this, bindingConfig.getChannelUID(),
 235                 bindingConfig.getChannelName());
 236         fl.setParameters(bindingConfig.getParameters());
 237         f.addListener(fl);
 238
 239         bindingConfigs.put(bindingConfig.getChannelName(), bindingConfig);
 240     }
 241
 242     public void removeFeatureListener(ChannelUID channelUID) {
 243         String channelName = channelUID.getAsString();
 244
 245         logger.debug("removing listener for channel {}", channelName);
 246
 247         for (Iterator<Entry<InsteonAddress, InsteonDevice>> it = devices.entrySet().iterator(); it.hasNext();) {
 248             InsteonDevice dev = it.next().getValue();
 249             boolean removedListener = dev.removeFeatureListener(channelName);
 250             if (removedListener) {
 251                 logger.trace("removed feature listener {} from dev {}", channelName, dev);
 252             }
 253         }
 254     }
 255
 256     public void updateFeatureState(ChannelUID channelUID, State state) {
 257         handler.updateState(channelUID, state);
 258     }
 259
 260     public @Nullable InsteonDevice makeNewDevice(InsteonAddress addr, String productKey,
 261             Map<String, Object> deviceConfigMap) {
 262         DeviceTypeLoader instance = DeviceTypeLoader.instance();
 263         if (instance == null) {
 264             return null;
 265         }
 266         DeviceType dt = instance.getDeviceType(productKey);
 267         if (dt == null) {
 268             return null;
 269         }
 270         InsteonDevice dev = InsteonDevice.makeDevice(dt);
 271         dev.setAddress(addr);
 272         dev.setProductKey(productKey);
 273         dev.setDriver(driver);
 274         dev.setIsModem(productKey.equals(InsteonDeviceHandler.PLM_PRODUCT_KEY));
 275         dev.setDeviceConfigMap(deviceConfigMap);
 276         if (!dev.hasValidPollingInterval()) {
 277             dev.setPollInterval(devicePollIntervalMilliseconds);
 278         }
 279         if (driver.isModemDBComplete() && dev.getStatus() != DeviceStatus.POLLING) {
 280             int ndev = checkIfInModemDatabase(dev);
 281             if (dev.hasModemDBEntry()) {
 282                 dev.setStatus(DeviceStatus.POLLING);
 283                 Poller.instance().startPolling(dev, ndev);
 284             }
 285         }
 286         devices.put(addr, dev);
 287
 288         handler.insteonDeviceWasCreated();
 289
 290         return (dev);
 291     }
 292
 293     public void removeDevice(InsteonAddress addr) {
 294         InsteonDevice dev = devices.remove(addr);
 295         if (dev == null) {
 296             return;
 297         }
 298
 299         if (dev.getStatus() == DeviceStatus.POLLING) {
 300             Poller.instance().stopPolling(dev);
 301         }
 302     }
 303
 304     /**
 305      * Checks if a device is in the modem link database, and, if the database
 306      * is complete, logs a warning if the device is not present
 307      *
 308      * @param dev The device to search for in the modem database
 309      * @return number of devices in modem database
 310      */
 311     private int checkIfInModemDatabase(InsteonDevice dev) {
 312         try {
 313             InsteonAddress addr = dev.getAddress();
 314             Map<InsteonAddress, ModemDBEntry> dbes = driver.lockModemDBEntries();
 315             if (dbes.containsKey(addr)) {
 316                 if (!dev.hasModemDBEntry()) {
 317                     logger.debug("device {} found in the modem database and {}.", addr, getLinkInfo(dbes, addr, true));
 318                     dev.setHasModemDBEntry(true);
 319                 }
 320             } else {
 321                 if (driver.isModemDBComplete() && !addr.isX10()) {
 322                     logger.warn("device {} not found in the modem database. Did you forget to link?", addr);
 323                 }
 324             }
 325             return dbes.size();
 326         } finally {
 327             driver.unlockModemDBEntries();
 328         }
 329     }
 330
 331     public Map<String, String> getDatabaseInfo() {
 332         try {
 333             Map<String, String> databaseInfo = new HashMap<>();
 334             Map<InsteonAddress, ModemDBEntry> dbes = driver.lockModemDBEntries();
 335             for (InsteonAddress addr : dbes.keySet()) {
 336                 String a = addr.toString();
 337                 databaseInfo.put(a, a + ": " + getLinkInfo(dbes, addr, false));
 338             }
 339
 340             return databaseInfo;
 341         } finally {
 342             driver.unlockModemDBEntries();
 343         }
 344     }
 345
 346     public boolean reconnect() {
 347         driver.stop();
 348         return startPolling();
 349     }
 350
 351     /**
 352      * Everything below was copied from Insteon PLM v1
 353      */
 354
 355     /**
 356      * Clean up all state.
 357      */
 358     public void shutdown() {
 359         logger.debug("shutting down Insteon bridge");
 360         driver.stop();
 361         devices.clear();
 362         RequestQueueManager.destroyInstance();
 363         Poller.instance().stop();
 364         isActive = false;
 365     }
 366
 367     /**
 368      * Method to find a device by address
 369      *
 370      * @param aAddr the insteon address to search for
 371      * @return reference to the device, or null if not found
 372      */
 373     public @Nullable InsteonDevice getDevice(@Nullable InsteonAddress aAddr) {
 374         InsteonDevice dev = (aAddr == null) ? null : devices.get(aAddr);
 375         return (dev);
 376     }
 377
 378     private String getLinkInfo(Map<InsteonAddress, ModemDBEntry> dbes, InsteonAddress a, boolean prefix) {
 379         ModemDBEntry dbe = dbes.get(a);
 380         if (dbe == null) {
 381             return "";
 382         }
 383         List<Byte> controls = dbe.getControls();
 384         List<Byte> responds = dbe.getRespondsTo();
 385
 386         Port port = dbe.getPort();
 387         if (port == null) {
 388             return "";
 389         }
 390         String deviceName = port.getDeviceName();
 391         String s = deviceName.startsWith("/hub") ? "hub" : "plm";
 392         StringBuilder buf = new StringBuilder();
 393         if (port.isModem(a)) {
 394             if (prefix) {
 395                 buf.append("it is the ");
 396             }
 397             buf.append(s);
 398             buf.append(" (");
 399             buf.append(Utils.redactPassword(deviceName));
 400             buf.append(")");
 401         } else {
 402             if (prefix) {
 403                 buf.append("the ");
 404             }
 405             buf.append(s);
 406             buf.append(" controls groups (");
 407             buf.append(toGroupString(controls));
 408             buf.append(") and responds to groups (");
 409             buf.append(toGroupString(responds));
 410             buf.append(")");
 411         }
 412
 413         return buf.toString();
 414     }
 415
 416     private String toGroupString(List<Byte> group) {
 417         List<Byte> sorted = new ArrayList<>(group);
 418         Collections.sort(sorted, new Comparator<Byte>() {
 419             @Override
 420             public int compare(Byte b1, Byte b2) {
 421                 int i1 = b1 & 0xFF;
 422                 int i2 = b2 & 0xFF;
 423                 return i1 < i2 ? -1 : i1 == i2 ? 0 : 1;
 424             }
 425         });
 426
 427         StringBuilder buf = new StringBuilder();
 428         for (Byte b : sorted) {
 429             if (buf.length() > 0) {
 430                 buf.append(",");
 431             }
 432             buf.append(b & 0xFF);
 433         }
 434
 435         return buf.toString();
 436     }
 437
 438     public void logDeviceStatistics() {
 439         String msg = String.format("devices: %3d configured, %3d polling, msgs received: %5d", devices.size(),
 440                 Poller.instance().getSizeOfQueue(), messagesReceived);
 441         logger.debug("{}", msg);
 442         messagesReceived = 0;
 443         for (InsteonDevice dev : devices.values()) {
 444             if (dev.isModem()) {
 445                 continue;
 446             }
 447             if (deadDeviceTimeout > 0 && dev.getPollOverDueTime() > deadDeviceTimeout) {
 448                 logger.debug("device {} has not responded to polls for {} sec", dev.toString(),
 449                         dev.getPollOverDueTime() / 3600);
 450             }
 451         }
 452     }
 453
 454     /**
 455      * Handles messages that come in from the ports.
 456      * Will only process one message at a time.
 457      */
 458     private class PortListener implements MsgListener, DriverListener {
 459         @Override
 460         public void msg(Msg msg) {
 461             if (msg.isEcho() || msg.isPureNack()) {
 462                 return;
 463             }
 464             messagesReceived++;
 465             logger.debug("got msg: {}", msg);
 466             if (msg.isX10()) {
 467                 handleX10Message(msg);
 468             } else {
 469                 handleInsteonMessage(msg);
 470             }
 471         }
 472
 473         @Override
 474         public void driverCompletelyInitialized() {
 475             List<String> missing = new ArrayList<>();
 476             try {
 477                 Map<InsteonAddress, ModemDBEntry> dbes = driver.lockModemDBEntries();
 478                 logger.debug("modem database has {} entries!", dbes.size());
 479                 if (dbes.isEmpty()) {
 480                     logger.warn("the modem link database is empty!");
 481                 }
 482                 for (InsteonAddress k : dbes.keySet()) {
 483                     logger.debug("modem db entry: {}", k);
 484                 }
 485                 Set<InsteonAddress> addrs = new HashSet<>();
 486                 for (InsteonDevice dev : devices.values()) {
 487                     InsteonAddress a = dev.getAddress();
 488                     if (!dbes.containsKey(a)) {
 489                         if (!a.isX10()) {
 490                             logger.warn("device {} not found in the modem database. Did you forget to link?", a);
 491                         }
 492                     } else {
 493                         if (!dev.hasModemDBEntry()) {
 494                             addrs.add(a);
 495                             logger.debug("device {} found in the modem database and {}.", a,
 496                                     getLinkInfo(dbes, a, true));
 497                             dev.setHasModemDBEntry(true);
 498                         }
 499                         if (dev.getStatus() != DeviceStatus.POLLING) {
 500                             Poller.instance().startPolling(dev, dbes.size());
 501                         }
 502                     }
 503                 }
 504
 505                 for (InsteonAddress k : dbes.keySet()) {
 506                     if (!addrs.contains(k)) {
 507                         logger.debug("device {} found in the modem database, but is not configured as a thing and {}.",
 508                                 k, getLinkInfo(dbes, k, true));
 509
 510                         missing.add(k.toString());
 511                     }
 512                 }
 513             } finally {
 514                 driver.unlockModemDBEntries();
 515             }
 516
 517             if (!missing.isEmpty()) {
 518                 handler.addMissingDevices(missing);
 519             }
 520         }
 521
 522         @Override
 523         public void disconnected() {
 524             handler.bindingDisconnected();
 525         }
 526
 527         private void handleInsteonMessage(Msg msg) {
 528             InsteonAddress toAddr = msg.getAddr("toAddress");
 529             if (!msg.isBroadcast() && !driver.isMsgForUs(toAddr)) {
 530                 // not for one of our modems, do not process
 531                 return;
 532             }
 533             InsteonAddress fromAddr = msg.getAddr("fromAddress");
 534             if (fromAddr == null) {
 535                 logger.debug("invalid fromAddress, ignoring msg {}", msg);
 536                 return;
 537             }
 538             handleMessage(fromAddr, msg);
 539         }
 540
 541         private void handleX10Message(Msg msg) {
 542             try {
 543                 int x10Flag = msg.getByte("X10Flag") & 0xff;
 544                 int rawX10 = msg.getByte("rawX10") & 0xff;
 545                 if (x10Flag == 0x80) { // actual command
 546                     if (x10HouseUnit != -1) {
 547                         InsteonAddress fromAddr = new InsteonAddress((byte) x10HouseUnit);
 548                         handleMessage(fromAddr, msg);
 549                     }
 550                 } else if (x10Flag == 0) {
 551                     // what unit the next cmd will apply to
 552                     x10HouseUnit = rawX10 & 0xFF;
 553                 }
 554             } catch (FieldException e) {
 555                 logger.warn("got bad X10 message: {}", msg, e);
 556                 return;
 557             }
 558         }
 559
 560         private void handleMessage(InsteonAddress fromAddr, Msg msg) {
 561             InsteonDevice dev = getDevice(fromAddr);
 562             if (dev == null) {
 563                 logger.debug("dropping message from unknown device with address {}", fromAddr);
 564             } else {
 565                 dev.handleMessage(msg);
 566             }
 567         }
 568     }
 569 }