Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hivemq/hivemq-sparkplug-influxdb-extension

Sparkplug extension, that enables you to monitor device and edge node data in an IIoT Sparkplug environment.
https://github.com/hivemq/hivemq-sparkplug-influxdb-extension

Last synced: 5 days ago
JSON representation

Sparkplug extension, that enables you to monitor device and edge node data in an IIoT Sparkplug environment.

Awesome Lists containing this project

README 

        
:hivemq-link: https://www.hivemq.com

:hivemq-support: {hivemq-link}/support/

:sparkplug-link: https://sparkplug.eclipse.org/

:influxdb-link: https://www.influxdata.com/time-series-platform/influxdb/

:docker: https://www.docker.com/

:influxdb-docker: https://hub.docker.com/_/influxdb/



= Sparkplug InfluxDB Extension for HiveMQ



image::/img/HiveMQSparkplugExtension.jpg[Logo]



image:https://img.shields.io/badge/Extension_Type-IIOT_Monitoring-orange?style=for-the-badge[Extension Type]

//image:https://img.shields.io/github/v/release/hivemq/hivemq-sparkplug-influxdb-extension?style=for-the-badge[GitHub release (latest by date),link=https://github.com/hivemq/hivemq-sparkplug-influxdb-extension/releases/latest]

image:https://img.shields.io/github/license/hivemq/hivemq-sparkplug-influxdb-extension?style=for-the-badge&color=brightgreen[GitHub,link=LICENSE]

image:https://img.shields.io/github/actions/workflow/status/hivemq/hivemq-sparkplug-influxdb-extension/check.yml?branch=master&style=for-the-badge[GitHub Workflow Status,link=https://github.com/hivemq/hivemq-sparkplug-influxdb-extension/actions/workflows/check.yml?query=branch%3Amaster]



== Purpose



The HiveMQ {sparkplug-link}[Sparkplug^] Extension can be leveraged to gather sparkplug metrics from {hivemq-link}[HiveMQ^] and persist them into a {influxdb-link}[InfluxDB^] database.

This database can be used as the data source for a monitoring dashboard to monitor directly the data from the devices and gateways of a Sparkplug Infrastructure.



#**This extension is not yet ready for production use.**#



If you want use this in production, please contact HiveMQ [email protected]



== Flow



image::/img/HiveMQExtensionFlow.jpg[Flow]



== Installation



Installing the extension for HiveMQ is very easy:



. Unzip the downloaded zip file

. In the folder `hivemq-sparkplug-extension`, modify the `sparkplug.properties` file to fit your needs.

Check that the mandatory properties for influx db (host, port) are set

. Copy the folder `hivemq-sparkplug-extension` to your `[HIVEMQ_HOME]/extensions` folder

. Done



== Configuration



The Sparkplug Monitoring extension uses its own configuration file `sparkplug.properties`.

The extension won't start if this file is missing or the required properties are not set.



=== Dashboards



2 InfluxDB example dashboards are provided in the `deploy` subfolder of this extension.



|===

| Influx dashboard | Description

| HiveMQInfluxDB-Dashboard.json | HiveMQ dashboard with the most useful hivemq metrics

| SparkplugInfluxDB-Dashboard.json | Sparkplug example dashboard, that vizualizes data of 2 edge nodes and their related devices.

|===



image::/img/SparkplugDashboard.jpg[Dashboard]



=== General Configuration



|===

| Config name | Required | Description | Default



| influxdb.mode | no | The mode configured for the InfluxDB sender.

Possibilities are: http, tcp, udp, cloud | http

| influxdb.host | yes | The host name of the InfluxDB instance. | -

| influxdb.port | yes | The port number the InfluxDB instance is listening. | 8086

| influxdb.protocol | no | The protocol the InfluxDB sender uses in http mode. | http

| influxdb.auth | no | The authorization string to be used to connect to InfluxDB, of format username:password.

If mode "cloud" is used, the token must be passed here| -

| influxdb.prefix | no | The measurement prefix. | -

| influxdb.database | no | The database name. | hivemq

| influxdb.reportingInterval | no | The reporting interval in seconds. | 1

| influxdb.connectTimeout | no | The connect and read timeout in seconds. | 5000

| influxdb.tags | no | The tags for each metric.

Listed as a semicolon ( `;` ) separated list. | -

| influxdb.organization | only for mode: "cloud" | The organization to push data to | -

| influxdb.bucket | only for mode: "cloud" | The bucket to push data to | -

| sparkplug.version | no | The sparkplug version to be used | spBv1.0



|===



.Example Configuration to connect to a local influxdb 2.0

[source]

----

influxdb.mode:cloud

influxdb.host:localhost

influxdb.port:8086

influxdb.protocol:http

influxdb.auth:



influxdb.bucket:hivemq

influxdb.organization:



influxdb.reportingInterval:1

influxdb.connectTimeout:5000



influxdb.tags:host=localhost

----



== First Steps



=== InfluxDB Setup



If you don't already have an InfluxDB 2.0 instance set up, here is a instruction how to start and configure an InfluxDB instance with Docker.



. Download and install {docker}[Docker^] for your platform

. Start an InfluxDB docker container with the command `docker run -p 8086:8086 -v $PWD:/var/lib/influxdb influxdb`.

For more information about using InfluxDB with Docker visit the {influxdb-docker}[official Docker repository^] for InfluxDB

. A local instance of InfluxDB should be running with the port for the database set to 8086

. The initial setup process for InfluxDB walks through creating a default organization, user, bucket, and Admin authentication token.

The setup process is available in both the InfluxDB user interface (UI) and in the influx command line interface (CLI).

. UI Setup - With InfluxDB running, visit localhost:8086.

.. Click Get Started

.. Set up your initial user

.. Enter a Username for your initial user.

.. Enter a Password and Confirm Password for your user.

.. Enter your initial Organization Name.

.. Enter your initial Bucket Name.

.. Click Continue.

. Done



=== Sparkplug Setup



The Extensions actual supports the Sparkplug B specification for payload.

The sparkplug schema is defined with protobuf.



=== Usage



After the extension is installed and an InfluxDB instance exists.



. Start HiveMQ

. Extension successfully started if configuration file exists and contains required properties



=== Example Deployment



For testing purposes a simple HiveMQ docker file with the sparkplug extension and a compose file for influxDB setup is available in the deploy/docker subfolder.

Further a Kubernetes script for deploying hivemq with sparkplug extension setup in Kuberntes is available in the deploy/k8s



=== Influx Dashboard



An influx dashboard example *SparkplugInfluxDB-Dashboard.json* is available in the deploy subfolder.

The dashboard contains diagrams to monitor the Sparkplug online status of edge nodes and devices.

It also gathered the sparkplug data values from the example devices.



== Need Help?



If you encounter any problems, we are happy to help.

The best place to get in contact is our {hivemq-support}[support^].



== Contributing



If you want to contribute to HiveMQ Sparkplug Extension, see the link:CONTRIBUTING.md[contribution guidelines].



== License



HiveMQ Sparkplug Extension is licensed under the `APACHE LICENSE, VERSION 2.0`.

A copy of the license can be found link:LICENSE[here].