# Sparkplug B

Sparkplug B node metrics as equipment data right in the chat

Метрики узлов Sparkplug B 3.0 (Ignition, HighByte, Litmus) через шлюз, только чтение

## How the agent works with Sparkplug B

The broker your Sparkplug B nodes publish to usually sits on the site's network, so the gateway reaches it: a program installed on a computer on the same network. The gateway is added on the Gateways tab and assigned to the connection. The connection takes the broker address, a login and password if needed, and the Sparkplug groups; empty means every group on the broker.

The gateway reads Sparkplug B 3.0 as an observing host. NBIRTH and DBIRTH declare metrics with their types and units and assign aliases, NDATA and DDATA arrive by name or alias, NDEATH and DDEATH darken a node's or device's metrics. A tag is named by the metric's name, never its alias. A sequence gap does not stop reading: the gateway drops the node's aliases and asks the broker for its kept BIRTH messages.

The gateway publishes no STATE and sends no NCMD Rebirth, so it cannot be mistaken for the Primary Host, and nodes do not disconnect when it goes away. It writes no messages to the broker at all, and subscribe rights are enough for its account. The agent reads values, history and freshness, but sends no commands to nodes or devices.

If the gateway joins in the middle of a node's session, alias names come from the BIRTH messages kept by a Sparkplug Aware broker or from the node's next BIRTH; metrics sent by name are read at once. The catalog is capped by the Max tags setting (10000 by default). History builds up from the moment of connection.

## Integration scenarios

### A node's current metrics
The agent finds metrics by group, node, device or name and shows the latest values with units from BIRTH and their freshness.

### History for a period
The agent collects a metric's history in intervals: minimum, maximum, average and last value, with gaps where there was no data.

### Which nodes went offline
The agent sees metrics darkened by NDEATH or DDEATH and names the nodes and devices that send no data.

### Comparing devices
The agent lines up one metric across devices of a group, such as pressure on several pumps, and compares averages and peaks over a period.

### A task on a condition
The agent sets up an On event task that starts when a metric's value crosses a threshold and holds there for the time you set.

### Gateway connectivity
The agent tells whether the gateway and its broker connection are online, and an On event task learns when the gateway drops and when it is back.

## How to connect

**Before you connect**

- An MQTT 5 or 3.1.1 broker with Sparkplug B 3.0 nodes
- Subscribe rights to spBv1.0/… and $sparkplug/certificates/… on the broker
- A computer on the site's network for the gateway program
- A separate Primary Host if the nodes require one

### Keep the existing Primary Host
The gateway only observes: it publishes no STATE and sends no NCMD Rebirth. If nodes require a Primary Host, another broker client must provide it.

### Wait for the nodes' BIRTH messages
Aliases get their names from NBIRTH/DBIRTH. Joining mid-session needs kept BIRTH messages from a Sparkplug Aware broker or the node's next BIRTH.

## FAQ

### How do I connect Sparkplug B?
Install the gateway on a computer on the site's network and add it on the Gateways tab. In the Sparkplug B connection enter the broker address, for example mqtt://10.0.12.5:1883, a login and password if the broker requires them, and exact group names separated by commas, or leave the field empty for every group.

### What does the agent see in Sparkplug B?
The metrics of nodes and devices in the chosen groups as tags with types, units and descriptions from BIRTH, their current values, history from the moment of connection and which nodes and devices are darkened by DEATH.

### Does the agent send commands to nodes?
No. The gateway publishes no STATE, NCMD or DCMD and writes nothing to the broker at all. Subscribe rights are enough for it.

### Metrics arrived without names. Why?
The node sends data by alias, and the gateway missed its BIRTH. The names appear from kept BIRTH messages if the broker is Sparkplug Aware, or from the node's next BIRTH.