Skip to content

[#145] Made quality a top level metric member and added quality context #559

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 9, 2025
Merged

[#145] Made quality a top level metric member and added quality context #559

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
73 changes: 34 additions & 39 deletions specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,18 +282,20 @@ message Payload {

message Metric {

optional string name = 1; // Metric name - Required in BIRTH messages, optional in DATA messages if using aliases
optional uint64 alias = 2; // Metric alias - tied to name on BIRTH and included in all later DATA messages
optional uint64 timestamp = 3; // Timestamp associated with data acquisition time - if omitted, the overall payload timestamp is assumed as the data acquisition time
optional DataType datatype = 4; // DataType of the metric/tag value
optional string source = 5; // Source for CMD messages if unique to the Metric (typically for forwarded writes in CMD messages)
optional bool is_historical = 6; // If this is historical data and should not update real time tag
optional bool is_transient = 7; // Tells consuming clients such as MQTT Engine to not store this as a tag
optional bool is_null = 8; // If this is null - explicitly say so rather than using -1, false, etc for some datatypes.
optional MetaData metadata = 9; // Metadata for the Metric
optional PropertySet properties = 10; // Properties of the Metric
optional TypedValue value = 11;
extensions 12 to max;
optional string name = 1; // Metric name - Required in BIRTH messages, optional in DATA messages if using aliases
optional uint64 alias = 2; // Metric alias - tied to name on BIRTH and included in all later DATA messages
optional uint64 timestamp = 3; // Timestamp associated with data acquisition time - if omitted, the overall payload timestamp is assumed as the data acquisition time
optional DataType datatype = 4; // DataType of the metric/tag value
optional int32 quality = 5; // Quality code of the metric/tag value
optional string quality_context = 6; // The optional quality context of the metric/tag value
optional string source = 7; // Source for CMD messages if unique to the Metric (typically for forwarded writes in CMD messages)
optional bool is_historical = 8; // If this is historical data and should not update real time tag
optional bool is_transient = 9; // Tells consuming clients such as MQTT Engine to not store this as a tag
optional bool is_null = 10; // If this is null - explicitly say so rather than using -1, false, etc for some datatypes.
optional MetaData metadata = 11; // Metadata for the Metric
optional PropertySet properties = 12; // Properties of the Metric
optional TypedValue value = 13;
extensions 14 to max;
}

optional uint64 timestamp = 1; // Timestamp at message sending time
Expand Down Expand Up @@ -452,7 +454,6 @@ name MUST be included with every metric unless aliases are being used.*#
** All UTF-8 characters are allowed in the metric name. However, special characters including but
not limited to the following are discouraged: . , \ @ # $ % ^ & * ( ) [ ] { } | ! ` ~ : ; ' " < > ?.
This is because many Sparkplug Host Applications may have issues handling them.

* *alias*
** This is an unsigned 64-bit integer representing an optional alias for a Sparkplug B payload.
Aliases are optional and not required. *If aliases are used, the following rules apply.*
Expand Down Expand Up @@ -493,6 +494,22 @@ link:#payloads_b_datatypes[valid Sparkplug Data Types].*#
datatype MUST be included with each metric definition in NBIRTH and DBIRTH messages.*#
** [tck-testable tck-id-payloads-metric-datatype-not-req]#[yellow-background]*[tck-id-payloads-metric-datatype-not-req] The
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. 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.
** There are three defined qualities. These are defined below with their associated meanings.
*** *0*
**** BAD
*** *192*
**** GOOD
*** *500*
**** STALE
** [tck-testable tck-id-payloads-quality-value]#[yellow-background]*[tck-id-payloads-quality-value] The
value of quality MUST be an int32.*#
* *quality_context*
** This is an optional string value used to provide additional context to the quality code of the
metric.
* *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
Expand Down Expand Up @@ -628,43 +645,21 @@ can be found here: https://developers.google.com/protocol-buffers/docs/proto#sca
[[payloads_b_well_known_properties]]
==== Well Known Properties

[cols="1,5"]
[cols="1,1,5"]
|===
|*Key Name*
|*Type*
|*Value*

|engUnit
|_string_
|UNECE codes for 'units of measure' are recommended

|readOnly
|_bool_
|True or False
|===


[[payloads_b_quality_codes]]
===== Quality Codes

There is one specific property key in Sparkplug called 'Quality'. This defines the quality of the
value associated with the metric. This property is optional and is only required if the quality of
the metric is not GOOD.

There are three possible quality code values. These are defined below with their associated
meanings.

* *0*
** BAD
* *192*
** GOOD
* *500*
** STALE

[tck-testable tck-id-payloads-propertyset-quality-value-type]#[yellow-background]*[tck-id-payloads-propertyset-quality-value-type] The
'type' of the Property Value MUST be a value of 3 which represents a Signed 32-bit Integer.*#

[tck-testable tck-id-payloads-propertyset-quality-value-value]#[yellow-background]*[tck-id-payloads-propertyset-quality-value-value] The
'value' of the Property Value MUST be an int_value and be one of the valid quality codes of 0, 192,
or 500.*#

[[payloads_b_propertysetlist]]
==== PropertySetList

Expand Down
Loading