Package org.openhab.core.thing.binding.firmware

Interface Firmware

All Superinterfaces:
Comparable<Firmware>
@NonNullByDefault public interface Firmware extends Comparable<Firmware>

The Firmware is the description of a firmware to be installed on the physical device of a Thing. A firmware relates always to exactly one Thing. By using the model restrictions (see isModelRestricted()) and the firmware version it is ensured that there is only one firmware in a specific version for a thing available. Firmwares can be easily created by the FirmwareBuilder.

Firmwares are made available to the system by FirmwareProviders that are tracked by the FirmwareRegistry. The registry can be used to get a dedicated firmware or to get all available firmwares for a specific Thing.

The FirmwareUpdateService is responsible to provide the current FirmwareStatusInfo of a thing. Furthermore this service is the central instance to start a firmware update process. In order that the firmware of a thing can be updated the hander of the thing has to implement the FirmwareUpdateHandler interface.

The Firmware implements the Comparable interface in order to be able to sort firmwares based on their versions. Firmwares are sorted in a descending sequence, i.e. that the latest firmware will be the first element in a sorted result set. The implementation of Comparable.compareTo(T) splits the firmware version by the delimiters ".", "-" and "_" and compares the different parts of the firmware version. As a result the firmware version 2-0-1 is newer then firmware version 2.0.0 which again is newer than firmware version 1-9_9.9_abc. Consequently 2.0-0, 2-0_0 and 2_0.0 represent the same firmware version. Furthermore firmware version xyz_1 is newer than firmware version abc.2 which again is newer than firmware version 2-0-1.

A Firmware consists of various meta information like a version, a vendor or a description. Additionally FirmwareProviders can specify further meta information in form of properties (e.g. a factory reset of the device is required afterwards) so that FirmwareUpdateHandlers can handle this information accordingly.

Author:
Thomas Höfer - Initial contribution, Dimitar Ivanov - Firmware is extracted as interface with default implementation, introduced firmware restriction function

  • Field Details

    • PROPERTY_REQUIRES_FACTORY_RESET

      static final String PROPERTY_REQUIRES_FACTORY_RESET
      The key for the requires a factory reset property.
      See Also:

  • Method Details

    • getThingTypeUID

      ThingTypeUID getThingTypeUID()
      Returns the thing type UID, that this firmware is associated with.
      Returns:
      the thing type UID (not null)

    • getVendor

      @Nullable String getVendor()
      Returns the vendor of the firmware.
      Returns:
      the vendor of the firmware (can be null)

    • getModel

      @Nullable String getModel()
      Returns the model of the firmware.
      Returns:
      the model of the firmware (can be null)

    • isModelRestricted

      boolean isModelRestricted()
      Returns whether this firmware is restricted to things with the model provided by the getModel() method.
      Returns:
      whether the firmware is restricted to a particular model

    • getDescription

      @Nullable String getDescription()
      Returns the description of the firmware.
      Returns:
      the description of the firmware (can be null)

    • getVersion

      String getVersion()
      Returns the version of the firmware.
      Returns:
      the version of the firmware (not null)

    • getPrerequisiteVersion

      @Nullable String getPrerequisiteVersion()
      Returns the prerequisite version of the firmware.

      A non-null prerequisite firmware version indicates that this firmware can only be installed on things for which the installed firmware has a version greater or equal to the prerequisite firmware version.

      Returns:
      the prerequisite version of the firmware (can be null)

    • getFirmwareRestriction

      FirmwareRestriction getFirmwareRestriction()
      Provides the restriction of the firmware as FirmwareRestriction function.
      Returns:
      the restriction of the firmware as FirmwareRestriction function (not null)

    • getChangelog

      @Nullable String getChangelog()
      Returns the changelog of the firmware.
      Returns:
      the changelog of the firmware (can be null)

    • getOnlineChangelog

      @Nullable URL getOnlineChangelog()
      Returns the URL to the online changelog of the firmware.
      Returns:
      the URL the an online changelog of the firmware (can be null)

    • getInputStream

      @Nullable InputStream getInputStream()
      Returns the input stream for the binary content of the firmware.
      Returns:
      the input stream for the binary content of the firmware (can be null)

    • getMd5Hash

      @Nullable String getMd5Hash()
      Returns the MD5 hash value of the firmware.
      Returns:
      the MD5 hash value of the firmware (can be null)

    • getBytes

      byte @Nullable [] getBytes()
      Returns the binary content of the firmware using the firmware´s input stream. If the firmware provides a MD5 hash value then this operation will also validate the MD5 checksum of the firmware.
      Returns:
      the binary content of the firmware (can be null)
      Throws:
      IllegalStateException - if the MD5 hash value of the firmware is invalid

    • getProperties

      Map<String,String> getProperties()
      Returns the immutable properties of the firmware.
      Returns:
      the immutable properties of the firmware (not null)

    • isSuccessorVersion

      boolean isSuccessorVersion(@Nullable String firmwareVersion)
      Returns true, if this firmware is a successor version of the given firmware version, otherwise false. If the given firmware version is null, then this operation will return false.
      Parameters:
      firmwareVersion - the firmware version to be compared
      Returns:
      true, if this firmware is a successor version for the given firmware version, otherwise false

    • isSuitableFor

      boolean isSuitableFor(Thing thing)
      Checks whether this firmware is suitable for the given thing.
      Parameters:
      thing - to be checked for suitability with the current firmware
      Returns:
      true if the current firmware is suitable for the given thing and false otherwise.