sparkplug_c.h File Reference

C API for Sparkplug B protocol implementation. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for sparkplug_c.h:

Go to the source code of this file.

Classes
union	sparkplug_metric_value_t
	Metric value union. More...
struct	sparkplug_metric_t
	Metric information struct. More...

Typedefs
typedef struct sparkplug_publisher	sparkplug_publisher_t
	Opaque handle to a Sparkplug publisher.
typedef struct sparkplug_payload	sparkplug_payload_t
	Opaque handle to a Sparkplug payload builder.
typedef void(*	sparkplug_log_callback_t) (int level, const char *message, size_t message_len, void *user_data)
	Callback function type for receiving log messages from the library.
typedef void(*	sparkplug_message_callback_t) (const char *topic, const uint8_t *payload_data, size_t payload_len, void *user_data)
	Callback function type for receiving Sparkplug messages.
typedef void(*	sparkplug_command_callback_t) (const char *topic, const uint8_t *payload_data, size_t payload_len, void *user_data)
	Callback function type for Sparkplug command messages (NCMD/DCMD).
typedef struct sparkplug_host_application	sparkplug_host_application_t
	Opaque handle to a Sparkplug Host Application.

Enumerations
enum	sparkplug_log_level_t {   SPARKPLUG_LOG_DEBUG = 0 ,   SPARKPLUG_LOG_INFO = 1 ,   SPARKPLUG_LOG_WARN = 2 ,   SPARKPLUG_LOG_ERROR = 3 }
	Log severity levels for library diagnostics. More...
enum	sparkplug_data_type_t {   SPARKPLUG_DATA_TYPE_UNKNOWN = 0 ,   SPARKPLUG_DATA_TYPE_INT8 = 1 ,   SPARKPLUG_DATA_TYPE_INT16 = 2 ,   SPARKPLUG_DATA_TYPE_INT32 = 3 ,   SPARKPLUG_DATA_TYPE_INT64 = 4 ,   SPARKPLUG_DATA_TYPE_UINT8 = 5 ,   SPARKPLUG_DATA_TYPE_UINT16 = 6 ,   SPARKPLUG_DATA_TYPE_UINT32 = 7 ,   SPARKPLUG_DATA_TYPE_UINT64 = 8 ,   SPARKPLUG_DATA_TYPE_FLOAT = 9 ,   SPARKPLUG_DATA_TYPE_DOUBLE = 10 ,   SPARKPLUG_DATA_TYPE_BOOLEAN = 11 ,   SPARKPLUG_DATA_TYPE_STRING = 12 ,   SPARKPLUG_DATA_TYPE_DATETIME = 13 ,   SPARKPLUG_DATA_TYPE_TEXT = 14 }
	Sparkplug data types enum. More...

Functions
sparkplug_publisher_t *	sparkplug_publisher_create (const char *broker_url, const char *client_id, const char *group_id, const char *edge_node_id)
	Creates a new Sparkplug publisher.
void	sparkplug_publisher_destroy (sparkplug_publisher_t *pub)
	Destroys a publisher and frees all resources.
int	sparkplug_publisher_set_credentials (sparkplug_publisher_t *pub, const char *username, const char *password)
	Sets MQTT username and password for authentication.
int	sparkplug_publisher_set_tls (sparkplug_publisher_t *pub, const char *trust_store, const char *key_store, const char *private_key, const char *private_key_password, int enable_server_cert_auth)
	Configures TLS/SSL for secure MQTT connections.
void	sparkplug_publisher_set_log_callback (sparkplug_publisher_t *pub, sparkplug_log_callback_t callback, void *user_data)
int	sparkplug_publisher_connect (sparkplug_publisher_t *pub)
int	sparkplug_publisher_disconnect (sparkplug_publisher_t *pub)
	Disconnects the publisher from the MQTT broker.
int	sparkplug_publisher_publish_birth (sparkplug_publisher_t *pub, const uint8_t *payload_data, size_t payload_len)
	Publishes an NBIRTH (Node Birth) message.
int	sparkplug_publisher_publish_data (sparkplug_publisher_t *pub, const uint8_t *payload_data, size_t payload_len)
	Publishes an NDATA (Node Data) message.
int	sparkplug_publisher_publish_death (sparkplug_publisher_t *pub)
	Publishes an NDEATH (Node Death) message.
int	sparkplug_publisher_rebirth (sparkplug_publisher_t *pub)
	Triggers a rebirth (publishes new NBIRTH with incremented bdSeq).
uint64_t	sparkplug_publisher_get_seq (const sparkplug_publisher_t *pub)
	Gets the current message sequence number.
uint64_t	sparkplug_publisher_get_bd_seq (const sparkplug_publisher_t *pub)
	Gets the current birth/death sequence number.
int	sparkplug_publisher_publish_device_birth (sparkplug_publisher_t *pub, const char *device_id, const uint8_t *payload_data, size_t payload_len)
	Publishes a DBIRTH (Device Birth) message for a device.
int	sparkplug_publisher_publish_device_data (sparkplug_publisher_t *pub, const char *device_id, const uint8_t *payload_data, size_t payload_len)
	Publishes a DDATA (Device Data) message for a device.
int	sparkplug_publisher_publish_device_death (sparkplug_publisher_t *pub, const char *device_id)
	Publishes a DDEATH (Device Death) message for a device.
