In This Topic

General

In the pull data consumption model, the Sparkplug commands ("Writes") received by the edge node or device simply store the command data into the metric object. You then write an independently running code that retrieves (pulls) the data from the metric(s), and sends the data to the underlying system.

Rapid Toolkit for Sparkplug stores the data written to the metric in its WriteData Property. Your code retrieves the written data by getting the value of this property. When and how it is done is completely up to you, and depends highly on the specifics of the Sparkplug edge node you are developing. In many cases, the retrieval will be based on some kind of periodic timer. In other scenarios, it may be triggered by the underlying system or connected device.

The pull data consumption model is inherently asynchronous, i.e. the actual data writing to the underlying system happens independently of the actual Sparkplug command timing. This means that the actual writing occurs at possibly later time, after the Sparkplug command itself is processed. The pull data consumption model can therefore be only used in applications where this behavior does not pose a problem.

Conversely, the advantage of the pull data consumption model is that Sparkplug commands are fulfilled very quickly, as the code that sends the data to the underlying system cannot "block" their processing.

The following picture illustrates how the pull data consumption model works.

// This example shows how to retrieve the metric data in the pull data consumption model. In this model, the data that
// Sparkplug applications send to the edge node or device is pulled and processed by your code when needed.
//
// You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
// program, to subscribe to the edge node data. SparkplugCmd, or other capable Sparkplug application, can be used to write
// data into the metric.
//
// 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 OpcLabs.EasySparkplug;
using System;
using Timer = System.Timers.Timer;

namespace SparkplugDocExamples.EdgeNode._SparkplugMetric
{
    class WriteData
    {
        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}");
            };

            // Create a read-write data variable with an initial value.
            var metric = SparkplugMetric.CreateIn(edgeNode, "WriteToThisMetric").ReadWriteValue(0);

            // Create a timer for pulling the data from OPC writes. In a real server the activity may also come from other
            // sources.
            var timer = new Timer
            {
                Interval = 1000,    // 1 second
                AutoReset = true,
            };

            // Periodically display the value of the metric on the console.
            timer.Elapsed += (sender, args) => Console.Write($"  {metric.WriteData.Value}");
            timer.Start();
            Console.WriteLine("Values of the example metric are displayed on the console periodically.");

            // 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.");
            
            // Stop the timer.
            timer.Stop();
        }
    }
}

' This example shows how to retrieve the metric data in the pull data consumption model. In this model, the data that
' Sparkplug applications send to the edge node or device is pulled and processed by your code when needed.
'
' You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
' program, to subscribe to the edge node data. SparkplugCmd, or other capable Sparkplug application, can be used to write
' data into the metric.
'
' 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 Timer = System.Timers.Timer

Namespace Global.SparkplugDocExamples.EdgeNode._SparkplugMetric
    Class WriteData
        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

            ' Create a read-write data variable with an initial value.
            Dim metric = SparkplugMetric.CreateIn(edgeNode, "WriteToThisMetric").ReadWriteValue(0)

            ' Create a timer for pulling the data from OPC writes. In a real server the activity may also come from other
            ' sources.
            Dim timer = New Timer With
            {
                .Interval = 1000, ' 1 second
                .AutoReset = True
            }

            ' Periodically display the value of the metric on the console.
            AddHandler timer.Elapsed, Sub(s, a) Console.Write($"  {metric.WriteData.Value}")
            timer.Start()
            Console.WriteLine("Values of the example metric are displayed on the console periodically.")

            ' 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.")

            ' Stop the timer.
            timer.Stop()
        End Sub
    End Class
End Namespace

Initial Data

When using the pull data consumption model, in general, you are responsible for providing the initial contents of the WriteData Property. Make sure you have a reasonable contents even before your code first gets a chance to pull the metric data and process it. WIthout further configuration, the WriteData Property contains empty data - meaning that there is no timestamp, and the value itself is null. This may not be what you want - especially with non-nullable types where null is not even a valid value for the data type of your metric. You always need to specify initial data that make sense for your edge node or device.

Many extension methods for Sparkplug Metric Configuration already initialize the WriteData Property at least to the default value for the given data type. This assures that the initial value is valid for that data type, but it still may not be the "right" value for your edge node or device. Some metric configuration extension methods (such as the ReadWriteValue Method) allow you (and force you to) specify the initial data (or just the value) directly as an argument in the method call.

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.