# Run Sparkplug B clients

This guide configures the gateway for Sparkplug B 3.0 edge nodes and host applications. Sparkplug needs QoS 1 wills, retained messages and, optionally, stored birth certificates. The gateway serves these only when the config file turns them on.

Before you start, you need:

* The `mq-gateway` binary.
* A NATS server with JetStream.
* A NATS user that can create streams and buckets.
* The Sparkplug group IDs of your edge nodes.

## 1. Write the config file

```
nats:

  url: nats://nats.example.com:4222

  user: gateway

  password: env://GATEWAY_PASSWORD

bindings:

  - { subjects: [spBv1//0.STATE.*, spBv1//0.*.NDEATH.*], stream: SPARKPLUG }

mqtt:

  bindings: [SPARKPLUG]

  retained: { bucket: MQTT_RETAINED }

  sparkplug: { aware: true }
```

* **`spBv1//0.STATE.*`** stores the STATE message of each host application. A host application publishes STATE at QoS 1 and uses it as its will. Without this binding, the gateway refuses the host application.
* **`spBv1//0.*.NDEATH.*`** stores the NDEATH will of each edge node.
* **`mqtt.retained`** keeps the last STATE of each host application, and the birth certificates.
* **`mqtt.sparkplug.aware`** makes the gateway a Sparkplug Aware server. It needs `mqtt.retained`.

In a subject, `spBv1.0` becomes `spBv1//0`, because `.` separates subject tokens. `mq-gateway binding` writes the binding from MQTT filters:

```
mq-gateway binding --mqtt 'spBv1.0/STATE/+' --mqtt 'spBv1.0/+/NDEATH/+' --stream SPARKPLUG
```

The other Sparkplug messages use QoS 0 and need no binding. To store all of them too, bind `spBv1.0/#` instead.

Sparkplug clients use clean sessions, so you need no sessions bucket.

## 2. Provision the stream and the bucket

```
mq-gateway generate --config sparkplug.yaml --format nats-cli > provision.sh

export SPARKPLUG_RETENTION=limits SPARKPLUG_REPLICAS=1 SPARKPLUG_MAX_BYTES=1GB SPARKPLUG_MAX_AGE=24h SPARKPLUG_DISCARD=old SPARKPLUG_MAX_CONSUMERS=20000

export KV_MQTT_RETAINED_REPLICAS=1 KV_MQTT_RETAINED_MAX_BYTES=100MB KV_MQTT_RETAINED_TTL=0

NATS_URL=nats://admin:secret@nats.example.com:4222 bash provision.sh
```

Keep the bucket TTL at `0`, so that each birth certificate stays until the next birth replaces it. [Provision the streams and buckets](/mq-gateway/0.4/how-to/provision-streams-and-buckets.md) explains each limit.

## 3. Set the permissions

```
mq-gateway generate --config sparkplug.yaml --format nats-server > permissions.conf
```

Narrow `$client_permissions` for each user, as in [Configure listeners and auth](/mq-gateway/0.4/how-to/configure-listeners-and-auth.md). Keep the JetStream, KV and `$SYS` subjects. For edge nodes in group `G1` and a host application `h1`:

| User                  | Publish                                                       | Subscribe                                                                        |
| --------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Edge node in `G1`     | `spBv1//0.G1.>`, `$sparkplug.certificates.spBv1//0.G1.>`      | `spBv1//0.G1.NCMD.*`, `spBv1//0.G1.DCMD.>`, `spBv1//0.STATE.*`                   |
| Host application `h1` | `spBv1//0.STATE.h1`, `spBv1//0.*.NCMD.*`, `spBv1//0.*.DCMD.>` | `spBv1//0.>`, `spBv1//0`, `$sparkplug.certificates.>`, `$sparkplug.certificates` |

The host application subscribes to `spBv1.0/#`. A `#` filter also matches its parent level, so the user needs `spBv1//0` too.

An edge node must be able to publish on `$sparkplug.certificates.>`. If it cannot, the gateway still delivers its births but stores no certificate. The gateway then logs `Sparkplug certificate not retained`.

## 4. Start the gateway

```
mq-gateway check --config sparkplug.yaml

mq-gateway --config sparkplug.yaml
```

## Check it works

1. Connect a host application and an edge node.
2. Connect a third client after the edge node sends its NBIRTH.
3. Subscribe the third client to `$sparkplug/certificates/spBv1.0/G1/#`.

The third client gets the NBIRTH and each DBIRTH as retained messages. Then it gets each new birth.

A filter that starts with a wildcard, such as `#`, never matches a `$sparkplug` topic.

## Next to another fleet

A Sparkplug plant and another fleet can share a gateway. Put each in its own NATS account, with its own bindings under `accounts`:

```
mqtt: {}

accounts:

  PLANT_A:

    bindings:

      - { subjects: [uagv.v2.*.*.connection], stream: VDA_CONNECTION }

    mqtt:

      bindings: [VDA_CONNECTION]

      retained: { bucket: VDA_RETAINED }

      sessions: { bucket: VDA_SESSIONS }

  PLANT_B:

    creds: /etc/mqg/gw-plant-b.creds

    bindings:

      - { subjects: [spBv1//0.STATE.*, spBv1//0.*.NDEATH.*], stream: SPARKPLUG }

    mqtt:

      bindings: [SPARKPLUG]

      retained: { bucket: SPARKPLUG_RETAINED }

      sparkplug: { aware: true }
```

`PLANT_A` is the account of the `nats` user, so it needs no credential here. `generate` prints a section for each account. Its names start with the account name, such as `PLANT_B_SPARKPLUG_RETENTION` and `$PLANT_B_client_permissions`. Set each `<ACCOUNT>_CONTEXT` variable to a `nats` context of a user in that account.

## NATS applications

A NATS application reads all Sparkplug messages on `spBv1//0.>`, and the birth certificates on `$sparkplug.certificates.spBv1//0.>`.
