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

   1 /**
   2  * Copyright (c) 2010-2020 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 @SuppressWarnings({ "null", "unused" })
 110 public class InsteonBinding {
 111     private static final int DEAD_DEVICE_COUNT = 10;
 112
 113     private final Logger logger = LoggerFactory.getLogger(InsteonBinding.class);
 114
 115     private Driver driver;
 116     private ConcurrentHashMap<InsteonAddress, InsteonDevice> devices = new ConcurrentHashMap<>();
 117     private ConcurrentHashMap<String, InsteonChannelConfiguration> bindingConfigs = new ConcurrentHashMap<>();
 118     private PortListener portListener = new PortListener();
 119     private int devicePollIntervalMilliseconds = 300000;
 120     private int deadDeviceTimeout = -1;
 121     private int messagesReceived = 0;
 122     private boolean isActive = false; // state of binding
 123     private int x10HouseUnit = -1;
 124     private InsteonNetworkHandler handler;
 125
 126     public InsteonBinding(InsteonNetworkHandler handler, @Nullable InsteonNetworkConfiguration config,
 127             @Nullable SerialPortManager serialPortManager, ScheduledExecutorService scheduler) {
 128         this.handler = handler;
 129
 130         String port = config.getPort();
 131         logger.debug("port = '{}'", Utils.redactPassword(port));
 132
 133         driver = new Driver(port, portListener, serialPortManager, scheduler);
 134         driver.addMsgListener(portListener);
 135
 136         Integer devicePollIntervalSeconds = config.getDevicePollIntervalSeconds();
 137         if (devicePollIntervalSeconds != null) {
 138             devicePollIntervalMilliseconds = devicePollIntervalSeconds * 1000;
 139         }
 140         logger.debug("device poll interval set to {} seconds", devicePollIntervalMilliseconds / 1000);
 141
 142         String additionalDevices = config.getAdditionalDevices();
 143         if (additionalDevices != null) {
 144             try {
 145                 DeviceTypeLoader.instance().loadDeviceTypesXML(additionalDevices);
 146                 logger.debug("read additional device definitions from {}", additionalDevices);
 147             } catch (ParserConfigurationException | SAXException | IOException e) {
 148                 logger.warn("error reading additional devices from {}", additionalDevices, e);
 149             }
 150         }
 151
 152         String additionalFeatures = config.getAdditionalFeatures();
 153         if (additionalFeatures != null) {
 154             logger.debug("reading additional feature templates from {}", additionalFeatures);
 155             DeviceFeature.readFeatureTemplates(additionalFeatures);
 156         }
 157
 158         deadDeviceTimeout = devicePollIntervalMilliseconds * DEAD_DEVICE_COUNT;
 159         logger.debug("dead device timeout set to {} seconds", deadDeviceTimeout / 1000);
 160     }
 161
 162     public Driver getDriver() {
 163         return driver;
 164     }
 165
 166     public boolean startPolling() {
 167         logger.debug("starting to poll {}", driver.getPortName());
 168         driver.start();
 169         return driver.isRunning();
 170     }
 171
 172     public void setIsActive(boolean isActive) {
 173         this.isActive = isActive;
 174     }
 175
 176     public void sendCommand(String channelName, Command command) {
 177         if (!isActive) {
 178             logger.debug("not ready to handle commands yet, returning.");
 179             return;
 180         }
 181
 182         InsteonChannelConfiguration bindingConfig = bindingConfigs.get(channelName);
 183         if (bindingConfig == null) {
 184             logger.warn("unable to find binding config for channel {}", channelName);
 185             return;
 186         }
 187
 188         InsteonDevice dev = getDevice(bindingConfig.getAddress());
 189         if (dev == null) {
 190             logger.warn("no device found with insteon address {}", bindingConfig.getAddress());
 191             return;
 192         }
 193
 194         dev.processCommand(driver, bindingConfig, command);
 195
 196         logger.debug("found binding config for channel {}", channelName);
 197     }
 198
 199     public void addFeatureListener(InsteonChannelConfiguration bindingConfig) {
 200         logger.debug("adding listener for channel {}", bindingConfig.getChannelName());
 201
 202         InsteonAddress address = bindingConfig.getAddress();
 203         InsteonDevice dev = getDevice(address);
 204         @Nullable
 205         DeviceFeature f = dev.getFeature(bindingConfig.getFeature());
 206         if (f == null || f.isFeatureGroup()) {
 207             StringBuilder buf = new StringBuilder();
 208             ArrayList<String> names = new ArrayList<>(dev.getFeatures().keySet());
 209             Collections.sort(names);
 210             for (String name : names) {
 211                 DeviceFeature feature = dev.getFeature(name);
 212                 if (!feature.isFeatureGroup()) {
 213                     if (buf.length() > 0) {
 214                         buf.append(", ");
 215                     }
 216                     buf.append(name);
 217                 }
 218             }
 219
 220             logger.warn("channel {} references unknown feature: {}, it will be ignored. Known features for {} are: {}.",
 221                     bindingConfig.getChannelName(), bindingConfig.getFeature(), bindingConfig.getProductKey(),
 222                     buf.toString());
 223             return;
 224         }
 225
 226         DeviceFeatureListener fl = new DeviceFeatureListener(this, bindingConfig.getChannelUID(),
 227                 bindingConfig.getChannelName());
 228         fl.setParameters(bindingConfig.getParameters());
 229         f.addListener(fl);
 230
 231         bindingConfigs.put(bindingConfig.getChannelName(), bindingConfig);
 232     }
 233
 234     public void removeFeatureListener(ChannelUID channelUID) {
 235         String channelName = channelUID.getAsString();
 236
 237         logger.debug("removing listener for channel {}", channelName);
 238
 239         for (Iterator<Entry<InsteonAddress, InsteonDevice>> it = devices.entrySet().iterator(); it.hasNext();) {
 240             InsteonDevice dev = it.next().getValue();
 241             boolean removedListener = dev.removeFeatureListener(channelName);
 242             if (removedListener) {
 243                 logger.trace("removed feature listener {} from dev {}", channelName, dev);
 244             }
 245         }
 246     }
 247
 248     public void updateFeatureState(ChannelUID channelUID, State state) {
 249         handler.updateState(channelUID, state);
 250     }
 251
 252     public InsteonDevice makeNewDevice(InsteonAddress addr, String productKey, Map<String, Object> deviceConfigMap) {
 253         DeviceType dt = DeviceTypeLoader.instance().getDeviceType(productKey);
 254         InsteonDevice dev = InsteonDevice.makeDevice(dt);
 255         dev.setAddress(addr);
 256         dev.setProductKey(productKey);
 257         dev.setDriver(driver);
 258         dev.setIsModem(productKey.equals(InsteonDeviceHandler.PLM_PRODUCT_KEY));
 259         dev.setDeviceConfigMap(deviceConfigMap);
 260         if (!dev.hasValidPollingInterval()) {
 261             dev.setPollInterval(devicePollIntervalMilliseconds);
 262         }
 263         if (driver.isModemDBComplete() && dev.getStatus() != DeviceStatus.POLLING) {
 264             int ndev = checkIfInModemDatabase(dev);
 265             if (dev.hasModemDBEntry()) {
 266                 dev.setStatus(DeviceStatus.POLLING);
 267                 Poller.instance().startPolling(dev, ndev);
 268             }
 269         }
 270         devices.put(addr, dev);
 271
 272         handler.insteonDeviceWasCreated();
 273
 274         return (dev);
 275     }
 276
 277     public void removeDevice(InsteonAddress addr) {
 278         InsteonDevice dev = devices.remove(addr);
 279         if (dev == null) {
 280             return;
 281         }
 282
 283         if (dev.getStatus() == DeviceStatus.POLLING) {
 284             Poller.instance().stopPolling(dev);
 285         }
 286     }
 287
 288     /**
 289      * Checks if a device is in the modem link database, and, if the database
 290      * is complete, logs a warning if the device is not present
 291      *
 292      * @param dev The device to search for in the modem database
 293      * @return number of devices in modem database
 294      */
 295     private int checkIfInModemDatabase(InsteonDevice dev) {
 296         try {
 297             InsteonAddress addr = dev.getAddress();
 298             Map<InsteonAddress, ModemDBEntry> dbes = driver.lockModemDBEntries();
 299             if (dbes.containsKey(addr)) {
 300                 if (!dev.hasModemDBEntry()) {
 301                     logger.debug("device {} found in the modem database and {}.", addr, getLinkInfo(dbes, addr, true));
 302                     dev.setHasModemDBEntry(true);
 303                 }
 304             } else {
 305                 if (driver.isModemDBComplete() && !addr.isX10()) {
 306                     logger.warn("device {} not found in the modem database. Did you forget to link?", addr);
 307                 }
 308             }
 309             return dbes.size();
 310         } finally {
 311             driver.unlockModemDBEntries();
 312         }
 313     }
 314
 315     public Map<String, String> getDatabaseInfo() {
 316         try {
 317             Map<String, String> databaseInfo = new HashMap<>();
 318             Map<InsteonAddress, ModemDBEntry> dbes = driver.lockModemDBEntries();
 319             for (InsteonAddress addr : dbes.keySet()) {
 320                 String a = addr.toString();
 321                 databaseInfo.put(a, a + ": " + getLinkInfo(dbes, addr, false));
 322             }
 323
 324             return databaseInfo;
 325         } finally {
 326             driver.unlockModemDBEntries();
 327         }
 328     }
 329
 330     public boolean reconnect() {
 331         driver.stop();
 332         return startPolling();
 333     }
 334
 335     /**
 336      * Everything below was copied from Insteon PLM v1
 337      */
 338
 339     /**
 340      * Clean up all state.
 341      */
 342     public void shutdown() {
 343         logger.debug("shutting down Insteon bridge");
 344         driver.stop();
 345         devices.clear();
 346         RequestQueueManager.destroyInstance();
 347         Poller.instance().stop();
 348         isActive = false;
 349     }
 350
 351     /**
 352      * Method to find a device by address
 353      *
 354      * @param aAddr the insteon address to search for
 355      * @return reference to the device, or null if not found
 356      */
 357     public @Nullable InsteonDevice getDevice(@Nullable InsteonAddress aAddr) {
 358         InsteonDevice dev = (aAddr == null) ? null : devices.get(aAddr);
 359         return (dev);
 360     }
 361
 362     private String getLinkInfo(Map<InsteonAddress, ModemDBEntry> dbes, InsteonAddress a, boolean prefix) {
 363         ModemDBEntry dbe = dbes.get(a);
 364         List<Byte> controls = dbe.getControls();
 365         List<Byte> responds = dbe.getRespondsTo();
 366
 367         Port port = dbe.getPort();
 368         String deviceName = port.getDeviceName();
 369         String s = deviceName.startsWith("/hub") ? "hub" : "plm";
 370         StringBuilder buf = new StringBuilder();
 371         if (port.isModem(a)) {
 372             if (prefix) {
 373                 buf.append("it is the ");
 374             }
 375             buf.append(s);
 376             buf.append(" (");
 377             buf.append(Utils.redactPassword(deviceName));
 378             buf.append(")");
 379         } else {
 380             if (prefix) {
 381                 buf.append("the ");
 382             }
 383             buf.append(s);
 384             buf.append(" controls groups (");
 385             buf.append(toGroupString(controls));
 386             buf.append(") and responds to groups (");
 387             buf.append(toGroupString(responds));
 388             buf.append(")");
 389         }
 390
 391         return buf.toString();
 392     }
 393
 394     private String toGroupString(List<Byte> group) {
 395         List<Byte> sorted = new ArrayList<>(group);
 396         Collections.sort(sorted, new Comparator<Byte>() {
 397             @Override
 398             public int compare(Byte b1, Byte b2) {
 399                 int i1 = b1 & 0xFF;
 400                 int i2 = b2 & 0xFF;
 401                 return i1 < i2 ? -1 : i1 == i2 ? 0 : 1;
 402             }
 403         });
 404
 405         StringBuilder buf = new StringBuilder();
 406         for (Byte b : sorted) {
 407             if (buf.length() > 0) {
 408                 buf.append(",");
 409             }
 410             buf.append(b & 0xFF);
 411         }
 412
 413         return buf.toString();
 414     }
 415
 416     public void logDeviceStatistics() {
 417         String msg = String.format("devices: %3d configured, %3d polling, msgs received: %5d", devices.size(),
 418                 Poller.instance().getSizeOfQueue(), messagesReceived);
 419         logger.debug("{}", msg);
 420         messagesReceived = 0;
 421         for (InsteonDevice dev : devices.values()) {
 422             if (dev.isModem()) {
 423                 continue;
 424             }
 425             if (deadDeviceTimeout > 0 && dev.getPollOverDueTime() > deadDeviceTimeout) {
 426                 logger.debug("device {} has not responded to polls for {} sec", dev.toString(),
 427                         dev.getPollOverDueTime() / 3600);
 428             }
 429         }
 430     }
 431
 432     /**
 433      * Handles messages that come in from the ports.
 434      * Will only process one message at a time.
 435      */
 436     @NonNullByDefault
 437     private class PortListener implements MsgListener, DriverListener {
 438         @Override
 439         public void msg(Msg msg) {
 440             if (msg.isEcho() || msg.isPureNack()) {
 441                 return;
 442             }
 443             messagesReceived++;
 444             logger.debug("got msg: {}", msg);
 445             if (msg.isX10()) {
 446                 handleX10Message(msg);
 447             } else {
 448                 handleInsteonMessage(msg);
 449             }
 450         }
 451
 452         @Override
 453         public void driverCompletelyInitialized() {
 454             List<String> missing = new ArrayList<>();
 455             try {
 456                 Map<InsteonAddress, ModemDBEntry> dbes = driver.lockModemDBEntries();
 457                 logger.debug("modem database has {} entries!", dbes.size());
 458                 if (dbes.isEmpty()) {
 459                     logger.warn("the modem link database is empty!");
 460                 }
 461                 for (InsteonAddress k : dbes.keySet()) {
 462                     logger.debug("modem db entry: {}", k);
 463                 }
 464                 Set<InsteonAddress> addrs = new HashSet<>();
 465                 for (InsteonDevice dev : devices.values()) {
 466                     InsteonAddress a = dev.getAddress();
 467                     if (!dbes.containsKey(a)) {
 468                         if (!a.isX10()) {
 469                             logger.warn("device {} not found in the modem database. Did you forget to link?", a);
 470                         }
 471                     } else {
 472                         if (!dev.hasModemDBEntry()) {
 473                             addrs.add(a);
 474                             logger.debug("device {} found in the modem database and {}.", a,
 475                                     getLinkInfo(dbes, a, true));
 476                             dev.setHasModemDBEntry(true);
 477                         }
 478                         if (dev.getStatus() != DeviceStatus.POLLING) {
 479                             Poller.instance().startPolling(dev, dbes.size());
 480                         }
 481                     }
 482                 }
 483
 484                 for (InsteonAddress k : dbes.keySet()) {
 485                     if (!addrs.contains(k)) {
 486                         logger.debug("device {} found in the modem database, but is not configured as a thing and {}.",
 487                                 k, getLinkInfo(dbes, k, true));
 488
 489                         missing.add(k.toString());
 490                     }
 491                 }
 492             } finally {
 493                 driver.unlockModemDBEntries();
 494             }
 495
 496             if (!missing.isEmpty()) {
 497                 handler.addMissingDevices(missing);
 498             }
 499         }
 500
 501         @Override
 502         public void disconnected() {
 503             handler.bindingDisconnected();
 504         }
 505
 506         private void handleInsteonMessage(Msg msg) {
 507             InsteonAddress toAddr = msg.getAddr("toAddress");
 508             if (!msg.isBroadcast() && !driver.isMsgForUs(toAddr)) {
 509                 // not for one of our modems, do not process
 510                 return;
 511             }
 512             InsteonAddress fromAddr = msg.getAddr("fromAddress");
 513             if (fromAddr == null) {
 514                 logger.debug("invalid fromAddress, ignoring msg {}", msg);
 515                 return;
 516             }
 517             handleMessage(fromAddr, msg);
 518         }
 519
 520         private void handleX10Message(Msg msg) {
 521             try {
 522                 int x10Flag = msg.getByte("X10Flag") & 0xff;
 523                 int rawX10 = msg.getByte("rawX10") & 0xff;
 524                 if (x10Flag == 0x80) { // actual command
 525                     if (x10HouseUnit != -1) {
 526                         InsteonAddress fromAddr = new InsteonAddress((byte) x10HouseUnit);
 527                         handleMessage(fromAddr, msg);
 528                     }
 529                 } else if (x10Flag == 0) {
 530                     // what unit the next cmd will apply to
 531                     x10HouseUnit = rawX10 & 0xFF;
 532                 }
 533             } catch (FieldException e) {
 534                 logger.warn("got bad X10 message: {}", msg, e);
 535                 return;
 536             }
 537         }
 538
 539         private void handleMessage(InsteonAddress fromAddr, Msg msg) {
 540             InsteonDevice dev = getDevice(fromAddr);
 541             if (dev == null) {
 542                 logger.debug("dropping message from unknown device with address {}", fromAddr);
 543             } else {
 544                 dev.handleMessage(msg);
 545             }
 546         }
 547     }
 548 }