Type-safe builder for Sparkplug B payloads with automatic type detection. More...

#include <payload_builder.hpp>

Public Member Functions
	PayloadBuilder ()
	Constructs an empty payload.

template<SparkplugMetricType T>
PayloadBuilder &	add_metric (std::string_view name, T &&value)
	Adds a metric by name only (for NBIRTH without aliases).

template<SparkplugMetricType T>
PayloadBuilder &	add_metric (std::string_view name, T &&value, uint64_t timestamp_ms)
	Adds a metric by name with a custom timestamp.

template<SparkplugMetricType T>
PayloadBuilder &	add_metric_with_alias (std::string_view name, uint64_t alias, T &&value)
	Adds a metric with both name and alias (for NBIRTH messages).

template<SparkplugMetricType T>
PayloadBuilder &	add_metric_with_alias (std::string_view name, uint64_t alias, T &&value, uint64_t timestamp_ms)
	Adds a metric with name, alias, and custom timestamp (for NBIRTH with historical data).

template<SparkplugMetricType T>
PayloadBuilder &	add_metric_by_alias (uint64_t alias, T &&value)
	Adds a metric by alias only (for NDATA messages).

template<SparkplugMetricType T>
PayloadBuilder &	add_metric_by_alias (uint64_t alias, T &&value, uint64_t timestamp_ms)
	Adds a metric by alias with a custom timestamp.

PayloadBuilder &	set_timestamp (uint64_t ts)
	Sets the payload-level timestamp.

PayloadBuilder &	set_seq (uint64_t seq)
	Sets the sequence number manually.

PayloadBuilder &	add_node_control_rebirth (bool value=false)

PayloadBuilder &	add_node_control_reboot (bool value=false)

PayloadBuilder &	add_node_control_next_server (bool value=false)

PayloadBuilder &	add_node_control_scan_rate (int64_t value)

bool	has_seq () const noexcept

bool	has_timestamp () const noexcept

std::vector< uint8_t >	build () const

const org::eclipse::tahu::protobuf::Payload &	payload () const noexcept

org::eclipse::tahu::protobuf::Payload &	mutable_payload () noexcept

Detailed Description

Type-safe builder for Sparkplug B payloads with automatic type detection.

PayloadBuilder provides a fluent API for constructing Sparkplug B payloads with compile-time type safety. It automatically:

Maps C++ types to Sparkplug DataTypes
Generates timestamps (milliseconds since Unix epoch)
Manages sequence numbers (when used with Publisher)

Supported Types

Integers: int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t
Floating-point: float, double
Boolean: bool
String: std::string, std::string_view, const char*

Usage Patterns

NBIRTH messages: Use add_metric_with_alias() to establish metric names with their aliases.

sparkplug::PayloadBuilder birth;
birth.add_metric_with_alias("Temperature", 1, 20.5);
birth.add_metric_with_alias("Pressure", 2, 101.3);
publisher.publish_birth(birth);

NDATA messages: Use add_metric_by_alias() for bandwidth-efficient updates. Your application decides which metrics to include based on Report by Exception principles (i.e., only metrics that have changed according to your domain-specific criteria).

sparkplug::PayloadBuilder data;
data.add_metric_by_alias(1, 21.0);  // Application determined Temperature changed
publisher.publish_data(data);       // (Pressure unchanged, not included)

See also: Publisher::publish_birth(); Publisher::publish_data()

Definition at line 187 of file payload_builder.hpp.

Member Function Documentation

◆ add_metric() [1/2]

template<SparkplugMetricType T>

PayloadBuilder & sparkplug::PayloadBuilder::add_metric	(	std::string_view	name,
		T &&	value
	)

inline

Adds a metric by name only (for NBIRTH without aliases).

Template Parameters

T	Value type (automatically deduced, must satisfy SparkplugMetricType)

Parameters

name	Metric name
value	Metric value

Returns: Reference to this builder for method chaining

Note: Timestamp is automatically generated.

Definition at line 206 of file payload_builder.hpp.

◆ add_metric() [2/2]

template<SparkplugMetricType T>

PayloadBuilder & sparkplug::PayloadBuilder::add_metric	(	std::string_view	name,
		T &&	value,
		uint64_t	timestamp_ms
	)

inline

Adds a metric by name with a custom timestamp.

Template Parameters

T	Value type (automatically deduced, must satisfy SparkplugMetricType)

Parameters

name	Metric name
value	Metric value
timestamp_ms	Custom timestamp in milliseconds since Unix epoch

Returns: Reference to this builder for method chaining

Note: Useful for historical data or backdated metrics.

Definition at line 225 of file payload_builder.hpp.

◆ add_metric_by_alias() [1/2]

template<SparkplugMetricType T>

PayloadBuilder & sparkplug::PayloadBuilder::add_metric_by_alias	(	uint64_t	alias,
		T &&	value
	)

inline

Adds a metric by alias only (for NDATA messages).

Template Parameters

T	Value type (automatically deduced, must satisfy SparkplugMetricType)

Parameters

alias	Metric alias (must be established in NBIRTH)
value	Metric value

Returns: Reference to this builder for method chaining

