In This Topic

Introduction

The operation monitoring services in Rapid Toolkit for Sparkplug allow your code to receive information about the status of Sparkplug operations. The operation monitoring services are purely for informational purposes, diagnostics and troubleshooting; you absolutely do not have to use these services if you do not want to.

ISparkplugSystemConnectionMonitoring Interface

This interface is used when developing Sparkplug edge nodes, and is implemented and available as a component service on edge node objects (EasySparkplugEdgeNode Class) and device objects (SparkplugDevice Class).

Using the ISparkplugSystemConnectionMonitoring Interface, your code can get notified about the status of the connection to the Sparkplug system (MQTT broker). The notifications are delivered through the SystemConnectionStateChanged Event. The event arguments (SparkplugConnectionStateChangedEventArgs Class) contain various related information, such as:

ConnectionState Property: Indicates the state of the connection.
RetrialDelay Property: When disconnected, contains time to next reconnection attempt.
ClientId Property: The effective (MQTT) client ID.
ConnectionDescriptor Property: The Sparkplug connection descriptor (contains the MQTT broker address).

Practically all our examples for Sparkplug edge node development hook to the SystemConnectionStateChanged Event and display the incoming notifications, because it is a very useful tool for informing the user about the status of the program, and possible troubleshooting. The example below is a very simple Sparkplug edge node implementation with a single metric, and it shows the Sparkplug system connection notifications on the console.

// This example shows how to create a Sparkplug edge node with a single metric, start and stop it.
//
// You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
// program, to subscribe to the edge node data. 
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
// Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using OpcLabs.EasySparkplug;
using OpcLabs.EasySparkplug.OperationModel;

namespace SparkplugDocExamples.EdgeNode._EasySparkplugEdgeNode
{
    partial class Start_Stop
    {
        static public void Main1()
        {
            // Note that the default port for the "mqtt" scheme is 1883.
            var hostDescriptor = new SparkplugHostDescriptor("mqtt://localhost");

            // Instantiate the edge node object and hook events.
            var edgeNode = new EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo");
            edgeNode.SystemConnectionStateChanged += edgeNode_Main1_SystemConnectionStateChanged;

            // Define a metric providing random integers.
            var random = new Random();
            edgeNode.Metrics.Add(new SparkplugMetric("MyMetric").ReadValueFunction(() => random.Next()));

            // Start the edge node.
            Console.WriteLine("The edge node is starting...");
            edgeNode.Start();

            Console.WriteLine("The edge node is started.");
            Console.WriteLine();

            // Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...");
            Console.ReadLine();

            // Stop the edge node.
            Console.WriteLine("The edge node is stopping...");
            edgeNode.Stop();

            Console.WriteLine("The edge node is stopped.");
        }


        static void edgeNode_Main1_SystemConnectionStateChanged(
            object sender, 
            SparkplugConnectionStateChangedEventArgs eventArgs)
        {
            // Display the new connection state (such as when the connection to the broker succeeds or fails).
            Console.WriteLine($"{nameof(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}");
        }
    }
}

' This example shows how to create a Sparkplug edge node with a single metric, start and stop it.
'
' You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
' program, to subscribe to the edge node data.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
' Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasySparkplug
Imports OpcLabs.EasySparkplug.OperationModel

Namespace Global.SparkplugDocExamples.EdgeNode._EasySparkplugEdgeNode
    Partial Class Start_Stop
        Public Shared Sub Main1()
            ' Note that the default port for the "mqtt" scheme is 1883.
            Dim hostDescriptor = New SparkplugHostDescriptor("mqtt://localhost")

            ' Instantiate the edge node object and hook events.
            Dim edgeNode = New EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo")
            AddHandler edgeNode.SystemConnectionStateChanged, AddressOf edgeNode_Main1_SystemConnectionStateChanged

            ' Define a metric providing random integers.
            Dim random = New Random()
            edgeNode.Metrics.Add(New SparkplugMetric("MyMetric").ReadValueFunction(Function() random.Next()))

            ' Start the edge node.
            Console.WriteLine("The edge node is starting...")
            edgeNode.Start()

            Console.WriteLine("The edge node is started.")
            Console.WriteLine()

            ' Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...")
            Console.ReadLine()

            ' Stop the edge node.
            Console.WriteLine("The edge node is stopping...")
            edgeNode.Stop()

            Console.WriteLine("The edge node is stopped.")
        End Sub

        Private Shared Sub edgeNode_Main1_SystemConnectionStateChanged _
            (ByVal sender As Object, ByVal eventArgs As SparkplugConnectionStateChangedEventArgs)
            ' Display the new connection state (such as when the connection to the broker succeeds or fails).
            Console.WriteLine($"{NameOf(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}")
        End Sub
    End Class
