Skip to content

Latest commit

 

History

History
213 lines (138 loc) · 7.91 KB

README.adoc

File metadata and controls

213 lines (138 loc) · 7.91 KB
Raw

HiveMQ Edge

GitHub Workflow Status (with branch)

HiveMQ Edge is a Java-based open-source, modular, secure by design platform which consolidates industrial workloads, unifying them into open-standards MQTT to connect to the enterprise. Seamlessly defining UNS by deployment, using targeted data model & transformation plugins, allows IT and OT to unify and ‘control by policy’, data collected at the Edge.

It is a Java-based open source MQTT and MQTT-SN broker that fully supports MQTT 3.x,5 and MQTT-SN 1.2.

edge intro
Figure 1. Edge Intro

When you deploy HiveMQ Edge using Docker, you will have a preview of commercially licensed features.

Features

  • Converters for OPC UA, Modbus, and other protocols into MQTT messages

  • All MQTT 3.1, 3.1.1 and MQTT 5.0 features

  • MQTT over TCP, TLS, WebSocket and Secure WebSocket transport

  • Integrated MQTT-SN gateway allowing constrained devices to access the MQTT broker.

  • Bidirectional MQTT bridge functionality to connect to enterprise MQTT brokers

  • Java Extension SDK for:

    • Authentication

    • Authorization

    • Client Initializers

    • MQTT Packet Interceptors

    • Interacting with Publishes, Retained Messages, Clients and Subscriptions

  • Running on Windows, Linux and MacOS (Linux is recommended)

MQTT Broker

HiveMQ Edge incorporates a fully standards compliant MQTT broker. Connect your devices to the broker to subscribe and gain access to data obtained from devices on the Edge.

HiveMQ Edge is compatible with all MQTT 3.x and MQTT 5 clients, including Eclipse Paho and HiveMQ MQTT Client.

MQTT-SN Gateway

HiveMQ Edge incorporates an MQTT-SN gateway allowing constrained devices to access the MQTT broker.

MQTT-SN is an optimized version of the MQTT specification designed for use on small, low powered, sensor devices, often running on the edge of the network; typical of the IoT.

Protocol Adapters

A protocol adapter contributes code to connect to PLCs and converts the data retrieved from these devices into MQTT messages which are PUBLISHED into the local MQTT broker. More Protocol adapters will be added to the project over time.

  • OPC UA

  • Modbus

  • Siemens S7

  • Beckhoff ADS

  • Allen-Bradley Ethernet/IP

  • HTTP

  • File-input

  • and many more

MQTT Bridging

HiveMQ allows you to backhaul your data into an enterprise broker using MQTT bridges. Connect any number of bridges to transport Edge data upstream. By connecting Edge to enterprise MQTT brokers like HiveMQ you can build a flexible Unified Namespace (UNS) solution based on open standards.

Documentation

The documentation for the HiveMQ Edge can be found here.

Additional Resources

HiveMQ Community Forum

The ideal place for questions or discussions about the HiveMQ Edge Edition is our brand new HiveMQ Community Forum.

How to Use

Quick Start

  • Download the latest HiveMQ Edge binary package.

  • Unzip the package.

  • Run the run.sh (Linux/OSX) or run.bat (Windows) in the bin folder of the package.

cd hivemq-edge-<version>
bin/run.sh
Important
 At least Java version 11 is required to run HiveMQ Edge. If you are in doubt, you can check the installed Java version by entering java -version on your command line.

You can now connect MQTT clients to <ip address>:1883.

Caution
 If you want to connect devices on external networks to HiveMQ Edge, please make sure your server is reachable from those networks and the required ports (default: 1883) are accessible through your firewall.

Run with Docker

All releases are available in the hivemq/hivemq-edge repository on DockerHub. To execute this image, simply run the following command:

docker run --name hivemq-edge -d -p 1883:1883 -p 8080:8080 hivemq/hivemq-edge

When the container is running you can connect MQTT clients at port 1883 and access the UI at http://localhost:8080/.

Default credentials for the UI are user: admin, password: hivemq

To run the current state of master branch instead of the latest released version you can use the snapshot tag.

docker run --name hivemq-edge -p 1883:1883 -p 8080:8080 hivemq/hivemq-edge:snapshot

To change the default log level you can set the environment variable HIVEMQ_LOG_LEVEL when running the container:

docker run --name hivemq-edge -e HIVEMQ_LOG_LEVEL=INFO -d -p 1883:1883 -p 8080:8080 hivemq/hivemq-edge

Building from Source

Building the Binary Package

Check out the git repository and build the binary package.

git clone https://github.com/hivemq/hivemq-edge.git

cd hivemq-edge

./gradlew :hivemqEdgeZip

The package hivemq-edge-<version>.zip is created in the sub-folder build/distributions/.

Building the Docker Image

Check out the git repository and build the Docker image.

git clone https://github.com/hivemq/hivemq-edge.git

cd hivemq-edge

docker/build.sh

The Docker image hivemq/hivemq-edge:snapshot is created locally.

For further development instructions see the contribution guidelines.

Contributing

If you want to contribute to HiveMQ Edge, see the contribution guidelines.

License

HiveMQ Edge is licensed under the APACHE LICENSE, VERSION 2.0. A copy of the license can be found here.

Privacy settings

HiveMQ Edge uses a limited number of tracking technologies within the web application. These technologies enable us to analyse usage behavior within the Edge product, in order to measure and improve performance.

The following technologies are currently configured:

A consent form will be displayed in the browser at first usage. Opt-in or pot-out will be recorded into the local storage of the browser and the tracker activated - or not - accordingly.

There are two ways you can opt-out before installation and running:

  • modify the Edge configuration via the config.xml (the usage-tracking property allows corporate-wide consent)

Example configuration to disable usage tracking centrally for all users
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <usage-tracking>
        <enabled>false</enabled>
    </usage-tracking>
</hivemq>

  • modify the frontend configuration (the VITE_MONITORING_????? properties in the ./.env file contains HiveMQ unique application id required to activate the different trackers).

Note that you can also change the VITE_MONITORING_????? values to your own account(s) if you use any. It will allow you to collect behaviour on your own infrastructure