From 9f9e236dae37b318bbb41c2f07c19b531f07385a Mon Sep 17 00:00:00 2001 From: wes-johnson Date: Tue, 10 Nov 2026 23:23:48 +0000 Subject: [PATCH 1/2] [#231] Rename the Protocol Buffers namespace to spPv4.0 The working group chose spPv4.0 over spCv4.0, so the letter in the token names the payload encoding - 'P' for Google Protocol Buffers alongside 'J' for JSON - rather than continuing the A, B, C sequence of encoding scheme generations. - spCv4.0 becomes spPv4.0 throughout the specification, the PlantUML source and the 4.0.0 release plan (135 occurrences). - The encoding scheme is renamed from 'Sparkplug P' accordingly, so the scheme name and its token agree. - The payloads_c_* anchor family becomes payloads_p_* (122 occurrences). These are the fragment identifiers of the published specification, so deep links to a section change. - Sections constants are generated from those anchors, so the 112 Sections.PAYLOADS_C_* references in the TCK become PAYLOADS_P_*. - payloads_c_sparkplug_cv1_0_payload_components named the wrong encoding for a section titled 'Sparkplug B v1.0 Payload Components'; it is now payloads_p_sparkplug_bv1_0_payload_components. --- .../Sparkplug4.0.0ReleasePlan.html | 2 +- .../Sparkplug4.0.0ReleasePlan.md | 10 +- .../plantuml/host-session-establishment.puml | 8 +- .../chapters/Sparkplug_10_Conformance.adoc | 6 +- .../chapters/Sparkplug_1_Introduction.adoc | 8 +- .../chapters/Sparkplug_2_Principles.adoc | 4 +- .../chapters/Sparkplug_3_Components.adoc | 2 +- .../asciidoc/chapters/Sparkplug_4_Topics.adoc | 50 ++-- .../Sparkplug_5_Operational_Behavior.adoc | 50 ++-- .../chapters/Sparkplug_6_Payloads.adoc | 276 +++++++++--------- .../chapters/Sparkplug_7_Security.adoc | 104 +++---- .../eclipse/sparkplug/tck/test/Monitor.java | 24 +- .../tck/test/edge/ReceiveCommandTest.java | 2 +- .../tck/test/edge/SendComplexDataTest.java | 58 ++-- .../sparkplug/tck/test/edge/SendDataTest.java | 40 +-- .../test/edge/SessionEstablishmentTest.java | 54 ++-- .../tck/test/edge/SessionTerminationTest.java | 14 +- .../tck/test/host/SendCommandTest.java | 18 +- .../test/host/SessionEstablishmentTest.java | 14 +- 19 files changed, 372 insertions(+), 372 deletions(-) diff --git a/docs/sparkplug_4.0.0_release_plan/Sparkplug4.0.0ReleasePlan.html b/docs/sparkplug_4.0.0_release_plan/Sparkplug4.0.0ReleasePlan.html index ccf1a848..70149e75 100644 --- a/docs/sparkplug_4.0.0_release_plan/Sparkplug4.0.0ReleasePlan.html +++ b/docs/sparkplug_4.0.0_release_plan/Sparkplug4.0.0ReleasePlan.html @@ -1 +1 @@ -

Eclipse Sparkplug 4.0.0 Release Plan

The Sparkplug Specification Team is working towards a new release of the Sparkplug Specification. When it is released, this will be version 4.0.0. It will have significant changes that will require a new initial topic token identifier of ‘spCv4.0’ rather than the current 3.0.0 version of ‘spBv1.0’. This is required due to what will be significant differences in the MQTT topic structure and the payload encoding.

The goal of the new release is to incorporate as many changes as possible into a single release. Because Sparkplug is protocol for a cross-vendor, cross-platform distributed system, we would like to prevent multiple smaller incremental releases. This will make it simpler for implementors of Sparkplug in that a single update can be performed rather than multiple smaller updates.

Note the Sparkplug B definition will still remain in the Sparkplug 4.0.0 Specification document. The final document will include language for both the existing Sparkplug B variant as well as the Sparkplug C variant.

Scope

There are a number of design goals associated with the Sparkplug 4.0.0 release. At a high level these are:

A full working list of the Sparkplug issues can be found here:

https://htmlpreview.github.io/?https://github.com/eclipse-sparkplug/sparkplug/blob/develop/docs/sparkplug_4.0.0_features/Features.html

Note, the list of issues includes issues that have been discussed by the Sparkplug project team that we’ve decided not to include. Specific reasons as to why they will not be included are in the associated Github issues.

Deliverables

There are three artifacts associated with the release. Each of the milestone builds and release candidates will include all three. These are the Sparkplug Specification itself, the Technology Compatibility Kit (TCK), and compatible implementations for each of the Sparkplug profiles.

Sparkplug Specification

A new draft of the Sparkplug Specification will be written. It will be modified in such a way that Sparkplug B and Sparkplug C are both included in the document. It will contain all of the new features for Sparkplug C. It will likely also include some additional cleanup and clarification in the language around Sparkplug B.

Sparkplug TCK

The Sparkplug TCK will be modified to support testing and validation of both Sparkplug B and Sparkplug C. There will also be changes to the reporting mechanism of the TCK to provide better feedback to users of the TCK about their implementation.

Sparkplug Compatible Implementations

At a minimum the Java implementation of Sparkplug will be expanded to support Sparkplug C in the new Sparkplug 4.0.0 Specification.

Release Milestones

There will be two milestone releases associated with the release of Sparkplug 4.0.0. After the release of M2 there will also be at least one release candidate as we get closer to the final release. There may be additional release candidates as well.

Each of the milestones will include all three deliverables. These will be the Specification document itself, the TCK, and the Java based compatible implementations.. These are the Sparkplug Specification itself, the TCK, and the compatible implementations.

The milestone builds are as follows.

FAQ

TBD

\ No newline at end of file +

Eclipse Sparkplug 4.0.0 Release Plan

The Sparkplug Specification Team is working towards a new release of the Sparkplug Specification. When it is released, this will be version 4.0.0. It will have significant changes that will require a new initial topic token identifier of ‘spPv4.0’ rather than the current 3.0.0 version of ‘spBv1.0’. This is required due to what will be significant differences in the MQTT topic structure and the payload encoding.

The goal of the new release is to incorporate as many changes as possible into a single release. Because Sparkplug is protocol for a cross-vendor, cross-platform distributed system, we would like to prevent multiple smaller incremental releases. This will make it simpler for implementors of Sparkplug in that a single update can be performed rather than multiple smaller updates.

Note the Sparkplug B definition will still remain in the Sparkplug 4.0.0 Specification document. The final document will include language for both the existing Sparkplug B variant as well as the Sparkplug P variant.

Scope

There are a number of design goals associated with the Sparkplug 4.0.0 release. At a high level these are:

A full working list of the Sparkplug issues can be found here:

https://htmlpreview.github.io/?https://github.com/eclipse-sparkplug/sparkplug/blob/develop/docs/sparkplug_4.0.0_features/Features.html

Note, the list of issues includes issues that have been discussed by the Sparkplug project team that we’ve decided not to include. Specific reasons as to why they will not be included are in the associated Github issues.

Deliverables

There are three artifacts associated with the release. Each of the milestone builds and release candidates will include all three. These are the Sparkplug Specification itself, the Technology Compatibility Kit (TCK), and compatible implementations for each of the Sparkplug profiles.

Sparkplug Specification

A new draft of the Sparkplug Specification will be written. It will be modified in such a way that Sparkplug B and Sparkplug P are both included in the document. It will contain all of the new features for Sparkplug P. It will likely also include some additional cleanup and clarification in the language around Sparkplug B.

Sparkplug TCK

The Sparkplug TCK will be modified to support testing and validation of both Sparkplug B and Sparkplug P. There will also be changes to the reporting mechanism of the TCK to provide better feedback to users of the TCK about their implementation.

Sparkplug Compatible Implementations

At a minimum the Java implementation of Sparkplug will be expanded to support Sparkplug P in the new Sparkplug 4.0.0 Specification.

Release Milestones

There will be two milestone releases associated with the release of Sparkplug 4.0.0. After the release of M2 there will also be at least one release candidate as we get closer to the final release. There may be additional release candidates as well.

Each of the milestones will include all three deliverables. These will be the Specification document itself, the TCK, and the Java based compatible implementations.. These are the Sparkplug Specification itself, the TCK, and the compatible implementations.

The milestone builds are as follows.

FAQ

TBD

\ No newline at end of file diff --git a/docs/sparkplug_4.0.0_release_plan/Sparkplug4.0.0ReleasePlan.md b/docs/sparkplug_4.0.0_release_plan/Sparkplug4.0.0ReleasePlan.md index d3fd98be..4204978c 100644 --- a/docs/sparkplug_4.0.0_release_plan/Sparkplug4.0.0ReleasePlan.md +++ b/docs/sparkplug_4.0.0_release_plan/Sparkplug4.0.0ReleasePlan.md @@ -1,9 +1,9 @@ # Eclipse Sparkplug 4.0.0 Release Plan -The Sparkplug Specification Team is working towards a new release of the Sparkplug Specification. When it is released, this will be version 4.0.0. It will have significant changes that will require a new initial topic token identifier of ‘spCv4.0’ rather than the current 3.0.0 version of ‘spBv1.0’. This is required due to what will be significant differences in the MQTT topic structure and the payload encoding. +The Sparkplug Specification Team is working towards a new release of the Sparkplug Specification. When it is released, this will be version 4.0.0. It will have significant changes that will require a new initial topic token identifier of ‘spPv4.0’ rather than the current 3.0.0 version of ‘spBv1.0’. This is required due to what will be significant differences in the MQTT topic structure and the payload encoding. The goal of the new release is to incorporate as many changes as possible into a single release. Because Sparkplug is protocol for a cross-vendor, cross-platform distributed system, we would like to prevent multiple smaller incremental releases. This will make it simpler for implementers of Sparkplug in that a single update can be performed rather than multiple smaller updates. -Note the Sparkplug B definition will still remain in the Sparkplug 4.0.0 Specification document. The final document will include language for both the existing Sparkplug B variant as well as the Sparkplug C variant. +Note the Sparkplug B definition will still remain in the Sparkplug 4.0.0 Specification document. The final document will include language for both the existing Sparkplug B variant as well as the Sparkplug P variant. ## Scope There are a number of design goals associated with the Sparkplug 4.0.0 release. At a high level these are: @@ -26,13 +26,13 @@ Note, the list of issues includes issues that have been discussed by the Sparkpl There are three artifacts associated with the release. Each of the milestone builds and release candidates will include all three. These are the Sparkplug Specification itself, the Technology Compatibility Kit (TCK), and compatible implementations for each of the Sparkplug profiles. ### Sparkplug Specification -A new draft of the Sparkplug Specification will be written. It will be modified in such a way that Sparkplug B and Sparkplug C are both included in the document. It will contain all of the new features for Sparkplug C. It will likely also include some additional cleanup and clarification in the language around Sparkplug B. +A new draft of the Sparkplug Specification will be written. It will be modified in such a way that Sparkplug B and Sparkplug P are both included in the document. It will contain all of the new features for Sparkplug P. It will likely also include some additional cleanup and clarification in the language around Sparkplug B. ### Sparkplug TCK -The Sparkplug TCK will be modified to support testing and validation of both Sparkplug B and Sparkplug C. There will also be changes to the reporting mechanism of the TCK to provide better feedback to users of the TCK about their implementation. +The Sparkplug TCK will be modified to support testing and validation of both Sparkplug B and Sparkplug P. There will also be changes to the reporting mechanism of the TCK to provide better feedback to users of the TCK about their implementation. ### Sparkplug Compatible Implementations -At a minimum the Java implementation of Sparkplug will be expanded to support Sparkplug C in the new Sparkplug 4.0.0 Specification. +At a minimum the Java implementation of Sparkplug will be expanded to support Sparkplug P in the new Sparkplug 4.0.0 Specification. ## Release Milestones There will be two milestone releases associated with the release of Sparkplug 4.0.0. After the release of M2 there will also be at least one release candidate as we get closer to the final release. There may be additional release candidates as well. diff --git a/specification/src/main/asciidoc/assets/plantuml/host-session-establishment.puml b/specification/src/main/asciidoc/assets/plantuml/host-session-establishment.puml index fc188f66..c875efaf 100644 --- a/specification/src/main/asciidoc/assets/plantuml/host-session-establishment.puml +++ b/specification/src/main/asciidoc/assets/plantuml/host-session-establishment.puml @@ -14,9 +14,9 @@ autonumber 1 "(#)" PrimApp -> Server : CONNECT ||| -PrimApp -> Server : SUBSCRIBE( **[topic_prefix/]spCv4.0/#** ) +PrimApp -> Server : SUBSCRIBE( **[topic_prefix/]spPv4.0/#** ) ||| -PrimApp -> Server : SUBSCRIBE( **spCv4.0/STATE/host_app_id** ) +PrimApp -> Server : SUBSCRIBE( **spPv4.0/STATE/host_app_id** ) PrimApp -> Server : PUBLISH( **STATE** ) @@ -60,9 +60,9 @@ end note PrimApp -> Server : CONNECT ||| -PrimApp -> Server : SUBSCRIBE( **[topic_prefix/]spCv4.0/#** ) +PrimApp -> Server : SUBSCRIBE( **[topic_prefix/]spPv4.0/#** ) ||| -PrimApp -> Server : SUBSCRIBE( **spCv4.0/STATE/host_app_id** ) +PrimApp -> Server : SUBSCRIBE( **spPv4.0/STATE/host_app_id** ) PrimApp -> Server : PUBLISH( **STATE** ) diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_10_Conformance.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_10_Conformance.adoc index fa9475c4..11c41537 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_10_Conformance.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_10_Conformance.adoc @@ -35,7 +35,7 @@ typically be both an Edge Node and a Host Application. ==== Sparkplug Edge Node A Sparkplug Edge Node is typically an 'Edge Gateway'. It sends and receives data to an MQTT Server -using a Sparkplug namespace, either spCv4.0/# or spJv4.0/#. Edge Nodes typically interact with +using a Sparkplug namespace, either spPv4.0/# or spJv4.0/#. Edge Nodes typically interact with physical devices to gather data and also write to device outputs. Sparkplug defines two payload encodings, as described in the @@ -99,7 +99,7 @@ cannot assume which payload encoding those Edge Nodes use. * [tck-testable tck-id-conformance-host-encoding-both]#[yellow-background]*[tck-id-conformance-host-encoding-both] A Sparkplug Host Application MUST support both Sparkplug payload encodings, and MUST be able to -consume messages on both the spCv4.0 and spJv4.0 namespaces.*# +consume messages on both the spPv4.0 and spJv4.0 namespaces.*# * [tck-testable tck-id-conformance-host-encoding-publish]#[yellow-background]*[tck-id-conformance-host-encoding-publish] When a Sparkplug Host Application publishes a message, it MUST encode that message using the encoding that corresponds to the namespace it publishes on.*# @@ -180,7 +180,7 @@ continue to be published with the MQTT retain flag set to false and are not reta Sparkplug Aware MQTT Server MUST support all aspects of a Sparkplug Compliant MQTT Server*# * [tck-testable tck-id-conformance-mqtt-aware-encoding-both]#[yellow-background]*[tck-id-conformance-mqtt-aware-encoding-both] A Sparkplug Aware MQTT Server that replaces NDEATH timestamps MUST do so for payloads in both -encodings, on both the spCv4.0 and spJv4.0 namespaces.*# +encodings, on both the spPv4.0 and spJv4.0 namespaces.*# ** Non-normative comment: replacing an NDEATH timestamp is the only behavior required of a Sparkplug Aware MQTT Server that decodes a payload at all, and it is itself optional. A Server that does not do it never inspects a payload and needs neither encoding. The requirement is therefore diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc index ec44dbfe..f4f57d9e 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc @@ -67,14 +67,14 @@ space. Sparkplug has defined an approach where the Topic Namespace can aid in the determination of the encoding scheme of any particular payload. Historically there have been three Sparkplug defined encoding schemes. The first one was 'Sparkplug A', the second was 'Sparkplug B', and the most recent -is 'Sparkplug C'. This version of the specification also reserves a namespace for a JSON encoding of +is 'Sparkplug P'. This version of the specification also reserves a namespace for a JSON encoding of the same data model. Each of these uses a 'first topic token identifier' so Sparkplug Edge Nodes can declare the payload encoding scheme they are using. These first topic tokens are: ---- spAv1.0 spBv1.0 -spCv4.0 +spPv4.0 spJv4.0 ---- @@ -106,11 +106,11 @@ The 'Sparkplug B' encoding scheme was created with a richer data model developed of many system integrators and end user customers using MQTT. These additions included metric timestamp support, complex datatype support, metadata, and other improvements. -The 'Sparkplug C' encoding scheme builds on Sparkplug B, retaining the concepts of the topic namespace +The 'Sparkplug P' encoding scheme builds on Sparkplug B, retaining the concepts of the topic namespace and data model while adding a number of new features. Some of these include better command/response capabilities, better support for multiple host applications (note this does not include multiple Primary Host Applications for the same Edge Node), file publishing support, compression, and many -others. It is the encoding scheme defined by this version of the specification and uses the 'spCv4.0' +others. It is the encoding scheme defined by this version of the specification and uses the 'spPv4.0' namespace. [[introduction_background]] diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_2_Principles.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_2_Principles.adoc index 01762dd6..7c307872 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_2_Principles.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_2_Principles.adoc @@ -89,7 +89,7 @@ Birth and Death Certificates are used by both Edge Nodes and Host Applications. for both are always registered in the MQTT CONNECT packet as the MQTT Will Message. By using the MQTT Will message, the Death Certificates will be delivered to subscribers even if the MQTT client connection is lost ungracefully. For Edge Nodes, the Death Certificate uses the NDEATH Sparkplug -verb in the topic. For Host Applications, the spCv4.0/STATE/sparkplug_host_id topic is used. More +verb in the topic. For Host Applications, the spPv4.0/STATE/sparkplug_host_id topic is used. More information on Death certificates can be found in link:#payloads_b_ndeath[Edge Node Death Certificates] and link:#payloads_b_state[Host Application Death Certificates] @@ -100,7 +100,7 @@ Application.*# Birth Certificates denote to any subscribing MQTT clients that the Edge Node or Host Application is now online. For Edge Nodes, the Birth Certificate uses the NBIRTH Sparkplug verb in the topic. For -Host Applications, the spCv4.0/STATE/sparkplug_host_id topic is used. More details and requirements +Host Applications, the spPv4.0/STATE/sparkplug_host_id topic is used. More details and requirements on Birth certificates can be found in link:#payloads_b_nbirth[Edge Node Birth Certificates] and link:#payloads_b_state[Host Application Birth Certificates] diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_3_Components.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_3_Components.adoc index 49f842d2..c2e27975 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_3_Components.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_3_Components.adoc @@ -63,7 +63,7 @@ output results it returns, and it is included in the BIRTH certificate alongside or Device's other metrics. A Host Application invokes a command using a correlated request/response exchange so that returned data and error codes can be reliably matched back to the request. Commands are optional. An Edge Node or Device may expose no commands at all. The structure and behavior of -commands are defined in the link:#payloads_c_command[Command Section] and the +commands are defined in the link:#payloads_p_command[Command Section] and the link:#operational_behavior_commands_typed[Typed Commands and Command Responses Section]. [[components_mqtt_sparkplug_enabled_component]] diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_4_Topics.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_4_Topics.adoc index 6bad2e4a..329fc9f1 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_4_Topics.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_4_Topics.adoc @@ -52,7 +52,7 @@ the structure of the remaining namespace elements as well as the encoding used f payload data. The namespace element MAY be preceded by an optional topic_prefix of any number of levels (see the link:#topics_topic_prefix_element[topic_prefix Element]). When no topic_prefix is used the namespace element is at the root of the topic. Sparkplug defines two payload encodings, -each with its own namespace constant: spCv4.0 for the Google Protocol Buffers encoding, and spJv4.0 +each with its own namespace constant: spPv4.0 for the Google Protocol Buffers encoding, and spJv4.0 for a JSON encoding. Earlier payload definitions A (now deprecated) and B used the 'spAv1.0' and 'spBv1.0' namespaces respectively. @@ -64,15 +64,15 @@ the encoding of the associated payload.*# [tck-testable tck-id-topic-structure-namespace-a]#[yellow-background]*[tck-id-topic-structure-namespace-a] The UTF-8 string constant for the namespace element MUST be one of the two valid Sparkplug namespaces:*# - spCv4.0 + spPv4.0 spJv4.0 -Note that the topic namespace defined in the remainder of this document applies to both the spCv4.0 +Note that the topic namespace defined in the remainder of this document applies to both the spPv4.0 and spJv4.0 namespaces, which differ only in payload encoding. For earlier 'Sparkplug A' and 'Sparkplug B' topic namespace definitions and concepts, see the earlier versions of the Sparkplug Specification. -Non-normative comment: Topics are written with the spCv4.0 namespace element throughout the +Non-normative comment: Topics are written with the spPv4.0 namespace element throughout the remainder of this specification. Every such topic applies equally to the spJv4.0 namespace with that element substituted, because the two namespaces share one topic structure. The encoding of the payload carried on a topic is determined by the namespace element of that topic, as required in the @@ -80,14 +80,14 @@ link:#payloads_json_encoding_selection[Encoding Selection] section. [tck-testable tck-id-topics-state-single-namespace]#[yellow-background]*[tck-id-topics-state-single-namespace] The STATE topic is the one exception. A STATE message MUST be published on -'spCv4.0/STATE/sparkplug_host_id' whatever payload encoding the Edge Nodes and Host Applications in +'spPv4.0/STATE/sparkplug_host_id' whatever payload encoding the Edge Nodes and Host Applications in that infrastructure use, and an Edge Node that waits on a Primary Host Application MUST subscribe to that topic rather than to a spJv4.0 equivalent.*# Non-normative comment: STATE carries a JSON document rather than a Sparkplug payload, so there is nothing for a second namespace to encode differently. Publishing it on one topic also keeps a single Will Message per Host Application. Without this rule a JSON Edge Node would wait on -spJv4.0/STATE while the Host published on spCv4.0/STATE, and would never see the Host come +spJv4.0/STATE while the Host published on spPv4.0/STATE, and would never see the Host come online. [[topics_topic_prefix_element]] @@ -199,9 +199,9 @@ applications finer-grained control over their subscriptions. For example, the fo topics all describe a metric whose fully-qualified name is 'edge_node26/plc4/line3/machine1/counter/total_count' (topic_prefix empty, Edge Node 'edge_node26'): - spCv4.0/DBIRTH/edge_node26/plc4 + metric name: line3/machine1/counter/total_count - spCv4.0/DBIRTH/edge_node26/plc4/line3 + metric name: machine1/counter/total_count - spCv4.0/DBIRTH/edge_node26/plc4/line3/machine1 + metric name: counter/total_count + spPv4.0/DBIRTH/edge_node26/plc4 + metric name: line3/machine1/counter/total_count + spPv4.0/DBIRTH/edge_node26/plc4/line3 + metric name: machine1/counter/total_count + spPv4.0/DBIRTH/edge_node26/plc4/line3/machine1 + metric name: counter/total_count [tck-testable tck-id-topics-device-tokens-valid]#[yellow-background]*[tck-id-topics-device-tokens-valid] When present, the device_tokens consist of one or more MQTT topic levels separated by the / (forward @@ -651,7 +651,7 @@ NDEATH message contains a very simple payload that MUST only include a bd_seq nu NDEATH event can be associated with the Sparkplug session it terminates.*# ** The bd_seq number in the NDEATH matches the bd_seq number carried in the NMETA, NBIRTH, and any NREBIRTH published in that same MQTT session. A Host Application correlates the NDEATH against -whichever of those messages it holds, as required in the link:#payloads_c_ndeath[NDEATH] section. +whichever of those messages it holds, as required in the link:#payloads_p_ndeath[NDEATH] section. Since this is typically published by the MQTT Server on behalf of the Edge Node, information about the current state of the Edge Node and its devices is not and cannot be known. As a result, [tck-testable tck-id-topics-ndeath-seq]#[yellow-background]*[tck-id-topics-ndeath-seq] The NDEATH @@ -1167,28 +1167,28 @@ MQTT retain flag for the Birth Certificate MUST be set to TRUE*# The topic used for the Host Birth Certificate is identical to the topic used for the Death Certificate. [tck-testable tck-id-host-topic-phid-birth-topic]#[yellow-background]*[tck-id-host-topic-phid-birth-topic] The -Sparkplug Host Application Birth topic MUST be of the form spCv4.0/STATE/sparkplug_host_id where the +Sparkplug Host Application Birth topic MUST be of the form spPv4.0/STATE/sparkplug_host_id where the sparkplug_host_id must be replaced with the specific Spakrplug Host ID of this Sparkplug Host Application.*# * [tck-testable tck-id-host-topic-phid-birth-sub-required]#[yellow-background]*[tck-id-host-topic-phid-birth-sub-required] The -Sparkplug Host Application MUST subscribe to its own spCv4.0/STATE/sparkplug_host_id and the -appropriate spCv4.0 topic(s) immediately after successfully connecting to the MQTT Server.*# -** An 'appropriate' spCv4.0 topic could simply be 'spCv4.0/#' when no topic_prefix is in use. +Sparkplug Host Application MUST subscribe to its own spPv4.0/STATE/sparkplug_host_id and the +appropriate spPv4.0 topic(s) immediately after successfully connecting to the MQTT Server.*# +** An 'appropriate' spPv4.0 topic could simply be 'spPv4.0/#' when no topic_prefix is in use. However, when Edge Nodes publish beneath a topic_prefix it makes sense for a Host Application to -subscribe beneath that prefix, for example subscribing to 'my/prefix/spCv4.0/#'; the Host +subscribe beneath that prefix, for example subscribing to 'my/prefix/spPv4.0/#'; the Host Application must know the topic_prefix a priori. A Host Application could even issue a subscription -to only a single Sparkplug Edge Node using this: '[topic_prefix/]spCv4.0/+/EdgeNode1/#', where the + +to only a single Sparkplug Edge Node using this: '[topic_prefix/]spPv4.0/+/EdgeNode1/#', where the + matches the message_type element that now immediately follows the namespace. A Sparkplug Host Application could subscribe to a combination of specific topic_prefixes and/or Edge Nodes as well. -Note that the STATE topic is never prefixed and always remains at 'spCv4.0/STATE/sparkplug_host_id'. +Note that the STATE topic is never prefixed and always remains at 'spPv4.0/STATE/sparkplug_host_id'. ** For dynamic discovery, a Host Application that does not know the topic_prefixes in use in advance -can subscribe at each prefix depth in turn - 'spCv4.0/#' (no prefix), '+/spCv4.0/#' (a one-level -prefix), '+/+/spCv4.0/#' (a two-level prefix), '+/+/+/spCv4.0/#' (a three-level prefix), and so on - +can subscribe at each prefix depth in turn - 'spPv4.0/#' (no prefix), '+/spPv4.0/#' (a one-level +prefix), '+/+/spPv4.0/#' (a two-level prefix), '+/+/+/spPv4.0/#' (a three-level prefix), and so on - to discover Sparkplug namespaces published beneath any topic_prefix. * [tck-testable tck-id-host-topic-phid-birth-required]#[yellow-background]*[tck-id-host-topic-phid-birth-required] The Sparkplug Host Application MUST publish a Sparkplug Host Application BIRTH message to the MQTT -Server immediately after successfully subscribing its own spCv4.0/STATE/sparkplug_host_id topic.*# +Server immediately after successfully subscribing its own spPv4.0/STATE/sparkplug_host_id topic.*# [[payloads_desc_state_birth]] ====== Birth Certificate Payload (STATE) @@ -1197,9 +1197,9 @@ Server immediately after successfully subscribing its own spCv4.0/STATE/sparkplu Birth Certificate Payload MUST be JSON UTF-8 data. It MUST include four key/value pairs. One key MUST be 'online' and it's value is a boolean 'true'. One key MUST be 'timestamp' and the value MUST be a numeric value representing the current UTC time in nanoseconds since Epoch. One key MUST be -'bd_seq' and the value MUST be as defined in the link:#payloads_c_state_bd_seq[STATE bd_seq Number] +'bd_seq' and the value MUST be as defined in the link:#payloads_p_state_bd_seq[STATE bd_seq Number] section. One key MUST be 'client_id' and the value MUST be the MQTT Client ID of the MQTT session in -which the message was published, as defined in the link:#payloads_c_state_client_id[STATE client_id] +which the message was published, as defined in the link:#payloads_p_state_client_id[STATE client_id] section.*# * [tck-testable tck-id-host-topic-phid-birth-payload-timestamp]#[yellow-background]*[tck-id-host-topic-phid-birth-payload-timestamp] The timestamp metric value MUST be the same timestamp value set in the immediately prior MQTT CONNECT @@ -1224,7 +1224,7 @@ MQTT retain flag for the Birth Certificate MUST be set to TRUE*# ====== Death Certificate Topic (STATE) * [tck-testable tck-id-host-topic-phid-death-topic]#[yellow-background]*[tck-id-host-topic-phid-death-topic] The -Sparkplug Host Application Death topic MUST be of the form spCv4.0/STATE/sparkplug_host_id where the +Sparkplug Host Application Death topic MUST be of the form spPv4.0/STATE/sparkplug_host_id where the sparkplug_host_id must be replaced with the specific Sparkplug Host ID of this Sparkplug Host Application.*# * [tck-testable tck-id-host-topic-phid-death-required]#[yellow-background]*[tck-id-host-topic-phid-death-required] The @@ -1238,9 +1238,9 @@ Sparkplug Host Application MUST provide a Will message in the MQTT CONNECT packe STATE Death Certificate Payload MUST be JSON UTF-8 data. It MUST include four key/value pairs. One key MUST be 'online' and it's value is a boolean 'false'. One key MUST be 'timestamp' and the value MUST be a numeric value representing the current UTC time in nanoseconds since Epoch. One key MUST -be 'bd_seq' and the value MUST be as defined in the link:#payloads_c_state_bd_seq[STATE bd_seq +be 'bd_seq' and the value MUST be as defined in the link:#payloads_p_state_bd_seq[STATE bd_seq Number] section. One key MUST be 'client_id' and the value MUST be the MQTT Client ID of the MQTT -session in which the message was published, as defined in the link:#payloads_c_state_client_id[STATE +session in which the message was published, as defined in the link:#payloads_p_state_client_id[STATE client_id] section.*# * [tck-testable tck-id-host-topic-phid-death-payload-timestamp-connect]#[yellow-background]*[tck-id-host-topic-phid-death-payload-connect] The Death Certificate's used in the MQTT CONNECT packet Will message MUST use a timestamp value that 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 2ab161a2..6e93e2da 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_5_Operational_Behavior.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_5_Operational_Behavior.adoc @@ -44,7 +44,7 @@ connect to the next available MQTT Server where STATE for the Primary Host Appli === Timestamps in Sparkplug An important aspect of Sparkplug is its use of time. All timestamps are in Coordinated Universal -Time (UTC), as required in the link:#payloads_c_payload_header[Header] section. In order to ensure +Time (UTC), as required in the link:#payloads_p_payload_header[Header] section. In order to ensure this is the case, all Sparkplug Edge Nodes and Sparkplug Host Applications need an accurate mechanism for ensuring their clocks remain accurate. This is typically left to the system operating system using technologies such as Network Time Protocol (NTP). Regardless of the mechanism used, @@ -97,7 +97,7 @@ this situation well. Nodes in a Sparkplug environment SHOULD NOT have Edge Node IDs, Topic Prefixes, or device_tokens (which identify Sparkplug Devices) that when converted to lower case match*# ** For example there should not be two different Edge Nodes publishing NBIRTH messages on these two -topics spCv4.0/NBIRTH/EdgeNode1 and spCv4.0/NBIRTH/edgenode1 +topics spPv4.0/NBIRTH/EdgeNode1 and spPv4.0/NBIRTH/edgenode1 * [tck-testable tck-id-case-sensitivity-metric-names]#[yellow-background]*[tck-id-case-sensitivity-metric-names] An Edge Node SHOULD NOT publish metric names that when converted to all lower case match.*# ** For example a DBIRTH should not contain a metric 'a' and another metric 'A'. @@ -185,9 +185,9 @@ Host Application Birth Certificate Payload MUST be JSON UTF-8 data. It MUST incl pairs. One key MUST be 'online' and its value is a boolean 'true'. One key MUST be 'timestamp' and the value MUST be the same value set in the immediately prior MQTT CONNECT packet's Will Message payload. One key MUST be 'bd_seq' and the value MUST be as defined in the -link:#payloads_c_state_bd_seq[STATE bd_seq Number] section. One key MUST be 'client_id' and the +link:#payloads_p_state_bd_seq[STATE bd_seq Number] section. One key MUST be 'client_id' and the value MUST be the MQTT Client ID of the MQTT session in which the message was published, as defined -in the link:#payloads_c_state_client_id[STATE client_id] section.*# +in the link:#payloads_p_state_client_id[STATE client_id] section.*# + [tck-testable tck-id-message-flow-phid-sparkplug-state-publish-payload-timestamp]#[yellow-background]*[tck-id-message-flow-phid-sparkplug-state-publish-payload-timestamp] The timestamp value in the Host Application Birth Certificate payload MUST be the same value set in the @@ -448,13 +448,13 @@ receive NCMD messages with the following rules. * [tck-testable tck-id-message-flow-edge-node-rebirth-subscribe]#[yellow-background]*[tck-id-message-flow-edge-node-rebirth-subscribe] The MQTT client associated with the Edge Node MUST subscribe to a topic of the form -'[topic_prefix/]spCv4.0/REBIRTH/edge_node_id' where the optional topic_prefix is the Sparkplug Topic +'[topic_prefix/]spPv4.0/REBIRTH/edge_node_id' where the optional topic_prefix is the Sparkplug Topic Prefix and the edge_node_id is the Sparkplug Edge Node ID for this Edge Node. It MUST subscribe on this topic with a QoS of 0.*# ** This subscription is mandatory as Edge Nodes MUST be able to respond to 'rebirth requests'. * [tck-testable tck-id-message-flow-edge-node-ncmd-subscribe]#[yellow-background]*[tck-id-message-flow-edge-node-ncmd-subscribe] The MQTT client associated with the Edge Node SHOULD subscribe to a topic of the form -'[topic_prefix/]spCv4.0/NCMD/edge_node_id' where the optional topic_prefix is the Sparkplug Topic +'[topic_prefix/]spPv4.0/NCMD/edge_node_id' where the optional topic_prefix is the Sparkplug Topic Prefix and the edge_node_id is the Sparkplug Edge Node ID for this Edge Node. If it subscribes, it MUST do so with a QoS of 0.*# @@ -466,7 +466,7 @@ DBIRTH messages.*# * [tck-testable tck-id-message-flow-edge-node-birth-publish-will-message]#[yellow-background]*[tck-id-message-flow-edge-node-birth-publish-will-message] When a Sparkplug Edge Node sends its MQTT CONNECT packet, it MUST include a Will Message.*# * [tck-testable tck-id-message-flow-edge-node-birth-publish-will-message-topic]#[yellow-background]*[tck-id-message-flow-edge-node-birth-publish-will-message-topic] The -Edge Node's MQTT Will Message's topic MUST be of the form '[topic_prefix/]spCv4.0/NDEATH/edge_node_id' +Edge Node's MQTT Will Message's topic MUST be of the form '[topic_prefix/]spPv4.0/NDEATH/edge_node_id' where the optional topic_prefix is the Sparkplug Topic Prefix and the edge_node_id is the Sparkplug Edge Node ID for this Edge Node*# * [tck-testable tck-id-message-flow-edge-node-birth-publish-will-message-payload]#[yellow-background]*[tck-id-message-flow-edge-node-birth-publish-will-message-payload] The @@ -564,7 +564,7 @@ a session the Edge Node has already observed, whereas the timestamp gives an ord can evaluate on a value it is seeing for the first time. * [tck-testable tck-id-message-flow-edge-node-birth-publish-nbirth-topic]#[yellow-background]*[tck-id-message-flow-edge-node-birth-publish-nbirth-topic] The Edge Node's NBIRTH MQTT topic MUST be of the form -'[topic_prefix/]spCv4.0/NBIRTH/edge_node_id' where the optional topic_prefix is the Sparkplug Topic +'[topic_prefix/]spPv4.0/NBIRTH/edge_node_id' where the optional topic_prefix is the Sparkplug Topic Prefix and the edge_node_id is the Sparkplug Edge Node ID for this Edge Node*# * [tck-testable tck-id-message-flow-edge-node-birth-publish-nbirth-payload]#[yellow-background]*[tck-id-message-flow-edge-node-birth-publish-nbirth-payload] The Edge Node's NBIRTH payload MUST be a Sparkplug payload encoded as defined for the namespace on @@ -833,7 +833,7 @@ rules. * [tck-testable tck-id-message-flow-device-dcmd-subscribe]#[yellow-background]*[tck-id-message-flow-device-dcmd-subscribe] If the Device supports Device Command (DCMD) messages, the MQTT client associated with the Device MUST -subscribe to a topic of the form '[topic_prefix/]spCv4.0/DCMD/edge_node_id/device_tokens' where the +subscribe to a topic of the form '[topic_prefix/]spPv4.0/DCMD/edge_node_id/device_tokens' where the optional topic_prefix is the Sparkplug Topic Prefix, the edge_node_id is the Sparkplug Edge Node ID, and the device_tokens identify the Sparkplug Device (and MUST match the device_tokens used by that Device's DDATA messages). Any such subscription MUST use a QoS of 0.*# @@ -846,7 +846,7 @@ NBIRTH message MUST have been sent within the current MQTT session prior to a DB published.*# * [tck-testable tck-id-message-flow-device-birth-publish-dbirth-topic]#[yellow-background]*[tck-id-message-flow-device-birth-publish-dbirth-topic] The Device's DBIRTH MQTT topic MUST be of the form -'[topic_prefix/]spCv4.0/DBIRTH/edge_node_id/device_tokens' where the optional topic_prefix is the +'[topic_prefix/]spPv4.0/DBIRTH/edge_node_id/device_tokens' where the optional topic_prefix is the Sparkplug Topic Prefix, the edge_node_id is the Sparkplug Edge Node ID, and the device_tokens identify the Sparkplug Device.*# * [tck-testable tck-id-message-flow-device-birth-publish-dbirth-match-edge-node-topic]#[yellow-background]*[tck-id-message-flow-device-birth-publish-dbirth-match-edge-node-topic] The @@ -1046,13 +1046,13 @@ Because the message_type element immediately follows the namespace element, a si the message_type position selects all message types for a given Edge Node or Device. For a Host Application interested only in 'Device1' beneath 'EdgeNode1', two subscriptions are sufficient: - [topic_prefix/]spCv4.0/+/EdgeNode1 <- all Edge Node scoped messages for EdgeNode1 - [topic_prefix/]spCv4.0/+/EdgeNode1/Device1/# <- all messages for Device1 and anything beneath it + [topic_prefix/]spPv4.0/+/EdgeNode1 <- all Edge Node scoped messages for EdgeNode1 + [topic_prefix/]spPv4.0/+/EdgeNode1/Device1/# <- all messages for Device1 and anything beneath it A Host Application that does not want the Edge Node's own data messages can subscribe to the specific Edge Node scoped message types it requires instead of using the '+' wildcard, for example -'[topic_prefix/]spCv4.0/NBIRTH/EdgeNode1', '[topic_prefix/]spCv4.0/NREBIRTH/EdgeNode1', and -'[topic_prefix/]spCv4.0/NDEATH/EdgeNode1'. +'[topic_prefix/]spPv4.0/NBIRTH/EdgeNode1', '[topic_prefix/]spPv4.0/NREBIRTH/EdgeNode1', and +'[topic_prefix/]spPv4.0/NDEATH/EdgeNode1'. Whatever form the subscriptions take, a Host Application cannot correctly interpret a Device's data unless it also receives the messages that define and terminate that Device's Sparkplug session. @@ -1294,7 +1294,7 @@ receive them. * [tck-testable tck-id-operational-behavior-host-partial-rebirth-scope]#[yellow-background]*[tck-id-operational-behavior-host-partial-rebirth-scope] A Host Application with partial subscriptions that requires a rebirth of a single Sparkplug Device MUST issue the Rebirth Request to the Edge Node that reports that Device, on a topic of the form -'[topic_prefix/]spCv4.0/REBIRTH/edge_node_id', following the rules in the +'[topic_prefix/]spPv4.0/REBIRTH/edge_node_id', following the rules in the link:#operational_behavior_rebirth[Rebirth Requests] section. There is no Device scoped Rebirth Request.*# * [tck-testable tck-id-operational-behavior-host-partial-rebirth-rate]#[yellow-background]*[tck-id-operational-behavior-host-partial-rebirth-rate] A @@ -1497,16 +1497,16 @@ sparkplug_host_id MUST be unique to all other Sparkplug Host IDs in the infrastr * [tck-testable tck-id-operational-behavior-host-application-connect-will]#[yellow-background]*[tck-id-operational-behavior-host-application-connect-will] When a Sparkplug Host Application sends its MQTT CONNECT packet, it MUST include a Will Message.*# * [tck-testable tck-id-operational-behavior-host-application-connect-will-topic]#[yellow-background]*[tck-id-operational-behavior-host-application-connect-will-topic] The -MQTT Will Message's topic MUST be of the form 'spCv4.0/STATE/sparkplug_host_id' where host_id is the +MQTT Will Message's topic MUST be of the form 'spPv4.0/STATE/sparkplug_host_id' where host_id is the unique identifier of the Sparkplug Host Application*# * [tck-testable tck-id-operational-behavior-host-application-connect-will-payload]#[yellow-background]*[tck-id-operational-behavior-host-application-connect-will-payload] The Death Certificate Payload MUST be JSON UTF-8 data. It MUST include four key/value pairs. One key MUST be 'online' and it's value is a boolean 'false'. One key MUST be 'timestamp' and the value MUST be the same value that was used for the timestamp in its own prior MQTT CONNECT packet Will Message payload. One key MUST be 'bd_seq' and the value MUST be as defined in the -link:#payloads_c_state_bd_seq[STATE bd_seq Number] section. One key MUST be 'client_id' and the +link:#payloads_p_state_bd_seq[STATE bd_seq Number] section. One key MUST be 'client_id' and the value MUST be the MQTT Client ID of the MQTT session in which the message was published, as defined -in the link:#payloads_c_state_client_id[STATE client_id] section.*# +in the link:#payloads_p_state_client_id[STATE client_id] section.*# * [tck-testable tck-id-operational-behavior-host-application-connect-will-qos]#[yellow-background]*[tck-id-operational-behavior-host-application-connect-will-qos] The MQTT Will Message's MQTT QoS MUST be 1 (at least once).*# * [tck-testable tck-id-operational-behavior-host-application-connect-will-retained]#[yellow-background]*[tck-id-operational-behavior-host-application-connect-will-retained] The @@ -1519,16 +1519,16 @@ birth with the following rules. MQTT Client associated with the Sparkplug Host Application MUST send a birth message immediately after successfully connecting to the MQTT Server.*# * [tck-testable tck-id-operational-behavior-host-application-connect-birth-topic]#[yellow-background]*[tck-id-operational-behavior-host-application-connect-birth-topic] The -Host Application's Birth topic MUST be of the form 'spCv4.0/STATE/sparkplug_host_id' where host_id +Host Application's Birth topic MUST be of the form 'spPv4.0/STATE/sparkplug_host_id' where host_id is the unique identifier of the Sparkplug Host Application*# * [tck-testable tck-id-operational-behavior-host-application-connect-birth-payload]#[yellow-background]*[tck-id-operational-behavior-host-application-connect-birth-payload] The Birth Certificate Payload MUST be JSON UTF-8 data. It MUST include four key/value pairs. One key MUST be 'online' and it's value is a boolean 'true'. One key MUST be 'timestamp' and the value MUST match the timestamp value that was used in the immediately prior MQTT CONNECT packet Will Message payload. One key MUST be 'bd_seq' and the value MUST be as defined in the -link:#payloads_c_state_bd_seq[STATE bd_seq Number] section. One key MUST be 'client_id' and the +link:#payloads_p_state_bd_seq[STATE bd_seq Number] section. One key MUST be 'client_id' and the value MUST be the MQTT Client ID of the MQTT session in which the message was published, as defined -in the link:#payloads_c_state_client_id[STATE client_id] section.*# +in the link:#payloads_p_state_client_id[STATE client_id] section.*# * [tck-testable tck-id-operational-behavior-host-application-connect-birth-qos]#[yellow-background]*[tck-id-operational-behavior-host-application-connect-birth-qos] The Host Application's Birth MQTT QoS MUST be 1 (at least once).*# * [tck-testable tck-id-operational-behavior-host-application-connect-birth-retained]#[yellow-background]*[tck-id-operational-behavior-host-application-connect-birth-retained] The @@ -1551,16 +1551,16 @@ the Sparkplug Host Application ever disconnects intentionally, it MUST publish a the following characteristics.*# * [tck-testable tck-id-operational-behavior-host-application-death-topic]#[yellow-background]*[tck-id-operational-behavior-host-application-death-topic] The -Sparkplug Host Application's Death topic MUST be of the form 'spCv4.0/STATE/sparkplug_host_id' where +Sparkplug Host Application's Death topic MUST be of the form 'spPv4.0/STATE/sparkplug_host_id' where host_id is the unique identifier of the Sparkplug Host Application.*# * [tck-testable tck-id-operational-behavior-host-application-death-payload]#[yellow-background]*[tck-id-operational-behavior-host-application-death-payload] The Death Certificate Payload registered as the MQTT Will Message in the MQTT CONNECT packet MUST be JSON UTF-8 data. It MUST include four key/value pairs. One key MUST be 'online' and it's value is a boolean 'false'. One key MUST be 'timestamp' and the value MUST be a numeric value representing the current UTC time in nanoseconds since Epoch. One key MUST be 'bd_seq' and the value MUST be as -defined in the link:#payloads_c_state_bd_seq[STATE bd_seq Number] section. One key MUST be +defined in the link:#payloads_p_state_bd_seq[STATE bd_seq Number] section. One key MUST be 'client_id' and the value MUST be the MQTT Client ID of the MQTT session in which the message was -published, as defined in the link:#payloads_c_state_client_id[STATE client_id] section.*# +published, as defined in the link:#payloads_p_state_client_id[STATE client_id] section.*# * [tck-testable tck-id-operational-behavior-host-application-death-qos]#[yellow-background]*[tck-id-operational-behavior-host-application-death-qos] The Sparkplug Host Application's Death MQTT QoS MUST be 1 (at least once).*# * [tck-testable tck-id-operational-behavior-host-application-death-retained]#[yellow-background]*[tck-id-operational-behavior-host-application-death-retained] The @@ -1797,7 +1797,7 @@ an Edge Node or Device includes as Command metrics in its BIRTH. A command is a with a typed signature: it declares the inputs it accepts and the outputs it returns. Invoking a command follows a correlated request/response pattern so that the result, including any returned data or error code, can be reliably matched back to the request that produced it. The structure of a -Command metric is defined in the link:#payloads_c_command[Command Section]. +Command metric is defined in the link:#payloads_p_command[Command Section]. The general flow is: a Host Application publishes an NCMD or DCMD that targets a Command metric and includes the argument values and a correlation_id. The Edge Node executes the command, and the Edge diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc index af08d3c6..8d206708 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc @@ -99,7 +99,7 @@ Sparkplug B selected an existing, open, and highly available encoding scheme tha encodes register based process variables. The encoding technology selected for Sparkplug B is Google Protocol Buffers. -[[payloads_c_google_protocol_buffer_schema]] +[[payloads_p_google_protocol_buffer_schema]] ==== Google Protocol Buffer Schema Using lessons learned on the feedback from the Sparkplug A implementation a new Google Protocol @@ -357,7 +357,7 @@ message Payload { } ---- -[[payloads_c_payload_metric_naming_convention]] +[[payloads_p_payload_metric_naming_convention]] ==== Payload Metric Naming Convention For the remainder of this document JSON will be used to represent components of a Sparkplug B @@ -423,7 +423,7 @@ Topic Namespace, consuming applications can organize metrics in the same hierarc .Figure 9 – Payload Metric Folder Structure plantuml::{assetsdir}assets/plantuml/payload-metric-folder-structure.puml[format=svg, alt="Payload Metric Folder Structure"] -[[payloads_c_sparkplug_cv1_0_payload_components]] +[[payloads_p_sparkplug_bv1_0_payload_components]] ==== Sparkplug B v1.0 Payload Components The Sparkplug specification link:#topics[Topics Section] defines the Topic Namespace that Sparkplug @@ -431,13 +431,13 @@ uses to publish and subscribe between Edge Nodes and Host Applications within th infrastructure. Using that Topic Namespace, this section of the specification defines the actual payload contents of each message type in Sparkplug B v1.0. -[[payloads_c_payload_component_definitions]] +[[payloads_p_payload_component_definitions]] ==== Payload Component Definitions Sparkplug B consists of a series of one or more metrics with metadata surrounding those metrics. The following definitions explain the components that make up a payload. -[[payloads_c_payload]] +[[payloads_p_payload]] ==== Payload A Sparkplug payload is the top-level component that is encoded and used in an MQTT message. It is @@ -472,7 +472,7 @@ Sparkplug payload MUST include a header.*# ** Non-normative comment: this applies to every message that carries a Sparkplug payload, which is every message type other than STATE. A STATE message is JSON UTF-8 data published by a Sparkplug Host Application and does not use a Sparkplug payload at all, so it has neither a header nor a -content section. Its required contents are defined in the link:#payloads_c_state[STATE] section. +content section. Its required contents are defined in the link:#payloads_p_state[STATE] section. * [tck-testable tck-id-payloads-header-first]#[yellow-background]*[tck-id-payloads-header-first] A publishing application MUST serialize the header section before the content section.*# ** Non-normative comment: Google Protocol Buffers implementations serialize fields in ascending @@ -504,7 +504,7 @@ determine whether it belongs to a session it currently holds, or the definition determine whether it already holds the metric structure the message reports against, without decoding any metrics. -[[payloads_c_payload_header]] +[[payloads_p_payload_header]] ===== Header The header section includes the following components. @@ -573,7 +573,7 @@ is therefore known when the Will Message is registered in the MQTT CONNECT packe Applications do not carry a bd_seq number. A STATE message does carry one, scoping it to the MQTT session of the Sparkplug Host Application that published it, but it is a bd_seq number maintained by that Host Application and is unrelated to the bd_seq number of any Edge Node. See the -link:#payloads_c_state_bd_seq[STATE bd_seq Number] section. +link:#payloads_p_state_bd_seq[STATE bd_seq Number] section. **** [tck-testable tck-id-payloads-bd-sequence-num-req-nbirth]#[yellow-background]*[tck-id-payloads-bd-sequence-num-req-nbirth] Every birth/death sequence number included in the payload from an Edge Node MUST always be between 0 and 9223372036854775807 (inclusive).*# @@ -623,7 +623,7 @@ the descriptor sequence stream. It MUST carry the next incrementing descriptor s continuing the stream like any other message.*# ** _definition_id_ *** This is the definition identifier, a content hash of the metric definitions this message reports -against. It is defined in the link:#payloads_c_definition_identifier[Definition Identifier] section. +against. It is defined in the link:#payloads_p_definition_identifier[Definition Identifier] section. ** _previous_definition_id_ *** This is the definition identifier that was in effect immediately before the change conveyed by an NMMETA or DMMETA message. It is only present in those messages. @@ -642,21 +642,21 @@ message. Example usage would be to supply a UUID which represents an encoding me optional array of bytes associated with a payload. ** _compression_algorithm_ *** This names the algorithm used to compress the content section, and is present only when the -content section is compressed. It is defined in the link:#payloads_c_compression[Compression] +content section is compressed. It is defined in the link:#payloads_p_compression[Compression] section. -[[payloads_c_payload_content]] +[[payloads_p_payload_content]] ===== Content The content section carries the metrics of the message. It is the section that a consuming application can leave undecoded when it only requires the header, and it is the section that is compressed when Sparkplug compression is used, as described in the -link:#payloads_c_compression[Compression] section. +link:#payloads_p_compression[Compression] section. * *content* ** _metrics_ *** This is an array of metrics representing key/value/datatype values. Metrics are further defined -link:#payloads_c_metric[here]. +link:#payloads_p_metric[here]. *** [tck-testable tck-id-payloads-metrics-ordered]#[yellow-background]*[tck-id-payloads-metrics-ordered] A payload that carries more than one value for the same metric MUST order its metrics by value change time, oldest first.*# @@ -669,7 +669,7 @@ Definition or the Command definition.*# *** [tck-testable tck-id-payloads-metrics-ordered-no-timestamp]#[yellow-background]*[tck-id-payloads-metrics-ordered-no-timestamp] A metric that omits its timestamp MUST be ordered as though its value change time were the payload timestamp, which is the time that metric is taken to have changed as described in the -link:#payloads_c_metric[Metric] section.*# +link:#payloads_p_metric[Metric] section.*# *** [tck-not-testable tck-id-payloads-metrics-ordered-ties]#[yellow-background]*[tck-id-payloads-metrics-ordered-ties] Metrics that share a value change time MAY appear in any order relative to one another, and a consuming application MUST NOT reorder them.*# @@ -683,22 +683,22 @@ carries no identity. and is preserved by both encodings, because a JSON array and a Google Protocol Buffers repeated field are both ordered. Multi-part file publishing depends on this: every metric of a multi-part publish carries the same timestamp, as required in the -link:#payloads_c_file_publishing[File Publishing] section, so they tie, and the rules that +link:#payloads_p_file_publishing[File Publishing] section, so they tie, and the rules that distinguish the first metric of the publish from the rest continue to apply. ** _body_ *** This is an array of bytes which can be used for any custom binary encoded data. -[[payloads_c_typedvalue]] +[[payloads_p_typedvalue]] ==== TypedValue A Sparkplug TypedValue object carries a single value together with the datatype that describes it. It is the one structure used wherever the specification carries a value: the value of a -link:#payloads_c_metric[Metric], the value of a property in a -link:#payloads_c_propertyset[PropertySet], and the value of a -link:#payloads_c_template_parameter[Template Parameter]. It includes the following components. +link:#payloads_p_metric[Metric], the value of a property in a +link:#payloads_p_propertyset[PropertySet], and the value of a +link:#payloads_p_template_parameter[Template Parameter]. It includes the following components. * *datatype* -** This is the DataType of the value, as enumerated in the link:#payloads_c_datatypes[DataTypes] +** This is the DataType of the value, as enumerated in the link:#payloads_p_datatypes[DataTypes] section. It tells a consuming application how to interpret the value, and which of the fields below carries it. * *is_null* @@ -720,15 +720,15 @@ types can be found here: https://developers.google.com/protocol-buffers/docs/pro *** Google Protocol Buffer Type: _string_ *** Google Protocol Buffer Type: _bytes_ *** Sparkplug _DataSet_ -**** Defined link:#payloads_c_dataset[here]. +**** Defined link:#payloads_p_dataset[here]. *** Sparkplug _Template_ -**** Defined link:#payloads_c_template[here]. +**** Defined link:#payloads_p_template[here]. *** Sparkplug _PropertySet_ -**** Defined link:#payloads_c_propertyset[here]. +**** Defined link:#payloads_p_propertyset[here]. *** Sparkplug _PropertySetList_ -**** Defined link:#payloads_c_propertysetlist[here]. +**** Defined link:#payloads_p_propertysetlist[here]. *** Sparkplug _ValueArray_ -**** Defined link:#payloads_c_datatype_array[here]. +**** Defined link:#payloads_p_datatype_array[here]. Where the enclosing object also carries a datatype and an is_null of its own, as a Metric does, the two are required to agree; see the link:#payloads_json_typed_values[Typed Values] section, which @@ -740,7 +740,7 @@ does, the restriction is stated in that context's own section rather than restat the permitted fields are described in exactly one place. For example, a context that accepts only scalar values says so in its own section, without repeating this list. -[[payloads_c_metric]] +[[payloads_p_metric]] ==== Metric A Sparkplug B metric is a core component of data in the payload. It represents a key, value, @@ -814,7 +814,7 @@ datatype MUST be carried as a value of the DataType enumeration, represented as use defines (for JSON, see link:#payloads_json_scalar[Scalar Value Mapping]).*# ** [tck-testable tck-id-payloads-metric-datatype-value]#[yellow-background]*[tck-id-payloads-metric-datatype-value] The datatype MUST be one of the enumerated values as shown in the -link:#payloads_c_datatypes[valid Sparkplug Data Types].*# +link:#payloads_p_datatypes[valid Sparkplug Data Types].*# ** [tck-testable tck-id-payloads-metric-datatype-not-propertyset]#[yellow-background]*[tck-id-payloads-metric-datatype-not-propertyset] The datatype MUST NOT be PropertySet or PropertySetList, which are value types for a property rather than for a metric. A metric's properties are carried in its properties field.*# @@ -824,11 +824,11 @@ datatype MUST be included with each metric definition in NBIRTH and DBIRTH messa datatype SHOULD NOT be included with metric definitions in NDATA, NCMD, DDATA, and DCMD messages.*# * *quality* ** This defines the quality of the value associated with the metric. It is defined in the -link:#payloads_c_quality[Quality] section. This property is optional and is only required if the +link:#payloads_p_quality[Quality] section. This property is optional and is only required if the quality of the metric is not Good. If the quality is not present, it is implicitly Good. * *quality_context* ** This is an optional string value used to provide additional context to the quality code of the -metric. It is defined in the link:#payloads_c_quality[Quality] section. +metric. It is defined in the link:#payloads_p_quality[Quality] section. * *source* ** This is the source field which represents the Sparkplug Host Application ID of the publisher for NCMD, DCMD, and REBIRTH messages if it differs from the overall payload source value. This may be @@ -851,17 +851,17 @@ not be stored in a historian. mechanism of explicitly denoting a metric’s value is actually null. * *metadata* ** This is a MetaData object associated with the metric for dealing with more complex datatypes. -This is covered in the link:#payloads_c_metadata[metadata section]. +This is covered in the link:#payloads_p_metadata[metadata section]. * *properties* ** This is a PropertySet object associated with the metric for including custom key/value pairs of metadata associated with a metric. This is covered in the -link:#payloads_c_propertyset[property set section]. +link:#payloads_p_propertyset[property set section]. * *value* ** This is a TypedValue carrying the metric's value, as described in the -link:#payloads_c_typedvalue[TypedValue section]. Which field carries the value is determined by the +link:#payloads_p_typedvalue[TypedValue section]. Which field carries the value is determined by the metric's datatype, and the value may be omitted altogether if the is_null flag is set to true. -[[payloads_c_quality]] +[[payloads_p_quality]] ==== Quality The quality of a Metric's value is carried in the quality field of that Metric, with optional @@ -874,7 +874,7 @@ existing numbering rather than defining a new one means that the large number of Nodes which acquire data from OPC UA servers, or which are themselves fronting an OPC UA address space, can report a value's quality without translating it. -[[payloads_c_quality_severity]] +[[payloads_p_quality_severity]] ===== Severity * [tck-testable tck-id-payloads-quality-severity-valid]#[yellow-background]*[tck-id-payloads-quality-severity-valid] The @@ -904,7 +904,7 @@ Good.*# field containing Good carry the same meaning. An Edge Node therefore only needs to include the field when the quality of a value is something other than Good. -[[payloads_c_quality_codes]] +[[payloads_p_quality_codes]] ===== Quality Codes * [tck-not-testable tck-id-payloads-quality-recognized-codes]#[yellow-background]*[tck-id-payloads-quality-recognized-codes] A consuming application MUST recognize the following quality @@ -945,7 +945,7 @@ quality code is carried in a Metric field that exists only in this version of th because an Edge Node publishes under a namespace that identifies which version of the specification it implements. -[[payloads_c_quality_context]] +[[payloads_p_quality_context]] ===== Quality Context * [tck-not-testable tck-id-payloads-quality-context-not-required]#[yellow-background]*[tck-id-payloads-quality-context-not-required] The quality_context is an optional UTF-8 string carrying @@ -957,7 +957,7 @@ typically carries something like the identifier of the failed source or the text reported by an underlying protocol. The quality code itself carries everything a consuming application needs in order to act. -[[payloads_c_metadata]] +[[payloads_p_metadata]] ==== MetaData A Sparkplug B MetaData object is used to describe different types of binary data. These are optional @@ -988,7 +988,7 @@ string to represent it. metric. It can contain JSON, XML, text, or anything else that can be understood by both the publisher and the subscriber. -[[payloads_c_propertyset]] +[[payloads_p_propertyset]] ==== PropertySet A Sparkplug B PropertySet object is used with a metric to add custom properties to the object. The @@ -1006,7 +1006,7 @@ PropertySet. ** [tck-testable tck-id-payloads-propertyset-values-array-size]#[yellow-background]*[tck-id-payloads-propertyset-values-array-size] The array of values in a PropertySet MUST contain the same number of items that are in the keys array.*# -[[payloads_c_propertyvalue]] +[[payloads_p_propertyvalue]] ==== PropertyValue A Sparkplug B PropertyValue object is used to encode the value and datatype of the value of a @@ -1018,9 +1018,9 @@ MUST be a value of the DataType enumeration, represented as the encoding in use JSON, see link:#payloads_json_scalar[Scalar Value Mapping]).*# ** [tck-testable tck-id-payloads-metric-propertyvalue-type-value]#[yellow-background]*[tck-id-payloads-metric-propertyvalue-type-value] This value MUST be one of the enumerated values as shown in the -link:#payloads_c_datatype_basic[Sparkplug Basic Data Types] +link:#payloads_p_datatype_basic[Sparkplug Basic Data Types] or the -link:#payloads_c_datatype_propertyvalue[Sparkplug Property Value Data Types].*# +link:#payloads_p_datatype_propertyvalue[Sparkplug Property Value Data Types].*# ** [tck-testable tck-id-payloads-metric-propertyvalue-type-req]#[yellow-background]*[tck-id-payloads-metric-propertyvalue-type-req] This MUST be included in Property Value Definitions in NBIRTH and DBIRTH messages.*# * *is_null* @@ -1028,10 +1028,10 @@ MUST be included in Property Value Definitions in NBIRTH and DBIRTH messages.*# B’s mechanism of explicitly denoting a property’s value is actually null. * *value* ** This is a TypedValue carrying the property's value, as described in the -link:#payloads_c_typedvalue[TypedValue section]. Which field carries the value is determined by the +link:#payloads_p_typedvalue[TypedValue section]. Which field carries the value is determined by the property's datatype, and the value may be omitted altogether if the is_null flag is set to true. -[[payloads_c_well_known_properties]] +[[payloads_p_well_known_properties]] ==== Well Known Properties [cols="1,1,5"] @@ -1049,16 +1049,16 @@ property's datatype, and the value may be omitted altogether if the is_null flag |True or False |=== -[[payloads_c_propertysetlist]] +[[payloads_p_propertysetlist]] ==== PropertySetList A Sparkplug B PropertySetList object is an array of PropertySet objects. It includes the following components. * *propertyset* -** This is an array of link:#payloads_c_propertyset[PropertySet objects]. +** This is an array of link:#payloads_p_propertyset[PropertySet objects]. -[[payloads_c_dataset]] +[[payloads_p_dataset]] ==== DataSet A Sparkplug DataSet object is used to encode matrices of data. A DataSet is column oriented: it @@ -1083,7 +1083,7 @@ Non-normative comment: A column oriented layout lets every value in a column sha one Google Protocol Buffers field, so the values pack into a single length delimited run rather than repeating a type tag per cell. The row at index i is read by taking element i of each Column. -[[payloads_c_dataset_column]] +[[payloads_p_dataset_column]] ==== DataSet.Column A Sparkplug DataSet.Column object represents a single column of a DataSet. It includes the following @@ -1097,11 +1097,11 @@ Column MUST include a name, which is the column header for that column.*# Column MUST include a datatype, which is the datatype of every value in that column.*# ** [tck-testable tck-id-payloads-dataset-column-datatype-value]#[yellow-background]*[tck-id-payloads-dataset-column-datatype-value] The datatype MUST be one of the enumerated values shown in the -link:#payloads_c_datatype_basic[Sparkplug Basic Data Types].*# +link:#payloads_p_datatype_basic[Sparkplug Basic Data Types].*# * *values* ** The values of a Column are carried in a ValueArray, one entry per row, in row order. The typed array within it is selected by the Column's datatype, as described in the -link:#payloads_c_datatype_array[Array Types] section, which defines the same structure for the +link:#payloads_p_datatype_array[Array Types] section, which defines the same structure for the array DataTypes. ** [tck-testable tck-id-payloads-dataset-column-values-field]#[yellow-background]*[tck-id-payloads-dataset-column-values-field] A DataSet.Column MUST carry its values in a ValueArray, populating only the typed array that @@ -1115,7 +1115,7 @@ equivalent, because a repeated field is dense, so null_indexes restores what the could express. Without it an encoder would have to omit the cell, which shortens the column and shifts every later row, or write a zero, which is indistinguishable from a real zero. -[[payloads_c_dataset_example]] +[[payloads_p_dataset_example]] ===== DataSet Example The following is a non-normative example of a metric whose value is a DataSet of three columns and @@ -1143,7 +1143,7 @@ two rows. The first row is (1, 72.5, true) and the second is (2, 80.0, false). } ---- -[[payloads_c_template]] +[[payloads_p_template]] ==== Template A Sparkplug B Template is used for encoding complex datatypes in a payload. It is a type of metric @@ -1173,7 +1173,7 @@ appears in a Definition or in an Instance, so it has is_definition set to false names that type. A member cannot be a Definition, because a Definition omits template_ref and so could not say which type the member is. Nesting can be carried to any depth, though a deeply nested type is correspondingly harder for a consuming application to present, and the flatter alternatives -described in the link:#payloads_c_template_choosing[Choosing How to Express Structure] section are +described in the link:#payloads_p_template_choosing[Choosing How to Express Structure] section are often a better fit. Non-normative comment: A Template Definition is scoped to the Edge Node that publishes it, so @@ -1282,7 +1282,7 @@ MUST be set to true if this is a Template Definition.*# ** [tck-testable tck-id-payloads-template-is-definition-instance]#[yellow-background]*[tck-id-payloads-template-is-definition-instance] This MUST be set to false if this is a Template Instance.*# -[[payloads_c_template_example]] +[[payloads_p_template_example]] ===== Template Example The following is a non-normative example of a Template Definition and Template Instances of it, @@ -1294,7 +1294,7 @@ in the Edge Node's NMETA. It carries no metric values, because a Definition desc only. ---- -Acme/Dublin/Packaging/spCv4.0/NMETA/EdgeNode1 +Acme/Dublin/Packaging/spPv4.0/NMETA/EdgeNode1 ---- ---- @@ -1339,7 +1339,7 @@ metric, the DMETA carries structure only: each Instance sets is_definition to fa 'MotorType' in its template_ref, and no values appear. ---- -Acme/Dublin/Packaging/spCv4.0/DMETA/EdgeNode1/Line3 +Acme/Dublin/Packaging/spPv4.0/DMETA/EdgeNode1/Line3 ---- ---- @@ -1378,7 +1378,7 @@ through its definition_id. The first Instance overrides the Manufacturer paramet it and so takes the default of 'Acme' from the Definition. ---- -Acme/Dublin/Packaging/spCv4.0/DBIRTH/EdgeNode1/Line3 +Acme/Dublin/Packaging/spPv4.0/DBIRTH/EdgeNode1/Line3 ---- ---- @@ -1447,7 +1447,7 @@ A subsequent DDATA reporting only a change to the conveyor motor's RPM may carry because a Template Instance in a DATA message MAY include a subset of the Definition's metrics. ---- -Acme/Dublin/Packaging/spCv4.0/DDATA/EdgeNode1/Line3 +Acme/Dublin/Packaging/spPv4.0/DDATA/EdgeNode1/Line3 ---- ---- @@ -1477,7 +1477,7 @@ Acme/Dublin/Packaging/spCv4.0/DDATA/EdgeNode1/Line3 } ---- -[[payloads_c_template_choosing]] +[[payloads_p_template_choosing]] ===== Choosing How to Express Structure Non-normative comment: Sparkplug offers three ways to express that data is structured, and they are @@ -1509,12 +1509,12 @@ consuming applications to resynchronize. Non-normative comment: Because a Template Definition is part of an Edge Node's metric structure, any change to a Definition changes the definition identifier of the NMETA that carries it, as required -in the link:#payloads_c_definition_identifier[Definition Identifier] section. Every consuming +in the link:#payloads_p_definition_identifier[Definition Identifier] section. Every consuming application then re-resolves that Edge Node's metadata. Adding a member to a widely instantiated type is therefore more disruptive than its size suggests, and it is worth designing a Template with the members it will eventually need. -[[payloads_c_template_parameter]] +[[payloads_p_template_parameter]] ==== Template.Parameter A Sparkplug B Template.Parameter is a metadata field for a Template. This can be used to represent @@ -1532,7 +1532,7 @@ MUST be a value of the DataType enumeration, represented as the encoding in use JSON, see link:#payloads_json_scalar[Scalar Value Mapping]).*# ** [tck-testable tck-id-payloads-template-parameter-type-value]#[yellow-background]*[tck-id-payloads-template-parameter-type-value] This value MUST be one of the enumerated values as shown in the -link:#payloads_c_datatype_basic[Sparkplug Basic Data Types].*# +link:#payloads_p_datatype_basic[Sparkplug Basic Data Types].*# ** [tck-testable tck-id-payloads-template-parameter-type-req]#[yellow-background]*[tck-id-payloads-template-parameter-type-req] This MUST be included in every Template Parameter Definition in an NMETA message.*# *** Non-normative comment: Template Parameter Definitions appear only inside Template Definitions, and @@ -1548,10 +1548,10 @@ https://developers.google.com/protocol-buffers/docs/proto#scalar ** For a template definition, this is the default value of the parameter. For a template instance, this is the value unique to that instance. -[[payloads_c_command]] +[[payloads_p_command]] ==== Command -A Sparkplug C Command object is used to define and invoke a strongly typed, callable command (also +A Sparkplug P Command object is used to define and invoke a strongly typed, callable command (also referred to as a function or method) on an Edge Node or Device. It is carried by a Metric whose datatype is _Command_. The same Command object is used in three roles which are distinguished by which fields are populated: @@ -1615,9 +1615,9 @@ in the corresponding Command Response so that the response can be matched to the produced it. * *status* ** This is a Status object representing the outcome of executing the command. It is defined -link:#payloads_c_status[here]. +link:#payloads_p_status[here]. -[[payloads_c_status]] +[[payloads_p_status]] ==== Status A Sparkplug B Status object represents the outcome of a command invocation and is included in a @@ -1632,7 +1632,7 @@ represent an error.*# * *message* ** This is an optional UTF-8 string providing a human readable description of the status or error. -[[payloads_c_datatypes]] +[[payloads_p_datatypes]] ==== Data Types Sparkplug defines the valid data types used for various Sparkplug constucts including Metric @@ -1694,10 +1694,10 @@ enum DataType { } ---- -[[payloads_c_datatype_details]] +[[payloads_p_datatype_details]] ==== Datatype Details -[[payloads_c_datatype_basic]] +[[payloads_p_datatype_basic]] * *Basic Types* ** _Unknown_ *** Sparkplug enum value: 0 @@ -1758,20 +1758,20 @@ payload and metric timestamps carry, and is signed for the same reason. Every ma representation it interoperates with is signed, so the ceiling is 2262-04-11 as described in the link:#operational_behavior_timestamps[Timestamps] section. A DateTime carried in an array or a DataSet.Column uses the int64_values array of the ValueArray, as the -link:#payloads_c_datatype_array[Array Types] section describes. +link:#payloads_p_datatype_array[Array Types] section describes. * _Text_ ** String value (UTF-8) ** Google Protocol Buffer Type: string ** Sparkplug enum value: 14 -[[payloads_c_datatype_additional]] +[[payloads_p_datatype_additional]] * *Additional Types* ** _UUID_ *** UUID value as a UTF-8 string *** Google Protocol Buffer Type: string *** Sparkplug enum value: 15 ** _DataSet_ -*** DataSet as defined link:#payloads_c_dataset[here] +*** DataSet as defined link:#payloads_p_dataset[here] *** Google Protocol Buffer Type: none – defined in Sparkplug *** Sparkplug enum value: 16 ** _Bytes_ @@ -1783,22 +1783,22 @@ link:#payloads_c_datatype_array[Array Types] section describes. *** Google Protocol Buffer Type: bytes *** Sparkplug enum value: 18 ** _Template_ -*** Template as defined link:#payloads_c_template[here] +*** Template as defined link:#payloads_p_template[here] *** Google Protocol Buffer Type: none – defined in Sparkplug *** Sparkplug enum value: 19 -[[payloads_c_datatype_propertyvalue]] +[[payloads_p_datatype_propertyvalue]] * *Additional PropertyValue Types* ** _PropertySet_ -*** PropertySet as defined link:#payloads_c_propertyset[here] +*** PropertySet as defined link:#payloads_p_propertyset[here] *** Google Protocol Buffer Type: none – defined in Sparkplug *** Sparkplug enum value: 20 ** _PropertySetList_ -*** PropertySetList as defined link:#payloads_c_propertysetlist[here] +*** PropertySetList as defined link:#payloads_p_propertysetlist[here] *** Google Protocol Buffer Type: none – defined in Sparkplug *** Sparkplug enum value: 21 -[[payloads_c_datatype_array]] +[[payloads_p_datatype_array]] * *Array Types* An array DataType carries its elements in a ValueArray, in the array_value field of the Metric's @@ -1873,11 +1873,11 @@ null_indexes to [1]. *** Elements are carried in the int64_values field of the ValueArray *** Sparkplug enum value: 34 -[[payloads_c_datatype_command]] +[[payloads_p_datatype_command]] * *Command Type* ** _Command_ *** A callable command/function metric whose typed inputs and outputs are described by a Command -object as defined link:#payloads_c_command[here]. A Command metric carries its content in the +object as defined link:#payloads_p_command[here]. A Command metric carries its content in the Metric _command_ field rather than the _value_ field. *** Google Protocol Buffer Type: none – defined in Sparkplug *** Sparkplug enum value: 35 @@ -1888,7 +1888,7 @@ Metric _command_ field rather than the _value_ field. Sparkplug B payloads in conjunction with the Sparkplug topic namespace result in hierarchical data structures that can be represented in folder structures with metrics which are often called tags. -[[payloads_c_definition_identifier]] +[[payloads_p_definition_identifier]] ==== Definition Identifier The _definition identifier_ is a recalculatable content hash of the metric definitions (metadata) of @@ -1928,7 +1928,7 @@ definition, or to any Template definition MUST result in a different definition consumer MUST be able to recompute the definition identifier from the assembled metadata and obtain a value identical to the one published by the Edge Node.*# -[[payloads_c_nmeta]] +[[payloads_p_nmeta]] ==== NMETA The NMETA describes the metric structure (metadata) of an Edge Node. It carries the definition of @@ -1959,7 +1959,7 @@ messages MUST be published with the MQTT QoS set to 0.*# NMETA MUST be published with the MQTT retain flag set to true, so that the current metric structure is retained by the MQTT Server and delivered to any client that subscribes.*# -[[payloads_c_dmeta]] +[[payloads_p_dmeta]] ==== DMETA The DMETA describes the metric structure (metadata) of a Sparkplug Device. It is the Device @@ -1985,7 +1985,7 @@ messages MUST be published with the MQTT QoS set to 0.*# * [tck-testable tck-id-payloads-dmeta-retain]#[yellow-background]*[tck-id-payloads-dmeta-retain] A full DMETA MUST be published with the MQTT retain flag set to true.*# -[[payloads_c_nmmeta]] +[[payloads_p_nmmeta]] ==== NMMETA and DMMETA An NMMETA (for an Edge Node) or DMMETA (for a Device) conveys a change to the metric structure after @@ -2018,7 +2018,7 @@ name, and MUST include the complete new definition for that metric.*# DELETE metric MUST be identified by its existing alias, if an alias was assigned, or otherwise by its name.*# -[[payloads_c_nbirth]] +[[payloads_p_nbirth]] ==== NBIRTH The NBIRTH reports the current values of the Edge Node's metrics to Host Applications. It does not @@ -2070,7 +2070,7 @@ messages MUST be published with the MQTT retain flag set to false.*# The following is a representation of a simple NBIRTH message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/NBIRTH/EdgeNode1 +Acme/Dublin/Packaging/spPv4.0/NBIRTH/EdgeNode1 ---- In the topic above the following information is known based on the Sparkplug topic definition: @@ -2138,7 +2138,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_c_nrebirth]] +[[payloads_p_nrebirth]] ==== NREBIRTH The NREBIRTH reports the current values of the Edge Node's metrics to a specific Host Application that @@ -2195,7 +2195,7 @@ messages MUST be published with the MQTT retain flag set to false.*# The following is a representation of a simple NREBIRTH message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/NREBIRTH/EdgeNode1 +Acme/Dublin/Packaging/spPv4.0/NREBIRTH/EdgeNode1 ---- In the topic above the following information is known based on the Sparkplug topic definition: @@ -2263,7 +2263,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_c_dbirth]] +[[payloads_p_dbirth]] ==== DBIRTH The DBIRTH reports the current values of a Sparkplug Device's metrics to Host Applications. It does not @@ -2300,7 +2300,7 @@ messages MUST be published with the MQTT retain flag set to false.*# The following is a representation of a simple DBIRTH message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/DBIRTH/EdgeNode1/Filler +Acme/Dublin/Packaging/spPv4.0/DBIRTH/EdgeNode1/Filler ---- In the topic above the following information is known based on the Sparkplug topic definition: @@ -2368,7 +2368,7 @@ This would result in a structure as follows on the Host Application. .Figure 11 – Sparkplug B Metric Structure 2 plantuml::{assetsdir}assets/plantuml/sparkplugb-metric-structure-2.puml[format=svg, alt="Sparkplug B Metric Structure 2"] -[[payloads_c_drebirth]] +[[payloads_p_drebirth]] ==== DREBIRTH The DREBIRTH reports the current values of a Sparkplug Device's metrics to a specific Host Application @@ -2403,7 +2403,7 @@ messages MUST be published with the MQTT retain flag set to false.*# The following is a representation of a simple DREBIRTH message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/DREBIRTH/EdgeNode1/Filler +Acme/Dublin/Packaging/spPv4.0/DREBIRTH/EdgeNode1/Filler ---- In the topic above the following information is known based on the Sparkplug topic definition: @@ -2471,7 +2471,7 @@ This would result in a structure as follows on the Host Application. .Figure 11 – Sparkplug B Metric Structure 2 plantuml::{assetsdir}assets/plantuml/sparkplugb-metric-structure-2.puml[format=svg, alt="Sparkplug B Metric Structure 2"] -[[payloads_c_ndata]] +[[payloads_p_ndata]] ==== NDATA NDATA messages are used to update the values of any Edge Node metrics that were originally published @@ -2506,7 +2506,7 @@ describes this Edge Node, and MUST identify each metric by its alias or name.*# The following is a representation of a simple NDATA message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/NDATA/EdgeNode1 +Acme/Dublin/Packaging/spPv4.0/NDATA/EdgeNode1 ---- In the topic above the following information is known based on the Sparkplug topic definition: @@ -2538,7 +2538,7 @@ Consider the following Sparkplug B payload in the NDATA message shown above: This would result in the host application updating the value of the 'Supply Voltage' metric. -[[payloads_c_ddata]] +[[payloads_p_ddata]] ==== DDATA DDATA messages are used to update the values of any device metrics that were originally published in @@ -2572,7 +2572,7 @@ describes this Device, and MUST identify each metric by its alias or name.*# The following is a representation of a simple DDATA message on the topic: -Acme/Dublin/Packaging/spCv4.0/DDATA/EdgeNode1/Filler +Acme/Dublin/Packaging/spPv4.0/DDATA/EdgeNode1/Filler * The ‘Topic Prefix’ is: Acme/Dublin/Packaging * The ‘Edge Node ID’ is: EdgeNode1 @@ -2607,7 +2607,7 @@ Consider the following Sparkplug B payload in the DDATA message shown above: This would result in the Host Application updating the value of the ‘Running’ metric and ‘Speed’ metric. -[[payloads_c_rebirth]] +[[payloads_p_rebirth]] ==== REBIRTH REBIRTH messages are used by Host Applications to resync with an Edge Nodes existing data stream. @@ -2628,7 +2628,7 @@ value representing the Host ID of the Sparkplug Host Application that sent the R The following is a representation of a REBIRTH message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/REBIRTH/EdgeNode1 +Acme/Dublin/Packaging/spPv4.0/REBIRTH/EdgeNode1 ---- * The ‘Topic Prefix’ is: Acme/Dublin/Packaging @@ -2650,7 +2650,7 @@ This REBIRTH payload tells the Edge Node to publish NREBIRTH and DREBIRTH(s) mes requested if a Host Application gets an out of order seq number or if a metric arrives in an NDATA or DDATA message that was not provided in the original NBIRTH or DBIRTH messages. -[[payloads_c_ncmd]] +[[payloads_p_ncmd]] ==== NCMD NCMD messages are used by Host Applications to write to Edge Node outputs and send Node Control @@ -2677,7 +2677,7 @@ forwarding metric writes on behalf of another Host Application.*# The following is a representation of a simple NCMD message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/NCMD/EdgeNode1 +Acme/Dublin/Packaging/spPv4.0/NCMD/EdgeNode1 ---- * The ‘Topic Prefix’ is: Acme/Dublin/Packaging @@ -2709,7 +2709,7 @@ DIGITAL_OUT_1 is successfully set to true. An NCMD message MAY also invoke a strongly typed Command that was included in the NBIRTH. In this case the metric datatype is Command and the metric carries a Command object with the supplied -argument values and a correlation_id. See the link:#payloads_c_command[Command Section] for the +argument values and a correlation_id. See the link:#payloads_p_command[Command Section] for the full Command Request rules. * [tck-testable tck-id-payloads-ncmd-command-correlation]#[yellow-background]*[tck-id-payloads-ncmd-command-correlation] An @@ -2744,7 +2744,7 @@ The following is a representation of an NCMD payload that invokes the 'Calibrate The Edge Node executes the command and publishes the result in an NRESP message that echoes the correlation_id. -[[payloads_c_dcmd]] +[[payloads_p_dcmd]] ==== DCMD DCMD messages are used by Host Applications to write to device outputs and send Device Control @@ -2771,7 +2771,7 @@ forwarding metric writes on behalf of another Host Application.*# The following is a representation of a simple DCMD message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/DCMD/EdgeNode1/Filler +Acme/Dublin/Packaging/spPv4.0/DCMD/EdgeNode1/Filler ---- * The ‘Topic Prefix’ is: Acme/Dublin/Packaging @@ -2808,17 +2808,17 @@ As a result, the Filler should begin running and result in a DDATA message back after the motor is successfully started. A DCMD message MAY also invoke a strongly typed Command that was supplied in the DBIRTH, following -the same Command Request rules as NCMD. See the link:#payloads_c_command[Command Section]. +the same Command Request rules as NCMD. See the link:#payloads_p_command[Command Section]. * [tck-testable tck-id-payloads-dcmd-command-correlation]#[yellow-background]*[tck-id-payloads-dcmd-command-correlation] A DCMD message that invokes a Command MUST include a correlation_id in the Command object.*# -[[payloads_c_nresp]] +[[payloads_p_nresp]] ==== NRESP NRESP messages are published by an Edge Node to return the result of an Edge Node level Command Request that was received in an NCMD message. See the -link:#payloads_c_command[Command Section] for the structure of a Command Response. +link:#payloads_p_command[Command Section] for the structure of a Command Response. * [tck-testable tck-id-payloads-nresp-timestamp]#[yellow-background]*[tck-id-payloads-nresp-timestamp] NRESP messages MUST include an overall payload timestamp that denotes the time at which the message was @@ -2834,7 +2834,7 @@ NRESP message MUST include a status for the command being responded to.*# The following is a representation of a simple NRESP message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/NRESP/EdgeNode1 +Acme/Dublin/Packaging/spPv4.0/NRESP/EdgeNode1 ---- * The ‘Topic Prefix’ is: Acme/Dublin/Packaging @@ -2876,12 +2876,12 @@ Consider the following Sparkplug B payload in the NRESP message shown above: The NRESP payload returns the result of the 'Calibrate' command that was invoked in a prior NCMD, correlated by the matching correlation_id. -[[payloads_c_dresp]] +[[payloads_p_dresp]] ==== DRESP DRESP messages are published by an Edge Node to return the result of a Device level Command Request that was received in a DCMD message. See the -link:#payloads_c_command[Command Section] for the structure of a Command Response. +link:#payloads_p_command[Command Section] for the structure of a Command Response. * [tck-testable tck-id-payloads-dresp-timestamp]#[yellow-background]*[tck-id-payloads-dresp-timestamp] DRESP messages MUST include an overall payload timestamp that denotes the time at which the message was @@ -2897,7 +2897,7 @@ DRESP message MUST include a status for the command being responded to.*# The following is a representation of a simple DRESP message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/DRESP/EdgeNode1/Filler +Acme/Dublin/Packaging/spPv4.0/DRESP/EdgeNode1/Filler ---- * The ‘Topic Prefix’ is: Acme/Dublin/Packaging @@ -2935,7 +2935,7 @@ Consider the following Sparkplug B payload in the DRESP message shown above: The DRESP payload returns an error status for the 'Reset' command that was invoked in a prior DCMD, correlated by the matching correlation_id. -[[payloads_c_ndeath]] +[[payloads_p_ndeath]] ==== NDEATH The NDEATH messages are registered with the MQTT Server in the MQTT CONNECT packet as the 'Will @@ -2992,7 +2992,7 @@ to tell which session an NDEATH refers to. The following is a representation of a NDEATH message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/NDEATH/EdgeNode1 +Acme/Dublin/Packaging/spPv4.0/NDEATH/EdgeNode1 ---- * The ‘Topic Prefix’ is: Acme/Dublin/Packaging @@ -3013,7 +3013,7 @@ Consider the following Sparkplug B payload in the NDEATH message shown above: The bd_seq number value in the payload allows a Host Application to reconcile this NDEATH with the NBIRTH and/or NREBIRTH that occurred previously. -[[payloads_c_ddeath]] +[[payloads_p_ddeath]] ==== DDEATH The DDEATH messages are published by an Edge Node on behalf of an attached device. If the Edge Node @@ -3034,7 +3034,7 @@ sequence number sent MUST have a value of 0.*# The following is a representation of a simple DDEATH message on the topic: ---- -Acme/Dublin/Packaging/spCv4.0/DDEATH/EdgeNode1/Filler +Acme/Dublin/Packaging/spPv4.0/DDEATH/EdgeNode1/Filler ---- * The ‘Topic Prefix’ is: Acme/Dublin/Packaging @@ -3059,7 +3059,7 @@ Consider the following Sparkplug B payload in the DDEATH message shown above: sequence number MUST be included with the DDEATH messages so the Host Application can ensure order of messages and maintain the state of the data.*# -[[payloads_c_state]] +[[payloads_p_state]] ==== STATE As noted previously, the STATE messages published by Sparkplug Host Applications do not use @@ -3068,7 +3068,7 @@ whether or not the Sparkplug Host Application is online and operational or not. * [tck-testable tck-id-payloads-state-will-message]#[yellow-background]*[tck-id-payloads-state-will-message] Sparkplug Host Applications MUST register a Will Message in the MQTT CONNECT packet on the topic -'spCv4.0/STATE/[sparkplug_host_id]'.*# +'spPv4.0/STATE/[sparkplug_host_id]'.*# ** The [sparkplug_host_id] must be replaced with the Sparkplug Host Application's ID. This can be any UTF-8 string. * [tck-testable tck-id-payloads-state-will-message-qos]#[yellow-background]*[tck-id-payloads-state-will-message-qos] The @@ -3079,21 +3079,21 @@ Sparkplug Host Application MUST set the Will Retained flag to true in the MQTT C Death Certificate Payload MUST be JSON UTF-8 data. It MUST include four key/value pairs. One key MUST be 'online' and it's value is a boolean 'false'. One key MUST be 'timestamp' and the value MUST be a numeric value representing the current UTC time in nanoseconds since Epoch. One key MUST be -'bd_seq' and the value MUST be a numeric value as defined in the link:#payloads_c_state_bd_seq[STATE +'bd_seq' and the value MUST be a numeric value as defined in the link:#payloads_p_state_bd_seq[STATE bd_seq Number] section. One key MUST be 'client_id' and the value MUST be the UTF-8 MQTT Client ID that the Sparkplug Host Application used in the MQTT CONNECT packet that registered this Will Message.*# * [tck-testable tck-id-payloads-state-subscribe]#[yellow-background]*[tck-id-payloads-state-subscribe] After establishing an MQTT connection, the Sparkplug Host Application MUST subscribe on it's own -'spCv4.0/STATE/[sparkplug_host_id]' topic.*# +'spPv4.0/STATE/[sparkplug_host_id]' topic.*# ** The [sparkplug_host_id] should be replaced with the Sparkplug Host Application's ID. This can be any UTF-8 string. ** Non-normative comment: This allows the Sparkplug Host Application handle timing issues around STATE 'offline' messages being published on it's behalf by the MQTT Server when it is in fact online. * [tck-testable tck-id-payloads-state-birth]#[yellow-background]*[tck-id-payloads-state-birth] After -subscribing on it's own spCv4.0/STATE/[sparkplug_host_id] topic, the Sparkplug Host Application MUST -publish an MQTT message on the topic 'spCv4.0/STATE/[sparkplug_host_id]' with a QoS of 1, and the +subscribing on it's own spPv4.0/STATE/[sparkplug_host_id] topic, the Sparkplug Host Application MUST +publish an MQTT message on the topic 'spPv4.0/STATE/[sparkplug_host_id]' with a QoS of 1, and the retain flag set to true.*# ** The [sparkplug_host_id] should be replaced with the Sparkplug Host Application's ID. This can be any UTF-8 string. @@ -3105,7 +3105,7 @@ Message payload. One key MUST be 'bd_seq' and the value MUST match the bd_seq va that same Will Message payload. One key MUST be 'client_id' and the value MUST be the UTF-8 MQTT Client ID that the Sparkplug Host Application used in that same MQTT CONNECT packet.*# -[[payloads_c_state_bd_seq]] +[[payloads_p_state_bd_seq]] ===== STATE bd_seq Number The bd_seq number in a STATE payload scopes that STATE message to a single MQTT session of a @@ -3136,7 +3136,7 @@ an independent bd_seq number for each MQTT Server.*# Server independently, so a single shared counter would advance for reasons unrelated to the server a consuming Edge Node is connected to. -[[payloads_c_state_client_id]] +[[payloads_p_state_client_id]] ===== STATE client_id The client_id in a STATE payload is the MQTT Client ID of the MQTT client that published the @@ -3166,7 +3166,7 @@ The following is a representation of a Sparkplug Host Application Birth Certific topic: ---- -spCv4.0/STATE/my_host_application +spPv4.0/STATE/my_host_application ---- ---- @@ -3190,7 +3190,7 @@ packet carries the same timestamp, the same bd_seq number, and the same client_i } ---- -[[payloads_c_compression]] +[[payloads_p_compression]] ==== Compression Sparkplug payloads may optionally be compressed to further improve bandwidth utilization. @@ -3265,10 +3265,10 @@ definition identifier, without decompressing anything. It decompresses the conte determined from the header that the message is of interest to it and that it supports the named algorithm. -[[payloads_c_file_publishing]] +[[payloads_p_file_publishing]] ==== File Publishing -Sparkplug C supports publishing of files either a single published metric or in multi-part form. If +Sparkplug P supports publishing of files either a single published metric or in multi-part form. If publishing as a single metric, the following rules apply. * [tck-testable tck-id-payloads-file-single-metric-data]#[yellow-background]*[tck-id-payloads-file-single-metric-data] When @@ -3331,7 +3331,7 @@ the file publish. Non-normative comment: The rules below identify a metric by its position in the payload, which is the one place in this specification where the position of a metric carries meaning. This does not conflict with the requirement that metrics be ordered by value change time, stated in the -link:#payloads_c_payload_content[Content] section, because every metric of a multi-part file +link:#payloads_p_payload_content[Content] section, because every metric of a multi-part file publish carries the same timestamp. They therefore tie, the ordering requirement does not constrain their relative order, and the order the publishing Edge Node or Device chooses is carried unchanged by both payload encodings. @@ -3372,7 +3372,7 @@ MUST be set to an array of bytes representing this metric's portion of the file. metrics that are not the first metric in the multi-part file MUST either not include the is_null flag or it MUST be set to false.*# -[[payloads_c_file_publish_acknowledgment]] +[[payloads_p_file_publish_acknowledgment]] ==== File Publish Acknowledgment When a file is published as described above, the receiving application may acknowledge each received file @@ -3387,8 +3387,8 @@ receiving application SHOULD publish an acknowledgment for each received file me confirm receipt and, for a multi-part file publish, advance the transfer to the next part.*# * [tck-testable tck-id-payloads-file-ack-topic]#[yellow-background]*[tck-id-payloads-file-ack-topic] When a receiving application acknowledges a received file metric, the acknowledgment MUST be published as an -NCMD message on topic '[topic_prefix/]spCv4.0/NCMD/edge_node_id' if the file metric was received in an NDATA -message, or as a DCMD message on topic '[topic_prefix/]spCv4.0/DCMD/edge_node_id/device_tokens' if the file metric +NCMD message on topic '[topic_prefix/]spPv4.0/NCMD/edge_node_id' if the file metric was received in an NDATA +message, or as a DCMD message on topic '[topic_prefix/]spPv4.0/DCMD/edge_node_id/device_tokens' if the file metric was received in a DDATA message, scoped to the same Sparkplug Edge Node or Device that published the file.*# * [tck-testable tck-id-payloads-file-ack-seq-metric]#[yellow-background]*[tck-id-payloads-file-ack-seq-metric] The @@ -3519,7 +3519,7 @@ on the publishing (transmission) side, and 5xx indicate an error on the receivin Sparkplug defines two payload encodings of the same data model. The Google Protocol Buffers encoding is defined in the link:#payloads_sparkplug_c_mqtt_payload_definition[Sparkplug B MQTT -Payload Definition] section above and is published on the spCv4.0 namespace. The JSON encoding is +Payload Definition] section above and is published on the spPv4.0 namespace. The JSON encoding is defined in this section and is published on the spJv4.0 namespace. The two encodings carry identical information. Every component defined in the sections above - @@ -3531,7 +3531,7 @@ session management defined elsewhere in this specification is encoding independe Non-normative comment: Because the two encodings are two representations of one model, a message may be converted from one to the other without loss and without consulting anything outside the -message itself. This is what allows a bridging application to republish an spCv4.0 namespace onto +message itself. This is what allows a bridging application to republish an spPv4.0 namespace onto spJv4.0, or the reverse, as a mechanical transformation. This section defines the JSON encoding completely. Conformance to it does not depend on any @@ -3557,9 +3557,9 @@ payload of any Sparkplug message published on the spJv4.0 namespace MUST be enco this section.*# [tck-testable tck-id-payloads-protobuf-namespace-encoding]#[yellow-background]*[tck-id-payloads-protobuf-namespace-encoding] The -payload of any Sparkplug message published on the spCv4.0 namespace MUST be encoded using the +payload of any Sparkplug message published on the spPv4.0 namespace MUST be encoded using the Google Protocol Buffers schema defined in the -link:#payloads_c_google_protocol_buffer_schema[Google Protocol Buffer Schema] section.*# +link:#payloads_p_google_protocol_buffer_schema[Google Protocol Buffer Schema] section.*# [tck-testable tck-id-payloads-json-utf8]#[yellow-background]*[tck-id-payloads-json-utf8] A Sparkplug JSON payload MUST be a JSON text as defined by RFC 8259, encoded as UTF-8 with no byte order @@ -3707,7 +3707,7 @@ UInt64, and DateTime have the same exposure. Non-normative comment: The sequence numbers are subject to this for the same reason. A Sparkplug seq, bd_seq, and descriptor_seq each count up to 9223372036854775807 before rolling over to zero, as -required in the link:#payloads_c_payload_header[Header] section, so they reach magnitudes a JSON +required in the link:#payloads_p_payload_header[Header] section, so they reach magnitudes a JSON number cannot carry exactly. A sequence number is small early in a session and large late in one, which would make a numeric form correct in testing and lossy in production. @@ -3795,7 +3795,7 @@ because it is observable in a payload, whereas the absence of meaning in the ord In the Protocol Buffers encoding the array DataTypes and a DataSet.Column carry their elements in a ValueArray, which selects one of several typed arrays and records absent elements separately, as -described in the link:#payloads_c_datatype_array[Array Types] section. In JSON the datatype is +described in the link:#payloads_p_datatype_array[Array Types] section. In JSON the datatype is already known and a JSON array can hold a null directly, so a ValueArray is represented as a plain array. @@ -4038,10 +4038,10 @@ Sparkplug JSON payload MUST validate against the JSON Schema below.*# The following is a non-normative example of one DDATA message shown in both encodings, so the two may be compared directly. The payload reports a single aliased Float metric. -The spCv4.0 form, shown as a structural illustration of the Protocol Buffers message: +The spPv4.0 form, shown as a structural illustration of the Protocol Buffers message: ---- -Acme/Dublin/Packaging/spCv4.0/DDATA/EdgeNode1/Line3 +Acme/Dublin/Packaging/spPv4.0/DDATA/EdgeNode1/Line3 ---- ---- @@ -4112,7 +4112,7 @@ encode and decode cost is of roughly one order of magnitude, and unlike the size not narrow with message size. Non-normative comment: The size difference largely disappears when the content section is -compressed, as described in the link:#payloads_c_compression[Compression] section. The repeated +compressed, as described in the link:#payloads_p_compression[Compression] section. The repeated field names that make JSON large are highly compressible, so for payloads of more than a few metrics the two encodings compress to within a few percent of one another. On a bandwidth constrained link where compression is already in use, message size is therefore not a strong reason @@ -4124,5 +4124,5 @@ and frequent, which is the case Sparkplug was originally designed around. The JS better fit where Sparkplug data is consumed directly by applications that cannot readily add a Protocol Buffers dependency, and where readability during development and troubleshooting is worth more than the bytes. A deployment may use both, with a bridging application republishing one -namespace onto the other, so that constrained Edge Nodes publish spCv4.0 while enterprise consumers +namespace onto the other, so that constrained Edge Nodes publish spPv4.0 while enterprise consumers subscribe to spJv4.0. diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_7_Security.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_7_Security.adoc index 04f1739a..c075509c 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_7_Security.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_7_Security.adoc @@ -75,26 +75,26 @@ device_tokens (Sparkplug Device) = D1 Based on this, the following could be reasonable MQTT ACLs to be provisioned in the MQTT Server for the MQTT client associated with this Edge Node: ``` -Publish: plantA/spCv4.0/NMETA/E1 -Publish: plantA/spCv4.0/NMMETA/E1 -Publish: plantA/spCv4.0/NBIRTH/E1 -Publish: plantA/spCv4.0/NREBIRTH/E1 -Publish: plantA/spCv4.0/NDATA/E1 -Publish: plantA/spCv4.0/NRESP/E1 -Publish: plantA/spCv4.0/NDEATH/E1 -Publish: plantA/spCv4.0/DMETA/E1/D1 -Publish: plantA/spCv4.0/DMMETA/E1/D1 -Publish: plantA/spCv4.0/DBIRTH/E1/D1 -Publish: plantA/spCv4.0/DREBIRTH/E1/D1 -Publish: plantA/spCv4.0/DDATA/E1/D1 -Publish: plantA/spCv4.0/DRESP/E1/D1 -Publish: plantA/spCv4.0/DDEATH/E1/D1 -Subscribe: plantA/spCv4.0/REBIRTH/E1 -Subscribe: plantA/spCv4.0/NCMD/E1 -Subscribe: plantA/spCv4.0/DCMD/E1/D1 -Subscribe: plantA/spCv4.0/NMETA/E1 -Subscribe: plantA/spCv4.0/DMETA/E1/D1 -Subscribe: spCv4.0/STATE/my_primary_host +Publish: plantA/spPv4.0/NMETA/E1 +Publish: plantA/spPv4.0/NMMETA/E1 +Publish: plantA/spPv4.0/NBIRTH/E1 +Publish: plantA/spPv4.0/NREBIRTH/E1 +Publish: plantA/spPv4.0/NDATA/E1 +Publish: plantA/spPv4.0/NRESP/E1 +Publish: plantA/spPv4.0/NDEATH/E1 +Publish: plantA/spPv4.0/DMETA/E1/D1 +Publish: plantA/spPv4.0/DMMETA/E1/D1 +Publish: plantA/spPv4.0/DBIRTH/E1/D1 +Publish: plantA/spPv4.0/DREBIRTH/E1/D1 +Publish: plantA/spPv4.0/DDATA/E1/D1 +Publish: plantA/spPv4.0/DRESP/E1/D1 +Publish: plantA/spPv4.0/DDEATH/E1/D1 +Subscribe: plantA/spPv4.0/REBIRTH/E1 +Subscribe: plantA/spPv4.0/NCMD/E1 +Subscribe: plantA/spPv4.0/DCMD/E1/D1 +Subscribe: plantA/spPv4.0/NMETA/E1 +Subscribe: plantA/spPv4.0/DMETA/E1/D1 +Subscribe: spPv4.0/STATE/my_primary_host ``` Three of these are easy to overlook. The subscription on REBIRTH is mandatory, because an Edge Node @@ -113,37 +113,37 @@ an Edge Node has many dynamic associated devices. In this case, it may make sens device level topic token. Note that device_tokens may be more than one topic level deep, so a multi level wildcard is used here rather than a single level wildcard: ``` -Publish: plantA/spCv4.0/NMETA/E1 -Publish: plantA/spCv4.0/NMMETA/E1 -Publish: plantA/spCv4.0/NBIRTH/E1 -Publish: plantA/spCv4.0/NREBIRTH/E1 -Publish: plantA/spCv4.0/NDATA/E1 -Publish: plantA/spCv4.0/NRESP/E1 -Publish: plantA/spCv4.0/NDEATH/E1 -Publish: plantA/spCv4.0/DMETA/E1/# -Publish: plantA/spCv4.0/DMMETA/E1/# -Publish: plantA/spCv4.0/DBIRTH/E1/# -Publish: plantA/spCv4.0/DREBIRTH/E1/# -Publish: plantA/spCv4.0/DDATA/E1/# -Publish: plantA/spCv4.0/DRESP/E1/# -Publish: plantA/spCv4.0/DDEATH/E1/# -Subscribe: plantA/spCv4.0/REBIRTH/E1 -Subscribe: plantA/spCv4.0/NCMD/E1 -Subscribe: plantA/spCv4.0/DCMD/E1/# -Subscribe: plantA/spCv4.0/NMETA/E1 -Subscribe: plantA/spCv4.0/DMETA/E1/# -Subscribe: spCv4.0/STATE/my_primary_host +Publish: plantA/spPv4.0/NMETA/E1 +Publish: plantA/spPv4.0/NMMETA/E1 +Publish: plantA/spPv4.0/NBIRTH/E1 +Publish: plantA/spPv4.0/NREBIRTH/E1 +Publish: plantA/spPv4.0/NDATA/E1 +Publish: plantA/spPv4.0/NRESP/E1 +Publish: plantA/spPv4.0/NDEATH/E1 +Publish: plantA/spPv4.0/DMETA/E1/# +Publish: plantA/spPv4.0/DMMETA/E1/# +Publish: plantA/spPv4.0/DBIRTH/E1/# +Publish: plantA/spPv4.0/DREBIRTH/E1/# +Publish: plantA/spPv4.0/DDATA/E1/# +Publish: plantA/spPv4.0/DRESP/E1/# +Publish: plantA/spPv4.0/DDEATH/E1/# +Subscribe: plantA/spPv4.0/REBIRTH/E1 +Subscribe: plantA/spPv4.0/NCMD/E1 +Subscribe: plantA/spPv4.0/DCMD/E1/# +Subscribe: plantA/spPv4.0/NMETA/E1 +Subscribe: plantA/spPv4.0/DMETA/E1/# +Subscribe: spPv4.0/STATE/my_primary_host ``` Also, it may be the case that DCMD messages should not be 'writable'. In this case, maybe DCMD subscriptions should not be allowed at all. In this case, the DCMD subscription is removed and the rest of the ACLs are unchanged: ``` -Subscribe: plantA/spCv4.0/REBIRTH/E1 -Subscribe: plantA/spCv4.0/NCMD/E1 -Subscribe: plantA/spCv4.0/NMETA/E1 -Subscribe: plantA/spCv4.0/DMETA/E1/# -Subscribe: spCv4.0/STATE/my_primary_host +Subscribe: plantA/spPv4.0/REBIRTH/E1 +Subscribe: plantA/spPv4.0/NCMD/E1 +Subscribe: plantA/spPv4.0/NMETA/E1 +Subscribe: plantA/spPv4.0/DMETA/E1/# +Subscribe: spPv4.0/STATE/my_primary_host ``` Note that the REBIRTH subscription cannot be removed in the same way. Denying it would prevent the @@ -156,19 +156,19 @@ ACLs for a Sparkplug Host Application follow the same approach. Consider a Host Sparkplug Host Application ID 'my_primary_host' that consumes the 'plantA' namespace and sends commands to it: ``` -Publish: spCv4.0/STATE/my_primary_host -Subscribe: spCv4.0/STATE/my_primary_host -Subscribe: plantA/spCv4.0/# -Publish: plantA/spCv4.0/REBIRTH/+ -Publish: plantA/spCv4.0/NCMD/+ -Publish: plantA/spCv4.0/DCMD/# +Publish: spPv4.0/STATE/my_primary_host +Subscribe: spPv4.0/STATE/my_primary_host +Subscribe: plantA/spPv4.0/# +Publish: plantA/spPv4.0/REBIRTH/+ +Publish: plantA/spPv4.0/NCMD/+ +Publish: plantA/spPv4.0/DCMD/# ``` The first two entries are the ones that matter most. A Sparkplug Host Application is the only client with a legitimate reason to publish on its own STATE topic, and it is required to subscribe to that same topic so that it can detect and repair displacement of the retained value. Note that the entry granting it publish access names its own STATE topic specifically. An entry of the form -'spCv4.0/STATE/#' would additionally grant it publish access to every other Host Application's STATE +'spPv4.0/STATE/#' would additionally grant it publish access to every other Host Application's STATE topic, which would let it displace their retained STATE values. The consequences of that are described in the link:#operational_behavior_host_application_own_state_limits[Limits of Retained STATE Restoration] diff --git a/tck/src/main/java/org/eclipse/sparkplug/tck/test/Monitor.java b/tck/src/main/java/org/eclipse/sparkplug/tck/test/Monitor.java index 1ae2459e..9337be75 100644 --- a/tck/src/main/java/org/eclipse/sparkplug/tck/test/Monitor.java +++ b/tck/src/main/java/org/eclipse/sparkplug/tck/test/Monitor.java @@ -342,13 +342,13 @@ public void onDisconnect(DisconnectEventInput disconnectEventInput) { } @SpecAssertion( - section = Sections.PAYLOADS_C_STATE, + section = Sections.PAYLOADS_P_STATE, id = ID_PAYLOADS_STATE_BIRTH_PAYLOAD) @SpecAssertion( section = Sections.PAYLOADS_DESC_NBIRTH, id = ID_TOPICS_NBIRTH_BDSEQ_INCREMENT) @SpecAssertion( - section = Sections.PAYLOADS_C_STATE, + section = Sections.PAYLOADS_P_STATE, id = ID_PAYLOADS_STATE_WILL_MESSAGE_PAYLOAD) @SpecAssertion( section = Sections.PAYLOADS_DESC_STATE_DEATH, @@ -493,7 +493,7 @@ public void subscribe(String clientId, SubscribePacket packet) { } @SpecAssertion( - section = Sections.PAYLOADS_C_PAYLOAD, + section = Sections.PAYLOADS_P_PAYLOAD, id = ID_PAYLOADS_TIMESTAMP_IN_UTC) @SpecAssertion( section = Sections.TOPICS_NAMESPACE_ELEMENT, @@ -715,10 +715,10 @@ private boolean checkMQTTChars(String inString) { section = Sections.TOPICS_EDGE_NODE_ID_ELEMENT, id = ID_TOPIC_STRUCTURE_NAMESPACE_UNIQUE_EDGE_NODE_DESCRIPTOR) @SpecAssertion( - section = Sections.PAYLOADS_C_NBIRTH, + section = Sections.PAYLOADS_P_NBIRTH, id = ID_PAYLOADS_NBIRTH_SEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_NBIRTH, + section = Sections.PAYLOADS_P_NBIRTH, id = ID_PAYLOADS_NBIRTH_EDGE_NODE_DESCRIPTOR) @SpecAssertion( section = Sections.OPERATIONAL_BEHAVIOR_DATA_PUBLISH, @@ -815,7 +815,7 @@ private void handleNBIRTH(String group_id, String edge_node_id, String clientId, section = Sections.TOPICS_EDGE_NODE_ID_ELEMENT, id = ID_TOPIC_STRUCTURE_NAMESPACE_UNIQUE_EDGE_NODE_DESCRIPTOR) @SpecAssertion( - section = Sections.PAYLOADS_C_NBIRTH, + section = Sections.PAYLOADS_P_NBIRTH, id = ID_PAYLOADS_NBIRTH_EDGE_NODE_DESCRIPTOR) private void handleNDEATH(String group_id, String edge_node_id, String clientId) { @@ -852,7 +852,7 @@ private void handleNDEATH(String group_id, String edge_node_id, String clientId) } @SpecAssertion( - section = Sections.PAYLOADS_C_NDATA, + section = Sections.PAYLOADS_P_NDATA, id = ID_PAYLOADS_NDATA_SEQ_INC) @SpecAssertion( section = Sections.PAYLOADS_DESC_NBIRTH, @@ -873,7 +873,7 @@ private void handleNDEATH(String group_id, String edge_node_id, String clientId) section = Sections.PRINCIPLES_REPORT_BY_EXCEPTION, id = ID_PRINCIPLES_RBE_RECOMMENDED) @SpecAssertion( - section = Sections.PAYLOADS_C_PAYLOAD, + section = Sections.PAYLOADS_P_PAYLOAD, id = ID_PAYLOADS_SEQUENCE_NUM_INCREMENTING) private void handleNDATA(String group_id, String edge_node_id, PayloadOrBuilder payload) { logger.info("Monitor: *** NDATA *** {}/{}", group_id, edge_node_id); @@ -1015,7 +1015,7 @@ private void handleNDATA(String group_id, String edge_node_id, PayloadOrBuilder // TODO(#598): device_id UNIQUE / DUPLICATE-ACROSS-EDGE-NODE @SpecAssertions removed with the // device_id element; re-add device_tokens coverage when the TCK topic model is updated. @SpecAssertion( - section = Sections.PAYLOADS_C_DBIRTH, + section = Sections.PAYLOADS_P_DBIRTH, id = ID_PAYLOADS_DBIRTH_SEQ_INC) @SpecAssertion( section = Sections.OPERATIONAL_BEHAVIOR_DEVICE_SESSION_ESTABLISHMENT, @@ -1138,7 +1138,7 @@ private void handleDBIRTH(String group_id, String edge_node_id, String device_id } @SpecAssertion( - section = Sections.PAYLOADS_C_DDEATH, + section = Sections.PAYLOADS_P_DDEATH, id = ID_PAYLOADS_DDEATH_SEQ_INC) private void handleDDEATH(String group_id, String edge_node_id, String device_id, PayloadOrBuilder payload) { logger.info("Monitor: *** DDEATH *** {}/{}/{}", group_id, edge_node_id, device_id); @@ -1174,7 +1174,7 @@ private void handleDDEATH(String group_id, String edge_node_id, String device_id } @SpecAssertion( - section = Sections.PAYLOADS_C_DDATA, + section = Sections.PAYLOADS_P_DDATA, id = ID_PAYLOADS_DDATA_SEQ_INC) @SpecAssertion( section = Sections.PAYLOADS_DESC_DBIRTH, @@ -1195,7 +1195,7 @@ private void handleDDEATH(String group_id, String edge_node_id, String device_id section = Sections.PRINCIPLES_REPORT_BY_EXCEPTION, id = ID_PRINCIPLES_RBE_RECOMMENDED) @SpecAssertion( - section = Sections.PAYLOADS_C_PAYLOAD, + section = Sections.PAYLOADS_P_PAYLOAD, id = ID_PAYLOADS_SEQUENCE_NUM_INCREMENTING) private void handleDDATA(String group_id, String edge_node_id, String device_id, PayloadOrBuilder payload) { logger.info("Monitor: *** DDATA *** {}/{}/{}", group_id, edge_node_id, device_id); diff --git a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/ReceiveCommandTest.java b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/ReceiveCommandTest.java index fda3fdf5..64385e67 100644 --- a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/ReceiveCommandTest.java +++ b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/ReceiveCommandTest.java @@ -254,7 +254,7 @@ public Map getResults() { } @SpecAssertion( - section = Sections.PAYLOADS_C_NDEATH, + section = Sections.PAYLOADS_P_NDEATH, id = ID_PAYLOADS_NDEATH_WILL_MESSAGE) @Override public void connect(final String clientId, final ConnectPacket packet) { diff --git a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java index 42225df5..53d189a3 100644 --- a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java +++ b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java @@ -318,7 +318,7 @@ private void checkCommandTopicPayload(final @NotNull String clientId, final @Not } @SpecAssertion( - section = Sections.PAYLOADS_C_PAYLOAD, + section = Sections.PAYLOADS_P_PAYLOAD, id = ID_PAYLOADS_SEQUENCE_NUM_ALWAYS_INCLUDED) public void checkSequenceNumberIncluded(final @NotNull PublishPacket packet, String topic) { logger.debug( @@ -343,10 +343,10 @@ public void checkSequenceNumberIncluded(final @NotNull PublishPacket packet, Str } @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_METRIC_DATATYPE_VALUE_TYPE) @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_METRIC_DATATYPE_VALUE) public void checkDatatypeValidType(final @NotNull PublishPacket packet) { boolean isValid_DataType = true; @@ -383,19 +383,19 @@ public void checkDatatypeValidType(final @NotNull PublishPacket packet) { } @SpecAssertion( - section = Sections.PAYLOADS_C_PROPERTYSET, + section = Sections.PAYLOADS_P_PROPERTYSET, id = ID_PAYLOADS_PROPERTYSET_KEYS_ARRAY_SIZE) @SpecAssertion( - section = Sections.PAYLOADS_C_PROPERTYSET, + section = Sections.PAYLOADS_P_PROPERTYSET, id = ID_PAYLOADS_PROPERTYSET_VALUES_ARRAY_SIZE) @SpecAssertion( - section = Sections.PAYLOADS_C_PROPERTYVALUE, + section = Sections.PAYLOADS_P_PROPERTYVALUE, id = ID_PAYLOADS_METRIC_PROPERTYVALUE_TYPE_TYPE) @SpecAssertion( - section = Sections.PAYLOADS_C_PROPERTYVALUE, + section = Sections.PAYLOADS_P_PROPERTYVALUE, id = ID_PAYLOADS_METRIC_PROPERTYVALUE_TYPE_VALUE) @SpecAssertion( - section = Sections.PAYLOADS_C_PROPERTYVALUE, + section = Sections.PAYLOADS_P_PROPERTYVALUE, id = ID_PAYLOADS_METRIC_PROPERTYVALUE_TYPE_REQ) public void checkPropertiesValidType(final @NotNull PublishPacket packet, String topic) { boolean isValid_KeyArraySize = true; @@ -409,7 +409,7 @@ public void checkPropertiesValidType(final @NotNull PublishPacket packet, String isValid_KeyArraySize = false; isValid_PropertyValueType = false; isValid_PropertyValueTypeReq = false; - logger.error("Check req set for : {}", Sections.PAYLOADS_C_PROPERTYVALUE); + logger.error("Check req set for : {}", Sections.PAYLOADS_P_PROPERTYVALUE); } else { logger.debug( "Check Req: {} The array of keys in a PropertySet MUST contain the same number of values included in the array of PropertyValue objects.", @@ -463,7 +463,7 @@ public void checkPropertiesValidType(final @NotNull PublishPacket packet, String // corresponds to anything the specification defines; see the Sparkplug v4 TCK rewrite. @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_ALIAS_DATA_CMD_REQUIREMENT) public void checkAliasInData(final @NotNull PayloadOrBuilder sparkplugPayload, String topic) { logger.debug( @@ -484,7 +484,7 @@ public void checkAliasInData(final @NotNull PayloadOrBuilder sparkplugPayload, S } @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_METRIC_DATATYPE_NOT_REQ) public void checkMetricsDataTypeNotRec(final @NotNull PayloadOrBuilder sparkplugPayload, String topic) { logger.debug( @@ -505,7 +505,7 @@ public void checkMetricsDataTypeNotRec(final @NotNull PayloadOrBuilder sparkplug } @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_NAME_REQUIREMENT) public void checkPayloadsNameRequirement(final @NotNull PayloadOrBuilder sparkplugPayload) { logger.debug("Check Req: The name MUST be included with every metric unless aliases are being used."); @@ -520,7 +520,7 @@ public void checkPayloadsNameRequirement(final @NotNull PayloadOrBuilder sparkpl } @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_NAME_BIRTH_DATA_REQUIREMENT) public void checkPayloadsNameInDataRequirement(final @NotNull PayloadOrBuilder sparkplugPayload) { logger.debug( @@ -537,53 +537,53 @@ public void checkPayloadsNameInDataRequirement(final @NotNull PayloadOrBuilder s } @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_IS_DEFINITION) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_DEFINITION_IS_DEFINITION) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_INSTANCE_IS_DEFINITION) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_DEFINITION_REF) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_REF_DEFINITION) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_INSTANCE_REF) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_IS_DEFINITION_DEFINITION) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_IS_DEFINITION_INSTANCE) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_REF_INSTANCE) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_VERSION) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE_PARAMETER, + section = Sections.PAYLOADS_P_TEMPLATE_PARAMETER, id = ID_PAYLOADS_TEMPLATE_PARAMETER_NAME_REQUIRED) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE_PARAMETER, + section = Sections.PAYLOADS_P_TEMPLATE_PARAMETER, id = ID_PAYLOADS_TEMPLATE_PARAMETER_NAME_TYPE) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE_PARAMETER, + section = Sections.PAYLOADS_P_TEMPLATE_PARAMETER, id = ID_PAYLOADS_TEMPLATE_PARAMETER_VALUE_TYPE) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE_PARAMETER, + section = Sections.PAYLOADS_P_TEMPLATE_PARAMETER, id = ID_PAYLOADS_TEMPLATE_PARAMETER_TYPE_VALUE) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE_PARAMETER, + section = Sections.PAYLOADS_P_TEMPLATE_PARAMETER, id = ID_PAYLOADS_TEMPLATE_PARAMETER_TYPE_REQ) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE_PARAMETER, + section = Sections.PAYLOADS_P_TEMPLATE_PARAMETER, id = ID_PAYLOADS_TEMPLATE_PARAMETER_VALUE) public boolean checkTemplate(final @NotNull PublishPacket packet) { final PayloadOrBuilder sparkplugPayload = Utils.getSparkplugPayload(packet); diff --git a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendDataTest.java b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendDataTest.java index ff5001ae..2457eae8 100644 --- a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendDataTest.java +++ b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendDataTest.java @@ -289,16 +289,16 @@ public void publish(String clientId, PublishPacket packet) { } @SpecAssertion( - section = Sections.PAYLOADS_C_NDATA, + section = Sections.PAYLOADS_P_NDATA, id = ID_PAYLOADS_NDATA_TIMESTAMP) @SpecAssertion( - section = Sections.PAYLOADS_C_NDATA, + section = Sections.PAYLOADS_P_NDATA, id = ID_PAYLOADS_NDATA_SEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_NDATA, + section = Sections.PAYLOADS_P_NDATA, id = ID_PAYLOADS_NDATA_QOS) @SpecAssertion( - section = Sections.PAYLOADS_C_NDATA, + section = Sections.PAYLOADS_P_NDATA, id = ID_PAYLOADS_NDATA_RETAIN) @SpecAssertion( section = Sections.PAYLOADS_DESC_NDATA, @@ -316,7 +316,7 @@ public void publish(String clientId, PublishPacket packet) { section = Sections.TOPICS_DATA_MESSAGE_NDATA, id = ID_TOPICS_NDATA_TOPIC) @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_METRIC_TIMESTAMP_IN_UTC) public void checkNDATA(String clientId, PublishPacket packet) { logger.info("Send data test payload::check Edge Node data - Start"); @@ -396,16 +396,16 @@ public void checkNDATA(String clientId, PublishPacket packet) { } @SpecAssertion( - section = Sections.PAYLOADS_C_DDATA, + section = Sections.PAYLOADS_P_DDATA, id = ID_PAYLOADS_DDATA_TIMESTAMP) @SpecAssertion( - section = Sections.PAYLOADS_C_DDATA, + section = Sections.PAYLOADS_P_DDATA, id = ID_PAYLOADS_DDATA_SEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_DDATA, + section = Sections.PAYLOADS_P_DDATA, id = ID_PAYLOADS_DDATA_QOS) @SpecAssertion( - section = Sections.PAYLOADS_C_DDATA, + section = Sections.PAYLOADS_P_DDATA, id = ID_PAYLOADS_DDATA_RETAIN) @SpecAssertion( section = Sections.PAYLOADS_DESC_DDATA, @@ -423,7 +423,7 @@ public void checkNDATA(String clientId, PublishPacket packet) { section = Sections.TOPICS_DATA_MESSAGE_DDATA, id = ID_TOPICS_DDATA_TOPIC) @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_METRIC_TIMESTAMP_IN_UTC) public void checkDDATA(String clientId, PublishPacket packet) { logger.info("Send data test payload::check Device data - Start"); @@ -526,28 +526,28 @@ private Boolean[] checkValidPayload(PayloadOrBuilder payload) { } @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_INSTANCE_REF) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_DEFINITION_MEMBERS) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_INSTANCE_MEMBERS_BIRTH) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_INSTANCE_MEMBERS_DATA) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_DEFINITION_MEMBERS) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_INSTANCE_MEMBERS) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_DEFINITION_PARAMETERS) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_INSTANCE_PARAMETERS) private void checkInstance(String sparkplugDescriptor, String instanceName, Payload.Template instance, String msgtype) { @@ -658,10 +658,10 @@ private void checkInstance(String sparkplugDescriptor, String instanceName, Payl } @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_DEFINITION_REF) @SpecAssertion( - section = Sections.PAYLOADS_C_TEMPLATE, + section = Sections.PAYLOADS_P_TEMPLATE, id = ID_PAYLOADS_TEMPLATE_DEFINITION_PARAMETERS_DEFAULT) public void checkNBIRTH(String clientId, PublishPacket packet) { diff --git a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SessionEstablishmentTest.java b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SessionEstablishmentTest.java index 540fa6bf..3193cc89 100644 --- a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SessionEstablishmentTest.java +++ b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SessionEstablishmentTest.java @@ -218,7 +218,7 @@ public void endTest(Map results) { section = Sections.PRINCIPLES_PERSISTENT_VS_NON_PERSISTENT_CONNECTIONS, id = ID_PRINCIPLES_PERSISTENCE_CLEAN_SESSION_50) @SpecAssertion( - section = Sections.PAYLOADS_C_NDEATH, + section = Sections.PAYLOADS_P_NDEATH, id = ID_PAYLOADS_NDEATH_WILL_MESSAGE) @SpecAssertion( @@ -320,10 +320,10 @@ public void subscribe(final @NotNull String clientId, final @NotNull SubscribePa section = Sections.PRINCIPLES_BIRTH_AND_DEATH_CERTIFICATES, id = ID_PRINCIPLES_BIRTH_CERTIFICATES_ORDER) @SpecAssertion( - section = Sections.PAYLOADS_C_NDATA, + section = Sections.PAYLOADS_P_NDATA, id = ID_PAYLOADS_NDATA_ORDER) @SpecAssertion( - section = Sections.PAYLOADS_C_DDATA, + section = Sections.PAYLOADS_P_DDATA, id = ID_PAYLOADS_DDATA_ORDER) public void publish(final @NotNull String clientId, final @NotNull PublishPacket packet) { @@ -372,7 +372,7 @@ public void publish(final @NotNull String clientId, final @NotNull PublishPacket } @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_NAME_BIRTH_DATA_REQUIREMENT) public void checkPayloadsNameInDataRequirement(final @NotNull PayloadOrBuilder sparkplugPayload) { logger.debug( @@ -393,10 +393,10 @@ public void checkPayloadsNameInDataRequirement(final @NotNull PayloadOrBuilder s } @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_ALIAS_BIRTH_REQUIREMENT) @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_ALIAS_UNIQUENESS) public void checkPayloadsAliasAndNameRequirement(final @NotNull PayloadOrBuilder sparkplugPayload) { logger.debug("Check Req: " @@ -422,16 +422,16 @@ public void checkPayloadsAliasAndNameRequirement(final @NotNull PayloadOrBuilder } @SpecAssertion( - section = Sections.PAYLOADS_C_NDEATH, + section = Sections.PAYLOADS_P_NDEATH, id = ID_PAYLOADS_NDEATH_WILL_MESSAGE_QOS) @SpecAssertion( - section = Sections.PAYLOADS_C_NDEATH, + section = Sections.PAYLOADS_P_NDEATH, id = ID_PAYLOADS_NDEATH_SEQ) @SpecAssertion( section = Sections.PAYLOADS_DESC_NDEATH, id = ID_TOPICS_NDEATH_SEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_NDEATH, + section = Sections.PAYLOADS_P_NDEATH, id = ID_PAYLOADS_NDEATH_WILL_MESSAGE_RETAIN) @SpecAssertion( section = Sections.PAYLOADS_DESC_NDEATH, @@ -513,31 +513,31 @@ public Optional checkWillMessage(final @NotNull ConnectPacket id = ID_TOPICS_NBIRTH_METRICS) @SpecAssertion( - section = Sections.PAYLOADS_C_NBIRTH, + section = Sections.PAYLOADS_P_NBIRTH, id = ID_PAYLOADS_NBIRTH_BDSEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_NBIRTH, + section = Sections.PAYLOADS_P_NBIRTH, id = ID_PAYLOADS_NBIRTH_QOS) @SpecAssertion( - section = Sections.PAYLOADS_C_NBIRTH, + section = Sections.PAYLOADS_P_NBIRTH, id = ID_PAYLOADS_NBIRTH_RETAIN) @SpecAssertion( - section = Sections.PAYLOADS_C_NBIRTH, + section = Sections.PAYLOADS_P_NBIRTH, id = ID_PAYLOADS_NBIRTH_SEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_PAYLOAD, + section = Sections.PAYLOADS_P_PAYLOAD, id = ID_PAYLOADS_SEQUENCE_NUM_REQ_NBIRTH) @SpecAssertion( - section = Sections.PAYLOADS_C_NBIRTH, + section = Sections.PAYLOADS_P_NBIRTH, id = ID_PAYLOADS_NBIRTH_TIMESTAMP) @SpecAssertion( - section = Sections.PAYLOADS_C_NBIRTH, + section = Sections.PAYLOADS_P_NBIRTH, id = ID_PAYLOADS_NBIRTH_REBIRTH_REQ) @SpecAssertion( - section = Sections.PAYLOADS_C_NDEATH, + section = Sections.PAYLOADS_P_NDEATH, id = ID_PAYLOADS_NDEATH_BDSEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_METRIC_DATATYPE_REQ) @SpecAssertion( section = Sections.OPERATIONAL_BEHAVIOR_DATA_PUBLISH, @@ -565,7 +565,7 @@ public Optional checkWillMessage(final @NotNull ConnectPacket section = Sections.OPERATIONAL_BEHAVIOR_EDGE_NODE_SESSION_ESTABLISHMENT, id = ID_MESSAGE_FLOW_EDGE_NODE_BIRTH_PUBLISH_NBIRTH_PAYLOAD_BDSEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_NBIRTH, + section = Sections.PAYLOADS_P_NBIRTH, id = ID_PAYLOADS_NBIRTH_BDSEQ_REPEAT) @SpecAssertion( section = Sections.TOPICS_BIRTH_MESSAGE_NBIRTH, @@ -696,22 +696,22 @@ public void checkNBirth(final @NotNull PublishPacket packet) { } @SpecAssertion( - section = Sections.PAYLOADS_C_DBIRTH, + section = Sections.PAYLOADS_P_DBIRTH, id = ID_PAYLOADS_DBIRTH_QOS) @SpecAssertion( - section = Sections.PAYLOADS_C_DBIRTH, + section = Sections.PAYLOADS_P_DBIRTH, id = ID_PAYLOADS_DBIRTH_RETAIN) @SpecAssertion( - section = Sections.PAYLOADS_C_DBIRTH, + section = Sections.PAYLOADS_P_DBIRTH, id = ID_PAYLOADS_DBIRTH_TIMESTAMP) @SpecAssertion( - section = Sections.PAYLOADS_C_DBIRTH, + section = Sections.PAYLOADS_P_DBIRTH, id = ID_PAYLOADS_DBIRTH_SEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_DBIRTH, + section = Sections.PAYLOADS_P_DBIRTH, id = ID_PAYLOADS_DBIRTH_SEQ_INC) @SpecAssertion( - section = Sections.PAYLOADS_C_DBIRTH, + section = Sections.PAYLOADS_P_DBIRTH, id = ID_PAYLOADS_DBIRTH_ORDER) @SpecAssertion( section = Sections.PAYLOADS_DESC_DBIRTH, @@ -750,10 +750,10 @@ public void checkNBirth(final @NotNull PublishPacket packet) { section = Sections.OPERATIONAL_BEHAVIOR_DEVICE_SESSION_ESTABLISHMENT, id = ID_MESSAGE_FLOW_DEVICE_BIRTH_PUBLISH_DBIRTH_PAYLOAD) @SpecAssertion( - section = Sections.PAYLOADS_C_NDATA, + section = Sections.PAYLOADS_P_NDATA, id = ID_PAYLOADS_NDATA_ORDER) @SpecAssertion( - section = Sections.PAYLOADS_C_DDATA, + section = Sections.PAYLOADS_P_DDATA, id = ID_PAYLOADS_DDATA_ORDER) @SpecAssertion( section = Sections.TOPICS_BIRTH_MESSAGE_DBIRTH, diff --git a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SessionTerminationTest.java b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SessionTerminationTest.java index d33f23ea..658a0d31 100644 --- a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SessionTerminationTest.java +++ b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SessionTerminationTest.java @@ -204,10 +204,10 @@ public void connect(final @NotNull String clientId, final @NotNull ConnectPacket } @SpecAssertion( - section = Sections.PAYLOADS_C_NDEATH, + section = Sections.PAYLOADS_P_NDEATH, id = ID_PAYLOADS_NDEATH_WILL_MESSAGE_PUBLISHER_DISCONNECT_MQTT311) @SpecAssertion( - section = Sections.PAYLOADS_C_NDEATH, + section = Sections.PAYLOADS_P_NDEATH, id = ID_PAYLOADS_NDEATH_WILL_MESSAGE_PUBLISHER_DISCONNECT_MQTT50) @SpecAssertion( section = Sections.OPERATIONAL_BEHAVIOR_EDGE_NODE_SESSION_TERMINATION, @@ -279,19 +279,19 @@ public void subscribe(final @NotNull String clientId, final @NotNull SubscribePa section = Sections.PAYLOADS_DESC_DDEATH, id = ID_TOPICS_DDEATH_SEQ_NUM) @SpecAssertion( - section = Sections.PAYLOADS_C_DDEATH, + section = Sections.PAYLOADS_P_DDEATH, id = ID_PAYLOADS_DDEATH_TIMESTAMP) @SpecAssertion( - section = Sections.PAYLOADS_C_DDEATH, + section = Sections.PAYLOADS_P_DDEATH, id = ID_PAYLOADS_DDEATH_SEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_DDEATH, + section = Sections.PAYLOADS_P_DDEATH, id = ID_PAYLOADS_DDEATH_SEQ_INC) @SpecAssertion( - section = Sections.PAYLOADS_C_DDEATH, + section = Sections.PAYLOADS_P_DDEATH, id = ID_PAYLOADS_DDEATH_SEQ_NUMBER) @SpecAssertion( - section = Sections.PAYLOADS_C_NDEATH, + section = Sections.PAYLOADS_P_NDEATH, id = ID_PAYLOADS_NDEATH_WILL_MESSAGE_PUBLISHER) @SpecAssertion( diff --git a/tck/src/main/java/org/eclipse/sparkplug/tck/test/host/SendCommandTest.java b/tck/src/main/java/org/eclipse/sparkplug/tck/test/host/SendCommandTest.java index 75c36595..6e7b31ec 100644 --- a/tck/src/main/java/org/eclipse/sparkplug/tck/test/host/SendCommandTest.java +++ b/tck/src/main/java/org/eclipse/sparkplug/tck/test/host/SendCommandTest.java @@ -346,16 +346,16 @@ public void publish(String clientId, PublishPacket packet) { } @SpecAssertion( - section = Sections.PAYLOADS_C_NCMD, + section = Sections.PAYLOADS_P_NCMD, id = ID_PAYLOADS_NCMD_TIMESTAMP) @SpecAssertion( - section = Sections.PAYLOADS_C_NCMD, + section = Sections.PAYLOADS_P_NCMD, id = ID_PAYLOADS_NCMD_SEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_NCMD, + section = Sections.PAYLOADS_P_NCMD, id = ID_PAYLOADS_NCMD_QOS) @SpecAssertion( - section = Sections.PAYLOADS_C_NCMD, + section = Sections.PAYLOADS_P_NCMD, id = ID_PAYLOADS_NCMD_RETAIN) @SpecAssertion( section = Sections.PAYLOADS_DESC_NCMD, @@ -417,16 +417,16 @@ private void checkNodeCommand(final String clientId, final @NotNull PublishPacke } @SpecAssertion( - section = Sections.PAYLOADS_C_DCMD, + section = Sections.PAYLOADS_P_DCMD, id = ID_PAYLOADS_DCMD_TIMESTAMP) @SpecAssertion( - section = Sections.PAYLOADS_C_DCMD, + section = Sections.PAYLOADS_P_DCMD, id = ID_PAYLOADS_DCMD_SEQ) @SpecAssertion( - section = Sections.PAYLOADS_C_DCMD, + section = Sections.PAYLOADS_P_DCMD, id = ID_PAYLOADS_DCMD_QOS) @SpecAssertion( - section = Sections.PAYLOADS_C_DCMD, + section = Sections.PAYLOADS_P_DCMD, id = ID_PAYLOADS_DCMD_RETAIN) @SpecAssertion( section = Sections.PAYLOADS_DESC_DCMD, @@ -577,7 +577,7 @@ private Boolean[] checkValidCommandPayload(PayloadOrBuilder payload) { } @SpecAssertion( - section = Sections.PAYLOADS_C_METRIC, + section = Sections.PAYLOADS_P_METRIC, id = ID_PAYLOADS_NAME_CMD_REQUIREMENT) public void checkPayloadsTimestampCommand(final @NotNull PayloadOrBuilder sparkplugPayload, String topic) { logger.debug("Check Req: The timestamp MAY be included with metrics in NCMD and DCMD messages."); diff --git a/tck/src/main/java/org/eclipse/sparkplug/tck/test/host/SessionEstablishmentTest.java b/tck/src/main/java/org/eclipse/sparkplug/tck/test/host/SessionEstablishmentTest.java index e0c927de..08ae2a8f 100644 --- a/tck/src/main/java/org/eclipse/sparkplug/tck/test/host/SessionEstablishmentTest.java +++ b/tck/src/main/java/org/eclipse/sparkplug/tck/test/host/SessionEstablishmentTest.java @@ -381,7 +381,7 @@ public void publish(final @NotNull String clientId, final @NotNull PublishPacket section = Sections.OPERATIONAL_BEHAVIOR_PRIMARY_HOST_APPLICATION_SESSION_ESTABLISHMENT, id = ID_MESSAGE_FLOW_PHID_SPARKPLUG_CLEAN_SESSION_50) @SpecAssertion( - section = Sections.PAYLOADS_C_STATE, + section = Sections.PAYLOADS_P_STATE, id = ID_PAYLOADS_STATE_WILL_MESSAGE) @SpecAssertion( section = Sections.TOPICS_DEATH_MESSAGE_STATE, @@ -448,13 +448,13 @@ private boolean checkConnectMessage(final @NotNull ConnectPacket packet) { section = Sections.DEATH_MESSAGE_STATE, id = ID_HOST_TOPIC_PHID_DEATH_RETAIN) @SpecAssertion( - section = Sections.PAYLOADS_C_STATE, + section = Sections.PAYLOADS_P_STATE, id = ID_PAYLOADS_STATE_WILL_MESSAGE_QOS) @SpecAssertion( - section = Sections.PAYLOADS_C_STATE, + section = Sections.PAYLOADS_P_STATE, id = ID_PAYLOADS_STATE_WILL_MESSAGE_RETAIN) @SpecAssertion( - section = Sections.PAYLOADS_C_STATE, + section = Sections.PAYLOADS_P_STATE, id = ID_PAYLOADS_STATE_WILL_MESSAGE_PAYLOAD) private boolean checkDeathMessage(final @NotNull ConnectPacket packet) { @@ -546,7 +546,7 @@ private boolean checkDeathMessage(final @NotNull ConnectPacket packet) { } @SpecAssertion( - section = Sections.PAYLOADS_C_STATE, + section = Sections.PAYLOADS_P_STATE, id = ID_PAYLOADS_STATE_SUBSCRIBE) @SpecAssertion( section = Sections.TOPICS_BIRTH_MESSAGE_STATE, @@ -630,10 +630,10 @@ private boolean checkSubscribes(final boolean shouldBeSubscribed) { id = ID_MESSAGE_FLOW_PHID_SPARKPLUG_STATE_PUBLISH_PAYLOAD) @SpecAssertion( - section = Sections.PAYLOADS_C_STATE, + section = Sections.PAYLOADS_P_STATE, id = ID_PAYLOADS_STATE_BIRTH) @SpecAssertion( - section = Sections.PAYLOADS_C_STATE, + section = Sections.PAYLOADS_P_STATE, id = ID_PAYLOADS_STATE_BIRTH_PAYLOAD) @SpecAssertion( section = Sections.PAYLOADS_DESC_STATE_BIRTH, From 814c029e73e8cf7b9e92b434aac4f6bcbaddac8f Mon Sep 17 00:00:00 2001 From: wes-johnson Date: Fri, 13 Nov 2026 19:58:37 +0000 Subject: [PATCH 2/2] [#231] Review fixes: the encoding letter list and the schema filename - The Payload Encoding Scheme bullet still listed the letters as 'A', 'B', 'C', or 'J'. My sweep searched for spCv4.0, Sparkplug C and the payloads_c_ identifiers, none of which match a bare quoted letter. - States the rule the rename introduced, which the specification did not say anywhere: from version 4.0 the letter names the payload encoding rather than the generation of the scheme. Without it a reader sees 'first A, second B, most recent P' with no explanation, and 'P' can read as Protocol Buffers in general, which Sparkplug B also is. - Renames the extracted schema artifact to sparkplug_p.proto, both in the task that writes it and in the 'To compile' comment carried verbatim into it. The TCK consumes the artifact as a single file without reference to its name. - payloads_sparkplug_c_mqtt_payload_definition anchors a section titled 'Sparkplug B MQTT Payload Definition', beside a sibling anchored payloads_sparkplug_a_. The letter was wrong before this PR; it is now payloads_sparkplug_b_mqtt_payload_definition. --- specification/build.gradle.kts | 2 +- .../main/asciidoc/chapters/Sparkplug_1_Introduction.adoc | 5 ++++- .../src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc | 6 +++--- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/specification/build.gradle.kts b/specification/build.gradle.kts index 55b0cf7c..b9d6b0bf 100644 --- a/specification/build.gradle.kts +++ b/specification/build.gradle.kts @@ -247,7 +247,7 @@ val extractProtoSchema by tasks.registering { group = "tck" val chapter = layout.projectDirectory.file( "src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc") - val output = layout.buildDirectory.file("proto/sparkplug_c.proto") + val output = layout.buildDirectory.file("proto/sparkplug_p.proto") inputs.file(chapter) outputs.file(output) doLast { diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc index f4f57d9e..653199c7 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_1_Introduction.adoc @@ -83,7 +83,10 @@ Each token is divided up into three distinct components. These are: * Sparkplug Identifier ** Always 'sp' * Payload Encoding Scheme -** Currently 'A', 'B', 'C', or 'J' but there could be future encoding schemes +** Currently 'A', 'B', 'P', or 'J' but there could be future encoding schemes +** From version 4.0 the letter names the payload encoding rather than the generation of the +encoding scheme: 'P' for Google Protocol Buffers and 'J' for JSON. 'A' and 'B' are the earlier +schemes, which were lettered by generation. * Sparkplug Specification Version ** The major and minor version of the Sparkplug Specification that first defined the encoding scheme ** 'Sparkplug A' and 'Sparkplug B' were defined by specification versions that predate this diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc index 8d206708..8fc0343e 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc @@ -65,7 +65,7 @@ https://developers.google.com/protocol-buffers/ As described in the link:#introduction_define_the_mqtt_payload[Introduction Section] Sparkplug A is deprecated and is not included in this document. -[[payloads_sparkplug_c_mqtt_payload_definition]] +[[payloads_sparkplug_b_mqtt_payload_definition]] === Sparkplug B MQTT Payload Definition The goal of Sparkplug is to provide a specification that both OEM device manufactures and @@ -121,7 +121,7 @@ being requested. The entire Google Protocol Buffers definition is below. // // To compile: // cd client_libraries/java -// protoc --proto_path=../../ --java_out=src/main/java ../../sparkplug_c.proto +// protoc --proto_path=../../ --java_out=src/main/java ../../sparkplug_p.proto // Requires protoc 27 or later and a Protocol Buffers runtime that supports edition 2023 // (protobuf-java 4.27 or later, Python protobuf 5.27 or later, and equivalents). // @@ -3518,7 +3518,7 @@ on the publishing (transmission) side, and 5xx indicate an error on the receivin ==== Overview Sparkplug defines two payload encodings of the same data model. The Google Protocol Buffers -encoding is defined in the link:#payloads_sparkplug_c_mqtt_payload_definition[Sparkplug B MQTT +encoding is defined in the link:#payloads_sparkplug_b_mqtt_payload_definition[Sparkplug B MQTT Payload Definition] section above and is published on the spPv4.0 namespace. The JSON encoding is defined in this section and is published on the spJv4.0 namespace.