int	sparkplug_publisher_publish_node_command (sparkplug_publisher_t *pub, const char *target_edge_node_id, const uint8_t *payload_data, size_t payload_len)
	Publishes an NCMD (Node Command) message to another edge node.
int	sparkplug_publisher_publish_device_command (sparkplug_publisher_t *pub, const char *target_edge_node_id, const char *target_device_id, const uint8_t *payload_data, size_t payload_len)
	Publishes a DCMD (Device Command) message to a device on another edge node.
sparkplug_host_application_t *	sparkplug_host_application_create (const char *broker_url, const char *client_id, const char *host_id)
	Creates a new Sparkplug Host Application.
void	sparkplug_host_application_destroy (sparkplug_host_application_t *host)
	Destroys a Host Application and frees all resources.
int	sparkplug_host_application_set_credentials (sparkplug_host_application_t *host, const char *username, const char *password)
	Sets MQTT username and password for authentication.
int	sparkplug_host_application_set_tls (sparkplug_host_application_t *host, const char *trust_store, const char *key_store, const char *private_key, const char *private_key_password, int enable_server_cert_auth)
	Configures TLS/SSL for secure MQTT connections.
int	sparkplug_host_application_connect (sparkplug_host_application_t *host)
	Connects the Host Application to the MQTT broker.
int	sparkplug_host_application_disconnect (sparkplug_host_application_t *host)
	Disconnects the Host Application from the MQTT broker.
int	sparkplug_host_application_publish_state_birth (sparkplug_host_application_t *host, uint64_t timestamp)
	Publishes a STATE birth message to indicate Host Application is online.
int	sparkplug_host_application_publish_state_death (sparkplug_host_application_t *host, uint64_t timestamp)
	Publishes a STATE death message to indicate Host Application is offline.
int	sparkplug_host_application_publish_node_command (sparkplug_host_application_t *host, const char *group_id, const char *target_edge_node_id, const uint8_t *payload_data, size_t payload_len)
	Publishes an NCMD (Node Command) message to an Edge Node.
int	sparkplug_host_application_publish_device_command (sparkplug_host_application_t *host, const char *group_id, const char *target_edge_node_id, const char *target_device_id, const uint8_t *payload_data, size_t payload_len)
	Publishes a DCMD (Device Command) message to a device on an Edge Node.
int	sparkplug_host_application_set_message_callback (sparkplug_host_application_t *host, sparkplug_message_callback_t callback, void *user_data)
	Sets a message callback for receiving Sparkplug messages.
void	sparkplug_host_application_set_log_callback (sparkplug_host_application_t *host, sparkplug_log_callback_t callback, void *user_data)
	Sets a log callback for receiving library log messages including MQTT errors.
int	sparkplug_host_application_subscribe_all (sparkplug_host_application_t *host)
	Subscribes to all Sparkplug messages across all groups.
int	sparkplug_host_application_subscribe_group (sparkplug_host_application_t *host, const char *group_id)
	Subscribes to messages from a specific group.
int	sparkplug_host_application_subscribe_node (sparkplug_host_application_t *host, const char *group_id, const char *edge_node_id)
	Subscribes to messages from a specific edge node.
int	sparkplug_host_application_get_metric_name (sparkplug_host_application_t *host, const char *group_id, const char *edge_node_id, const char *device_id, uint64_t alias, char *name_buffer, size_t buffer_size)
	Resolves a metric alias to its name for a specific node or device.
sparkplug_payload_t *	sparkplug_payload_create (void)
	Creates a new payload builder.
void	sparkplug_payload_destroy (sparkplug_payload_t *payload)
	Destroys a payload builder and frees all resources.
void	sparkplug_payload_set_timestamp (sparkplug_payload_t *payload, uint64_t ts)
	Sets the payload-level timestamp.
void	sparkplug_payload_set_seq (sparkplug_payload_t *payload, uint64_t seq)
	Sets the sequence number manually.
void	sparkplug_payload_add_int8 (sparkplug_payload_t *payload, const char *name, int8_t value)
	Adds an int8_t metric by name.
void	sparkplug_payload_add_int16 (sparkplug_payload_t *payload, const char *name, int16_t value)
	Adds an int16_t metric by name.
void	sparkplug_payload_add_int32 (sparkplug_payload_t *payload, const char *name, int32_t value)
	Adds an int32_t metric by name.
void	sparkplug_payload_add_int64 (sparkplug_payload_t *payload, const char *name, int64_t value)
	Adds an int64_t metric by name.
void	sparkplug_payload_add_uint8 (sparkplug_payload_t *payload, const char *name, uint8_t value)
	Adds a uint8_t metric by name.
void	sparkplug_payload_add_uint16 (sparkplug_payload_t *payload, const char *name, uint16_t value)
	Adds a uint16_t metric by name.
void	sparkplug_payload_add_uint32 (sparkplug_payload_t *payload, const char *name, uint32_t value)
	Adds a uint32_t metric by name.
void	sparkplug_payload_add_uint64 (sparkplug_payload_t *payload, const char *name, uint64_t value)
	Adds a uint64_t metric by name.
void	sparkplug_payload_add_float (sparkplug_payload_t *payload, const char *name, float value)
	Adds a float metric by name.
void	sparkplug_payload_add_double (sparkplug_payload_t *payload, const char *name, double value)
	Adds a double metric by name.
void	sparkplug_payload_add_bool (sparkplug_payload_t *payload, const char *name, bool value)
	Adds a boolean metric by name.