End Namespace

ISparkplugProducerMonitoring Interface

This interface is used when developing Sparkplug edge nodes, and is available as a component service on edge node objects (EasySparkplugEdgeNode Class) and device objects (SparkplugDevice Class).

Using the ISparkplugProducerMonitoring service, your code can get notifications when the Sparkplug producer (edge node, or particular device on the edge node) is undergoing a birth, death, or rebirth sequence.

The Birth Event is raised when the producer is undergoing a birth sequence. This event is raised when the edge node or device is publishing the Birth payload. For edge node, this includes an edge node restart, but *not* an edge node rebirth.
The Death Event is raised when the producer is undergoing a death sequence. The death sequence can be initiated by multiple reasons, such as the graceful or ungraceful disconnection from the broker, or going offline of the primary host application.
The Rebirth Event is raised when the producer is undergoing a rebirth sequence. This event is raised when the edge node or device is publishing the Birth payload for a rebirth. For edge node, this includes edge node rebirth, but *not* an edge node restart.

Edge node restart involves disconnection and reconnection to the broker, and happens when the primary host application goes offline. Edge node rebirth happens upon reception of true value on the special "Node Control/Rebirth" metric, or when your code calls the PerformRebirth Method.

.NET

C#
VB.NET

// This example shows how to monitor birth, death, and rebirth of a Sparkplug edge node and its devices.
//
// You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
// program, to subscribe to the edge node data. 
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
// Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using Microsoft.Extensions.DependencyInjection;
using OpcLabs.EasySparkplug;
using System;
using OpcLabs.EasySparkplug.Services;

namespace SparkplugDocExamples.EdgeNode._SparkplugProducerMonitoring
{
    class EdgeNodeAndDevices
    {
        static public void Main1()
        {
            // Note that the default port for the "mqtt" scheme is 1883.
            var hostDescriptor = new SparkplugHostDescriptor("mqtt://localhost");

            // Instantiate the edge node object and hook events.
            var edgeNode = new EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo");
            edgeNode.SystemConnectionStateChanged += (sender, eventArgs) =>
            {
                // Display the new connection state (such as when the connection to the broker succeeds or fails).
                Console.WriteLine($"{nameof(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}");
            };

            // Define a metric providing random integers.
            var random = new Random();
            SparkplugMetric.CreateIn(edgeNode, "MyMetric").ReadValueFunction(() => random.Next());

            // Define two devices, each with a single metric providing random integers.
            SparkplugDevice myDevice1 = SparkplugDevice.CreateIn(edgeNode, "MyDevice1");
            SparkplugMetric.CreateIn(myDevice1, "MyMetric1").ReadValueFunction(() => random.Next());
            SparkplugDevice myDevice2 = SparkplugDevice.CreateIn(edgeNode, "MyDevice2");
            SparkplugMetric.CreateIn(myDevice2, "MyMetric2").ReadValueFunction(() => random.Next());

            // Obtain monitoring services and hook events to them.
            ISparkplugProducerMonitoring edgeNodeMonitoring = edgeNode.GetService<ISparkplugProducerMonitoring>();
            if (!(edgeNodeMonitoring is null))
            {
                // Monitor the edge node itself.
                edgeNodeMonitoring.Birth += (sender, eventArgs) =>
                    Console.WriteLine($"{sender}.{nameof(edgeNodeMonitoring.Birth)}");
                edgeNodeMonitoring.Death += (sender, eventArgs) =>
                    Console.WriteLine($"{sender}.{nameof(edgeNodeMonitoring.Death)}");
                edgeNodeMonitoring.Rebirth += (sender, eventArgs) =>
                    Console.WriteLine($"{sender}.{nameof(edgeNodeMonitoring.Rebirth)}");

                // Monitor all devices in the edge node.
                foreach (SparkplugDevice device in edgeNode.Devices)
                {
                    ISparkplugProducerMonitoring deviceMonitoring = device.GetService<ISparkplugProducerMonitoring>();
                    if (!(deviceMonitoring is null))
                    {
                        deviceMonitoring.Birth += (sender, eventArgs) =>
                            Console.WriteLine($"{sender}.{nameof(deviceMonitoring.Birth)}");
                        deviceMonitoring.Death += (sender, eventArgs) =>
                            Console.WriteLine($"{sender}.{nameof(deviceMonitoring.Death)}");
                        deviceMonitoring.Rebirth += (sender, eventArgs) =>
                            Console.WriteLine($"{sender}.{nameof(deviceMonitoring.Rebirth)}");
                    }
                }
            }

            // Start the edge node.
            Console.WriteLine("The edge node is starting...");
            edgeNode.Start();

            Console.WriteLine("The edge node is started.");
            Console.WriteLine();

            // Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...");
            Console.ReadLine();

            // Stop the edge node.
            Console.WriteLine("The edge node is stopping...");
            edgeNode.Stop();

            Console.WriteLine("The edge node is stopped.");
        }
    }
}

