tagbridge 0.1.0__py3-none-any.whl

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/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """Config-driven Modbus and OPC UA to MQTT gateway with Sparkplug B support."""
2
+
3
+ __version__ = "0.1.0"
tagbridge/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
tagbridge/browse.py ADDED
@@ -0,0 +1,62 @@
1
+ """Generate a tag list by browsing an OPC UA server."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from .sources.opcua import _VARIANT_TO_DATATYPE
8
+
9
+
10
+ async def browse_opcua(
11
+ endpoint: str,
12
+ root: str = "i=85",
13
+ max_depth: int = 6,
14
+ username: str | None = None,
15
+ password: str | None = None,
16
+ include_ns0: bool = False,
17
+ ) -> list[dict[str, Any]]:
18
+ """Return tag dicts for every Variable under ``root`` (Objects folder by default)."""
19
+ from asyncua import Client, ua
20
+
21
+ client = Client(endpoint)
22
+ if username:
23
+ client.set_user(username)
24
+ if password:
25
+ client.set_password(password)
26
+ tags: list[dict[str, Any]] = []
27
+ seen: set[str] = set()
28
+ async with client:
29
+
30
+ async def walk(node: Any, path: list[str], depth: int) -> None:
31
+ if depth > max_depth:
32
+ return
33
+ for child in await node.get_children(refs=ua.ObjectIds.HierarchicalReferences):
34
+ node_id = child.nodeid.to_string()
35
+ if node_id in seen:
36
+ continue
37
+ seen.add(node_id)
38
+ if child.nodeid.NamespaceIndex == 0 and not include_ns0:
39
+ continue
40
+ name = (await child.read_browse_name()).Name
41
+ node_class = await child.read_node_class()
42
+ if node_class == ua.NodeClass.Variable:
43
+ try:
44
+ vtype = await child.read_data_type_as_variant_type()
45
+ datatype = _VARIANT_TO_DATATYPE.get(vtype.name, "auto")
46
+ except Exception:
47
+ datatype = "auto"
48
+ access = await child.read_attribute(ua.AttributeIds.UserAccessLevel)
49
+ level = access.Value.Value or 0
50
+ tag: dict[str, Any] = {
51
+ "name": "/".join([*path, name]),
52
+ "node": node_id,
53
+ "datatype": datatype,
54
+ }
55
+ if level & ua.AccessLevel.CurrentWrite.mask:
56
+ tag["writable"] = True
57
+ tags.append(tag)
58
+ elif node_class == ua.NodeClass.Object:
59
+ await walk(child, [*path, name], depth + 1)
60
+
61
+ await walk(client.get_node(root), [], 0)
62
+ return tags
tagbridge/cli.py ADDED
@@ -0,0 +1,244 @@
1
+ """Command line interface."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import asyncio
7
+ import contextlib
8
+ import json
9
+ import logging
10
+ import signal
11
+ import sys
12
+ from typing import Any
13
+
14
+ import yaml
15
+
16
+ from . import __version__
17
+ from .config import ConfigError, GatewayConfig, ModbusDeviceConfig, load_config
18
+ from .sources.base import SourceError
19
+
20
+ log = logging.getLogger("tagbridge")
21
+
22
+
23
+ def _setup_logging(level: str) -> None:
24
+ logging.basicConfig(
25
+ level=getattr(logging, level),
26
+ format="%(asctime)s %(levelname)-7s %(name)s: %(message)s",
27
+ )
28
+ for noisy in ("asyncua", "pymodbus"):
29
+ logging.getLogger(noisy).setLevel(max(logging.ERROR, getattr(logging, level)))
30
+
31
+
32
+ def _load(path: str) -> GatewayConfig:
33
+ try:
34
+ return load_config(path)
35
+ except ConfigError as exc:
36
+ print(f"error: {exc}", file=sys.stderr)
37
+ raise SystemExit(2) from exc
38
+
39
+
40
+ async def _run(config: GatewayConfig) -> None:
41
+ from .engine import Gateway
42
+ from .http import serve
43
+ from .sinks.mqtt import MqttBridge
44
+
45
+ gateway = Gateway(config)
46
+ bridge = MqttBridge(config, gateway)
47
+ extra: list[Any] = [bridge.run]
48
+ if config.http.enabled:
49
+ extra.append(lambda: serve(gateway, config.http.host, config.http.port))
50
+ log.info(
51
+ "tagbridge %s starting: %d device(s), sparkplug=%s, uns=%s",
52
+ __version__,
53
+ len(gateway.devices),
54
+ config.sparkplug.enabled,
55
+ config.uns.enabled,
56
+ )
57
+ await gateway.run(extra)
58
+
59
+
60
+ def _run_forever(coro: Any) -> None:
61
+ async def main() -> None:
62
+ task = asyncio.ensure_future(coro)
63
+ loop = asyncio.get_running_loop()
64
+ for sig in (signal.SIGINT, signal.SIGTERM):
65
+ with contextlib.suppress(NotImplementedError):
66
+ loop.add_signal_handler(sig, task.cancel)
67
+ with contextlib.suppress(asyncio.CancelledError):
68
+ await task
69
+
70
+ with contextlib.suppress(KeyboardInterrupt):
71
+ asyncio.run(main())
72
+
73
+
74
+ def cmd_run(args: argparse.Namespace) -> int:
75
+ config = _load(args.config)
76
+ _setup_logging(args.log_level or config.log_level)
77
+ _run_forever(_run(config))
78
+ return 0
79
+
80
+
81
+ def cmd_validate(args: argparse.Namespace) -> int:
82
+ config = _load(args.config)
83
+ from .sources import create_source
84
+
85
+ print(f"{args.config}: OK")
86
+ targets = []
87
+ if config.sparkplug.enabled:
88
+ sp = config.sparkplug
89
+ targets.append(f"Sparkplug B spBv1.0/{sp.group_id}/+/{sp.edge_node_id}")
90
+ if config.uns.enabled:
91
+ targets.append(f"UNS {config.uns.topic_prefix}/<device>/<tag>")
92
+ print(f" mqtt: {config.mqtt.host}:{config.mqtt.port} -> {', '.join(targets)}")
93
+ for device in config.devices:
94
+ try:
95
+ source = create_source(device)
96
+ except ValueError as exc:
97
+ print(f"error: {exc}", file=sys.stderr)
98
+ return 2
99
+ state = "" if device.enabled else " (disabled)"
100
+ target = (
101
+ (device.host or device.serial_port)
102
+ if isinstance(device, ModbusDeviceConfig)
103
+ else device.endpoint
104
+ )
105
+ print(
106
+ f" {device.name}{state}: {device.type} {target}, {len(device.tags)} tags, "
107
+ f"scan {device.scan_ms} ms"
108
+ )
109
+ blocks = getattr(source, "blocks", None)
110
+ if blocks:
111
+ print(
112
+ f" {len(blocks)} read request(s) per scan: "
113
+ + ", ".join(f"{b.area}:{b.start}+{b.count}" for b in blocks)
114
+ )
115
+ return 0
116
+
117
+
118
+ async def _read_once(config: GatewayConfig, only: str | None) -> list[tuple[str, str, Any, bool]]:
119
+ from .model import apply_scaling
120
+ from .sources import create_source
121
+
122
+ rows: list[tuple[str, str, Any, bool]] = []
123
+ for device in config.active_devices:
124
+ if only and device.name != only:
125
+ continue
126
+ source = create_source(device)
127
+ try:
128
+ await source.connect()
129
+ readings = await source.read()
130
+ except SourceError as exc:
131
+ rows.append((device.name, "<error>", str(exc), False))
132
+ continue
133
+ finally:
134
+ await source.close()
135
+ for tag in device.tags:
136
+ r = readings.get(tag.name)
137
+ if r is None:
138
+ rows.append((device.name, tag.name, None, False))
139
+ else:
140
+ rows.append((device.name, tag.name, apply_scaling(tag, r.value), r.good))
141
+ return rows
142
+
143
+
144
+ def cmd_read(args: argparse.Namespace) -> int:
145
+ config = _load(args.config)
146
+ _setup_logging("WARNING")
147
+ rows = asyncio.run(_read_once(config, args.device))
148
+ if args.json:
149
+ print(
150
+ json.dumps(
151
+ [dict(zip(("device", "tag", "value", "good"), r, strict=True)) for r in rows],
152
+ indent=2,
153
+ default=str,
154
+ )
155
+ )
156
+ else:
157
+ width = max([len(f"{d}/{t}") for d, t, _, _ in rows] + [4])
158
+ for device, tag, value, good in rows:
159
+ flag = "" if good else " (bad)"
160
+ print(f"{device + '/' + tag:<{width}} {value!r}{flag}")
161
+ return 0 if all(r[3] for r in rows) else 1
162
+
163
+
164
+ def cmd_browse(args: argparse.Namespace) -> int:
165
+ from .browse import browse_opcua
166
+
167
+ _setup_logging("WARNING")
168
+ try:
169
+ tags = asyncio.run(
170
+ browse_opcua(args.endpoint, args.root, args.depth, args.username, args.password)
171
+ )
172
+ except Exception as exc:
173
+ print(f"error: {exc}", file=sys.stderr)
174
+ return 1
175
+ device = {
176
+ "name": args.name,
177
+ "type": "opcua",
178
+ "endpoint": args.endpoint,
179
+ "tags": tags,
180
+ }
181
+ print(f"# {len(tags)} variables found under {args.root}")
182
+ print(yaml.safe_dump({"devices": [device]}, sort_keys=False, allow_unicode=True), end="")
183
+ return 0
184
+
185
+
186
+ def cmd_demo(args: argparse.Namespace) -> int:
187
+ from .demo import run_demo
188
+
189
+ _setup_logging("INFO")
190
+ _run_forever(
191
+ run_demo(args.host, args.modbus_port or None, args.opcua_port or None, args.interval)
192
+ )
193
+ return 0
194
+
195
+
196
+ def build_parser() -> argparse.ArgumentParser:
197
+ parser = argparse.ArgumentParser(
198
+ prog="tagbridge",
199
+ description="Modbus and OPC UA to MQTT gateway with Sparkplug B support.",
200
+ )
201
+ parser.add_argument("--version", action="version", version=f"tagbridge {__version__}")
202
+ sub = parser.add_subparsers(dest="command", required=True)
203
+
204
+ run = sub.add_parser("run", help="run the gateway")
205
+ run.add_argument("config", help="path to the YAML config file")
206
+ run.add_argument("--log-level", choices=["DEBUG", "INFO", "WARNING", "ERROR"])
207
+ run.set_defaults(func=cmd_run)
208
+
209
+ validate = sub.add_parser("validate", help="check a config file and show the read plan")
210
+ validate.add_argument("config")
211
+ validate.set_defaults(func=cmd_validate)
212
+
213
+ read = sub.add_parser("read", help="read every tag once and print the values")
214
+ read.add_argument("config")
215
+ read.add_argument("--device", help="only read this device")
216
+ read.add_argument("--json", action="store_true", help="print JSON")
217
+ read.set_defaults(func=cmd_read)
218
+
219
+ browse = sub.add_parser("browse", help="browse an OPC UA server and print a device config")
220
+ browse.add_argument("endpoint", help="for example opc.tcp://localhost:4840")
221
+ browse.add_argument("--root", default="i=85", help="node to start from (default Objects)")
222
+ browse.add_argument("--depth", type=int, default=6)
223
+ browse.add_argument("--name", default="opcua1", help="device name to use in the output")
224
+ browse.add_argument("--username")
225
+ browse.add_argument("--password")
226
+ browse.set_defaults(func=cmd_browse)
227
+
228
+ demo = sub.add_parser("demo-server", help="start a demo Modbus TCP and OPC UA server")
229
+ demo.add_argument("--host", default="0.0.0.0")
230
+ demo.add_argument("--modbus-port", type=int, default=5020, help="0 to disable")
231
+ demo.add_argument("--opcua-port", type=int, default=4840, help="0 to disable")
232
+ demo.add_argument("--interval", type=float, default=1.0)
233
+ demo.set_defaults(func=cmd_demo)
234
+ return parser
235
+
236
+
237
+ def main(argv: list[str] | None = None) -> int:
238
+ args = build_parser().parse_args(argv)
239
+ result: int = args.func(args)
240
+ return result
241
+
242
+
243
+ if __name__ == "__main__":
244
+ raise SystemExit(main())
tagbridge/config.py ADDED
@@ -0,0 +1,254 @@
1
+ """Configuration models and YAML loading."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import re
7
+ from pathlib import Path
8
+ from typing import Annotated, Any, Literal
9
+
10
+ import yaml
11
+ from pydantic import (
12
+ AliasChoices,
13
+ BaseModel,
14
+ ConfigDict,
15
+ Field,
16
+ field_validator,
17
+ model_validator,
18
+ )
19
+
20
+ DataType = Literal[
21
+ "auto",
22
+ "bool",
23
+ "int16",
24
+ "uint16",
25
+ "int32",
26
+ "uint32",
27
+ "int64",
28
+ "uint64",
29
+ "float32",
30
+ "float64",
31
+ "string",
32
+ ]
33
+
34
+ _ENV_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-(.*?))?\}")
35
+ _NAME_PATTERN = re.compile(r"^[^/+#\s][^+#]*$")
36
+
37
+
38
+ class ConfigError(ValueError):
39
+ """Raised when a configuration file cannot be loaded or is invalid."""
40
+
41
+
42
+ def substitute_env(text: str, env: dict[str, str] | None = None) -> str:
43
+ """Replace ``${VAR}`` and ``${VAR:-default}`` with environment values."""
44
+ source = os.environ if env is None else env
45
+
46
+ def replace(match: re.Match[str]) -> str:
47
+ name, default = match.group(1), match.group(2)
48
+ if name in source and source[name] != "":
49
+ return source[name]
50
+ if default is not None:
51
+ return default
52
+ raise ConfigError(f"environment variable {name} is not set and has no default")
53
+
54
+ return _ENV_PATTERN.sub(replace, text)
55
+
56
+
57
+ class _Model(BaseModel):
58
+ model_config = ConfigDict(extra="forbid", populate_by_name=True)
59
+
60
+
61
+ class TlsConfig(_Model):
62
+ enabled: bool = False
63
+ ca_file: str | None = None
64
+ cert_file: str | None = None
65
+ key_file: str | None = None
66
+ insecure: bool = False
67
+
68
+
69
+ class MqttConfig(_Model):
70
+ host: str = "localhost"
71
+ port: int = 1883
72
+ username: str | None = None
73
+ password: str | None = None
74
+ client_id: str | None = None
75
+ keepalive: int = Field(default=30, ge=5)
76
+ tls: TlsConfig = TlsConfig()
77
+ qos: Literal[0, 1] = 0
78
+ reconnect_min_s: float = Field(default=1.0, gt=0)
79
+ reconnect_max_s: float = Field(default=30.0, gt=0)
80
+
81
+ @field_validator("username", "password", "client_id", mode="before")
82
+ @classmethod
83
+ def _empty_is_none(cls, value: object) -> object:
84
+ return None if value == "" else value
85
+
86
+
87
+ class SparkplugConfig(_Model):
88
+ enabled: bool = True
89
+ group_id: str = "tagbridge"
90
+ edge_node_id: str = "edge-01"
91
+ use_aliases: bool = True
92
+ allow_writes: bool = True
93
+
94
+ @field_validator("group_id", "edge_node_id")
95
+ @classmethod
96
+ def _valid_id(cls, value: str) -> str:
97
+ if not value or any(c in value for c in "/+#"):
98
+ raise ValueError("Sparkplug ids must be non-empty and must not contain / + or #")
99
+ return value
100
+
101
+
102
+ class UnsConfig(_Model):
103
+ enabled: bool = False
104
+ topic_prefix: str = "tagbridge"
105
+ payload: Literal["json", "value"] = "json"
106
+ retain: bool = True
107
+ allow_writes: bool = False
108
+
109
+ @field_validator("topic_prefix")
110
+ @classmethod
111
+ def _valid_prefix(cls, value: str) -> str:
112
+ value = value.strip("/")
113
+ if not value or "+" in value or "#" in value:
114
+ raise ValueError("topic_prefix must be non-empty and must not contain + or #")
115
+ return value
116
+
117
+
118
+ class HttpConfig(_Model):
119
+ enabled: bool = True
120
+ host: str = "0.0.0.0"
121
+ port: int = 8080
122
+
123
+
124
+ class TagConfig(_Model):
125
+ name: str
126
+ address: str = Field(validation_alias=AliasChoices("address", "node"))
127
+ datatype: DataType = "auto"
128
+ length: int | None = Field(default=None, ge=1, description="String length in characters")
129
+ scale: float | None = None
130
+ offset: float | None = None
131
+ deadband: float | None = Field(default=None, ge=0)
132
+ writable: bool = False
133
+ unit: str | None = None
134
+ description: str | None = None
135
+ low: float | None = None
136
+ high: float | None = None
137
+
138
+ @field_validator("name")
139
+ @classmethod
140
+ def _valid_name(cls, value: str) -> str:
141
+ value = value.strip()
142
+ if not _NAME_PATTERN.match(value) or value.endswith("/"):
143
+ raise ValueError(
144
+ f"invalid tag name {value!r}: use letters, digits, _ . - and / as a separator"
145
+ )
146
+ return value
147
+
148
+
149
+ class _DeviceBase(_Model):
150
+ name: str
151
+ enabled: bool = True
152
+ scan_ms: int = Field(default=1000, ge=10)
153
+ reconnect_min_s: float = Field(default=1.0, gt=0)
154
+ reconnect_max_s: float = Field(default=30.0, gt=0)
155
+ tags: list[TagConfig] = Field(default_factory=list)
156
+
157
+ @field_validator("name")
158
+ @classmethod
159
+ def _valid_name(cls, value: str) -> str:
160
+ if not value or any(c in value for c in "/+#"):
161
+ raise ValueError("device names must be non-empty and must not contain / + or #")
162
+ return value
163
+
164
+ @model_validator(mode="after")
165
+ def _unique_tags(self) -> _DeviceBase:
166
+ seen: set[str] = set()
167
+ for tag in self.tags:
168
+ if tag.name in seen:
169
+ raise ValueError(f"duplicate tag name {tag.name!r} in device {self.name!r}")
170
+ seen.add(tag.name)
171
+ return self
172
+
173
+
174
+ class ModbusDeviceConfig(_DeviceBase):
175
+ type: Literal["modbus"]
176
+ host: str | None = None
177
+ port: int = 502
178
+ serial_port: str | None = None
179
+ baudrate: int = 9600
180
+ parity: Literal["N", "E", "O"] = "N"
181
+ stopbits: Literal[1, 2] = 1
182
+ unit_id: int = Field(default=1, ge=0, le=255, validation_alias=AliasChoices("unit_id", "slave"))
183
+ timeout_s: float = Field(default=3.0, gt=0)
184
+ byte_order: Literal["big", "little"] = "big"
185
+ word_order: Literal["big", "little"] = "big"
186
+ max_registers_per_read: int = Field(default=100, ge=1, le=125)
187
+ max_gap: int = Field(default=10, ge=0, description="Registers to read across to merge blocks")
188
+
189
+ @model_validator(mode="after")
190
+ def _transport(self) -> ModbusDeviceConfig:
191
+ if bool(self.host) == bool(self.serial_port):
192
+ raise ValueError(f"modbus device {self.name!r}: set exactly one of host or serial_port")
193
+ return self
194
+
195
+
196
+ class OpcUaDeviceConfig(_DeviceBase):
197
+ type: Literal["opcua"]
198
+ endpoint: str
199
+ username: str | None = None
200
+ password: str | None = None
201
+ security: str | None = Field(
202
+ default=None,
203
+ description="asyncua security string, e.g. Basic256Sha256,SignAndEncrypt,cert.der,key.pem",
204
+ )
205
+ mode: Literal["subscribe", "poll"] = "subscribe"
206
+ timeout_s: float = Field(default=4.0, gt=0)
207
+
208
+
209
+ DeviceConfig = Annotated[ModbusDeviceConfig | OpcUaDeviceConfig, Field(discriminator="type")]
210
+
211
+
212
+ class GatewayConfig(_Model):
213
+ log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
214
+ mqtt: MqttConfig = MqttConfig()
215
+ sparkplug: SparkplugConfig = SparkplugConfig()
216
+ uns: UnsConfig = UnsConfig()
217
+ http: HttpConfig = HttpConfig()
218
+ devices: list[DeviceConfig] = Field(default_factory=list)
219
+
220
+ @model_validator(mode="after")
221
+ def _checks(self) -> GatewayConfig:
222
+ if not self.sparkplug.enabled and not self.uns.enabled:
223
+ raise ValueError("enable at least one of sparkplug or uns")
224
+ names = [d.name for d in self.devices]
225
+ dupes = {n for n in names if names.count(n) > 1}
226
+ if dupes:
227
+ raise ValueError(f"duplicate device names: {', '.join(sorted(dupes))}")
228
+ return self
229
+
230
+ @property
231
+ def active_devices(self) -> list[ModbusDeviceConfig | OpcUaDeviceConfig]:
232
+ return [d for d in self.devices if d.enabled]
233
+
234
+
235
+ def parse_config(data: dict[str, Any]) -> GatewayConfig:
236
+ try:
237
+ return GatewayConfig.model_validate(data)
238
+ except ValueError as exc:
239
+ raise ConfigError(str(exc)) from exc
240
+
241
+
242
+ def load_config(path: str | Path, env: dict[str, str] | None = None) -> GatewayConfig:
243
+ """Load a YAML config file, substituting environment variables first."""
244
+ try:
245
+ text = Path(path).read_text(encoding="utf-8")
246
+ except OSError as exc:
247
+ raise ConfigError(f"cannot read {path}: {exc}") from exc
248
+ try:
249
+ data = yaml.safe_load(substitute_env(text, env)) or {}
250
+ except yaml.YAMLError as exc:
251
+ raise ConfigError(f"invalid YAML in {path}: {exc}") from exc
252
+ if not isinstance(data, dict):
253
+ raise ConfigError(f"{path} must contain a mapping at the top level")
254
+ return parse_config(data)