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      * @param uid the thing type to look for
 146      * @throws EndpointNotInitializedException
 147      */
 148     public void detectModel() {
 149         if (possibleAddresses.isEmpty()) {
 150             parsingFinished();
 151             return;
 152         }
 153         // Try the next address from the possibles
 154         baseAddress = possibleAddresses.poll();
 155         logger.trace("Beginning scan for SunSpec device at address {}", baseAddress);
 156
 157         ModbusReadRequestBlueprint request = new ModbusReadRequestBlueprint(slaveId,
 158                 ModbusReadFunctionCode.READ_MULTIPLE_REGISTERS, baseAddress, // Start address
 159                 SUNSPEC_ID_SIZE, // number or words to return
 160                 maxTries);
 161
 162         comms.submitOneTimePoll(request, result -> result.getRegisters().ifPresent(this::headerReceived),
 163                 this::handleError);
 164     }
 165
 166     /**
 167      * We received the first two words, that should equal to SunS
 168      */
 169     private void headerReceived(ModbusRegisterArray registers) {
 170         logger.trace("Received response from device {}", registers.toString());
 171
 172         Optional<DecimalType> id = ModbusBitUtilities.extractStateFromRegisters(registers, 0, ValueType.UINT32);
 173
 174         if (!id.isPresent() || id.get().longValue() != SUNSPEC_ID) {
 175             logger.debug("Could not find SunSpec DID at address {}, received: {}, expected: {}", baseAddress, id,
 176                     SUNSPEC_ID);
 177             detectModel();
 178             return;
 179         }
 180
 181         logger.trace("Header looks correct");
 182         baseAddress += SUNSPEC_ID_SIZE;
 183
 184         lookForModelBlock();
 185     }
 186
 187     /**
 188      * Look for a valid model block at the current base address
 189      */
 190     private void lookForModelBlock() {
 191         ModbusReadRequestBlueprint request = new ModbusReadRequestBlueprint(slaveId,
 192                 ModbusReadFunctionCode.READ_MULTIPLE_REGISTERS, baseAddress, // Start address
 193                 MODEL_HEADER_SIZE, // number or words to return
 194                 maxTries);
 195
 196         comms.submitOneTimePoll(request, result -> result.getRegisters().ifPresent(this::modelBlockReceived),
 197                 this::handleError);
 198     }
 199
 200     /**
 201      * We received a model block header
 202      */
 203     private void modelBlockReceived(ModbusRegisterArray registers) {
 204         logger.debug("Received response from device {}", registers.toString());
 205
 206         Optional<DecimalType> moduleID = ModbusBitUtilities.extractStateFromRegisters(registers, 0, ValueType.UINT16);
 207         Optional<DecimalType> blockLength = ModbusBitUtilities.extractStateFromRegisters(registers, 1,
 208                 ValueType.UINT16);
 209
 210         if (!moduleID.isPresent() || !blockLength.isPresent()) {
 211             logger.info("Could not find valid module id or block length field.");
 212             parsingFinished();
 213             return;
 214         }
 215         ModelBlock block = new ModelBlock();
 216         block.address = baseAddress;
 217         block.moduleID = moduleID.get().intValue();
 218         block.length = blockLength.get().intValue() + MODEL_HEADER_SIZE;
 219         logger.debug("SunSpec detector found block {}", block);
 220
 221         blocksFound++;
 222
 223         if (block.moduleID == FINAL_BLOCK) {
 224             parsingFinished();
 225         } else {
 226             baseAddress += block.length;
 227             if (block.moduleID == COMMON_BLOCK) {
 228                 readCommonBlock(block); // This is an asynchronous task
 229                 return;
 230             } else {
 231                 createDiscoveryResult(block);
 232                 lookForModelBlock();
 233             }
 234         }
 235     }
 236
 237     /**
 238      * Start reading common block
 239      *
 240      * @param block
 241      */
 242     private void readCommonBlock(ModelBlock block) {
 243         ModbusReadRequestBlueprint request = new ModbusReadRequestBlueprint(slaveId,
 244                 ModbusReadFunctionCode.READ_MULTIPLE_REGISTERS, block.address, // Start address
 245                 block.length, // number or words to return
 246                 maxTries);
 247
 248         comms.submitOneTimePoll(request, result -> result.getRegisters().ifPresent(this::parseCommonBlock),
 249                 this::handleError);
 250     }
 251
 252     /**
 253      * We've read the details of a common block now parse it, and
 254      * store for later use
 255      *
 256      * @param registers
 257      */
 258     private void parseCommonBlock(ModbusRegisterArray registers) {
 259         logger.trace("Got common block data: {}", registers);
 260         lastCommonBlock = commonBlockParser.parse(registers);
 261         lookForModelBlock(); // Continue parsing
 262     }
 263
 264     /**
 265      * Create a discovery result from a model block
 266      *
 267      * @param block the block we've found
 268      */
 269     private void createDiscoveryResult(ModelBlock block) {
 270         if (!SUPPORTED_THING_TYPES_UIDS.containsKey(block.moduleID)) {
 271             logger.debug("ModuleID {} is not supported, skipping this block", block.moduleID);
 272             return;
 273         }
 274
 275         CommonModelBlock commonBlock = lastCommonBlock;
 276
 277         if (commonBlock == null) {
 278             logger.warn(
 279                     "Found model block without a preceding common block. Can't add device because details are unkown");
 280             return;
 281         }
 282
 283         ThingTypeUID thingTypeUID = SUPPORTED_THING_TYPES_UIDS.get(block.moduleID);
 284         if (thingTypeUID == null) {
 285             logger.warn("Found model block but no corresponding thing type UID present: {}", block.moduleID);
 286             return;
 287         }
 288         ThingUID thingUID = new ThingUID(thingTypeUID, handler.getUID(), Integer.toString(block.address));
 289
 290         Map<String, Object> properties = new HashMap<>();
 291         properties.put(PROPERTY_VENDOR, commonBlock.manufacturer);
 292         properties.put(PROPERTY_MODEL, commonBlock.model);
 293         properties.put(PROPERTY_SERIAL_NUMBER, commonBlock.serialNumber);
 294         properties.put(PROPERTY_VERSION, commonBlock.version);
 295         properties.put(PROPERTY_BLOCK_ADDRESS, block.address);
 296         properties.put(PROPERTY_BLOCK_LENGTH, block.length);
 297         properties.put(PROPERTY_UNIQUE_ADDRESS, handler.getUID().getAsString() + ":" + block.address);
 298
 299         DiscoveryResult result = DiscoveryResultBuilder.create(thingUID).withProperties(properties)
 300                 .withRepresentationProperty(PROPERTY_UNIQUE_ADDRESS).withBridge(handler.getUID())
 301                 .withLabel(commonBlock.manufacturer + " " + commonBlock.model).build();
 302
 303         listener.thingDiscovered(result);
 304     }
 305
 306     /**
 307      * Parsing of model blocks finished
 308      * Now we have to report back to the handler the common block and the block we were looking for
 309      */
 310     private void parsingFinished() {
 311         listener.discoveryFinished();
 312     }
 313
 314     /**
 315      * Handle errors received during communication
 316      */
 317     private void handleError(AsyncModbusFailure<ModbusReadRequestBlueprint> failure) {
 318         if (blocksFound > 1 && failure.getCause() instanceof ModbusSlaveErrorResponseException) {
 319             int code = ((ModbusSlaveErrorResponseException) failure.getCause()).getExceptionCode();
 320             if (code == ModbusSlaveErrorResponseException.ILLEGAL_DATA_ACCESS
 321                     || code == ModbusSlaveErrorResponseException.ILLEGAL_DATA_VALUE) {
 322                 // It is very likely that the slave does not report an end block (0xffff) after the main blocks
 323                 // so we treat this situation as normal.
 324                 logger.debug(
 325                         "Seems like slave device does not report an end block. Continuing with the dectected blocks");
 326                 parsingFinished();
 327                 return;
 328             }
 329         }
 330
 331         String cls = failure.getCause().getClass().getName();
 332         String msg = failure.getCause().getMessage();
 333
 334         logger.warn("Error with read at address {}: {} {}", baseAddress, cls, msg);
 335
 336         detectModel();
 337     }
 338 }