tagscope 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.
tagscope/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """TagScope: log OPC UA tags to a database and watch them live in your browser."""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ __all__ = ["__version__"]
tagscope/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
tagscope/cli.py ADDED
@@ -0,0 +1,215 @@
1
+ """Command line interface: ``tagscope demo | run | init | browse | export``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import asyncio
7
+ import contextlib
8
+ import logging
9
+ import sys
10
+ import time
11
+ import webbrowser
12
+ from pathlib import Path
13
+
14
+ from . import __version__
15
+ from .config import Config, ConfigError, load_config
16
+
17
+ EXAMPLE_CONFIG = """\
18
+ # TagScope configuration. Values like ${PLC_PASSWORD} are read from the environment.
19
+ storage: sqlite:///tagscope.db # or postgresql+psycopg://user:pass@host/db
20
+ retention_days: 30 # delete samples older than this (null = keep forever)
21
+
22
+ web:
23
+ host: 127.0.0.1
24
+ port: 8000
25
+
26
+ servers:
27
+ - name: line1
28
+ endpoint: opc.tcp://192.168.0.10:4840
29
+ # username: operator
30
+ # password: ${PLC_PASSWORD}
31
+ publishing_interval_ms: 500
32
+ tags:
33
+ - name: Tank level
34
+ node: ns=3;s="DB_Process"."TankLevel" # Siemens S7-1500 style node id
35
+ unit: "%"
36
+ low: 10
37
+ high: 90
38
+ deadband: 0.2 # only store changes larger than this
39
+ - name: Pump running
40
+ node: ns=3;s="DB_Process"."PumpRunning"
41
+ - ns=3;s="DB_Process"."BatchCounter" # short form: name = node id
42
+ """
43
+
44
+ BANNER = r"""
45
+ ______ _____
46
+ /_ __/___ _____ _/ ___/_________ ____ ___
47
+ / / / __ `/ __ `/\__ \/ ___/ __ \/ __ \/ _ \
48
+ / / / /_/ / /_/ /___/ / /__/ /_/ / /_/ / __/
49
+ /_/ \__,_/\__, //____/\___/\____/ .___/\___/
50
+ /____/ /_/ v{version}
51
+ """
52
+
53
+
54
+ async def serve(config: Config, *, simulate: bool = False, open_browser: bool = False) -> None:
55
+ """Run the collector, the database writer and the web server together."""
56
+ import uvicorn
57
+
58
+ from .collector import watch_server, writer_loop
59
+ from .hub import Hub
60
+ from .simulator import run_simulator
61
+ from .storage import Storage
62
+ from .web import create_app
63
+
64
+ tasks: list[asyncio.Task] = []
65
+ storage = Storage(config.storage)
66
+ storage.sync_tags(config.tags)
67
+ if simulate:
68
+ from .simulator import Plant, backfill
69
+
70
+ plant = Plant(seed=7)
71
+ await asyncio.to_thread(backfill, storage, config, plant)
72
+ ready = asyncio.Event()
73
+ tasks.append(asyncio.create_task(run_simulator(config.servers[0].endpoint, plant=plant, ready=ready)))
74
+ await asyncio.wait_for(ready.wait(), 15)
75
+ hub = Hub(config)
76
+ tasks.append(asyncio.create_task(writer_loop(hub, storage, config)))
77
+ tasks += [asyncio.create_task(watch_server(s, hub)) for s in config.servers]
78
+
79
+ app = create_app(hub, storage)
80
+ uv_config = uvicorn.Config(app, host=config.web.host, port=config.web.port, log_level="warning")
81
+ server = uvicorn.Server(uv_config)
82
+ url = f"http://{'localhost' if config.web.host in ('0.0.0.0', '127.0.0.1') else config.web.host}:{config.web.port}"
83
+ print(BANNER.format(version=__version__))
84
+ print(f" Dashboard {url}")
85
+ print(f" Storage {storage.engine.url.render_as_string(hide_password=True)}")
86
+ print(f" Logging {len(config.tags)} tags from {len(config.servers)} server(s)")
87
+ print(" Press Ctrl+C to stop.\n")
88
+ if open_browser:
89
+ asyncio.get_running_loop().call_later(1.0, webbrowser.open, url)
90
+ try:
91
+ await server.serve()
92
+ finally:
93
+ for task in reversed(tasks):
94
+ task.cancel()
95
+ with contextlib.suppress(asyncio.CancelledError, Exception):
96
+ await task
97
+ storage.close()
98
+
99
+
100
+ def _cmd_demo(args: argparse.Namespace) -> int:
101
+ from .simulator import demo_config
102
+
103
+ config = demo_config(storage=args.storage)
104
+ config.web.host, config.web.port = args.host, args.port
105
+ asyncio.run(serve(config, simulate=True, open_browser=not args.no_browser))
106
+ return 0
107
+
108
+
109
+ def _cmd_run(args: argparse.Namespace) -> int:
110
+ config = load_config(args.config)
111
+ if args.port:
112
+ config.web.port = args.port
113
+ if args.host:
114
+ config.web.host = args.host
115
+ if not config.servers:
116
+ print("error: no servers configured", file=sys.stderr)
117
+ return 2
118
+ asyncio.run(serve(config, open_browser=args.open))
119
+ return 0
120
+
121
+
122
+ def _cmd_init(args: argparse.Namespace) -> int:
123
+ path = Path(args.path)
124
+ if path.exists() and not args.force:
125
+ print(f"error: {path} already exists (use --force to overwrite)", file=sys.stderr)
126
+ return 1
127
+ path.write_text(EXAMPLE_CONFIG, encoding="utf-8")
128
+ print(f"Wrote {path}. Edit the endpoint and tags, then run: tagscope run {path}")
129
+ return 0
130
+
131
+
132
+ def _cmd_browse(args: argparse.Namespace) -> int:
133
+ from .collector import browse
134
+
135
+ items = asyncio.run(browse(args.endpoint, args.node, args.username, args.password))
136
+ width = max((len(i["node"]) for i in items), default=10)
137
+ for item in items:
138
+ icon = {"Object": "▸", "Variable": "•", "Method": "ƒ"}.get(item["class"], " ")
139
+ value = "" if item["value"] is None else f" = {item['value']!r}"
140
+ print(f"{icon} {item['node']:<{width}} {item['name']}{value}")
141
+ return 0
142
+
143
+
144
+ def _cmd_export(args: argparse.Namespace) -> int:
145
+ from .storage import Storage
146
+
147
+ config = load_config(args.config)
148
+ storage = Storage(config.storage)
149
+ end = time.time()
150
+ with contextlib.ExitStack() as stack:
151
+ out = stack.enter_context(open(args.output, "w", encoding="utf-8", newline="")) if args.output else sys.stdout
152
+ for chunk in storage.export_csv(args.tags or None, end - args.minutes * 60, end):
153
+ out.write(chunk)
154
+ storage.close()
155
+ return 0
156
+
157
+
158
+ def build_parser() -> argparse.ArgumentParser:
159
+ parser = argparse.ArgumentParser(
160
+ prog="tagscope", description="Log OPC UA tags to a database and watch them live in your browser."
161
+ )
162
+ parser.add_argument("--version", action="version", version=f"tagscope {__version__}")
163
+ parser.add_argument("-v", "--verbose", action="store_true", help="show debug logging")
164
+ sub = parser.add_subparsers(dest="command", required=True)
165
+
166
+ p = sub.add_parser("demo", help="start a simulated plant and open the dashboard")
167
+ p.add_argument("--storage", default="sqlite:///tagscope-demo.db")
168
+ p.add_argument("--host", default="127.0.0.1")
169
+ p.add_argument("--port", type=int, default=8000)
170
+ p.add_argument("--no-browser", action="store_true", help="do not open a browser window")
171
+ p.set_defaults(func=_cmd_demo)
172
+
173
+ p = sub.add_parser("run", help="log the servers and tags from a config file")
174
+ p.add_argument("config", help="path to tagscope.yaml")
175
+ p.add_argument("--host")
176
+ p.add_argument("--port", type=int)
177
+ p.add_argument("--open", action="store_true", help="open the dashboard in a browser")
178
+ p.set_defaults(func=_cmd_run)
179
+
180
+ p = sub.add_parser("init", help="write an example config file")
181
+ p.add_argument("path", nargs="?", default="tagscope.yaml")
182
+ p.add_argument("--force", action="store_true")
183
+ p.set_defaults(func=_cmd_init)
184
+
185
+ p = sub.add_parser("browse", help="list the nodes of an OPC UA server")
186
+ p.add_argument("endpoint", help="e.g. opc.tcp://192.168.0.10:4840")
187
+ p.add_argument("node", nargs="?", help="node id to browse (default: Objects folder)")
188
+ p.add_argument("--username")
189
+ p.add_argument("--password")
190
+ p.set_defaults(func=_cmd_browse)
191
+
192
+ p = sub.add_parser("export", help="export logged samples as CSV")
193
+ p.add_argument("config", help="path to tagscope.yaml")
194
+ p.add_argument("--tags", nargs="*", help="tag names (default: all)")
195
+ p.add_argument("--minutes", type=float, default=60)
196
+ p.add_argument("-o", "--output", help="output file (default: stdout)")
197
+ p.set_defaults(func=_cmd_export)
198
+ return parser
199
+
200
+
201
+ def main(argv: list[str] | None = None) -> int:
202
+ args = build_parser().parse_args(argv)
203
+ logging.basicConfig(
204
+ level=logging.DEBUG if args.verbose else logging.WARNING,
205
+ format="%(asctime)s %(levelname)s %(name)s: %(message)s",
206
+ )
207
+ if not args.verbose:
208
+ logging.getLogger("asyncua").setLevel(logging.ERROR)
209
+ try:
210
+ return args.func(args)
211
+ except ConfigError as exc:
212
+ print(f"config error: {exc}", file=sys.stderr)
213
+ return 2
214
+ except KeyboardInterrupt:
215
+ return 0
tagscope/collector.py ADDED
@@ -0,0 +1,154 @@
1
+ """OPC UA subscriptions and the background database writer."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import logging
7
+ import time
8
+ from typing import Any
9
+
10
+ from asyncua import Client, ua
11
+
12
+ from .config import Config, ServerConfig
13
+ from .hub import Hub
14
+ from .storage import BAD, GOOD, UNCERTAIN, Storage
15
+
16
+ log = logging.getLogger("tagscope")
17
+
18
+
19
+ def _quality(status: Any) -> int:
20
+ try:
21
+ if status is None or status.is_good():
22
+ return GOOD
23
+ if status.is_uncertain():
24
+ return UNCERTAIN
25
+ except AttributeError: # pragma: no cover - defensive
26
+ return GOOD
27
+ return BAD
28
+
29
+
30
+ def _timestamp(data_value: Any) -> float:
31
+ for attr in ("SourceTimestamp", "ServerTimestamp"):
32
+ ts = getattr(data_value, attr, None)
33
+ if ts is not None:
34
+ return ts.timestamp()
35
+ return time.time()
36
+
37
+
38
+ class _Handler:
39
+ def __init__(self, hub: Hub, names: dict[str, str]) -> None:
40
+ self.hub = hub
41
+ self.names = names # node id string -> tag name
42
+
43
+ def datachange_notification(self, node, val, data) -> None:
44
+ name = self.names.get(node.nodeid.to_string())
45
+ if name is None:
46
+ return
47
+ dv = data.monitored_item.Value
48
+ self.hub.update(name, val, _timestamp(dv), _quality(dv.StatusCode))
49
+
50
+ def status_change_notification(self, status) -> None: # pragma: no cover - server side
51
+ log.warning("subscription status changed: %s", status)
52
+
53
+
54
+ async def _connect(server: ServerConfig) -> Client:
55
+ client = Client(server.endpoint, timeout=5)
56
+ if server.username:
57
+ client.set_user(server.username)
58
+ if server.password:
59
+ client.set_password(server.password)
60
+ await client.connect()
61
+ return client
62
+
63
+
64
+ async def watch_server(server: ServerConfig, hub: Hub, retry_max_s: float = 30.0) -> None:
65
+ """Subscribe to every tag of ``server`` and keep reconnecting forever."""
66
+ delay = 1.0
67
+ while True:
68
+ client: Client | None = None
69
+ try:
70
+ hub.set_server_status(server.name, "connecting")
71
+ client = await _connect(server)
72
+ names: dict[str, str] = {}
73
+ nodes = []
74
+ for tag in server.tags:
75
+ node = client.get_node(tag.node)
76
+ names[node.nodeid.to_string()] = tag.name
77
+ nodes.append(node)
78
+ handler = _Handler(hub, names)
79
+ sub = await client.create_subscription(server.publishing_interval_ms, handler)
80
+ if nodes:
81
+ results = await sub.subscribe_data_change(nodes, queuesize=10)
82
+ for tag, res in zip(server.tags, results, strict=True):
83
+ if isinstance(res, ua.StatusCode):
84
+ hub.add_event("error", f"cannot subscribe {tag.name} ({tag.node}): {res.name}", tag.name)
85
+ hub.set_server_status(server.name, "connected")
86
+ delay = 1.0
87
+ while True:
88
+ await asyncio.sleep(2)
89
+ await client.check_connection()
90
+ except asyncio.CancelledError:
91
+ raise
92
+ except Exception as exc: # noqa: BLE001 - any failure means "reconnect"
93
+ msg = str(exc) or exc.__class__.__name__
94
+ log.warning("%s: %s, retrying in %.0fs", server.name, msg, delay)
95
+ hub.set_server_status(server.name, "disconnected", msg[:200])
96
+ for tag in server.tags:
97
+ if tag.name in hub.values:
98
+ hub.values[tag.name]["quality"] = BAD
99
+ finally:
100
+ if client is not None:
101
+ try:
102
+ await asyncio.wait_for(client.disconnect(), 3)
103
+ except Exception: # noqa: BLE001
104
+ pass
105
+ await asyncio.sleep(delay)
106
+ delay = min(delay * 2, retry_max_s)
107
+
108
+
109
+ async def writer_loop(hub: Hub, storage: Storage, config: Config) -> None:
110
+ """Flush buffered samples and events to the database periodically."""
111
+ last_purge = 0.0
112
+ try:
113
+ while True:
114
+ await asyncio.sleep(config.flush_interval_s)
115
+ await flush(hub, storage)
116
+ if config.retention_days and time.time() - last_purge > 3600:
117
+ cutoff = time.time() - config.retention_days * 86400
118
+ await asyncio.to_thread(storage.purge, cutoff)
119
+ last_purge = time.time()
120
+ finally:
121
+ await flush(hub, storage)
122
+
123
+
124
+ async def flush(hub: Hub, storage: Storage) -> None:
125
+ samples = hub.drain_samples()
126
+ events = hub.drain_events()
127
+ if samples:
128
+ hub.stats["samples_written"] += await asyncio.to_thread(storage.write_samples, samples)
129
+ for event in events:
130
+ await asyncio.to_thread(storage.add_event, event["kind"], event["message"], event["tag"], event["ts"])
131
+
132
+
133
+ async def browse(endpoint: str, node_id: str | None = None, username: str | None = None, password: str | None = None):
134
+ """List the children of a node (the Objects folder by default)."""
135
+ server = ServerConfig(name="browse", endpoint=endpoint, username=username, password=password)
136
+ client = await _connect(server)
137
+ try:
138
+ parent = client.get_node(node_id) if node_id else client.nodes.objects
139
+ children = []
140
+ for child in await parent.get_children():
141
+ node_class = await child.read_node_class()
142
+ name = (await child.read_browse_name()).Name
143
+ item = {"node": child.nodeid.to_string(), "name": name, "class": node_class.name, "value": None}
144
+ if node_class == ua.NodeClass.Variable:
145
+ try:
146
+ value = await child.read_value()
147
+ item["value"] = value if isinstance(value, (int, float, str, bool)) else str(value)
148
+ item["type"] = (await child.read_data_type_as_variant_type()).name
149
+ except Exception: # noqa: BLE001
150
+ pass
151
+ children.append(item)
152
+ return children
153
+ finally:
154
+ await client.disconnect()
tagscope/config.py ADDED
@@ -0,0 +1,159 @@
1
+ """Configuration model and YAML loader."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import re
7
+ from dataclasses import dataclass, field
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ import yaml
12
+
13
+ _ENV_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}")
14
+
15
+
16
+ class ConfigError(ValueError):
17
+ """Raised when a configuration file is invalid."""
18
+
19
+
20
+ @dataclass
21
+ class TagConfig:
22
+ name: str
23
+ node: str
24
+ unit: str = ""
25
+ description: str = ""
26
+ low: float | None = None
27
+ high: float | None = None
28
+ deadband: float = 0.0
29
+ server: str = ""
30
+
31
+
32
+ @dataclass
33
+ class ServerConfig:
34
+ name: str
35
+ endpoint: str
36
+ username: str | None = None
37
+ password: str | None = None
38
+ publishing_interval_ms: int = 500
39
+ tags: list[TagConfig] = field(default_factory=list)
40
+
41
+
42
+ @dataclass
43
+ class WebConfig:
44
+ host: str = "127.0.0.1"
45
+ port: int = 8000
46
+
47
+
48
+ @dataclass
49
+ class Config:
50
+ storage: str = "sqlite:///tagscope.db"
51
+ retention_days: float | None = 30
52
+ flush_interval_s: float = 1.0
53
+ web: WebConfig = field(default_factory=WebConfig)
54
+ servers: list[ServerConfig] = field(default_factory=list)
55
+
56
+ @property
57
+ def tags(self) -> list[TagConfig]:
58
+ return [tag for server in self.servers for tag in server.tags]
59
+
60
+ def tag(self, name: str) -> TagConfig | None:
61
+ return next((t for t in self.tags if t.name == name), None)
62
+
63
+
64
+ def _expand_env(value: Any) -> Any:
65
+ """Expand ``${VAR}`` and ``${VAR:-default}`` inside strings."""
66
+ if isinstance(value, str):
67
+
68
+ def repl(match: re.Match[str]) -> str:
69
+ name, default = match.group(1), match.group(2)
70
+ if name in os.environ:
71
+ return os.environ[name]
72
+ if default is not None:
73
+ return default
74
+ raise ConfigError(f"environment variable {name!r} is not set")
75
+
76
+ return _ENV_PATTERN.sub(repl, value)
77
+ if isinstance(value, dict):
78
+ return {k: _expand_env(v) for k, v in value.items()}
79
+ if isinstance(value, list):
80
+ return [_expand_env(v) for v in value]
81
+ return value
82
+
83
+
84
+ def _opt_float(value: Any, where: str) -> float | None:
85
+ if value is None:
86
+ return None
87
+ try:
88
+ return float(value)
89
+ except (TypeError, ValueError) as exc:
90
+ raise ConfigError(f"{where}: expected a number, got {value!r}") from exc
91
+
92
+
93
+ def parse_config(data: dict[str, Any]) -> Config:
94
+ """Build a :class:`Config` from a plain dictionary (e.g. parsed YAML)."""
95
+ if not isinstance(data, dict):
96
+ raise ConfigError("configuration must be a mapping")
97
+ data = _expand_env(data)
98
+
99
+ web_data = data.get("web") or {}
100
+ web = WebConfig(host=str(web_data.get("host", "127.0.0.1")), port=int(web_data.get("port", 8000)))
101
+
102
+ servers: list[ServerConfig] = []
103
+ seen_tags: set[str] = set()
104
+ for i, raw in enumerate(data.get("servers") or []):
105
+ where = f"servers[{i}]"
106
+ if "endpoint" not in raw:
107
+ raise ConfigError(f"{where}: 'endpoint' is required")
108
+ server = ServerConfig(
109
+ name=str(raw.get("name") or f"server{i + 1}"),
110
+ endpoint=str(raw["endpoint"]),
111
+ username=raw.get("username"),
112
+ password=raw.get("password"),
113
+ publishing_interval_ms=int(raw.get("publishing_interval_ms", 500)),
114
+ )
115
+ for j, traw in enumerate(raw.get("tags") or []):
116
+ twhere = f"{where}.tags[{j}]"
117
+ if isinstance(traw, str):
118
+ traw = {"node": traw}
119
+ if "node" not in traw:
120
+ raise ConfigError(f"{twhere}: 'node' is required")
121
+ name = str(traw.get("name") or traw["node"])
122
+ if name in seen_tags:
123
+ raise ConfigError(f"{twhere}: duplicate tag name {name!r}")
124
+ seen_tags.add(name)
125
+ server.tags.append(
126
+ TagConfig(
127
+ name=name,
128
+ node=str(traw["node"]),
129
+ unit=str(traw.get("unit", "")),
130
+ description=str(traw.get("description", "")),
131
+ low=_opt_float(traw.get("low"), f"{twhere}.low"),
132
+ high=_opt_float(traw.get("high"), f"{twhere}.high"),
133
+ deadband=_opt_float(traw.get("deadband"), f"{twhere}.deadband") or 0.0,
134
+ server=server.name,
135
+ )
136
+ )
137
+ servers.append(server)
138
+
139
+ if len({s.name for s in servers}) != len(servers):
140
+ raise ConfigError("server names must be unique")
141
+
142
+ retention = data.get("retention_days", 30)
143
+ return Config(
144
+ storage=str(data.get("storage", "sqlite:///tagscope.db")),
145
+ retention_days=_opt_float(retention, "retention_days"),
146
+ flush_interval_s=float(data.get("flush_interval_s", 1.0)),
147
+ web=web,
148
+ servers=servers,
149
+ )
150
+
151
+
152
+ def load_config(path: str | Path) -> Config:
153
+ """Load and validate a YAML configuration file."""
154
+ text = Path(path).read_text(encoding="utf-8")
155
+ try:
156
+ data = yaml.safe_load(text) or {}
157
+ except yaml.YAMLError as exc:
158
+ raise ConfigError(f"invalid YAML in {path}: {exc}") from exc
159
+ return parse_config(data)
tagscope/hub.py ADDED
@@ -0,0 +1,148 @@
1
+ """Live state shared between the collector, the database writer and the UI."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import time
7
+ from typing import Any
8
+
9
+ from .config import Config, TagConfig
10
+ from .storage import BAD, GOOD, Sample
11
+
12
+
13
+ def limit_state(tag: TagConfig, value: float | None) -> str:
14
+ """Classify a value against its configured limits."""
15
+ if value is None:
16
+ return "unknown"
17
+ if tag.high is not None and value >= tag.high:
18
+ return "high"
19
+ if tag.low is not None and value <= tag.low:
20
+ return "low"
21
+ return "normal"
22
+
23
+
24
+ class Hub:
25
+ """Keeps the latest value of every tag and fans updates out to listeners.
26
+
27
+ Listeners (WebSocket clients) receive small JSON-able dictionaries via an
28
+ :class:`asyncio.Queue`. Slow listeners never block the collector: when a
29
+ queue is full the oldest message is dropped.
30
+ """
31
+
32
+ def __init__(self, config: Config) -> None:
33
+ self.config = config
34
+ self.tags: dict[str, TagConfig] = {t.name: t for t in config.tags}
35
+ self.values: dict[str, dict[str, Any]] = {}
36
+ self.servers: dict[str, dict[str, Any]] = {
37
+ s.name: {"name": s.name, "endpoint": s.endpoint, "status": "connecting", "error": "", "since": time.time()}
38
+ for s in config.servers
39
+ }
40
+ self.stats = {"samples_written": 0, "started": time.time()}
41
+ self._listeners: set[asyncio.Queue] = set()
42
+ self._pending: list[Sample] = []
43
+ self._last_stored: dict[str, float | None] = {}
44
+ self.events: list[dict] = []
45
+
46
+ # -- listeners ----------------------------------------------------------
47
+ def subscribe(self) -> asyncio.Queue:
48
+ queue: asyncio.Queue = asyncio.Queue(maxsize=1000)
49
+ self._listeners.add(queue)
50
+ return queue
51
+
52
+ def unsubscribe(self, queue: asyncio.Queue) -> None:
53
+ self._listeners.discard(queue)
54
+
55
+ def broadcast(self, message: dict[str, Any]) -> None:
56
+ for queue in list(self._listeners):
57
+ if queue.full():
58
+ try:
59
+ queue.get_nowait()
60
+ except asyncio.QueueEmpty: # pragma: no cover - race
61
+ pass
62
+ queue.put_nowait(message)
63
+
64
+ # -- updates ------------------------------------------------------------
65
+ def snapshot(self) -> dict[str, Any]:
66
+ return {
67
+ "type": "snapshot",
68
+ "values": self.values,
69
+ "servers": list(self.servers.values()),
70
+ "stats": self.stats,
71
+ }
72
+
73
+ def set_server_status(self, name: str, status: str, error: str = "") -> None:
74
+ server = self.servers.setdefault(name, {"name": name, "endpoint": ""})
75
+ if server.get("status") == status and server.get("error") == error:
76
+ return
77
+ server.update(status=status, error=error, since=time.time())
78
+ self.broadcast({"type": "server", "server": server})
79
+ kind = {"connected": "info", "disconnected": "warning", "error": "error"}.get(status)
80
+ if kind:
81
+ text = f"{name}: {status}" + (f" ({error})" if error else "")
82
+ self.add_event(kind, text)
83
+
84
+ def add_event(self, kind: str, message: str, tag: str = "", ts: float | None = None) -> None:
85
+ event = {"ts": ts or time.time(), "tag": tag, "kind": kind, "message": message}
86
+ self.events.append(event)
87
+ self.broadcast({"type": "event", "event": event})
88
+
89
+ def drain_events(self) -> list[dict]:
90
+ events, self.events = self.events, []
91
+ return events
92
+
93
+ def update(self, name: str, value: Any, ts: float | None = None, quality: int = GOOD) -> None:
94
+ """Record a new value coming from a server."""
95
+ tag = self.tags.get(name)
96
+ if tag is None:
97
+ return
98
+ ts = ts or time.time()
99
+ num = _to_float(value)
100
+ if num is None and value is not None:
101
+ quality = max(quality, BAD)
102
+ state = limit_state(tag, num)
103
+
104
+ previous = self.values.get(name)
105
+ prev_state = previous["state"] if previous else "normal"
106
+ if state != prev_state and prev_state != "unknown" and state != "unknown":
107
+ if state == "normal":
108
+ self.add_event("cleared", f"{name} back to normal ({_fmt(num)} {tag.unit})".rstrip(), name, ts)
109
+ else:
110
+ limit = tag.high if state == "high" else tag.low
111
+ self.add_event(
112
+ "alarm",
113
+ f"{name} {state.upper()} {_fmt(num)} {tag.unit} (limit {_fmt(limit)})".replace(" ", " "),
114
+ name,
115
+ ts,
116
+ )
117
+
118
+ entry = {"value": num, "raw": value if num is None else None, "ts": ts, "quality": quality, "state": state}
119
+ self.values[name] = entry
120
+ self.broadcast({"type": "value", "tag": name, **entry})
121
+
122
+ last = self._last_stored.get(name, _MISSING)
123
+ if (
124
+ last is _MISSING or num is None or last is None or tag.deadband <= 0 or abs(num - last) >= tag.deadband # type: ignore[operator]
125
+ ):
126
+ self._pending.append(Sample(name, ts, num, quality))
127
+ self._last_stored[name] = num
128
+
129
+ def drain_samples(self) -> list[Sample]:
130
+ samples, self._pending = self._pending, []
131
+ return samples
132
+
133
+
134
+ _MISSING = object()
135
+
136
+
137
+ def _to_float(value: Any) -> float | None:
138
+ if isinstance(value, bool):
139
+ return 1.0 if value else 0.0
140
+ if isinstance(value, (int, float)):
141
+ return float(value)
142
+ return None
143
+
144
+
145
+ def _fmt(value: float | None) -> str:
146
+ if value is None:
147
+ return "-"
148
+ return f"{value:.2f}".rstrip("0").rstrip(".")