void	sparkplug_payload_add_string (sparkplug_payload_t *payload, const char *name, const char *value)
	Adds a string metric by name.
void	sparkplug_payload_add_int32_with_alias (sparkplug_payload_t *payload, const char *name, uint64_t alias, int32_t value)
	Adds an int32_t metric with both name and alias (for NBIRTH).
void	sparkplug_payload_add_int64_with_alias (sparkplug_payload_t *payload, const char *name, uint64_t alias, int64_t value)
	Adds an int64_t metric with both name and alias (for NBIRTH).
void	sparkplug_payload_add_uint32_with_alias (sparkplug_payload_t *payload, const char *name, uint64_t alias, uint32_t value)
	Adds a uint32_t metric with both name and alias (for NBIRTH).
void	sparkplug_payload_add_uint64_with_alias (sparkplug_payload_t *payload, const char *name, uint64_t alias, uint64_t value)
	Adds a uint64_t metric with both name and alias (for NBIRTH).
void	sparkplug_payload_add_float_with_alias (sparkplug_payload_t *payload, const char *name, uint64_t alias, float value)
	Adds a float metric with both name and alias (for NBIRTH).
void	sparkplug_payload_add_double_with_alias (sparkplug_payload_t *payload, const char *name, uint64_t alias, double value)
	Adds a double metric with both name and alias (for NBIRTH).
void	sparkplug_payload_add_bool_with_alias (sparkplug_payload_t *payload, const char *name, uint64_t alias, bool value)
	Adds a boolean metric with both name and alias (for NBIRTH).
void	sparkplug_payload_add_int32_with_alias_timestamp (sparkplug_payload_t *payload, const char *name, uint64_t alias, int32_t value, uint64_t timestamp_ms)
	Adds an int32_t metric with name, alias, and timestamp (for NBIRTH with historical data).
void	sparkplug_payload_add_int64_with_alias_timestamp (sparkplug_payload_t *payload, const char *name, uint64_t alias, int64_t value, uint64_t timestamp_ms)
	Adds an int64_t metric with name, alias, and timestamp (for NBIRTH with historical data).
void	sparkplug_payload_add_uint32_with_alias_timestamp (sparkplug_payload_t *payload, const char *name, uint64_t alias, uint32_t value, uint64_t timestamp_ms)
	Adds a uint32_t metric with name, alias, and timestamp (for NBIRTH with historical data).
void	sparkplug_payload_add_uint64_with_alias_timestamp (sparkplug_payload_t *payload, const char *name, uint64_t alias, uint64_t value, uint64_t timestamp_ms)
	Adds a uint64_t metric with name, alias, and timestamp (for NBIRTH with historical data).
void	sparkplug_payload_add_float_with_alias_timestamp (sparkplug_payload_t *payload, const char *name, uint64_t alias, float value, uint64_t timestamp_ms)
	Adds a float metric with name, alias, and timestamp (for NBIRTH with historical data).
void	sparkplug_payload_add_double_with_alias_timestamp (sparkplug_payload_t *payload, const char *name, uint64_t alias, double value, uint64_t timestamp_ms)
	Adds a double metric with name, alias, and timestamp (for NBIRTH with historical data).
void	sparkplug_payload_add_bool_with_alias_timestamp (sparkplug_payload_t *payload, const char *name, uint64_t alias, bool value, uint64_t timestamp_ms)
	Adds a boolean metric with name, alias, and timestamp (for NBIRTH with historical data).
void	sparkplug_payload_add_int32_by_alias (sparkplug_payload_t *payload, uint64_t alias, int32_t value)
	Adds an int32_t metric by alias only (for NDATA).
void	sparkplug_payload_add_int64_by_alias (sparkplug_payload_t *payload, uint64_t alias, int64_t value)
	Adds an int64_t metric by alias only (for NDATA).
void	sparkplug_payload_add_uint32_by_alias (sparkplug_payload_t *payload, uint64_t alias, uint32_t value)
	Adds a uint32_t metric by alias only (for NDATA).
void	sparkplug_payload_add_uint64_by_alias (sparkplug_payload_t *payload, uint64_t alias, uint64_t value)
	Adds a uint64_t metric by alias only (for NDATA).
void	sparkplug_payload_add_float_by_alias (sparkplug_payload_t *payload, uint64_t alias, float value)
	Adds a float metric by alias only (for NDATA).
void	sparkplug_payload_add_double_by_alias (sparkplug_payload_t *payload, uint64_t alias, double value)
	Adds a double metric by alias only (for NDATA).
void	sparkplug_payload_add_bool_by_alias (sparkplug_payload_t *payload, uint64_t alias, bool value)
	Adds a boolean metric by alias only (for NDATA).
size_t	sparkplug_payload_serialize (const sparkplug_payload_t *payload, uint8_t *buffer, size_t buffer_size)
	Serializes the payload to a binary Protocol Buffers format.
sparkplug_payload_t *	sparkplug_payload_parse (const uint8_t *data, size_t data_len)
	Parses a Sparkplug payload from binary protobuf format.
bool	sparkplug_payload_get_timestamp (const sparkplug_payload_t *payload, uint64_t *out_timestamp)
	Gets the payload-level timestamp.
bool	sparkplug_payload_get_seq (const sparkplug_payload_t *payload, uint64_t *out_seq)
	Gets the payload-level sequence number.
const char *	sparkplug_payload_get_uuid (const sparkplug_payload_t *payload)
	Gets the payload UUID.
