Sparkplug B Consumer¶

The Sparkplug B consumer service lets NF subscribe to external MQTT brokers and ingest data published by other edge nodes as NF points. It is the inbound counterpart to the Sparkplug producer described in the Sparkplug overview.

Use cases:

• Consolidate data from fleets of third-party gateways that already publish Sparkplug B.
• Aggregate data at a regional site from multiple downstream NF instances.
• Bridge data from SCADA or historian systems that emit Sparkplug B.

The service subscribes to spBv1.0/{group_id}/# on each configured broker, processes NBIRTH, DBIRTH, NDEATH, DDEATH, and DDATA messages, and writes received metrics to NF points tagged with the hpl:sparkplug:1 layer.

Managing Connections¶

Connections are managed from the admin console Settings > Sparkplug Consumer page, or through the gRPC/REST API. Multiple broker connections can run simultaneously.

Each connection tracks a status (CONNECTED, DISCONNECTED, ERROR, DISABLED) along with a message summarizing the last failure (auth, TLS, broker unreachable, etc).

API¶

curl -X POST $NFURL/api/v1/sparkplug-consumer/connections \
  -H "Content-Type: application/json" \
  -d '{
    "id": "plant-a",
    "name": "Plant A broker",
    "broker_url": "tls://broker.plant-a.example:8883",
    "username": "nf-consumer",
    "password": "...",
    "group_id": "plant-a"
  }'

curl $NFURL/api/v1/sparkplug-consumer/connections

# SetConnectionEnabled (enabled=false) keeps the config and points
# but stops the MQTT subscription.

Deleting a connection stops the subscription. Pass delete_points=true to also remove all imported points.

Point Model¶

Each metric in a received DBIRTH or DDATA becomes (or updates) an NF point. Points are placed on the hpl:sparkplug:1 layer with indexed attributes for the connection name, edge-node ID, device ID, and metric name, so they can be queried like any other point.

All 21 Sparkplug B data types are mapped onto NF value types, including the numeric, boolean, string, and dataset forms.

Reliability¶

• The consumer tracks per-node bd_seq and per-device seq counters; gaps are recorded in the connection's sequence_gaps stat.
• If the broker drops the connection, the service retries with exponential backoff and resumes state from the next NBIRTH.
• Writes to the point database are batched for throughput.

Monitoring¶

GetConnectionStatus returns live per-node and per-device status, including online flags, last message timestamp, and metrics received. The admin console surfaces the same information in the connection details drawer.

Stats exported to Prometheus include metrics received, sequence gaps, and connection counts per broker.