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

   1 /**
   2  * Copyright (c) 2010-2024 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.mqtt.generic;
  14
  15 import java.util.List;
  16
  17 import org.eclipse.jdt.annotation.NonNullByDefault;
  18
  19 /**
  20  * Interface to keep track of the availability of device using an availability topic or messages received
  21  *
  22  * @author Jochen Klein - Initial contribution
  23  * @author Cody Cutrer - Support all/any/latest
  24  */
  25 @NonNullByDefault
  26 public interface AvailabilityTracker {
  27     /**
  28      * controls the conditions needed to set the entity to available
  29      */
  30     enum AvailabilityMode {
  31         /**
  32          * payload_available must be received on all configured availability topics before the entity is marked as
  33          * online
  34          */
  35         ALL,
  36
  37         /**
  38          * payload_available must be received on at least one configured availability topic before the entity is marked
  39          * as online
  40          */
  41         ANY,
  42
  43         /**
  44          * the last payload_available or payload_not_available received on any configured availability topic controls
  45          * the availability
  46          */
  47         LATEST
  48     }
  49
  50     /**
  51      * Sets how multiple availability topics are treated
  52      */
  53     void setAvailabilityMode(AvailabilityMode mode);
  54
  55     /**
  56      * Adds an availability topic to determine the availability of a device.
  57      * <p>
  58      * Availability topics are usually set by the device as LWT.
  59      *
  60      * @param availability_topic
  61      * @param payload_available
  62      * @param payload_not_available
  63      */
  64     void addAvailabilityTopic(String availability_topic, String payload_available, String payload_not_available);
  65
  66     /**
  67      * Adds an availability topic to determine the availability of a device.
  68      * <p>
  69      * Availability topics are usually set by the device as LWT.
  70      *
  71      * @param availability_topic The MQTT topic where availability is published to.
  72      * @param payload_available The value for the topic to indicate the device is online.
  73      * @param payload_not_available The value for the topic to indicate the device is offline.
  74      * @param transformation_pattern A transformation pattern to process the value before comparing to
  75      *            payload_available/payload_not_available.
  76      */
  77     void addAvailabilityTopic(String availability_topic, String payload_available, String payload_not_available,
  78             List<String> transformation_pattern);
  79
  80     void removeAvailabilityTopic(String availability_topic);
  81
  82     void clearAllAvailabilityTopics();
  83
  84     /**
  85      * resets the indicator, if messages have been received.
  86      * <p>
  87      * This is used to time out the availability of the device after some time without receiving a message.
  88      */
  89     void resetMessageReceived();
  90 }