size_t	sparkplug_payload_get_metric_count (const sparkplug_payload_t *payload)
	Gets the number of metrics in the payload.
bool	sparkplug_payload_get_metric_at (const sparkplug_payload_t *payload, size_t index, sparkplug_metric_t *out_metric)
	Gets information about a metric at a specific index.

Detailed Description

C API for Sparkplug B protocol implementation.

This header provides a pure C interface to the Sparkplug B C++ library. All functions return 0 on success, -1 on failure (unless otherwise specified).

Thread Safety

All functions in this API are thread-safe. Multiple threads may call any function concurrently on the same or different handles. Internal synchronization is handled automatically via mutex locking in the underlying C++ implementation.

This enables safe usage in multi-threaded applications, including:

• Publishing from multiple threads simultaneously
• Sharing publisher/subscriber handles across threads
• Concurrent calls to get_seq(), get_bd_seq(), etc.

Example Usage

// Create and use a publisher
sparkplug_publisher_t *pub = sparkplug_publisher_create(
    "tcp://localhost:1883", "client", "Energy", "Gateway01");
sparkplug_publisher_connect(pub);
 
// Create payload and publish
sparkplug_payload_t *payload = sparkplug_payload_create();
sparkplug_payload_add_double_with_alias(payload, "Temperature", 1, 20.5);
 
uint8_t buffer[4096];
size_t size = sparkplug_payload_serialize(payload, buffer, sizeof(buffer));
sparkplug_publisher_publish_birth(pub, buffer, size);
 
sparkplug_payload_destroy(payload);
sparkplug_publisher_destroy(pub);

Definition in file sparkplug_c.h.

Typedef Documentation

sparkplug_command_callback_t

typedef void(* sparkplug_command_callback_t) (const char *topic, const uint8_t *payload_data, size_t payload_len, void *user_data)

Callback function type for Sparkplug command messages (NCMD/DCMD).

Parameters

topic	MQTT topic string (valid only during callback)
payload_data	Raw protobuf payload data (valid only during callback)
payload_len	Length of payload data in bytes
user_data	User-provided context pointer

Warning

The topic and payload_data pointers are only valid during the callback. Do not store these pointers. Copy the data if needed after the callback returns.

Definition at line 130 of file sparkplug_c.h.

sparkplug_host_application_t

typedef struct sparkplug_host_application sparkplug_host_application_t

Opaque handle to a Sparkplug Host Application.

Definition at line 375 of file sparkplug_c.h.

sparkplug_log_callback_t

typedef void(* sparkplug_log_callback_t) (int level, const char *message, size_t message_len, void *user_data)

Callback function type for receiving log messages from the library.

The library will call this function to report warnings, errors, and debug information. If no callback is set, logging is silently disabled (zero overhead).

Parameters

level	Log severity level
message	Log message string (valid only during callback)
message_len	Length of message in bytes
user_data	User-provided context pointer

Warning

The message pointer is only valid during the callback. Do not store this pointer. Copy the data if needed after the callback returns.

Example Usage (integrating with syslog)

void my_log_callback(int level, const char* msg, size_t len, void* user_data) {
    if (level >= SPARKPLUG_LOG_WARN) {
        syslog(LOG_WARNING, "[sparkplug] %.*s", (int)len, msg);
    }
}

Example Usage (Rust FFI)

extern "C" fn log_callback(level: c_int, msg: *const c_char, len: usize, _user_data:
*mut c_void) { let level = match level { 0 => log::Level::Debug, 1 => log::Level::Info,
2 => log::Level::Warn, _ => log::Level::Error,
    };
    let msg = unsafe { std::slice::from_raw_parts(msg as *const u8, len) };
    log::log!(level, "{}", String::from_utf8_lossy(msg));
}

Definition at line 98 of file sparkplug_c.h.

sparkplug_message_callback_t

typedef void(* sparkplug_message_callback_t) (const char *topic, const uint8_t *payload_data, size_t payload_len, void *user_data)

Callback function type for receiving Sparkplug messages.

Parameters

topic	MQTT topic string (valid only during callback)
payload_data	Raw protobuf payload data (valid only during callback)
payload_len	Length of payload data in bytes
user_data	User-provided context pointer

Warning

The topic and payload_data pointers are only valid during the callback. Do not store these pointers. Copy the data if needed after the callback returns.

Definition at line 114 of file sparkplug_c.h.

sparkplug_payload_t

typedef struct sparkplug_payload sparkplug_payload_t

Opaque handle to a Sparkplug payload builder.

Definition at line 52 of file sparkplug_c.h.

sparkplug_publisher_t

typedef struct sparkplug_publisher sparkplug_publisher_t

Opaque handle to a Sparkplug publisher.

Definition at line 49 of file sparkplug_c.h.

Enumeration Type Documentation

sparkplug_data_type_t

enum sparkplug_data_type_t

Sparkplug data types enum.

Definition at line 943 of file sparkplug_c.h.

sparkplug_log_level_t

enum sparkplug_log_level_t

Log severity levels for library diagnostics.

Enumerator
SPARKPLUG_LOG_DEBUG	Detailed debugging information.
SPARKPLUG_LOG_INFO	Informational messages.
SPARKPLUG_LOG_WARN	Warning messages (potential issues)
SPARKPLUG_LOG_ERROR	Error messages (serious problems)

Definition at line 57 of file sparkplug_c.h.

Function Documentation

sparkplug_host_application_connect()

