HiveMQ Edge Upgrade Guide

HiveMQ Edge is prepackaged with all HiveMQ Edge Commercial Modules, HiveMQ Data Hub and all protocol adapters.

When you migrate from one HiveMQ Edge version to another, we recommend that you review the upgrade information for each version between your current HiveMQ Edge version and the target HiveMQ Edge version.
Note changes that are relevant to your use case and adjust your configuration as needed.

HiveMQ Edge 2024.7 to 2024.8 Migration Guide

HiveMQ Edge 2024.8 is a major version that brings many improvements and features. The configuration files has been changed from 2024.7 to 2024.8. However, at startup, HiveMQ Edge 2024.8 will automatically upgrade your existing configuration. Please make sure your configuration is writeable.

HiveMQ Edge Southbound Feature

HiveMQ Edge 2024.8 introduces southbound communication features. Several additions to the SDK makes it easier to implement the functionalities described in the following section.

Adapter SDK changes

Introduction of tags

HiveMQ Edge 2024.8 introduces the concept of tags. Tags are structured objects that are very similar to every protocol adapter. The definition part of a tag is different for every protocol adapter, since every protocol adapter implements the read and write capabilities according to the protocol. For example, the definition for OPC UA is shown below:

public class OpcuaTag implements Tag {

    @JsonProperty(value = "name", required = true)
    @ModuleConfigField(title = "name",
                       description = "name of the tag to be used in mappings",
                       format = ModuleConfigField.FieldType.MQTT_TAG,
                       required = true)
    private final @NotNull String name;

    @JsonProperty(value = "description")
    @ModuleConfigField(title = "description",
                       description = "A human readable description of the tag")
    private final @NotNull String description;

    @JsonProperty(value = "definition", required = true)
    @ModuleConfigField(title = "definition",
                       description = "The actual definition of the tag on the device")
    private final @NotNull OpcuaTagDefinition definition;

    public OpcuaTag(
            @JsonProperty(value = "name", required = true) final @NotNull String name,
            @JsonProperty(value = "description") final @Nullable String description,
            @JsonProperty(value = "definition", required = true) final @NotNull OpcuaTagDefinition definiton) {
        this.name = name;
        this.description = Objects.requireNonNullElse(description, "no description present.");
        this.definition = definiton;
    }
     // truncated
}

The example tag definition contains the nodeId on the OpcUa server:

public class OpcuaTagDefinition implements TagDefinition {

    @JsonProperty(value = "node", required = true)
    @ModuleConfigField(title = "Destination Node ID",
                       description = "identifier of the node on the OPC UA server. Example: \"ns=3;s=85/0:Temperature\"",
                       required = true)
    private final @NotNull String node;

    @JsonCreator
    public OpcuaTagDefinition(@JsonProperty(value = "node", required = true) final @NotNull String node) {
        this.node = node;
    }
     // truncated
}

Changes in the Configuration of the Adapter

The mapping from PLC to MQTT was removed from the authority of each adapter and is now implemented as a streamlined configuration (Northbound). This reduces the complexity of each adapter configuration and offers a common place to define mappings from PLC to MQTT (Northbound).

Rename of the ProtocolAdapterConfig interface to ProtocolSpecificAdapterConfig

As a result, the interface for the configuration for adapter was renamed to indicate that only the protocol specific configuration (e.g. how the adapter connects to the PLC) is contained:

public class HelloWorldAdapterConfig implements ProtocolAdapterConfig {

was changed to

public class HelloWorldAdapterConfig implements ProtocolSpecificAdapterConfig {

Changes in the id field in the configuration

The getId()-method is no longer inside the ProtocolSpecificAdapterConfig interface. Instead, the Id will be handled by Edge and supplied in the ProtocolAdapterInput, which is an argument for the constructor of the ProtocolAdapter:

    public HelloWorldSubscribingProtocolAdapter(
            final @NotNull ProtocolAdapterInformation adapterInformation, final @NotNull ProtocolAdapterInput<HelloWorldAdapterConfig> input) {
        this.adapterId = input.getAdapterId();
        this.adapterInformation = adapterInformation;
        this.adapterConfig = input.getConfig();
        this.protocolAdapterState = input.getProtocolAdapterState();
        this.adapterFactories = input.adapterFactories();
    }

The Id must still be defined in the configuration class for the generation of the form in the frontend. The field itself must not be used and it purely exists for the JsonSchema definition.

public class HelloWorldAdapterConfig implements ProtocolSpecificAdapterConfig {
    @JsonProperty(value = "id", required = true)
    @ModuleConfigField(title = "Identifier",
            description = "Unique identifier for this protocol adapter",
            format = ModuleConfigField.FieldType.IDENTIFIER,
            required = true,
            stringPattern = ID_REGEX,
            stringMinLength = 1,
            stringMaxLength = 1024)
    protected @NotNull String id;

Removal of the PollingContext field

As the ProtocolSpecificAdapterConfig is no longer responsible for any mappings, the List<PollingContext> must be removed:

    @JsonProperty("subscriptions")
    @ModuleConfigField(title = "subscription", description = "Map your sensor data to a MQTT Topic")
    private @NotNull List<HelloWorldPollingContext> pollingContexts = new ArrayList<>();

Changes for the ProtocolAdapter class

As the mappings are now streamlined and handled by HiveMQ Edge, there is no need for defining the concrete PollingContext implementation as a Generic of the PollingProtocolAdapter class:

public class HelloWorldPollingProtocolAdapter implements PollingProtocolAdapter<HelloWorldPollingContext>

now:

public class HelloWorldPollingProtocolAdapter implements PollingProtocolAdapter

This also leads to change in the signature of the poll() - method

    @Override
    public void poll(final @NotNull PollingInput<HelloWorldPollingContext> pollingInput, final @NotNull PollingOutput pollingOutput) {

now:

    public void poll(final @NotNull PollingInput pollingInput, final @NotNull PollingOutput pollingOutput) {

If any protocol specific information is needed, it must be added to the implementation of the ProtocolSpecificAdapterConfig. Examples of how to do that can be found in the official protocol adapter implementations at GitHub.

As Edge controls now the northbound mappings, there is no need for the method to get the former PollingContexts and this method is now removed:

    @Override
    public @NotNull List<HelloWorldPollingContext> getPollingContexts() {
        return pollingContext;
    }

Finally, the field that held the PollinContexts for an adapter can be removed:

private final @NotNull List<HelloWorldPollingContext> pollingContext;

Removal of the PollingContext implementation

Because the adapter does not handle the PollingContext and their parsing anymore, the implementation for the PollingContext is no longer needed and can be deleted:

public class HelloWorldPollingContext implements PollingContext {
    @JsonProperty(value = "destination", required = true)
    @ModuleConfigField(title = "Destination Topic",
            description = "The topic to publish data on",
            required = true,
            format = ModuleConfigField.FieldType.MQTT_TOPIC)
    protected @Nullable String destination;
    // truncated

Changes in the ProtocolAdapterFactory interface

The method to get the configuration class of an adapter was moved to the AdapterInformation class and is no longer part of the interface:

public class HelloWorldProtocolAdapterFactory implements ProtocolAdapterFactory<HelloWorldAdapterConfig> {
    // this is no longer part of the interface:
    @Override
    public @NotNull Class<HelloWorldAdapterConfig> getConfigClass() {
        return HelloWorldAdapterConfig.class;
    }
}

Changes in the ProtocolAdapterFactory interface

Specification of the configuration classes

As HiveMQ Edge now supports northbound and southbound protocol adapters, there is the need to have two configuration classes if the adapter supports bidirectional. One configuration if only northbound is available and another one if both directions are enabled. The configuration that supports both directions should extend the configuration that only allows Northbound traffic. If the adapter only allows northbound for now, both methods should return the Northbound configuration:

    @Override
    public @NotNull Class<? extends ProtocolSpecificAdapterConfig> configurationClassNorthbound() {
        return HelloWorldAdapterConfig.class;
    }

    @Override
    public @NotNull Class<? extends ProtocolSpecificAdapterConfig> configurationClassNorthAndSouthbound() {
        return HelloWorldAdapterConfig.class;
    }

Specification of the Tag implementation

HiveMQ Edge needs to know how to parse the Tag implementation for each adapter and therefore the implementing class needs to be returned to Edge via the tagConfigurationClass-method.

    @Override
    public @NotNull Class<? extends Tag> tagConfigurationClass() {
        return HelloWorldAdapterTag.class;
    }

HiveMQ Edge 2024.5.x to 2024.6 Migration Guide

This is a minor HiveMQ Edge upgrade. HiveMQ Edge 2024.6 is a drop in replacement for HiveMQ Edge 2024.5.

You can learn more about all the new features HiveMQ Edge 2024.6 introduces in our release blogpost.

Upgrade a HiveMQ Edge installation

Create a backup of the entire HiveMQ Edge 2024.5 installation folder from which you want to migrate.
Install HiveMQ Edge 2024.6 as described in the HiveMQ Edge Installation Guide.
Migrate the content of the config.xml and license files from your old HiveMQ Edge 2024.5 installation.
To migrate your persistent data, copy everything from the data folder of your backup to the data folder of the new HiveMQ Edge 2024.6 installation.

HiveMQ Edge Configuration File Changes

No changes.

HiveMQ Edge Persistent Data Migration

When you migrate, HiveMQ Edge 2024.5 automatically updates the file storage formats of all the data that you copied into your new data folder.

To migrate the persistent data, you must copy everything in the data folder of the previous HiveMQ Edge 2024.5 installation to the data folder of your new HiveMQ Edge 2024.6 installation.

Linux example

cp -r /opt/hivemq-edge-2024.5/data/* /opt/hivemq-edge-2024.6/data/

The first time you start HiveMQ Edge 2024.6, the file storage formats of the persistent data from your previous installation are automatically updated in the new persistent storage.

Breaking Change in the Adapter Discovery API

HiveMQ Edge 2024.6 changes the return type of the discoverValues() method from CompletableFuture<Void> to void. Use the ProtocolAdapterDiscoveryOutput object to signal Edge the progress of the discovery.

Before:

@NotNull CompletableFuture<Void> discoverValues(
    @NotNull ProtocolAdapterDiscoveryInput input,
    @NotNull ProtocolAdapterDiscoveryOutput output);

After:

void discoverValues(
    @NotNull ProtocolAdapterDiscoveryInput input,
    @NotNull ProtocolAdapterDiscoveryOutput output);