Note: Your application is responsible for implementing Report by Exception (RBE): only call this method for metrics that have changed according to your domain-specific criteria (e.g., deadband, threshold, exact equality).; Reduces bandwidth by 60-80% vs. using full metric names.

Definition at line 290 of file payload_builder.hpp.

◆ add_metric_by_alias() [2/2]

template<SparkplugMetricType T>

PayloadBuilder & sparkplug::PayloadBuilder::add_metric_by_alias	(	uint64_t	alias,
		T &&	value,
		uint64_t	timestamp_ms
	)

inline

Adds a metric by alias with a custom timestamp.

Template Parameters

T	Value type (automatically deduced, must satisfy SparkplugMetricType)

Parameters

alias	Metric alias
value	Metric value
timestamp_ms	Custom timestamp in milliseconds since Unix epoch

Returns: Reference to this builder for method chaining

Note: Useful for historical data with specific timestamps.

Definition at line 309 of file payload_builder.hpp.

◆ add_metric_with_alias() [1/2]

template<SparkplugMetricType T>

PayloadBuilder & sparkplug::PayloadBuilder::add_metric_with_alias	(	std::string_view	name,
		uint64_t	alias,
		T &&	value
	)

inline

Adds a metric with both name and alias (for NBIRTH messages).

Template Parameters

T	Value type (automatically deduced, must satisfy SparkplugMetricType)

Parameters

name	Metric name
alias	Metric alias (numeric identifier for NDATA)
value	Metric value

Returns: Reference to this builder for method chaining

Note: This establishes the name-to-alias mapping for subsequent NDATA messages.

Definition at line 245 of file payload_builder.hpp.

◆ add_metric_with_alias() [2/2]

template<SparkplugMetricType T>

PayloadBuilder & sparkplug::PayloadBuilder::add_metric_with_alias	(	std::string_view	name,
		uint64_t	alias,
		T &&	value,
		uint64_t	timestamp_ms
	)

inline

Adds a metric with name, alias, and custom timestamp (for NBIRTH with historical data).

Template Parameters

T	Value type (automatically deduced, must satisfy SparkplugMetricType)

Parameters

name	Metric name
alias	Metric alias (numeric identifier for NDATA)
value	Metric value
timestamp_ms	Custom timestamp in milliseconds since Unix epoch

Returns: Reference to this builder for method chaining

Note: Useful for NBIRTH messages with historical data or specific timestamps.

Definition at line 266 of file payload_builder.hpp.

◆ add_node_control_next_server()

PayloadBuilder & sparkplug::PayloadBuilder::add_node_control_next_server ( bool value = false )

inline

Definition at line 356 of file payload_builder.hpp.

◆ add_node_control_rebirth()

PayloadBuilder & sparkplug::PayloadBuilder::add_node_control_rebirth ( bool value = false )

inline

Definition at line 346 of file payload_builder.hpp.

◆ add_node_control_reboot()

PayloadBuilder & sparkplug::PayloadBuilder::add_node_control_reboot ( bool value = false )

inline

Definition at line 351 of file payload_builder.hpp.

◆ add_node_control_scan_rate()

PayloadBuilder & sparkplug::PayloadBuilder::add_node_control_scan_rate ( int64_t value )

inline

Definition at line 361 of file payload_builder.hpp.

◆ has_seq()

bool sparkplug::PayloadBuilder::has_seq ( ) const

inlinenoexcept

Definition at line 367 of file payload_builder.hpp.

◆ has_timestamp()

bool sparkplug::PayloadBuilder::has_timestamp ( ) const

inlinenoexcept

Definition at line 370 of file payload_builder.hpp.

◆ mutable_payload()

org::eclipse::tahu::protobuf::Payload & sparkplug::PayloadBuilder::mutable_payload ( )

inlinenoexcept

Definition at line 377 of file payload_builder.hpp.

◆ set_seq()

PayloadBuilder & sparkplug::PayloadBuilder::set_seq ( uint64_t seq )

inline

Sets the sequence number manually.

Parameters

seq	Sequence number (0-255)

Returns: Reference to this builder for method chaining

Warning: Do not use in normal operation; Publisher manages this automatically.

Definition at line 339 of file payload_builder.hpp.

◆ set_timestamp()

PayloadBuilder & sparkplug::PayloadBuilder::set_timestamp ( uint64_t ts )

inline

Sets the payload-level timestamp.

Parameters

ts	Timestamp in milliseconds since Unix epoch

Returns: Reference to this builder for method chaining

Note: Usually not needed; Publisher adds this automatically.

Definition at line 324 of file payload_builder.hpp.

The documentation for this class was generated from the following file:

include/sparkplug/payload_builder.hpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ add_metric() [1/2]

◆ add_metric() [2/2]

◆ add_metric_by_alias() [1/2]

◆ add_metric_by_alias() [2/2]

◆ add_metric_with_alias() [1/2]

◆ add_metric_with_alias() [2/2]

◆ add_node_control_next_server()

◆ add_node_control_rebirth()

◆ add_node_control_reboot()

◆ add_node_control_scan_rate()

◆ has_seq()

◆ has_timestamp()

◆ mutable_payload()

◆ set_seq()

◆ set_timestamp()