int sparkplug_host_application_connect

(

sparkplug_host_application_t *

host

)

Connects the Host Application to the MQTT broker.

Unlike Edge Nodes, this does NOT automatically publish any messages. Call sparkplug_host_application_publish_state_birth() after connecting.

Parameters

host	Host Application handle

Returns

0 on success, -1 on failure

sparkplug_host_application_create()

sparkplug_host_application_t * sparkplug_host_application_create	(	const char *	broker_url,
		const char *	client_id,
		const char *	host_id
	)

Creates a new Sparkplug Host Application.

Host Applications have different behavior than Edge Nodes:

• Publish STATE messages (JSON, not protobuf) to indicate online/offline status
• Publish NCMD/DCMD commands to control Edge Nodes and Devices (group_id specified per command)
• Do NOT publish NBIRTH/NDATA/NDEATH (those are for Edge Nodes only)

Parameters

broker_url	MQTT broker URL (e.g., "tcp://localhost:1883")
client_id	Unique MQTT client identifier
host_id	Host Application identifier (for STATE messages)

Returns

Host Application handle on success, NULL on failure

Note

Caller must call sparkplug_host_application_destroy() to free resources.

sparkplug_host_application_destroy()

void sparkplug_host_application_destroy

(

sparkplug_host_application_t *

host

)

Destroys a Host Application and frees all resources.

Parameters

host	Host Application handle (may be NULL)

sparkplug_host_application_disconnect()

int sparkplug_host_application_disconnect

(

sparkplug_host_application_t *

host

)

Disconnects the Host Application from the MQTT broker.

Parameters

host	Host Application handle

Returns

0 on success, -1 on failure

Note

Call sparkplug_host_application_publish_state_death() BEFORE disconnect() to properly signal offline status.

sparkplug_host_application_get_metric_name()

int sparkplug_host_application_get_metric_name	(	sparkplug_host_application_t *	host,
		const char *	group_id,
		const char *	edge_node_id,
		const char *	device_id,
		uint64_t	alias,
		char *	name_buffer,
		size_t	buffer_size
	)

Resolves a metric alias to its name for a specific node or device.

Looks up the metric name that corresponds to the given alias, based on the alias mappings captured from NBIRTH (node metrics) or DBIRTH (device metrics).

Parameters

host	Host Application handle
group_id	Sparkplug group ID
edge_node_id	Edge node identifier
device_id	Device identifier (may be NULL for node-level metrics)
alias	Metric alias value
name_buffer	Buffer to store the resolved metric name
buffer_size	Size of name_buffer in bytes

Returns

Number of bytes written to name_buffer (including null terminator) on success, 0 if not found, -1 on error

Note

Requires message callback to be set to track alias mappings from BIRTH messages.

sparkplug_host_application_publish_device_command()

int sparkplug_host_application_publish_device_command	(	sparkplug_host_application_t *	host,
		const char *	group_id,
		const char *	target_edge_node_id,
		const char *	target_device_id,
		const uint8_t *	payload_data,
		size_t	payload_len
	)

Publishes a DCMD (Device Command) message to a device on an Edge Node.

Parameters

host	Host Application handle
group_id	Sparkplug group ID containing the target Edge Node
target_edge_node_id	Target Edge Node identifier
target_device_id	Target device identifier
payload_data	Serialized Sparkplug protobuf payload
payload_len	Length of payload data in bytes

Returns

0 on success, -1 on failure

sparkplug_host_application_publish_node_command()

int sparkplug_host_application_publish_node_command	(	sparkplug_host_application_t *	host,
		const char *	group_id,
		const char *	target_edge_node_id,
		const uint8_t *	payload_data,
		size_t	payload_len
	)

Publishes an NCMD (Node Command) message to an Edge Node.

Parameters

host	Host Application handle
group_id	Sparkplug group ID containing the target Edge Node
target_edge_node_id	Target Edge Node identifier
payload_data	Serialized Sparkplug protobuf payload
payload_len	Length of payload data in bytes

Returns

0 on success, -1 on failure

sparkplug_host_application_publish_state_birth()

int sparkplug_host_application_publish_state_birth	(	sparkplug_host_application_t *	host,
		uint64_t	timestamp
	)

Publishes a STATE birth message to indicate Host Application is online.

Parameters

host	Host Application handle
timestamp	UTC milliseconds since epoch

Returns

0 on success, -1 on failure

Note

Topic: spBv1.0/STATE/<host_id>

Payload: JSON {"online": true, "timestamp": <timestamp>}

Published with QoS=1, Retain=true

sparkplug_host_application_publish_state_death()

int sparkplug_host_application_publish_state_death	(	sparkplug_host_application_t *	host,
		uint64_t	timestamp
	)

Publishes a STATE death message to indicate Host Application is offline.

Parameters

host	Host Application handle
timestamp	UTC milliseconds since epoch

Returns

0 on success, -1 on failure

Note

Topic: spBv1.0/STATE/<host_id>

Payload: JSON {"online": false, "timestamp": <timestamp>}

Published with QoS=1, Retain=true

sparkplug_host_application_set_credentials()

int sparkplug_host_application_set_credentials	(	sparkplug_host_application_t *	host,
		const char *	username,
		const char *	password
	)

Sets MQTT username and password for authentication.

Parameters

host	Host Application handle
username	MQTT username (may be NULL to unset)
password	MQTT password (may be NULL to unset)

Returns

0 on success, -1 on failure

Note

