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.
Files changed (33) hide show
  1. tagbridge-0.1.0/.gitignore +10 -0
  2. tagbridge-0.1.0/CHANGELOG.md +16 -0
  3. tagbridge-0.1.0/LICENSE +21 -0
  4. tagbridge-0.1.0/PKG-INFO +249 -0
  5. tagbridge-0.1.0/README.md +205 -0
  6. tagbridge-0.1.0/examples/demo.yaml +40 -0
  7. tagbridge-0.1.0/examples/fakeplc-line1.yaml +43 -0
  8. tagbridge-0.1.0/pyproject.toml +99 -0
  9. tagbridge-0.1.0/src/tagbridge/__init__.py +3 -0
  10. tagbridge-0.1.0/src/tagbridge/__main__.py +3 -0
  11. tagbridge-0.1.0/src/tagbridge/browse.py +62 -0
  12. tagbridge-0.1.0/src/tagbridge/cli.py +244 -0
  13. tagbridge-0.1.0/src/tagbridge/config.py +254 -0
  14. tagbridge-0.1.0/src/tagbridge/demo.py +206 -0
  15. tagbridge-0.1.0/src/tagbridge/engine.py +211 -0
  16. tagbridge-0.1.0/src/tagbridge/http.py +107 -0
  17. tagbridge-0.1.0/src/tagbridge/model.py +86 -0
  18. tagbridge-0.1.0/src/tagbridge/py.typed +0 -0
  19. tagbridge-0.1.0/src/tagbridge/sinks/__init__.py +1 -0
  20. tagbridge-0.1.0/src/tagbridge/sinks/mqtt.py +248 -0
  21. tagbridge-0.1.0/src/tagbridge/sinks/sparkplug_node.py +146 -0
  22. tagbridge-0.1.0/src/tagbridge/sinks/uns.py +97 -0
  23. tagbridge-0.1.0/src/tagbridge/sources/__init__.py +19 -0
  24. tagbridge-0.1.0/src/tagbridge/sources/base.py +33 -0
  25. tagbridge-0.1.0/src/tagbridge/sources/modbus.py +355 -0
  26. tagbridge-0.1.0/src/tagbridge/sources/opcua.py +189 -0
  27. tagbridge-0.1.0/src/tagbridge/sparkplug.py +275 -0
  28. tagbridge-0.1.0/tests/test_config.py +91 -0
  29. tagbridge-0.1.0/tests/test_engine.py +143 -0
  30. tagbridge-0.1.0/tests/test_integration.py +135 -0
  31. tagbridge-0.1.0/tests/test_modbus.py +99 -0
  32. tagbridge-0.1.0/tests/test_publishers.py +92 -0
  33. tagbridge-0.1.0/tests/test_sparkplug.py +123 -0
@@ -0,0 +1,10 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .mypy_cache/
9
+ .ruff_cache/
10
+ .coverage
@@ -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.
@@ -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.
@@ -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
+ [![CI](https://github.com/DanShinde/tagbridge/actions/workflows/ci.yml/badge.svg)](https://github.com/DanShinde/tagbridge/actions/workflows/ci.yml)
50
+ [![PyPI](https://img.shields.io/pypi/v/tagbridge.svg)](https://pypi.org/project/tagbridge/)
51
+ [![Python](https://img.shields.io/pypi/pyversions/tagbridge.svg)](https://pypi.org/project/tagbridge/)
52
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](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
+ [![CI](https://github.com/DanShinde/tagbridge/actions/workflows/ci.yml/badge.svg)](https://github.com/DanShinde/tagbridge/actions/workflows/ci.yml)
6
+ [![PyPI](https://img.shields.io/pypi/v/tagbridge.svg)](https://pypi.org/project/tagbridge/)
7
+ [![Python](https://img.shields.io/pypi/pyversions/tagbridge.svg)](https://pypi.org/project/tagbridge/)
8
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](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 }