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

   1 /**
   2  * Copyright (c) 2010-2023 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.modbus.sunspec.internal.discovery;
  14
  15 import static org.openhab.binding.modbus.sunspec.internal.SunSpecConstants.*;
  16
  17 import java.util.HashMap;
  18 import java.util.Map;
  19 import java.util.Optional;
  20 import java.util.Queue;
  21 import java.util.concurrent.ConcurrentLinkedQueue;
  22
  23 import org.eclipse.jdt.annotation.NonNullByDefault;
  24 import org.eclipse.jdt.annotation.Nullable;
  25 import org.openhab.binding.modbus.discovery.ModbusDiscoveryListener;
  26 import org.openhab.binding.modbus.handler.EndpointNotInitializedException;
  27 import org.openhab.binding.modbus.handler.ModbusEndpointThingHandler;
  28 import org.openhab.binding.modbus.sunspec.internal.dto.CommonModelBlock;
  29 import org.openhab.binding.modbus.sunspec.internal.dto.ModelBlock;
  30 import org.openhab.binding.modbus.sunspec.internal.parser.CommonModelParser;
  31 import org.openhab.core.config.discovery.DiscoveryResult;
  32 import org.openhab.core.config.discovery.DiscoveryResultBuilder;
  33 import org.openhab.core.io.transport.modbus.AsyncModbusFailure;
  34 import org.openhab.core.io.transport.modbus.ModbusBitUtilities;
  35 import org.openhab.core.io.transport.modbus.ModbusCommunicationInterface;
  36 import org.openhab.core.io.transport.modbus.ModbusConstants.ValueType;
  37 import org.openhab.core.io.transport.modbus.ModbusReadFunctionCode;
  38 import org.openhab.core.io.transport.modbus.ModbusReadRequestBlueprint;
  39 import org.openhab.core.io.transport.modbus.ModbusRegisterArray;
  40 import org.openhab.core.io.transport.modbus.exception.ModbusSlaveErrorResponseException;
  41 import org.openhab.core.library.types.DecimalType;
  42 import org.openhab.core.thing.ThingTypeUID;
  43 import org.openhab.core.thing.ThingUID;
  44 import org.slf4j.Logger;
  45 import org.slf4j.LoggerFactory;
  46
  47 /**
  48  * This class is used by the SunspecDiscoveryParticipant to detect
  49  * the model blocks defined by the given device.
  50  * It scans trough the defined model items and notifies the
  51  * discovery service about the discovered devices
  52  *
  53  * @author Nagy Attila Gabor - Initial contribution
  54  */
  55 @NonNullByDefault
  56 public class SunspecDiscoveryProcess {
  57
  58     /**
  59      * Logger instance
  60      */
  61     private final Logger logger = LoggerFactory.getLogger(SunspecDiscoveryProcess.class);
  62
  63     /**
  64      * The handler instance for this device
  65      */
  66     private final ModbusEndpointThingHandler handler;
  67
  68     /**
  69      * Listener for the discovered devices. We get this
  70      * from the main discovery service, and it is used to
  71      * submit any discovered Sunspec devices
  72      */
  73     private final ModbusDiscoveryListener listener;
  74
  75     /**
  76      * The endpoint's slave id
  77      */
  78     private int slaveId;
  79
  80     /**
  81      * Number of maximum retries
  82      */
  83     private static final int maxTries = 3;
  84
  85     /**
  86      * List of start addresses to try
  87      */
  88     private Queue<Integer> possibleAddresses;
  89
  90     /**
  91      * This is the base address where the next block should be searched for
  92      */
  93     private int baseAddress = 40000;
  94
  95     /**
  96      * Count of valid Sunspec blocks found
  97      */
  98     private int blocksFound = 0;
  99
 100     /**
 101      * Parser for commonblock
 102      */
 103     private final CommonModelParser commonBlockParser;
 104
 105     /**
 106      * The last common block found. This is used
 107      * to get the details of any found devices
 108      */
 109     private @Nullable CommonModelBlock lastCommonBlock = null;
 110
 111     /**
 112      * Communication interface to the endpoint
 113      */
 114     private ModbusCommunicationInterface comms;
 115
 116     /**
 117      * New instances of this class should get a reference to the handler
 118      *
 119      * @throws EndpointNotInitializedException
 120      */
 121     public SunspecDiscoveryProcess(ModbusEndpointThingHandler handler, ModbusDiscoveryListener listener)
 122             throws EndpointNotInitializedException {
 123         this.handler = handler;
 124
 125         ModbusCommunicationInterface localComms = handler.getCommunicationInterface();
 126         if (localComms != null) {
 127             this.comms = localComms;
 128         } else {
 129             throw new EndpointNotInitializedException();
 130         }
 131         slaveId = handler.getSlaveId();
 132         this.listener = listener;
 133         commonBlockParser = new CommonModelParser();
 134         possibleAddresses = new ConcurrentLinkedQueue<>();
 135         // Preferred and alternate base registers
 136         // @see SunSpec Information Model Overview
 137         possibleAddresses.add(40000);
 138         possibleAddresses.add(50000);
 139         possibleAddresses.add(0);
 140     }
 141
 142     /**
 143      * Start model detection
 144      *
 145      * @throws EndpointNotInitializedException
 146      */
 147     public void detectModel() {
 148         if (possibleAddresses.isEmpty()) {
 149             parsingFinished();
 150             return;
 151         }
 152         // Try the next address from the possibles
 153         baseAddress = possibleAddresses.poll();
 154         logger.trace("Beginning scan for SunSpec device at address {}", baseAddress);
 155
 156         ModbusReadRequestBlueprint request = new ModbusReadRequestBlueprint(slaveId,
 157                 ModbusReadFunctionCode.READ_MULTIPLE_REGISTERS, baseAddress, // Start address
 158                 SUNSPEC_ID_SIZE, // number or words to return
 159                 maxTries);
 160
 161         comms.submitOneTimePoll(request, result -> result.getRegisters().ifPresent(this::headerReceived),
 162                 this::handleError);
 163     }
 164
 165     /**
 166      * We received the first two words, that should equal to SunS
 167      */
 168     private void headerReceived(ModbusRegisterArray registers) {
 169         logger.trace("Received response from device {}", registers.toString());
 170
 171         Optional<DecimalType> id = ModbusBitUtilities.extractStateFromRegisters(registers, 0, ValueType.UINT32);
 172
 173         if (id.isEmpty() || id.get().longValue() != SUNSPEC_ID) {
 174             logger.debug("Could not find SunSpec DID at address {}, received: {}, expected: {}", baseAddress, id,
 175                     SUNSPEC_ID);
 176             detectModel();
 177             return;
 178         }
 179
 180         logger.trace("Header looks correct");
 181         baseAddress += SUNSPEC_ID_SIZE;
 182
 183         lookForModelBlock();
 184     }
 185
 186     /**
 187      * Look for a valid model block at the current base address
 188      */
 189     private void lookForModelBlock() {
 190         ModbusReadRequestBlueprint request = new ModbusReadRequestBlueprint(slaveId,
 191                 ModbusReadFunctionCode.READ_MULTIPLE_REGISTERS, baseAddress, // Start address
 192                 MODEL_HEADER_SIZE, // number or words to return
 193                 maxTries);
 194
 195         comms.submitOneTimePoll(request, result -> result.getRegisters().ifPresent(this::modelBlockReceived),
 196                 this::handleError);
 197     }
 198
 199     /**
 200      * We received a model block header
 201      */
 202     private void modelBlockReceived(ModbusRegisterArray registers) {
 203         logger.debug("Received response from device {}", registers.toString());
 204
 205         Optional<DecimalType> moduleID = ModbusBitUtilities.extractStateFromRegisters(registers, 0, ValueType.UINT16);
 206         Optional<DecimalType> blockLength = ModbusBitUtilities.extractStateFromRegisters(registers, 1,
 207                 ValueType.UINT16);
 208
 209         if (moduleID.isEmpty() || blockLength.isEmpty()) {
 210             logger.info("Could not find valid module id or block length field.");
 211             parsingFinished();
 212             return;
 213         }
 214         ModelBlock block = new ModelBlock();
 215         block.address = baseAddress;
 216         block.moduleID = moduleID.get().intValue();
 217         block.length = blockLength.get().intValue() + MODEL_HEADER_SIZE;
 218         logger.debug("SunSpec detector found block {}", block);
 219
 220         blocksFound++;
 221
 222         if (block.moduleID == FINAL_BLOCK) {
 223             parsingFinished();
 224         } else {
 225             baseAddress += block.length;
 226             if (block.moduleID == COMMON_BLOCK) {
 227                 readCommonBlock(block); // This is an asynchronous task
 228                 return;
 229             } else {
 230                 createDiscoveryResult(block);
 231                 lookForModelBlock();
 232             }
 233         }
 234     }
 235
 236     /**
 237      * Start reading common block
 238      *
 239      * @param block
 240      */
 241     private void readCommonBlock(ModelBlock block) {
 242         ModbusReadRequestBlueprint request = new ModbusReadRequestBlueprint(slaveId,
 243                 ModbusReadFunctionCode.READ_MULTIPLE_REGISTERS, block.address, // Start address
 244                 block.length, // number or words to return
 245                 maxTries);
 246
 247         comms.submitOneTimePoll(request, result -> result.getRegisters().ifPresent(this::parseCommonBlock),
 248                 this::handleError);
 249     }
 250
 251     /**
 252      * We've read the details of a common block now parse it, and
 253      * store for later use
 254      *
 255      * @param registers
 256      */
 257     private void parseCommonBlock(ModbusRegisterArray registers) {
 258         logger.trace("Got common block data: {}", registers);
 259         lastCommonBlock = commonBlockParser.parse(registers);
 260         lookForModelBlock(); // Continue parsing
 261     }
 262
 263     /**
 264      * Create a discovery result from a model block
 265      *
 266      * @param block the block we've found
 267      */
 268     private void createDiscoveryResult(ModelBlock block) {
 269         if (!SUPPORTED_THING_TYPES_UIDS.containsKey(block.moduleID)) {
 270             logger.debug("ModuleID {} is not supported, skipping this block", block.moduleID);
 271             return;
 272         }
 273
 274         CommonModelBlock commonBlock = lastCommonBlock;
 275
 276         if (commonBlock == null) {
 277             logger.warn(
 278                     "Found model block without a preceding common block. Can't add device because details are unkown");
 279             return;
 280         }
 281
 282         ThingTypeUID thingTypeUID = SUPPORTED_THING_TYPES_UIDS.get(block.moduleID);
 283         if (thingTypeUID == null) {
 284             logger.warn("Found model block but no corresponding thing type UID present: {}", block.moduleID);
 285             return;
 286         }
 287         ThingUID thingUID = new ThingUID(thingTypeUID, handler.getUID(), Integer.toString(block.address));
 288
 289         Map<String, Object> properties = new HashMap<>();
 290         properties.put(PROPERTY_VENDOR, commonBlock.manufacturer);
 291         properties.put(PROPERTY_MODEL, commonBlock.model);
 292         properties.put(PROPERTY_SERIAL_NUMBER, commonBlock.serialNumber);
 293         properties.put(PROPERTY_VERSION, commonBlock.version);
 294         properties.put(PROPERTY_BLOCK_ADDRESS, block.address);
 295         properties.put(PROPERTY_BLOCK_LENGTH, block.length);
 296         properties.put(PROPERTY_UNIQUE_ADDRESS, handler.getUID().getAsString() + ":" + block.address);
 297
 298         DiscoveryResult result = DiscoveryResultBuilder.create(thingUID).withProperties(properties)
 299                 .withRepresentationProperty(PROPERTY_UNIQUE_ADDRESS).withBridge(handler.getUID())
 300                 .withLabel(commonBlock.manufacturer + " " + commonBlock.model).build();
 301
 302         listener.thingDiscovered(result);
 303     }
 304
 305     /**
 306      * Parsing of model blocks finished
 307      * Now we have to report back to the handler the common block and the block we were looking for
 308      */
 309     private void parsingFinished() {
 310         listener.discoveryFinished();
 311     }
 312
 313     /**
 314      * Handle errors received during communication
 315      */
 316     private void handleError(AsyncModbusFailure<ModbusReadRequestBlueprint> failure) {
 317         if (blocksFound > 1 && failure.getCause() instanceof ModbusSlaveErrorResponseException) {
 318             int code = ((ModbusSlaveErrorResponseException) failure.getCause()).getExceptionCode();
 319             if (code == ModbusSlaveErrorResponseException.ILLEGAL_DATA_ACCESS
 320                     || code == ModbusSlaveErrorResponseException.ILLEGAL_DATA_VALUE) {
 321                 // It is very likely that the slave does not report an end block (0xffff) after the main blocks
 322                 // so we treat this situation as normal.
 323                 logger.debug(
 324                         "Seems like slave device does not report an end block. Continuing with the dectected blocks");
 325                 parsingFinished();
 326                 return;
 327             }
 328         }
 329
 330         String cls = failure.getCause().getClass().getName();
 331         String msg = failure.getCause().getMessage();
 332
 333         logger.warn("Error with read at address {}: {} {}", baseAddress, cls, msg);
 334
 335         detectModel();
 336     }
 337 }