Must be called before sparkplug_host_application_connect().

sparkplug_host_application_set_log_callback()

void sparkplug_host_application_set_log_callback	(	sparkplug_host_application_t *	host,
		sparkplug_log_callback_t	callback,
		void *	user_data
	)

Sets a log callback for receiving library log messages including MQTT errors.

Parameters

host	Host Application handle
callback	Log callback function (or NULL to disable logging)
user_data	User data pointer passed to callback (can be NULL)

Returns

0 on success, -1 on failure

Note

The callback receives all log messages from the sparkplug-cpp library, including detailed MQTT error codes from paho.mqtt.c.

Can be called at any time (before or after connect).

sparkplug_host_application_set_message_callback()

int sparkplug_host_application_set_message_callback	(	sparkplug_host_application_t *	host,
		sparkplug_message_callback_t	callback,
		void *	user_data
	)

Sets a message callback for receiving Sparkplug messages.

Enables the Host Application to receive NBIRTH, NDATA, NDEATH, DBIRTH, DDATA, DDEATH messages from Edge Nodes. The callback will be invoked for each received message.

Parameters

host	Host Application handle
callback	Function to call for each received message (may be NULL to clear)
user_data	User context pointer passed to callback

Returns

0 on success, -1 on failure

Note

Must be called before sparkplug_host_application_connect().

After setting the callback, use sparkplug_host_application_subscribe_* functions to subscribe.

sparkplug_host_application_set_tls()

int sparkplug_host_application_set_tls	(	sparkplug_host_application_t *	host,
		const char *	trust_store,
		const char *	key_store,
		const char *	private_key,
		const char *	private_key_password,
		int	enable_server_cert_auth
	)

Configures TLS/SSL for secure MQTT connections.

Parameters

host	Host Application handle
trust_store	Path to CA certificate file (PEM format) - REQUIRED for TLS
key_store	Path to client certificate file (PEM format, NULL for server-only TLS)
private_key	Path to client private key file (PEM format, NULL for server-only TLS)
private_key_password	Password for encrypted private key (NULL if not encrypted)
enable_server_cert_auth	Enable server certificate verification (1=yes, 0=no)

Returns

0 on success, -1 on failure

Note

Must be called before sparkplug_host_application_connect().

For mTLS (mutual authentication), provide key_store and private_key.

For TLS-only (server authentication), set key_store and private_key to NULL.

broker_url must use ssl:// prefix (e.g., "ssl://localhost:8883")

Example (TLS only)

sparkplug_host_application_set_tls(host, "certs/ca.crt", NULL, NULL, NULL, 1);

Example (mTLS)

sparkplug_host_application_set_tls(host, "certs/ca.crt", "certs/client.crt",
                                  "certs/client.key", NULL, 1);

sparkplug_host_application_subscribe_all()

int sparkplug_host_application_subscribe_all

(

sparkplug_host_application_t *

host

)

Subscribes to all Sparkplug messages across all groups.

Subscribes to: spBv1.0/#

Receives all message types (NBIRTH, NDATA, NDEATH, DBIRTH, DDATA, DDEATH) from all edge nodes in all groups.

Parameters

host	Host Application handle

Returns

0 on success, -1 on failure

Note

Requires message callback to be set via sparkplug_host_application_set_message_callback().

Must be called after sparkplug_host_application_connect().

sparkplug_host_application_subscribe_group()

int sparkplug_host_application_subscribe_group	(	sparkplug_host_application_t *	host,
		const char *	group_id
	)

Subscribes to messages from a specific group.

Subscribes to: spBv1.0/{group_id}/#

Parameters

host	Host Application handle
group_id	Sparkplug group ID to subscribe to

Returns

0 on success, -1 on failure

Note

Requires message callback to be set via sparkplug_host_application_set_message_callback().

Must be called after sparkplug_host_application_connect().

sparkplug_host_application_subscribe_node()

int sparkplug_host_application_subscribe_node	(	sparkplug_host_application_t *	host,
		const char *	group_id,
		const char *	edge_node_id
	)

Subscribes to messages from a specific edge node.

Subscribes to: spBv1.0/{group_id}/+/{edge_node_id}/#

Parameters

host	Host Application handle
group_id	Sparkplug group ID
edge_node_id	Edge node identifier to subscribe to

Returns

0 on success, -1 on failure

Note

Requires message callback to be set via sparkplug_host_application_set_message_callback().

Must be called after sparkplug_host_application_connect().

sparkplug_payload_create()

sparkplug_payload_t * sparkplug_payload_create

(

void

)

Creates a new payload builder.

Returns

Payload handle on success, NULL on failure

Note

Caller must call sparkplug_payload_destroy() to free resources.

sparkplug_payload_destroy()

void sparkplug_payload_destroy

(

sparkplug_payload_t *

payload

)

Destroys a payload builder and frees all resources.

Parameters

payload

Payload handle (may be NULL)

sparkplug_payload_get_metric_at()

bool sparkplug_payload_get_metric_at	(	const sparkplug_payload_t *	payload,
		size_t	index,
		sparkplug_metric_t *	out_metric
	)

Gets information about a metric at a specific index.

Parameters

payload	Payload handle
index	Metric index (0 to metric_count - 1)
out_metric	Pointer to receive metric information

Returns

true on success, false if index is out of bounds or payload is NULL

Note

The returned pointers in out_metric are valid until sparkplug_payload_destroy() is called.

Example

