Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view

Large diffs are not rendered by default.

10 changes: 5 additions & 5 deletions docs/sparkplug_4.0.0_release_plan/Sparkplug4.0.0ReleasePlan.md
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion specification/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ autonumber 1 "<b>(#)"
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** )
Expand Down Expand Up @@ -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** )
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.*#
Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment thread
wes-johnson marked this conversation as resolved.
Resolved
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
----
Comment thread
wes-johnson marked this conversation as resolved.
Resolved

Expand All @@ -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
Expand All @@ -106,11 +109,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]]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
Loading
Loading