From 8690b85931d5d481b1ecf51288fa01b7b332f265 Mon Sep 17 00:00:00 2001 From: wes-johnson Date: Mon, 9 Jun 2025 14:16:06 -0700 Subject: [PATCH 1/2] [#145] Made quality a top level metric member and added quality context --- .github/workflows/build.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 34d35d66..16e47da0 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -41,14 +41,14 @@ jobs: run: ./gradlew build - name: Upload specification artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: sparkplug_spec path: specification/build/docs/pdf/sparkplug_spec.pdf if-no-files-found: error - name: Upload coverage artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: coverage-report path: tck/build/coverage-report/**/* From 799868224903ab2460f9e699ca29988409fa6539 Mon Sep 17 00:00:00 2001 From: wes-johnson Date: Mon, 9 Jun 2025 15:30:58 -0700 Subject: [PATCH 2/2] [#174] Clarified Edge Node/MQTT Enabled Devices in the specification --- .../plantuml/infrastructure-components.puml | 8 ++-- .../chapters/Sparkplug_1_Introduction.adoc | 18 ++++----- .../chapters/Sparkplug_2_Principles.adoc | 23 ++++++----- .../chapters/Sparkplug_3_Components.adoc | 40 +++++++++++-------- .../asciidoc/chapters/Sparkplug_4_Topics.adoc | 4 +- .../Sparkplug_5_Operational_Behavior.adoc | 2 +- .../chapters/Sparkplug_6_Payloads.adoc | 4 +- 7 files changed, 53 insertions(+), 46 deletions(-) diff --git a/specification/src/main/asciidoc/assets/plantuml/infrastructure-components.puml b/specification/src/main/asciidoc/assets/plantuml/infrastructure-components.puml index 5d138f39..2cdb0b9b 100644 --- a/specification/src/main/asciidoc/assets/plantuml/infrastructure-components.puml +++ b/specification/src/main/asciidoc/assets/plantuml/infrastructure-components.puml @@ -96,13 +96,13 @@ package "Security" { ] card Node1Device1 [ - "" Device "" + "" PLC "" ] card Node1Sensor1 [ "" Sensor "" ] card Node1Device2 [ - "" Device "" + "" RTU "" ] } @@ -112,7 +112,7 @@ package "Security" { ""(Sparkplug)"" ] card Node2Device [ - "" Device "" + "" RTU "" ] } @@ -122,7 +122,7 @@ package "Security" { ""(Sparkplug)"" ] card Node3Device [ - "" Device "" + "" PLC "" ] } diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc index b641bfdf..7253e077 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc @@ -240,20 +240,20 @@ I/O, and/or any logical internal process variables (PVs). Physical or logical device that makes sense in the context of a distributed Sparkplug application. Often times a Sparkplug Device will be a physical PLC, RTU, Flow Computer, Sensor, etc. However, a -Sparkplug device could also represent a logical grouping of data points as makes sense for the +Sparkplug Device could also represent a logical grouping of data points as makes sense for the specific Sparkplug Application being developed. For example, it could represent a set of data points across multiple PLCs that make up a logical device that makes sense within the context of that application. -[[introduction_mqtt_sparkplug_enabled_device]] -===== MQTT/Sparkplug Enabled Device +[[introduction_mqtt_sparkplug_enabled_component]] +===== MQTT/Sparkplug Enabled Component -Any device, sensor, or hardware that directly connects to MQTT infrastructure using -a compliant MQTT v3.1.1 or v5.0 connection with the payload and topic notation as outlined in this -Sparkplug Specification. With MQTT/Sparkplug enabled directly in the device this could bypass the -use of a Sparkplug Edge Node in the infrastructure. In this case, the physical device or sensor is -the Edge Node. It is up to the developer of the application to decide if the concept of a 'Sparkplug -Device' is to be used within their application. +Any sensor or hardware component that directly connects to MQTT infrastructure using a compliant MQTT +v3.1.1 or v5.0 connection with the payload and topic notation as outlined in this Sparkplug +Specification. With MQTT/Sparkplug enabled directly in the component, the application could omit the +use of a 'Sparkplug Device'. In this case, the physical component is represented by a Sparkplug +Edge Node without any attached Sparkplug Devices. It is up to the developer of the application to +decide if the concept of a 'Sparkplug Device' is to be used within their application. [[introduction_host_applications]] ===== Host Applications diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_2_Principles.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_2_Principles.adoc index c150d284..ee8d1c2e 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_2_Principles.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_2_Principles.adoc @@ -109,19 +109,20 @@ link:#payloads_b_state[Host Application Birth Certificates] === Persistent vs Non-Persistent Connections for Edge Nodes Persistent connections are intended to remain connected to the MQTT infrastructure at all times. -They never send an MQTT DISCONNECT control packet [MQTTV5-3.14] during normal operation. This fact lets the -Host Applications provide the real-time state of every persistent node in the infrastructure within -the configured MQTT Keep Alive period using the BIRTH/DEATH mechanisms defined above. +They never send an MQTT DISCONNECT control packet [MQTTV5-3.14] during normal operation. This fact +lets the Host Applications provide the real-time state of every persistent node in the infrastructure +within the configured MQTT Keep Alive period using the BIRTH/DEATH mechanisms defined above. But in some use cases, such as sending GPS coordinates for asset tracking or other IOT applications -with periodic data from sensors, MQTT enabled devices do not need to remain connected to the MQTT -infrastructure. In these use cases, all the Device needs to do is to issue an MQTT DISCONNECT -control packet prior to going offline to leave the MQTT infrastructure “gracefully”. In this case an -MQTT device or associated DEATH certificate will not be sent to Sparkplug Host Applications. System -designers just need to be aware that the metric in the Host Application will represent “Last Known -Good” values with a timestamp of this data where the current state of the of the MQTT Device is not -a real-time indication. The Host Application metric timestamp values can be used to determine when -the values from this Edge Node were last updated. +with periodic data from sensors, Sparkplug Edge Nodes do not need to remain connected to the MQTT +infrastructure. In these use cases, all the component needs to do is to send an MQTT DISCONNECT +control packet prior to going offline to leave the MQTT infrastructure “gracefully”. In this case a +DEATH certificate will not be delivered to Sparkplug Host Applications. As a result, the Host +Applications will not set the qualities of the metrics associated with the Edge Node to STALE. +System designers just need to be aware that the metric in the Host Application will represent “Last +Known Good” values with a timestamp of this data where the current state of the of the MQTT Device +is not a real-time indication. The Host Application metric timestamp values can be used to determine +when the values from this Edge Node were last updated. Non-persistent MQTT Enabled Devices should still register a proper DEATH Certificate upon the establishment of an MQTT session. In this manner, the Host Application can still have a good diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_3_Components.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_3_Components.adoc index e3fc46e2..287417d2 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_3_Components.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_3_Components.adoc @@ -35,28 +35,34 @@ also be sized to properly manage all MQTT message traffic. One can implement the use (if required) of multiple MQTT servers for redundancy, high availability, and scalability within any given infrastructure. -[[components_mqtt_edge_node]] -=== MQTT Edge Node +[[components_sparkplug_edge_node]] +=== Sparklplug Edge Node In the context of this specification, an MQTT Edge Node is any MQTT v3.1.1 [MQTTV3.1.1] or v5.0 [MQTTV5] compliant MQTT Client application that manages an MQTT session and provides the physical and/or logical gateway functions required to participate in the topic namespace and payload definitions described in this document. The Edge Node is responsible for any local protocol -interface to existing legacy devices (PLCs, RTUs, Flow Computers, Sensors, etc.) and/or any local -discrete I/O, and/or any logical internal process variables(PVs). - -[[components_device_sensor]] -=== Device/Sensor - -The Device/Sensor represents any physical or logical device connected to the MQTT Edge Node -providing any data, process variables or metrics. - -[[components_mqtt_enabled_device]] -=== MQTT Enabled Device (Sparkplug) - -This represents any device, sensor, or hardware that directly connects to MQTT infrastructure using -a compliant MQTT v3.1.1 or v5.0 connection with the payload and topic notation as outlined in this -Sparkplug Specification. Note that it will be represented as an Edge Node in the Sparkplug topic. +interface to existing legacy hardware components (PLCs, RTUs, Flow Computers, Sensors, etc.) and/or +any local discrete I/O, and/or any logical internal process variables(PVs). + +[[components_sparkplug_device]] +=== Sparkplug Device + +Sparkplug Devices typically represent hardware components including, but not limited to PLCs, RTUs, +Flow Computers, and Sensors. However, a Sparkplug Device can also represent a logical grouping of +data across multiple physical or logical hardware or software components. Sparkplug Devices exist +under the scope of a Sparkplug Edge Node and have their own lifecycle within the context of the +Sparkplug Edge Node. + +[[components_mqtt_sparkplug_enabled_component]] +=== MQTT/Sparkplug Enabled Component + +This represents any hardware component that directly connects to MQTT infrastructure using a +compliant MQTT v3.1.1 or v5.0 connection with the payload and topic notation as outlined in this +Sparkplug Specification. Hardware components can be represented as 'Sparkplug Edge Nodes' or as +'Sparkplug Devices'. This is up to the developers of the Sparkplug Application. Note if it is +represented as a Sparkplug Device, a Sparkplug Edge Node must also be present in the application. It +is not possible to have a Sparkplug Device outside of the scope of a Sparkplug Edge Node. [[components_primary_host_application]] === Primary Host Application diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_4_Topics.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_4_Topics.adoc index 267169bd..adce2daa 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_4_Topics.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_4_Topics.adoc @@ -450,8 +450,8 @@ NCMD MUST include the metrics that need to be written to on the Edge Node.*# NCMD MUST have the 'source' field set in the payload and it MUST have a string value representing the Host ID of the Sparkplug Host Application that sent the NCMD message.*# -[[topics_device_sensor]] -==== Device/Sensor +[[topics_device]] +==== Device [upperalpha, start=1] [[birth_message_dbirth]] diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_5_Operational_Behavior.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_5_Operational_Behavior.adoc index d9be5bbb..82de318b 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_5_Operational_Behavior.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_5_Operational_Behavior.adoc @@ -462,7 +462,7 @@ link:#operational_behavior_edge_node_session_establishment[Edge Node Session Est flow diagram assumes that the Edge Node session has already been established with the Primary Host Application. Depending on the target platform, the Edge Node may be a physical "Edge of Network" gateway device polling physical legacy devices via Modbus, AB, DNP3.0, HART, etc, an MQTT enabled -sensor or device, or it might be a logical implementation of one of the Eclipse Tahu compatible +hardware component, or it might be a logical implementation of one of the Eclipse Tahu compatible implementations for prototype Edge Nodes running on a Raspberry Pi. Regardless of the implementation, at some point the device interface will need to provide a state and associated metrics to publish to the MQTT infrastructure. diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc index a00972a7..e5ce6e6f 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc @@ -107,7 +107,7 @@ Buffer schema was developed that could be used to represent and encode the more being requested. The entire Google Protocol Buffers definition is below. ---- -// * Copyright (c) 2015-2021 Cirrus Link Solutions and others +// * Copyright (c) 2015-2025 Cirrus Link Solutions and others // * // * This program and the accompanying materials are made available under the // * terms of the Eclipse Public License 2.0 which is available at @@ -1188,7 +1188,7 @@ This would result in a structure as follows on the Host Application. .Figure 10 – Sparkplug B Metric Structure 1 plantuml::{assetsdir}assets/plantuml/sparkplugb-metric-structure-1.puml[format=svg, alt="Sparkplug B Metric Structure 1"] -[[payloads_b_nbirth]] +[[payloads_b_nrebirth]] ==== NREBIRTH The NREBIRTH is responsible for informing a specific host application of all of the information