sparkplug_metric_t metric;
if (sparkplug_payload_get_metric_at(payload, 0, &metric)) {
    printf("Name: %s\n", metric.has_name ? metric.name : "<no name>");
    if (!metric.is_null) {
        switch (metric.datatype) {
            case SPARKPLUG_DATA_TYPE_DOUBLE:
                printf("Value: %f\n", metric.value.double_value);
                break;
            case SPARKPLUG_DATA_TYPE_BOOLEAN:
                printf("Value: %s\n", metric.value.boolean_value ? "true" : "false");
                break;
        }
    }
}

sparkplug_payload_get_metric_count()

size_t sparkplug_payload_get_metric_count

(

const sparkplug_payload_t *

payload

)

Gets the number of metrics in the payload.

Parameters

payload

Payload handle

Returns

Number of metrics (0 if payload is NULL)

sparkplug_payload_get_seq()

bool sparkplug_payload_get_seq	(	const sparkplug_payload_t *	payload,
		uint64_t *	out_seq
	)

Gets the payload-level sequence number.

Parameters

payload	Payload handle
out_seq	Pointer to receive sequence value

Returns

true if sequence is present, false otherwise

sparkplug_payload_get_timestamp()

bool sparkplug_payload_get_timestamp	(	const sparkplug_payload_t *	payload,
		uint64_t *	out_timestamp
	)

Gets the payload-level timestamp.

Parameters

payload	Payload handle
out_timestamp	Pointer to receive timestamp value

Returns

true if timestamp is present, false otherwise

sparkplug_payload_get_uuid()

const char * sparkplug_payload_get_uuid

(

const sparkplug_payload_t *

payload

)

Gets the payload UUID.

Parameters

payload

Payload handle

Returns

UUID string (owned by payload, valid until sparkplug_payload_destroy()), or NULL if not present

sparkplug_payload_parse()

sparkplug_payload_t * sparkplug_payload_parse	(	const uint8_t *	data,
		size_t	data_len
	)

Parses a Sparkplug payload from binary protobuf format.

Parameters

data	Binary protobuf data
data_len	Length of data in bytes

Returns

Payload handle on success, NULL on parse failure

Note

Caller must call sparkplug_payload_destroy() to free resources.

The returned payload can be used with all sparkplug_payload_get_* functions.

sparkplug_payload_serialize()

size_t sparkplug_payload_serialize	(	const sparkplug_payload_t *	payload,
		uint8_t *	buffer,
		size_t	buffer_size
	)

Serializes the payload to a binary Protocol Buffers format.

Parameters

payload	Payload handle
buffer	Output buffer
buffer_size	Size of output buffer in bytes

Returns

Number of bytes written on success, 0 on failure

Note

The serialized data can be passed to publish_birth() or publish_data().

sparkplug_payload_set_seq()

void sparkplug_payload_set_seq	(	sparkplug_payload_t *	payload,
		uint64_t	seq
	)

Sets the sequence number manually.

Parameters

payload	Payload handle
seq	Sequence number (0-255)

Note

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

sparkplug_payload_set_timestamp()

void sparkplug_payload_set_timestamp	(	sparkplug_payload_t *	payload,
		uint64_t	ts
	)

Sets the payload-level timestamp.

Parameters

payload	Payload handle
ts	Timestamp in milliseconds since Unix epoch

sparkplug_publisher_create()

sparkplug_publisher_t * sparkplug_publisher_create	(	const char *	broker_url,
		const char *	client_id,
		const char *	group_id,
		const char *	edge_node_id
	)

Creates a new Sparkplug publisher.

Parameters

broker_url	MQTT broker URL (e.g., "tcp://localhost:1883")
client_id	Unique MQTT client identifier
group_id	Sparkplug group ID
edge_node_id	Edge node identifier

Returns

Publisher handle on success, NULL on failure

Note

Caller must call sparkplug_publisher_destroy() to free resources.

sparkplug_publisher_destroy()

void sparkplug_publisher_destroy

(

sparkplug_publisher_t *

pub

)

Destroys a publisher and frees all resources.

Parameters

pub	Publisher handle (may be NULL)

sparkplug_publisher_disconnect()

int sparkplug_publisher_disconnect

(

sparkplug_publisher_t *

pub

)

Disconnects the publisher from the MQTT broker.

Parameters

pub	Publisher handle

Returns

0 on success, -1 on failure

Note

Sends NDEATH via MQTT Last Will Testament.

sparkplug_publisher_get_bd_seq()

uint64_t sparkplug_publisher_get_bd_seq

(

const sparkplug_publisher_t *

pub

)

Gets the current birth/death sequence number.

Parameters

pub	Publisher handle

Returns

Current bdSeq value

sparkplug_publisher_get_seq()

uint64_t sparkplug_publisher_get_seq

(

const sparkplug_publisher_t *

pub

)

Gets the current message sequence number.

Parameters

pub	Publisher handle

Returns

Current sequence number (0-255)

sparkplug_publisher_publish_birth()

int sparkplug_publisher_publish_birth	(	sparkplug_publisher_t *	pub,
		const uint8_t *	payload_data,
		size_t	payload_len
	)

Publishes an NBIRTH (Node Birth) message.

Parameters

pub	Publisher handle
payload_data	Serialized Sparkplug protobuf payload
payload_len	Length of payload data in bytes

Returns

0 on success, -1 on failure

Note

Must be called after connect() and before any publish_data() calls.