' This example shows how to monitor birth, death, and rebirth of a Sparkplug edge node and its devices.
'
' You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
' program, to subscribe to the edge node data.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
' Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports Microsoft.Extensions.DependencyInjection
Imports OpcLabs.EasySparkplug
Imports OpcLabs.EasySparkplug.Services

Namespace Global.SparkplugDocExamples.EdgeNode._SparkplugProducerMonitoring
    Class EdgeNodeAndDevices
        Public Shared Sub Main1()
            ' Note that the default port for the "mqtt" scheme is 1883.
            Dim hostDescriptor = New SparkplugHostDescriptor("mqtt://localhost")

            ' Instantiate the edge node object and hook events.
            Dim edgeNode = New EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo")
            AddHandler edgeNode.SystemConnectionStateChanged,
                Sub(sender, eventArgs)
                    ' Display the new connection state (such as when the connection to the broker succeeds or fails).
                    Console.WriteLine($"{NameOf(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}")
                End Sub

            ' Define a metric providing random integers.
            Dim random = New Random()
            SparkplugMetric.CreateIn(edgeNode, "MyMetric").ReadValueFunction(Function() random.Next())

            ' Define two devices, each with a single metric providing random integers.
            Dim myDevice1 As SparkplugDevice = SparkplugDevice.CreateIn(edgeNode, "MyDevice1")
            SparkplugMetric.CreateIn(myDevice1, "MyMetric1").ReadValueFunction(Function() random.Next())
            Dim myDevice2 As SparkplugDevice = SparkplugDevice.CreateIn(edgeNode, "MyDevice2")
            SparkplugMetric.CreateIn(myDevice2, "MyMetric2").ReadValueFunction(Function() random.Next())

            ' Obtain monitoring services and hook events to them.
            Dim edgeNodeMonitoring As ISparkplugProducerMonitoring = edgeNode.GetService(Of ISparkplugProducerMonitoring)()
            If Not edgeNodeMonitoring Is Nothing Then
                ' Monitor the edge node itself.
                AddHandler edgeNodeMonitoring.Birth, Sub(sender, EventArgs) _
                    Console.WriteLine($"{sender}.{NameOf(edgeNodeMonitoring.Birth)}")
                AddHandler edgeNodeMonitoring.Death, Sub(sender, EventArgs) _
                    Console.WriteLine($"{sender}.{NameOf(edgeNodeMonitoring.Death)}")
                AddHandler edgeNodeMonitoring.Rebirth, Sub(sender, EventArgs) _
                    Console.WriteLine($"{sender}.{NameOf(edgeNodeMonitoring.Rebirth)}")

                ' Monitor all devices in the edge node.
                For Each device As SparkplugDevice In edgeNode.Devices
                    Dim deviceMonitoring As ISparkplugProducerMonitoring = device.GetService(Of ISparkplugProducerMonitoring)()
                    If Not deviceMonitoring Is Nothing Then
                        AddHandler deviceMonitoring.Birth, Sub(sender, eventArgs) _
                            Console.WriteLine($"{sender}.{NameOf(deviceMonitoring.Birth)}")
                        AddHandler deviceMonitoring.Death, Sub(sender, eventArgs) _
                            Console.WriteLine($"{sender}.{NameOf(deviceMonitoring.Death)}")
                        AddHandler deviceMonitoring.Rebirth, Sub(sender, eventArgs) _
                            Console.WriteLine($"{sender}.{NameOf(deviceMonitoring.Rebirth)}")
                    End If
                Next
            End If

            ' Start the edge node.
            Console.WriteLine("The edge node is starting...")
            edgeNode.Start()

            Console.WriteLine("The edge node is started.")
            Console.WriteLine()

            ' Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...")
            Console.ReadLine()

            ' Stop the edge node.
            Console.WriteLine("The edge node is stopping...")
            edgeNode.Stop()

            Console.WriteLine("The edge node is stopped.")
        End Sub
    End Class
End Namespace

Sparkplug is a trademark of Eclipse Foundation, Inc. "MQTT" is a trademark of the OASIS Open standards consortium. Other related terms are trademarks of their respective owners. Any use of these terms on this site is for descriptive purposes only and does not imply any sponsorship, endorsement or affiliation.