tagbridge 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tagbridge-0.1.0/.gitignore +10 -0
- tagbridge-0.1.0/CHANGELOG.md +16 -0
- tagbridge-0.1.0/LICENSE +21 -0
- tagbridge-0.1.0/PKG-INFO +249 -0
- tagbridge-0.1.0/README.md +205 -0
- tagbridge-0.1.0/examples/demo.yaml +40 -0
- tagbridge-0.1.0/examples/fakeplc-line1.yaml +43 -0
- tagbridge-0.1.0/pyproject.toml +99 -0
- tagbridge-0.1.0/src/tagbridge/__init__.py +3 -0
- tagbridge-0.1.0/src/tagbridge/__main__.py +3 -0
- tagbridge-0.1.0/src/tagbridge/browse.py +62 -0
- tagbridge-0.1.0/src/tagbridge/cli.py +244 -0
- tagbridge-0.1.0/src/tagbridge/config.py +254 -0
- tagbridge-0.1.0/src/tagbridge/demo.py +206 -0
- tagbridge-0.1.0/src/tagbridge/engine.py +211 -0
- tagbridge-0.1.0/src/tagbridge/http.py +107 -0
- tagbridge-0.1.0/src/tagbridge/model.py +86 -0
- tagbridge-0.1.0/src/tagbridge/py.typed +0 -0
- tagbridge-0.1.0/src/tagbridge/sinks/__init__.py +1 -0
- tagbridge-0.1.0/src/tagbridge/sinks/mqtt.py +248 -0
- tagbridge-0.1.0/src/tagbridge/sinks/sparkplug_node.py +146 -0
- tagbridge-0.1.0/src/tagbridge/sinks/uns.py +97 -0
- tagbridge-0.1.0/src/tagbridge/sources/__init__.py +19 -0
- tagbridge-0.1.0/src/tagbridge/sources/base.py +33 -0
- tagbridge-0.1.0/src/tagbridge/sources/modbus.py +355 -0
- tagbridge-0.1.0/src/tagbridge/sources/opcua.py +189 -0
- tagbridge-0.1.0/src/tagbridge/sparkplug.py +275 -0
- tagbridge-0.1.0/tests/test_config.py +91 -0
- tagbridge-0.1.0/tests/test_engine.py +143 -0
- tagbridge-0.1.0/tests/test_integration.py +135 -0
- tagbridge-0.1.0/tests/test_modbus.py +99 -0
- tagbridge-0.1.0/tests/test_publishers.py +92 -0
- tagbridge-0.1.0/tests/test_sparkplug.py +123 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 (2026-11-22)
|
|
4
|
+
|
|
5
|
+
First release.
|
|
6
|
+
|
|
7
|
+
- Modbus TCP/RTU source with block-optimised reads, bit addressing, 16/32/64-bit integers,
|
|
8
|
+
floats and strings, byte and word order, scale and offset.
|
|
9
|
+
- OPC UA source with subscriptions or polling, authentication and security strings.
|
|
10
|
+
- Sparkplug B edge node: NBIRTH/DBIRTH with aliases, DDATA by exception, DDEATH, NDEATH will with
|
|
11
|
+
bdSeq, rebirth, DCMD writes.
|
|
12
|
+
- Unified Namespace JSON topics with status topics and optional `/set` writes.
|
|
13
|
+
- Per-tag deadband, reconnect with backoff, clean shutdown messages.
|
|
14
|
+
- `run`, `validate`, `read`, `browse` and `demo-server` commands.
|
|
15
|
+
- HTTP `/healthz`, `/readyz`, `/metrics` and `/api/tags`.
|
|
16
|
+
- Docker image, docker compose demo and Helm chart.
|
tagbridge-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Dan Shinde
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
tagbridge-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: tagbridge
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Config-driven Modbus and OPC UA to MQTT gateway with Sparkplug B and Unified Namespace support
|
|
5
|
+
Project-URL: Homepage, https://github.com/DanShinde/tagbridge
|
|
6
|
+
Project-URL: Documentation, https://github.com/DanShinde/tagbridge#readme
|
|
7
|
+
Project-URL: Issues, https://github.com/DanShinde/tagbridge/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/DanShinde/tagbridge/blob/main/CHANGELOG.md
|
|
9
|
+
Author: Dan Shinde
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: edge,gateway,iiot,industrial,modbus,mqtt,opc-ua,opcua,plc,scada,sparkplug,sparkplug-b,unified-namespace,uns
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Framework :: AsyncIO
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Intended Audience :: Manufacturing
|
|
18
|
+
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
26
|
+
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
|
|
27
|
+
Classifier: Topic :: System :: Hardware
|
|
28
|
+
Classifier: Topic :: System :: Networking
|
|
29
|
+
Classifier: Typing :: Typed
|
|
30
|
+
Requires-Python: >=3.10
|
|
31
|
+
Requires-Dist: aiomqtt>=2.3
|
|
32
|
+
Requires-Dist: pydantic>=2.6
|
|
33
|
+
Requires-Dist: pyyaml>=6
|
|
34
|
+
Provides-Extra: all
|
|
35
|
+
Requires-Dist: asyncua>=1.1; extra == 'all'
|
|
36
|
+
Requires-Dist: pymodbus[serial]>=3.10; extra == 'all'
|
|
37
|
+
Provides-Extra: modbus
|
|
38
|
+
Requires-Dist: pymodbus>=3.10; extra == 'modbus'
|
|
39
|
+
Provides-Extra: opcua
|
|
40
|
+
Requires-Dist: asyncua>=1.1; extra == 'opcua'
|
|
41
|
+
Provides-Extra: serial
|
|
42
|
+
Requires-Dist: pymodbus[serial]>=3.10; extra == 'serial'
|
|
43
|
+
Description-Content-Type: text/markdown
|
|
44
|
+
|
|
45
|
+
# tagbridge
|
|
46
|
+
|
|
47
|
+
**A small, config-driven gateway that reads tags from Modbus and OPC UA devices and publishes them to MQTT as Sparkplug B and/or a plain JSON Unified Namespace.**
|
|
48
|
+
|
|
49
|
+
[](https://github.com/DanShinde/tagbridge/actions/workflows/ci.yml)
|
|
50
|
+
[](https://pypi.org/project/tagbridge/)
|
|
51
|
+
[](https://pypi.org/project/tagbridge/)
|
|
52
|
+
[](LICENSE)
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
PLCs / drives / meters tagbridge MQTT broker
|
|
56
|
+
┌──────────────────────┐ ┌──────────────────────────────┐ ┌──────────────────────────┐
|
|
57
|
+
│ Modbus TCP / RTU │─────▶│ block reads, scaling, │─────▶│ spBv1.0/Plant1/DDATA/... │
|
|
58
|
+
│ OPC UA (subscribe or │◀─────│ deadband, report by exception│◀─────│ acme/plant1/press1/temp │
|
|
59
|
+
│ poll) │writes│ births, deaths, rebirths │ cmds │ │
|
|
60
|
+
└──────────────────────┘ └──────────────────────────────┘ └──────────────────────────┘
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
One YAML file, one process, one Docker image. No flow editor, no JVM, no licence server.
|
|
64
|
+
|
|
65
|
+
## Features
|
|
66
|
+
|
|
67
|
+
- **Modbus TCP and RTU**: `hr:100`, `holding 100`, `40101` or `hr:20.3` (bit) addresses; int16 to
|
|
68
|
+
uint64, float32/64, strings, bits; byte and word order per device; scale and offset.
|
|
69
|
+
Tags are merged into as few block reads as possible (`tagbridge validate` shows the plan).
|
|
70
|
+
- **OPC UA**: subscriptions (default) or polling, username/password and security policies,
|
|
71
|
+
data types detected from the server. `tagbridge browse` writes the tag list for you.
|
|
72
|
+
- **Sparkplug B**: each device becomes a Sparkplug device under one edge node. NBIRTH/DBIRTH with
|
|
73
|
+
metric aliases, DDATA by exception, DDEATH when a PLC drops, NDEATH as MQTT will with `bdSeq`,
|
|
74
|
+
`Node Control/Rebirth`, and DCMD writes. Payload encoder has no protobuf dependency.
|
|
75
|
+
- **Unified Namespace / plain MQTT**: retained `prefix/device/tag` topics with JSON
|
|
76
|
+
`{"value", "timestamp", "quality", "unit"}` or raw values, online/offline status topics and
|
|
77
|
+
optional `.../set` write topics. Use it alongside Sparkplug or on its own.
|
|
78
|
+
- **Report by exception** with per-tag deadband, reconnect with backoff for every device and the
|
|
79
|
+
broker, last known values re-published on reconnect.
|
|
80
|
+
- **Operations**: `/healthz`, `/readyz`, Prometheus `/metrics` and a JSON `/api/tags` snapshot;
|
|
81
|
+
`${ENV_VAR:-default}` substitution for secrets; non-root multi-arch image; Helm chart.
|
|
82
|
+
|
|
83
|
+
## Try it in one minute
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
git clone https://github.com/DanShinde/tagbridge && cd tagbridge
|
|
87
|
+
docker compose up
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
This starts Mosquitto, a simulated PLC (Modbus TCP on 5020 and OPC UA on 4840) and tagbridge with
|
|
91
|
+
[examples/demo.yaml](examples/demo.yaml). Point [MQTT Explorer](https://mqtt-explorer.com/) at
|
|
92
|
+
`localhost:1883`, or:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
curl localhost:8080/api/tags # live values
|
|
96
|
+
mosquitto_pub -t acme/plant1/press1/setpoint/set -m 65 # write a setpoint
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Install
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
pip install "tagbridge[all]" # Modbus (incl. serial) + OPC UA
|
|
103
|
+
pip install "tagbridge[modbus]" # Modbus TCP only
|
|
104
|
+
pip install "tagbridge[opcua]" # OPC UA only
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Or use the image: `docker run -v $PWD/tagbridge.yaml:/config/tagbridge.yaml ghcr.io/danshinde/tagbridge`.
|
|
108
|
+
|
|
109
|
+
## Configuration
|
|
110
|
+
|
|
111
|
+
```yaml
|
|
112
|
+
mqtt:
|
|
113
|
+
host: broker.local
|
|
114
|
+
port: 1883
|
|
115
|
+
username: ${MQTT_USERNAME:-}
|
|
116
|
+
password: ${MQTT_PASSWORD:-}
|
|
117
|
+
# tls: {enabled: true, ca_file: /certs/ca.pem}
|
|
118
|
+
|
|
119
|
+
sparkplug:
|
|
120
|
+
enabled: true
|
|
121
|
+
group_id: Plant1
|
|
122
|
+
edge_node_id: line1-gateway
|
|
123
|
+
|
|
124
|
+
uns: # optional plain-JSON topics
|
|
125
|
+
enabled: true
|
|
126
|
+
topic_prefix: acme/plant1
|
|
127
|
+
allow_writes: false
|
|
128
|
+
|
|
129
|
+
devices:
|
|
130
|
+
- name: press1
|
|
131
|
+
type: modbus
|
|
132
|
+
host: 192.168.1.20 # or serial_port: /dev/ttyUSB0 for RTU
|
|
133
|
+
unit_id: 1
|
|
134
|
+
scan_ms: 500
|
|
135
|
+
word_order: big # "little" for word-swapped 32-bit values
|
|
136
|
+
tags:
|
|
137
|
+
- { name: temperature, address: "hr:0", datatype: float32, unit: degC, deadband: 0.2 }
|
|
138
|
+
- { name: pressure, address: "40003", datatype: uint16, scale: 0.1, unit: bar }
|
|
139
|
+
- { name: alarms/overtemp, address: "hr:20.0" }
|
|
140
|
+
- { name: running, address: "co:0", writable: true }
|
|
141
|
+
|
|
142
|
+
- name: filler
|
|
143
|
+
type: opcua
|
|
144
|
+
endpoint: opc.tcp://192.168.1.30:4840
|
|
145
|
+
mode: subscribe
|
|
146
|
+
tags:
|
|
147
|
+
- { name: speed, node: "ns=3;s=Filler.Speed", deadband: 0.5 }
|
|
148
|
+
- { name: target, node: "ns=3;s=Filler.Target", writable: true }
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
| Tag field | Meaning |
|
|
152
|
+
|---|---|
|
|
153
|
+
| `name` | Metric / topic name. `/` builds a hierarchy (`alarms/overtemp`). |
|
|
154
|
+
| `address` / `node` | Modbus address or OPC UA node id. |
|
|
155
|
+
| `datatype` | `auto`, `bool`, `int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`, `float32`, `float64`, `string` |
|
|
156
|
+
| `length` | Characters, for Modbus strings. |
|
|
157
|
+
| `scale`, `offset` | Published value = raw × scale + offset (reversed for writes). |
|
|
158
|
+
| `deadband` | Absolute change needed before a new value is published. |
|
|
159
|
+
| `writable` | Accept writes from Sparkplug DCMD or `.../set` topics. |
|
|
160
|
+
| `unit`, `description`, `low`, `high` | Metadata. `unit` is included in UNS payloads. |
|
|
161
|
+
|
|
162
|
+
Modbus addresses: `co:`, `di:`, `hr:`, `ir:` (or `coil`, `discrete`, `holding`, `input`) take
|
|
163
|
+
zero-based offsets. Five and six digit Modicon numbers (`40001`, `300001`) are one-based.
|
|
164
|
+
|
|
165
|
+
Check a config and see the Modbus request plan without connecting:
|
|
166
|
+
|
|
167
|
+
```console
|
|
168
|
+
$ tagbridge validate examples/demo.yaml
|
|
169
|
+
examples/demo.yaml: OK
|
|
170
|
+
mqtt: localhost:1883 -> Sparkplug B spBv1.0/Plant1/+/gateway-01, UNS acme/plant1/<device>/<tag>
|
|
171
|
+
press1: modbus localhost, 6 tags, scan 1000 ms
|
|
172
|
+
2 read request(s) per scan: co:0+1, hr:0+21
|
|
173
|
+
line1: opcua opc.tcp://localhost:4840/tagbridge/demo, 4 tags, scan 500 ms
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Read every tag once, which helps when commissioning a new device:
|
|
177
|
+
|
|
178
|
+
```console
|
|
179
|
+
$ tagbridge read examples/demo.yaml
|
|
180
|
+
press1/temperature 70.0
|
|
181
|
+
press1/pressure 42.0
|
|
182
|
+
...
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Generate tags from an OPC UA server:
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
tagbridge browse opc.tcp://192.168.1.30:4840 --name filler > filler.yaml
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## Sparkplug B details
|
|
192
|
+
|
|
193
|
+
| Message | When |
|
|
194
|
+
|---|---|
|
|
195
|
+
| `NBIRTH` | On every MQTT connect and on `Node Control/Rebirth`. Carries `bdSeq`, `Node Control/Rebirth` and version info. |
|
|
196
|
+
| `DBIRTH` | When a device connects, after NBIRTH, and on rebirth. Every tag with name, alias, type and value. |
|
|
197
|
+
| `DDATA` | Changed tags only, by alias. Bad quality is sent as a null metric. |
|
|
198
|
+
| `DDEATH` | When a device stops answering. |
|
|
199
|
+
| `NDEATH` | Registered as the MQTT will (QoS 1) and published on clean shutdown. |
|
|
200
|
+
| `NCMD` / `DCMD` | Rebirth requests and writes to `writable` tags, by name or alias. |
|
|
201
|
+
|
|
202
|
+
Not in v0.1 yet: primary host `STATE` awareness, store and forward while the broker is down,
|
|
203
|
+
Sparkplug templates and datasets.
|
|
204
|
+
|
|
205
|
+
## Writes
|
|
206
|
+
|
|
207
|
+
Writes are off unless a tag is `writable: true`.
|
|
208
|
+
|
|
209
|
+
- Sparkplug: send a `DCMD` to `spBv1.0/<group>/DCMD/<edge node>/<device>` with the metric name
|
|
210
|
+
or alias (`sparkplug.allow_writes: false` turns this off).
|
|
211
|
+
- UNS: publish to `<prefix>/<device>/<tag>/set` with `42`, `true`, `"text"` or
|
|
212
|
+
`{"value": 42}` (needs `uns.allow_writes: true`).
|
|
213
|
+
|
|
214
|
+
## Kubernetes
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
helm install line1 oci://ghcr.io/danshinde/charts/tagbridge -f my-values.yaml
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
The chart mounts `config:` from your values as the config file, wires `/healthz` and `/readyz`
|
|
221
|
+
probes, runs as non-root with a read-only root filesystem, and can create a Prometheus
|
|
222
|
+
`ServiceMonitor`. See [deploy/helm/tagbridge/values.yaml](deploy/helm/tagbridge/values.yaml).
|
|
223
|
+
|
|
224
|
+
## Monitoring
|
|
225
|
+
|
|
226
|
+
`GET /metrics` exposes `tagbridge_device_online{device}`, `tagbridge_mqtt_connected`, and
|
|
227
|
+
counters for reads, read errors, changes, published messages and writes.
|
|
228
|
+
|
|
229
|
+
## Related projects
|
|
230
|
+
|
|
231
|
+
- [fakeplc](https://github.com/DanShinde/fakeplc): a scriptable fake PLC (Modbus TCP + OPC UA)
|
|
232
|
+
for testing gateways and HMIs without hardware.
|
|
233
|
+
- [TagScope](https://github.com/DanShinde/tagscope): log OPC UA tags to a database and view them
|
|
234
|
+
on a dashboard.
|
|
235
|
+
|
|
236
|
+
## Development
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
uv sync --all-extras
|
|
240
|
+
uv run pytest # set TAGBRIDGE_TEST_MQTT=host:port to run the broker test
|
|
241
|
+
uv run ruff check . && uv run mypy
|
|
242
|
+
uv run tagbridge demo-server # local Modbus + OPC UA simulator
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
246
|
+
|
|
247
|
+
## License
|
|
248
|
+
|
|
249
|
+
MIT
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# tagbridge
|
|
2
|
+
|
|
3
|
+
**A small, config-driven gateway that reads tags from Modbus and OPC UA devices and publishes them to MQTT as Sparkplug B and/or a plain JSON Unified Namespace.**
|
|
4
|
+
|
|
5
|
+
[](https://github.com/DanShinde/tagbridge/actions/workflows/ci.yml)
|
|
6
|
+
[](https://pypi.org/project/tagbridge/)
|
|
7
|
+
[](https://pypi.org/project/tagbridge/)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
PLCs / drives / meters tagbridge MQTT broker
|
|
12
|
+
┌──────────────────────┐ ┌──────────────────────────────┐ ┌──────────────────────────┐
|
|
13
|
+
│ Modbus TCP / RTU │─────▶│ block reads, scaling, │─────▶│ spBv1.0/Plant1/DDATA/... │
|
|
14
|
+
│ OPC UA (subscribe or │◀─────│ deadband, report by exception│◀─────│ acme/plant1/press1/temp │
|
|
15
|
+
│ poll) │writes│ births, deaths, rebirths │ cmds │ │
|
|
16
|
+
└──────────────────────┘ └──────────────────────────────┘ └──────────────────────────┘
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
One YAML file, one process, one Docker image. No flow editor, no JVM, no licence server.
|
|
20
|
+
|
|
21
|
+
## Features
|
|
22
|
+
|
|
23
|
+
- **Modbus TCP and RTU**: `hr:100`, `holding 100`, `40101` or `hr:20.3` (bit) addresses; int16 to
|
|
24
|
+
uint64, float32/64, strings, bits; byte and word order per device; scale and offset.
|
|
25
|
+
Tags are merged into as few block reads as possible (`tagbridge validate` shows the plan).
|
|
26
|
+
- **OPC UA**: subscriptions (default) or polling, username/password and security policies,
|
|
27
|
+
data types detected from the server. `tagbridge browse` writes the tag list for you.
|
|
28
|
+
- **Sparkplug B**: each device becomes a Sparkplug device under one edge node. NBIRTH/DBIRTH with
|
|
29
|
+
metric aliases, DDATA by exception, DDEATH when a PLC drops, NDEATH as MQTT will with `bdSeq`,
|
|
30
|
+
`Node Control/Rebirth`, and DCMD writes. Payload encoder has no protobuf dependency.
|
|
31
|
+
- **Unified Namespace / plain MQTT**: retained `prefix/device/tag` topics with JSON
|
|
32
|
+
`{"value", "timestamp", "quality", "unit"}` or raw values, online/offline status topics and
|
|
33
|
+
optional `.../set` write topics. Use it alongside Sparkplug or on its own.
|
|
34
|
+
- **Report by exception** with per-tag deadband, reconnect with backoff for every device and the
|
|
35
|
+
broker, last known values re-published on reconnect.
|
|
36
|
+
- **Operations**: `/healthz`, `/readyz`, Prometheus `/metrics` and a JSON `/api/tags` snapshot;
|
|
37
|
+
`${ENV_VAR:-default}` substitution for secrets; non-root multi-arch image; Helm chart.
|
|
38
|
+
|
|
39
|
+
## Try it in one minute
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
git clone https://github.com/DanShinde/tagbridge && cd tagbridge
|
|
43
|
+
docker compose up
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
This starts Mosquitto, a simulated PLC (Modbus TCP on 5020 and OPC UA on 4840) and tagbridge with
|
|
47
|
+
[examples/demo.yaml](examples/demo.yaml). Point [MQTT Explorer](https://mqtt-explorer.com/) at
|
|
48
|
+
`localhost:1883`, or:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
curl localhost:8080/api/tags # live values
|
|
52
|
+
mosquitto_pub -t acme/plant1/press1/setpoint/set -m 65 # write a setpoint
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Install
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pip install "tagbridge[all]" # Modbus (incl. serial) + OPC UA
|
|
59
|
+
pip install "tagbridge[modbus]" # Modbus TCP only
|
|
60
|
+
pip install "tagbridge[opcua]" # OPC UA only
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Or use the image: `docker run -v $PWD/tagbridge.yaml:/config/tagbridge.yaml ghcr.io/danshinde/tagbridge`.
|
|
64
|
+
|
|
65
|
+
## Configuration
|
|
66
|
+
|
|
67
|
+
```yaml
|
|
68
|
+
mqtt:
|
|
69
|
+
host: broker.local
|
|
70
|
+
port: 1883
|
|
71
|
+
username: ${MQTT_USERNAME:-}
|
|
72
|
+
password: ${MQTT_PASSWORD:-}
|
|
73
|
+
# tls: {enabled: true, ca_file: /certs/ca.pem}
|
|
74
|
+
|
|
75
|
+
sparkplug:
|
|
76
|
+
enabled: true
|
|
77
|
+
group_id: Plant1
|
|
78
|
+
edge_node_id: line1-gateway
|
|
79
|
+
|
|
80
|
+
uns: # optional plain-JSON topics
|
|
81
|
+
enabled: true
|
|
82
|
+
topic_prefix: acme/plant1
|
|
83
|
+
allow_writes: false
|
|
84
|
+
|
|
85
|
+
devices:
|
|
86
|
+
- name: press1
|
|
87
|
+
type: modbus
|
|
88
|
+
host: 192.168.1.20 # or serial_port: /dev/ttyUSB0 for RTU
|
|
89
|
+
unit_id: 1
|
|
90
|
+
scan_ms: 500
|
|
91
|
+
word_order: big # "little" for word-swapped 32-bit values
|
|
92
|
+
tags:
|
|
93
|
+
- { name: temperature, address: "hr:0", datatype: float32, unit: degC, deadband: 0.2 }
|
|
94
|
+
- { name: pressure, address: "40003", datatype: uint16, scale: 0.1, unit: bar }
|
|
95
|
+
- { name: alarms/overtemp, address: "hr:20.0" }
|
|
96
|
+
- { name: running, address: "co:0", writable: true }
|
|
97
|
+
|
|
98
|
+
- name: filler
|
|
99
|
+
type: opcua
|
|
100
|
+
endpoint: opc.tcp://192.168.1.30:4840
|
|
101
|
+
mode: subscribe
|
|
102
|
+
tags:
|
|
103
|
+
- { name: speed, node: "ns=3;s=Filler.Speed", deadband: 0.5 }
|
|
104
|
+
- { name: target, node: "ns=3;s=Filler.Target", writable: true }
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
| Tag field | Meaning |
|
|
108
|
+
|---|---|
|
|
109
|
+
| `name` | Metric / topic name. `/` builds a hierarchy (`alarms/overtemp`). |
|
|
110
|
+
| `address` / `node` | Modbus address or OPC UA node id. |
|
|
111
|
+
| `datatype` | `auto`, `bool`, `int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`, `float32`, `float64`, `string` |
|
|
112
|
+
| `length` | Characters, for Modbus strings. |
|
|
113
|
+
| `scale`, `offset` | Published value = raw × scale + offset (reversed for writes). |
|
|
114
|
+
| `deadband` | Absolute change needed before a new value is published. |
|
|
115
|
+
| `writable` | Accept writes from Sparkplug DCMD or `.../set` topics. |
|
|
116
|
+
| `unit`, `description`, `low`, `high` | Metadata. `unit` is included in UNS payloads. |
|
|
117
|
+
|
|
118
|
+
Modbus addresses: `co:`, `di:`, `hr:`, `ir:` (or `coil`, `discrete`, `holding`, `input`) take
|
|
119
|
+
zero-based offsets. Five and six digit Modicon numbers (`40001`, `300001`) are one-based.
|
|
120
|
+
|
|
121
|
+
Check a config and see the Modbus request plan without connecting:
|
|
122
|
+
|
|
123
|
+
```console
|
|
124
|
+
$ tagbridge validate examples/demo.yaml
|
|
125
|
+
examples/demo.yaml: OK
|
|
126
|
+
mqtt: localhost:1883 -> Sparkplug B spBv1.0/Plant1/+/gateway-01, UNS acme/plant1/<device>/<tag>
|
|
127
|
+
press1: modbus localhost, 6 tags, scan 1000 ms
|
|
128
|
+
2 read request(s) per scan: co:0+1, hr:0+21
|
|
129
|
+
line1: opcua opc.tcp://localhost:4840/tagbridge/demo, 4 tags, scan 500 ms
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Read every tag once, which helps when commissioning a new device:
|
|
133
|
+
|
|
134
|
+
```console
|
|
135
|
+
$ tagbridge read examples/demo.yaml
|
|
136
|
+
press1/temperature 70.0
|
|
137
|
+
press1/pressure 42.0
|
|
138
|
+
...
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Generate tags from an OPC UA server:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
tagbridge browse opc.tcp://192.168.1.30:4840 --name filler > filler.yaml
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## Sparkplug B details
|
|
148
|
+
|
|
149
|
+
| Message | When |
|
|
150
|
+
|---|---|
|
|
151
|
+
| `NBIRTH` | On every MQTT connect and on `Node Control/Rebirth`. Carries `bdSeq`, `Node Control/Rebirth` and version info. |
|
|
152
|
+
| `DBIRTH` | When a device connects, after NBIRTH, and on rebirth. Every tag with name, alias, type and value. |
|
|
153
|
+
| `DDATA` | Changed tags only, by alias. Bad quality is sent as a null metric. |
|
|
154
|
+
| `DDEATH` | When a device stops answering. |
|
|
155
|
+
| `NDEATH` | Registered as the MQTT will (QoS 1) and published on clean shutdown. |
|
|
156
|
+
| `NCMD` / `DCMD` | Rebirth requests and writes to `writable` tags, by name or alias. |
|
|
157
|
+
|
|
158
|
+
Not in v0.1 yet: primary host `STATE` awareness, store and forward while the broker is down,
|
|
159
|
+
Sparkplug templates and datasets.
|
|
160
|
+
|
|
161
|
+
## Writes
|
|
162
|
+
|
|
163
|
+
Writes are off unless a tag is `writable: true`.
|
|
164
|
+
|
|
165
|
+
- Sparkplug: send a `DCMD` to `spBv1.0/<group>/DCMD/<edge node>/<device>` with the metric name
|
|
166
|
+
or alias (`sparkplug.allow_writes: false` turns this off).
|
|
167
|
+
- UNS: publish to `<prefix>/<device>/<tag>/set` with `42`, `true`, `"text"` or
|
|
168
|
+
`{"value": 42}` (needs `uns.allow_writes: true`).
|
|
169
|
+
|
|
170
|
+
## Kubernetes
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
helm install line1 oci://ghcr.io/danshinde/charts/tagbridge -f my-values.yaml
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
The chart mounts `config:` from your values as the config file, wires `/healthz` and `/readyz`
|
|
177
|
+
probes, runs as non-root with a read-only root filesystem, and can create a Prometheus
|
|
178
|
+
`ServiceMonitor`. See [deploy/helm/tagbridge/values.yaml](deploy/helm/tagbridge/values.yaml).
|
|
179
|
+
|
|
180
|
+
## Monitoring
|
|
181
|
+
|
|
182
|
+
`GET /metrics` exposes `tagbridge_device_online{device}`, `tagbridge_mqtt_connected`, and
|
|
183
|
+
counters for reads, read errors, changes, published messages and writes.
|
|
184
|
+
|
|
185
|
+
## Related projects
|
|
186
|
+
|
|
187
|
+
- [fakeplc](https://github.com/DanShinde/fakeplc): a scriptable fake PLC (Modbus TCP + OPC UA)
|
|
188
|
+
for testing gateways and HMIs without hardware.
|
|
189
|
+
- [TagScope](https://github.com/DanShinde/tagscope): log OPC UA tags to a database and view them
|
|
190
|
+
on a dashboard.
|
|
191
|
+
|
|
192
|
+
## Development
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
uv sync --all-extras
|
|
196
|
+
uv run pytest # set TAGBRIDGE_TEST_MQTT=host:port to run the broker test
|
|
197
|
+
uv run ruff check . && uv run mypy
|
|
198
|
+
uv run tagbridge demo-server # local Modbus + OPC UA simulator
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
202
|
+
|
|
203
|
+
## License
|
|
204
|
+
|
|
205
|
+
MIT
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Works with `tagbridge demo-server` (or docker compose up in this folder).
|
|
2
|
+
mqtt:
|
|
3
|
+
host: ${MQTT_HOST:-localhost}
|
|
4
|
+
port: 1883
|
|
5
|
+
|
|
6
|
+
sparkplug:
|
|
7
|
+
enabled: true
|
|
8
|
+
group_id: Plant1
|
|
9
|
+
edge_node_id: ${EDGE_NODE_ID:-gateway-01}
|
|
10
|
+
|
|
11
|
+
uns:
|
|
12
|
+
enabled: true
|
|
13
|
+
topic_prefix: acme/plant1
|
|
14
|
+
allow_writes: true
|
|
15
|
+
|
|
16
|
+
devices:
|
|
17
|
+
- name: press1
|
|
18
|
+
type: modbus
|
|
19
|
+
host: ${DEMO_HOST:-localhost}
|
|
20
|
+
port: 5020
|
|
21
|
+
unit_id: 1
|
|
22
|
+
scan_ms: 1000
|
|
23
|
+
tags:
|
|
24
|
+
- { name: temperature, address: "hr:0", datatype: float32, unit: degC, deadband: 0.2 }
|
|
25
|
+
- { name: pressure, address: "hr:2", datatype: uint16, scale: 0.1, unit: bar }
|
|
26
|
+
- { name: part_count, address: "hr:3", datatype: uint32 }
|
|
27
|
+
- { name: setpoint, address: "hr:10", datatype: uint16, scale: 0.1, unit: degC, writable: true }
|
|
28
|
+
- { name: alarms/high_temperature, address: "hr:20.0" }
|
|
29
|
+
- { name: running, address: "co:0", writable: true }
|
|
30
|
+
|
|
31
|
+
- name: line1
|
|
32
|
+
type: opcua
|
|
33
|
+
endpoint: opc.tcp://${DEMO_HOST:-localhost}:4840/tagbridge/demo
|
|
34
|
+
mode: subscribe
|
|
35
|
+
scan_ms: 500
|
|
36
|
+
tags:
|
|
37
|
+
- { name: speed, node: "ns=2;s=Line1.Speed", unit: ppm, deadband: 0.5 }
|
|
38
|
+
- { name: state, node: "ns=2;s=Line1.State" }
|
|
39
|
+
- { name: count, node: "ns=2;s=Line1.Count" }
|
|
40
|
+
- { name: target_speed, node: "ns=2;s=Line1.Target", writable: true }
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Bridge the fakeplc "line1" example plant (https://github.com/DanShinde/fakeplc) to MQTT.
|
|
2
|
+
# fakeplc serve examples/line1.yaml
|
|
3
|
+
# tagbridge run examples/fakeplc-line1.yaml
|
|
4
|
+
mqtt:
|
|
5
|
+
host: ${MQTT_HOST:-localhost}
|
|
6
|
+
|
|
7
|
+
sparkplug:
|
|
8
|
+
group_id: Plant1
|
|
9
|
+
edge_node_id: line1-gateway
|
|
10
|
+
|
|
11
|
+
uns:
|
|
12
|
+
enabled: true
|
|
13
|
+
topic_prefix: acme/plant1
|
|
14
|
+
allow_writes: true
|
|
15
|
+
|
|
16
|
+
devices:
|
|
17
|
+
# Over Modbus TCP
|
|
18
|
+
- name: line1-modbus
|
|
19
|
+
type: modbus
|
|
20
|
+
host: ${PLC_HOST:-localhost}
|
|
21
|
+
port: 5020
|
|
22
|
+
scan_ms: 500
|
|
23
|
+
tags:
|
|
24
|
+
- { name: Motor/Start, address: "coil 0", writable: true }
|
|
25
|
+
- { name: Motor/Fault, address: "coil 1", writable: true }
|
|
26
|
+
- { name: Motor/Running, address: "discrete 0" }
|
|
27
|
+
- { name: Motor/Speed, address: "input 0", datatype: float32, unit: rpm }
|
|
28
|
+
- { name: Tank/Level, address: "holding 0", datatype: float32, unit: "%", deadband: 0.1 }
|
|
29
|
+
- { name: Pump/Setpoint, address: "holding 2", datatype: float32, writable: true }
|
|
30
|
+
- { name: Batch/Count, address: "holding 4", datatype: int32 }
|
|
31
|
+
- { name: Line/Temp, address: "input 2", datatype: float32, unit: degC, deadband: 0.2 }
|
|
32
|
+
|
|
33
|
+
# The same tags over OPC UA
|
|
34
|
+
- name: line1-opcua
|
|
35
|
+
type: opcua
|
|
36
|
+
endpoint: opc.tcp://${PLC_HOST:-localhost}:4840
|
|
37
|
+
scan_ms: 500
|
|
38
|
+
tags:
|
|
39
|
+
- { name: Motor/Start, node: "ns=2;s=Motor.Start", writable: true }
|
|
40
|
+
- { name: Motor/Running, node: "ns=2;s=Motor.Running" }
|
|
41
|
+
- { name: Motor/Speed, node: "ns=2;s=Motor.Speed", unit: rpm }
|
|
42
|
+
- { name: Batch/Count, node: "ns=2;s=Batch.Count" }
|
|
43
|
+
- { name: Line/Temp, node: "ns=2;s=Line.Temp", deadband: 0.2 }
|