Merge pull request #560 from wes-johnson/174

[#174] Clarified Edge Node/MQTT Enabled Devices in the specification

Author: wes-johnson

.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/**/*

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     ""
 		]
 	}
 

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

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

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

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]]

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.

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