sparkplug_publisher_publish_data()

int sparkplug_publisher_publish_data	(	sparkplug_publisher_t *	pub,
		const uint8_t *	payload_data,
		size_t	payload_len
	)

Publishes an NDATA (Node Data) message.

Parameters

pub	Publisher handle
payload_data	Serialized Sparkplug protobuf payload
payload_len	Length of payload data in bytes

Returns

0 on success, -1 on failure

Note

Sequence number is automatically incremented.

sparkplug_publisher_publish_death()

int sparkplug_publisher_publish_death

(

sparkplug_publisher_t *

pub

)

Publishes an NDEATH (Node Death) message.

Parameters

pub	Publisher handle

Returns

0 on success, -1 on failure

Note

Usually not needed; NDEATH is sent automatically on disconnect.

sparkplug_publisher_publish_device_birth()

int sparkplug_publisher_publish_device_birth	(	sparkplug_publisher_t *	pub,
		const char *	device_id,
		const uint8_t *	payload_data,
		size_t	payload_len
	)

Publishes a DBIRTH (Device Birth) message for a device.

Parameters

pub	Publisher handle
device_id	Device identifier (e.g., "Sensor01", "Motor02")
payload_data	Serialized Sparkplug protobuf payload
payload_len	Length of payload data in bytes

Returns

0 on success, -1 on failure

Note

Must call publish_birth() before publishing any device births.

sparkplug_publisher_publish_device_command()

int sparkplug_publisher_publish_device_command	(	sparkplug_publisher_t *	pub,
		const char *	target_edge_node_id,
		const char *	target_device_id,
		const uint8_t *	payload_data,
		size_t	payload_len
	)

Publishes a DCMD (Device Command) message to a device on another edge node.

Parameters

pub	Publisher handle
target_edge_node_id	Target edge node identifier
target_device_id	Target device identifier
payload_data	Serialized Sparkplug protobuf payload
payload_len	Length of payload data in bytes

Returns

0 on success, -1 on failure

sparkplug_publisher_publish_device_data()

int sparkplug_publisher_publish_device_data	(	sparkplug_publisher_t *	pub,
		const char *	device_id,
		const uint8_t *	payload_data,
		size_t	payload_len
	)

Publishes a DDATA (Device Data) message for a device.

Parameters

pub	Publisher handle
device_id	Device identifier
payload_data	Serialized Sparkplug protobuf payload
payload_len	Length of payload data in bytes

Returns

0 on success, -1 on failure

Note

Must call publish_device_birth() before the first publish_device_data().

sparkplug_publisher_publish_device_death()

int sparkplug_publisher_publish_device_death	(	sparkplug_publisher_t *	pub,
		const char *	device_id
	)

Publishes a DDEATH (Device Death) message for a device.

Parameters

pub	Publisher handle
device_id	Device identifier

Returns

0 on success, -1 on failure

sparkplug_publisher_publish_node_command()

int sparkplug_publisher_publish_node_command	(	sparkplug_publisher_t *	pub,
		const char *	target_edge_node_id,
		const uint8_t *	payload_data,
		size_t	payload_len
	)

Publishes an NCMD (Node Command) message to another edge node.

Parameters

pub	Publisher handle
target_edge_node_id	Target edge node identifier
payload_data	Serialized Sparkplug protobuf payload
payload_len	Length of payload data in bytes

Returns

0 on success, -1 on failure

sparkplug_publisher_rebirth()

int sparkplug_publisher_rebirth

(

sparkplug_publisher_t *

pub

)

Triggers a rebirth (publishes new NBIRTH with incremented bdSeq).

Parameters

pub	Publisher handle

Returns

0 on success, -1 on failure

sparkplug_publisher_set_credentials()

int sparkplug_publisher_set_credentials	(	sparkplug_publisher_t *	pub,
		const char *	username,
		const char *	password
	)

Sets MQTT username and password for authentication.

Parameters

pub	Publisher handle
username	MQTT username (may be NULL to unset)
password	MQTT password (may be NULL to unset)

Returns

0 on success, -1 on failure

Note

Must be called before sparkplug_publisher_connect().

sparkplug_publisher_set_tls()

int sparkplug_publisher_set_tls	(	sparkplug_publisher_t *	pub,
		const char *	trust_store,
		const char *	key_store,
		const char *	private_key,
		const char *	private_key_password,
		int	enable_server_cert_auth
	)

Configures TLS/SSL for secure MQTT connections.

Parameters

pub	Publisher handle
trust_store	Path to CA certificate file (PEM format) - REQUIRED for TLS
key_store	Path to client certificate file (PEM format, NULL for server-only TLS)
private_key	Path to client private key file (PEM format, NULL for server-only TLS)
private_key_password	Password for encrypted private key (NULL if not encrypted)
enable_server_cert_auth	Enable server certificate verification (1=yes, 0=no)

Returns

0 on success, -1 on failure

Note

Must be called before sparkplug_publisher_connect().

For mTLS (mutual authentication), provide key_store and private_key.

For TLS-only (server authentication), set key_store and private_key to NULL.

broker_url must use ssl:// prefix (e.g., "ssl://localhost:8883")

Example (TLS only)

sparkplug_publisher_set_tls(pub, "certs/ca.crt", NULL, NULL, NULL, 1);

Example (mTLS)

sparkplug_publisher_set_tls(pub, "certs/ca.crt", "certs/client.crt",
                           "certs/client.key", NULL, 1);