ciplink-tagserver 0.1.0__tar.gz

ciplink_tagserver-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rowan Ramamurthy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ciplink_tagserver-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: ciplink-tagserver
+Version: 0.1.0
+Summary: One server per site that owns the PLC connections and serves tag values over a WebSocket
+Author-email: Rowan Ramamurthy <rramamurthy@factoryautomation.com>
+License-Expression: MIT
+Project-URL: Source, https://github.com/RowanRama/ciplink-tagserver
+Project-URL: Driver, https://github.com/RowanRama/ciplink
+Project-URL: React client, https://www.npmjs.com/package/@ciplink/react
+Keywords: plc,allen-bradley,logix,ethernet-ip,hmi,websocket,react
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
+Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ciplink<0.2,>=0.1
+Requires-Dist: fastapi
+Requires-Dist: uvicorn[standard]
+Dynamic: license-file
+
+# ciplink-tagserver
+
+One server per site that owns all the PLC connections and serves tag values to React (or any) apps
+over a WebSocket. Apps never talk to the PLCs: each PLC gets one connection, one thread and one poll
+loop, however many screens are open.
+
+It is built on [ciplink](https://pypi.org/project/ciplink/), a fork of pycomm3 that reads by instance
+ID and reloads its tag table by itself after online edits.
+
+## Install
+
+```
+pip install ciplink-tagserver
+```
+
+or from a checkout with [uv](https://docs.astral.sh/uv/): `uv sync`, then `uv run ciplink-tagserver ...`.
+
+## Run
+
+```
+ciplink-tagserver run --config tagserver.toml          # real PLCs
+ciplink-tagserver run --config tagserver.toml --mock   # fake values, no PLC needed
+ciplink-tagserver dump-tags --config tagserver.toml --plc PLC1 --out PLC1_tags.json
+ciplink-tagserver types --url http://127.0.0.1:8765 --token T --plc PLC1 --out src/tags.d.ts
+```
+
+`types` asks a running server for its tag list (`GET /tags`) and writes a TypeScript union,
+`export type TagName = "Line1.Speed" | ...;`. AOIs appear as their readable members (`Valve1.Open`),
+never their local tags. Pass `--plc` once per PLC; with more than one, names are qualified (`PLC1/Line1.Speed`).
+
+Add `--log-file tagserver.log` to `run` to log to a file (rotated at 10 MB, 5 kept) instead of the console.
+
+## Run at Windows startup
+
+From an administrator terminal (right-click Terminal, "Run as administrator"):
+
+```
+ciplink-tagserver service install --config C:\TagServer\tagserver.toml
+ciplink-tagserver service status
+ciplink-tagserver service remove
+```
+
+`install` registers a Task Scheduler task that starts at every boot as SYSTEM, without anyone logging in,
+and starts it now. The task runs `ciplink-tagserver service run`, which starts the server again 5 s after
+it stops for any reason; Task Scheduler also restarts the task itself if it fails. Logs go to
+`tagserver.log` next to the config (`--log-file` to change it). Use full paths in the config, or paths
+relative to it; the task runs in the config's folder. `--name` sets the task name (default
+`ciplink-tagserver`), so several servers can run on one PC with different configs and ports.
+
+## Config
+
+```toml
+[server]
+host = "127.0.0.1"      # localhost only by default
+port = 8765
+cycle_ms = 250          # poll period per PLC
+audit_log = "audit.log" # optional, JSON lines of every write attempt
+
+[plc.PLC1]
+path = "192.168.1.10"                    # a ciplink/pycomm3 path, e.g. "10.0.0.5/1/3"
+tag_cache_file = "cache/PLC1.json"   # optional: fast restarts
+mock_tags = "PLC1_tags.json"         # optional: used only with --mock
+
+[token.viewer]
+secret = "change-me-too"                # no write patterns: read-only
+
+[token.hmi1]
+secret = "change-me"
+write = ["PLC1/Line1.*.SpeedSP", "PLC1/Program:Station1.Door*"]
+```
+
+Relative file paths are relative to the config file. A working example is in `examples/`.
+
+**Tag names** are qualified as `<plc>/<tag>`, e.g. `PLC1/Program:Main.Speed` (a slash cannot appear
+in a Logix tag name). With exactly one PLC configured, unqualified names mean that PLC.
+
+**Write patterns** are `fnmatch` patterns matched against the qualified name, ignoring case. `*` also
+matches dots, and `[...]` is a character class, so to allow `Arr[3]` write `Arr[[]3]` or `Arr?3?`.
+
+## Protocol (v1)
+
+JSON messages over `ws://host:port/ws`.
+
+Client to server:
+
+| message | meaning |
+|---|---|
+| `{"op":"hello","v":1,"token":"<secret>"}` | must be the first message |
+| `{"op":"sub","id":N,"tags":["..."],"tier":1}` | subscribe; reusing an id replaces that subscription |
+| `{"op":"unsub","id":N}` | drop subscription N |
+| `{"op":"write","id":N,"tag":"...","value":...}` | write one tag |
+
+Server to client:
+
+| message | when |
+|---|---|
+| `{"op":"welcome","v":1,"plcs":{"PLC1":"connected"},"write":true}` | after a good hello; `write` says whether the token has any write patterns |
+| `{"op":"values","d":{"<tag>":[value, quality, t]}}` | changed values only; right after a `sub`, the values already cached |
+| `{"op":"ack","id":N,"ok":true,"error":null}` | for `sub`, `unsub` and `write` |
+| `{"op":"status","plcs":{"PLC1":"disconnected"}}` | a PLC changed state |
+| `{"op":"meta","plc":"PLC1"}` | the PLC's tag table was reloaded (online edit, download): fetch `/tags` again |
+| `{"op":"error","id":N,"error":"..."}` | bad request (`id` is null when unknown) |
+
+- A bad token, a first message that is not `hello`, or another protocol version: the socket is closed with code **4401**.
+- Tags in `values` are keyed by the name as the client subscribed it.
+- `quality` is `good`, `bad` (the read failed), `missing` (no such tag, or an AOI local tag that cannot
+  be read from outside) or `stale` (PLC disconnected: the last value is kept). `value` is null for bad and missing.
+- `t` is the time of the change in ms since the epoch.
+- Values: structs and AOIs are objects, arrays are lists, bytes are hex strings, NaN and infinities are
+  the strings `"NaN"`, `"Infinity"`, `"-Infinity"`.
+- PLC states: `connecting`, `connected`, `disconnected`. Reconnects back off 1, 2, 5, then every 10 s.
+- `tier` is stored but not used yet: every subscribed tag is read every cycle.
+- Writes go to the PLC's thread, run after that cycle's read, and the ack carries the driver's result.
+  They are never retried; a write while the PLC is not connected fails at once.
+
+## HTTP
+
+- `GET /health`: per PLC `state`, `last_cycle_ms`, `last_ok_ts`, `reconnects`, `reloads`.
+- `GET /stats`: `sessions`, and per PLC `reads_per_cycle`, `last_cycle_ms`, `cycle_ms`, `overruns`, `subscriptions`.
+- `GET /tags?plc=NAME` with `Authorization: Bearer <secret>`: the PLC's tags with data type and, for
+  AOIs, `aoi_readable` (the members that can be read). `plc` may be left out with one PLC.
+
+## React
+
+[`@ciplink/react`](client/) (in `client/`) is the React side: one provider that owns the WebSocket, and
+hooks and components that subscribe while mounted.
+
+```tsx
+import { TagServerProvider, TagValue, TagLamp, useWriteTag, useTagServer } from "@ciplink/react";
+
+<TagServerProvider url="ws://127.0.0.1:8765/ws" token="change-me">
+  <TagValue name="Line1.Station1.Speed" decimals={1} unit="m/min" />
+  <TagLamp name="Line1.Running" />
+</TagServerProvider>
+```
+
+- `useTag(name)` gives `{value, quality, t}` and re-renders only when that tag changes; subscriptions are
+  counted across components and batched.
+- `useTags(names)`, `useWriteTag(name)` (resolves with the write's ack), `useTagServer()` (connection
+  state, PLC states, `canWrite`).
+- `<TagValue>` and `<TagLamp>` are fixed width with a quality marker, so nothing moves as values change.
+- `<TagLink to as?>` prefetches the tags of a page registered with `registerPage(path, tags)`.
+- Reconnects after 1, 2, 5, then every 10 s, re-subscribes, and shows values as `stale` meanwhile.
+
+A runnable app is in [`examples/react-app/`](examples/react-app/): start the server with
+`uv run ciplink-tagserver run --config examples/tagserver.toml --mock`, build `client/` once
+(`npm install && npm run build`), then `npm install && npm run dev` in the example.
+
+## Mock mode
+
+`--mock` replaces every PLC driver with a fake serving the tags in that PLC's `mock_tags` file:
+
+```json
+{"Line1.Station1.Speed": "REAL", "Line1.Running": "BOOL", "PartCount": "DINT"}
+```
+
+Numbers random-walk, BOOLs toggle now and then, writes are stored, unknown names are `missing`. Other
+types (UDTs, AOIs) read as `bad`; list their atomic members by full name to simulate them.
+`dump-tags` writes this file from a real PLC (it only uploads the tag list), so a mock can mirror it.
+
+## Safety
+
+- Writes are off unless a token has `write` patterns, and only names matching them can be written.
+- Every write attempt, allowed or not, is appended to the audit log.
+- The server binds to `127.0.0.1` by default. Put it behind a TLS proxy before opening it to a network:
+  tokens travel in clear text over plain `ws://` and `http://`.
+- Change the example secrets.

ciplink_tagserver-0.1.0/README.md

@@ -0,0 +1,167 @@
+# ciplink-tagserver
+
+One server per site that owns all the PLC connections and serves tag values to React (or any) apps
+over a WebSocket. Apps never talk to the PLCs: each PLC gets one connection, one thread and one poll
+loop, however many screens are open.
+
+It is built on [ciplink](https://pypi.org/project/ciplink/), a fork of pycomm3 that reads by instance
+ID and reloads its tag table by itself after online edits.
+
+## Install
+
+```
+pip install ciplink-tagserver
+```
+
+or from a checkout with [uv](https://docs.astral.sh/uv/): `uv sync`, then `uv run ciplink-tagserver ...`.
+
+## Run
+
+```
+ciplink-tagserver run --config tagserver.toml          # real PLCs
+ciplink-tagserver run --config tagserver.toml --mock   # fake values, no PLC needed
+ciplink-tagserver dump-tags --config tagserver.toml --plc PLC1 --out PLC1_tags.json
+ciplink-tagserver types --url http://127.0.0.1:8765 --token T --plc PLC1 --out src/tags.d.ts
+```
+
+`types` asks a running server for its tag list (`GET /tags`) and writes a TypeScript union,
+`export type TagName = "Line1.Speed" | ...;`. AOIs appear as their readable members (`Valve1.Open`),
+never their local tags. Pass `--plc` once per PLC; with more than one, names are qualified (`PLC1/Line1.Speed`).
+
+Add `--log-file tagserver.log` to `run` to log to a file (rotated at 10 MB, 5 kept) instead of the console.
+
+## Run at Windows startup
+
+From an administrator terminal (right-click Terminal, "Run as administrator"):
+
+```
+ciplink-tagserver service install --config C:\TagServer\tagserver.toml
+ciplink-tagserver service status
+ciplink-tagserver service remove
+```
+
+`install` registers a Task Scheduler task that starts at every boot as SYSTEM, without anyone logging in,
+and starts it now. The task runs `ciplink-tagserver service run`, which starts the server again 5 s after
+it stops for any reason; Task Scheduler also restarts the task itself if it fails. Logs go to
+`tagserver.log` next to the config (`--log-file` to change it). Use full paths in the config, or paths
+relative to it; the task runs in the config's folder. `--name` sets the task name (default
+`ciplink-tagserver`), so several servers can run on one PC with different configs and ports.
+
+## Config
+
+```toml
+[server]
+host = "127.0.0.1"      # localhost only by default
+port = 8765
+cycle_ms = 250          # poll period per PLC
+audit_log = "audit.log" # optional, JSON lines of every write attempt
+
+[plc.PLC1]
+path = "192.168.1.10"                    # a ciplink/pycomm3 path, e.g. "10.0.0.5/1/3"
+tag_cache_file = "cache/PLC1.json"   # optional: fast restarts
+mock_tags = "PLC1_tags.json"         # optional: used only with --mock
+
+[token.viewer]
+secret = "change-me-too"                # no write patterns: read-only
+
+[token.hmi1]
+secret = "change-me"
+write = ["PLC1/Line1.*.SpeedSP", "PLC1/Program:Station1.Door*"]
+```
+
+Relative file paths are relative to the config file. A working example is in `examples/`.
+
+**Tag names** are qualified as `<plc>/<tag>`, e.g. `PLC1/Program:Main.Speed` (a slash cannot appear
+in a Logix tag name). With exactly one PLC configured, unqualified names mean that PLC.
+
+**Write patterns** are `fnmatch` patterns matched against the qualified name, ignoring case. `*` also
+matches dots, and `[...]` is a character class, so to allow `Arr[3]` write `Arr[[]3]` or `Arr?3?`.
+
+## Protocol (v1)
+
+JSON messages over `ws://host:port/ws`.
+
+Client to server:
+
+| message | meaning |
+|---|---|
+| `{"op":"hello","v":1,"token":"<secret>"}` | must be the first message |
+| `{"op":"sub","id":N,"tags":["..."],"tier":1}` | subscribe; reusing an id replaces that subscription |
+| `{"op":"unsub","id":N}` | drop subscription N |
+| `{"op":"write","id":N,"tag":"...","value":...}` | write one tag |
+
+Server to client:
+
+| message | when |
+|---|---|
+| `{"op":"welcome","v":1,"plcs":{"PLC1":"connected"},"write":true}` | after a good hello; `write` says whether the token has any write patterns |
+| `{"op":"values","d":{"<tag>":[value, quality, t]}}` | changed values only; right after a `sub`, the values already cached |
+| `{"op":"ack","id":N,"ok":true,"error":null}` | for `sub`, `unsub` and `write` |
+| `{"op":"status","plcs":{"PLC1":"disconnected"}}` | a PLC changed state |
+| `{"op":"meta","plc":"PLC1"}` | the PLC's tag table was reloaded (online edit, download): fetch `/tags` again |
+| `{"op":"error","id":N,"error":"..."}` | bad request (`id` is null when unknown) |
+
+- A bad token, a first message that is not `hello`, or another protocol version: the socket is closed with code **4401**.
+- Tags in `values` are keyed by the name as the client subscribed it.
+- `quality` is `good`, `bad` (the read failed), `missing` (no such tag, or an AOI local tag that cannot
+  be read from outside) or `stale` (PLC disconnected: the last value is kept). `value` is null for bad and missing.
+- `t` is the time of the change in ms since the epoch.
+- Values: structs and AOIs are objects, arrays are lists, bytes are hex strings, NaN and infinities are
+  the strings `"NaN"`, `"Infinity"`, `"-Infinity"`.
+- PLC states: `connecting`, `connected`, `disconnected`. Reconnects back off 1, 2, 5, then every 10 s.
+- `tier` is stored but not used yet: every subscribed tag is read every cycle.
+- Writes go to the PLC's thread, run after that cycle's read, and the ack carries the driver's result.
+  They are never retried; a write while the PLC is not connected fails at once.
+
+## HTTP
+
+- `GET /health`: per PLC `state`, `last_cycle_ms`, `last_ok_ts`, `reconnects`, `reloads`.
+- `GET /stats`: `sessions`, and per PLC `reads_per_cycle`, `last_cycle_ms`, `cycle_ms`, `overruns`, `subscriptions`.
+- `GET /tags?plc=NAME` with `Authorization: Bearer <secret>`: the PLC's tags with data type and, for
+  AOIs, `aoi_readable` (the members that can be read). `plc` may be left out with one PLC.
+
+## React
+
+[`@ciplink/react`](client/) (in `client/`) is the React side: one provider that owns the WebSocket, and
+hooks and components that subscribe while mounted.
+
+```tsx
+import { TagServerProvider, TagValue, TagLamp, useWriteTag, useTagServer } from "@ciplink/react";
+
+<TagServerProvider url="ws://127.0.0.1:8765/ws" token="change-me">
+  <TagValue name="Line1.Station1.Speed" decimals={1} unit="m/min" />
+  <TagLamp name="Line1.Running" />
+</TagServerProvider>
+```
+
+- `useTag(name)` gives `{value, quality, t}` and re-renders only when that tag changes; subscriptions are
+  counted across components and batched.
+- `useTags(names)`, `useWriteTag(name)` (resolves with the write's ack), `useTagServer()` (connection
+  state, PLC states, `canWrite`).
+- `<TagValue>` and `<TagLamp>` are fixed width with a quality marker, so nothing moves as values change.
+- `<TagLink to as?>` prefetches the tags of a page registered with `registerPage(path, tags)`.
+- Reconnects after 1, 2, 5, then every 10 s, re-subscribes, and shows values as `stale` meanwhile.
+
+A runnable app is in [`examples/react-app/`](examples/react-app/): start the server with
+`uv run ciplink-tagserver run --config examples/tagserver.toml --mock`, build `client/` once
+(`npm install && npm run build`), then `npm install && npm run dev` in the example.
+
+## Mock mode
+
+`--mock` replaces every PLC driver with a fake serving the tags in that PLC's `mock_tags` file:
+
+```json
+{"Line1.Station1.Speed": "REAL", "Line1.Running": "BOOL", "PartCount": "DINT"}
+```
+
+Numbers random-walk, BOOLs toggle now and then, writes are stored, unknown names are `missing`. Other
+types (UDTs, AOIs) read as `bad`; list their atomic members by full name to simulate them.
+`dump-tags` writes this file from a real PLC (it only uploads the tag list), so a mock can mirror it.
+
+## Safety
+
+- Writes are off unless a token has `write` patterns, and only names matching them can be written.
+- Every write attempt, allowed or not, is appended to the audit log.
+- The server binds to `127.0.0.1` by default. Put it behind a TLS proxy before opening it to a network:
+  tokens travel in clear text over plain `ws://` and `http://`.
+- Change the example secrets.

ciplink_tagserver-0.1.0/ciplink_tagserver/__init__.py

@@ -0,0 +1,3 @@
+"""One server per site that owns the PLC connections and serves tag values over a WebSocket."""
+
+__version__ = "0.1.0"

ciplink_tagserver-0.1.0/ciplink_tagserver/cli.py

@@ -0,0 +1,128 @@
+"""ciplink-tagserver run | dump-tags | types | service"""
+
+import argparse
+import json
+import logging
+import logging.handlers
+from pathlib import Path
+import urllib.parse
+import urllib.request
+
+from .config import load_config
+from .values import type_name
+
+
+def run(args):
+    import uvicorn
+
+    from .server import create_app
+
+    config = load_config(args.config)
+    log_config = None if args.log_file else uvicorn.config.LOGGING_CONFIG  # with a log file, uvicorn logs go there too
+    uvicorn.run(create_app(config, mock=args.mock), host=config.host, port=config.port, log_config=log_config)
+
+
+def service(args):
+    from . import service as svc
+
+    config = Path(args.config).resolve()
+    log_file = Path(args.log_file).resolve() if args.log_file else config.with_name("tagserver.log")
+    if args.action == "install":
+        return svc.install(args.name, config, log_file)
+    if args.action == "remove":
+        return svc.remove(args.name)
+    if args.action == "status":
+        return svc.status(args.name)
+    args.mock, args.config, args.log_file = False, str(config), str(log_file)
+    svc.supervise(lambda: run(args))  # "run": what the installed task executes
+
+
+def setup_logging(log_file=None):
+    handlers = [logging.StreamHandler()]
+    if log_file:
+        handlers = [logging.handlers.RotatingFileHandler(log_file, maxBytes=10_000_000, backupCount=5, encoding="utf-8")]
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s", handlers=handlers)
+
+
+def dump_tags(args):
+    """Uploads the tag list of one PLC (reads only) and writes it in the mock_tags format."""
+    from .server import driver_factory
+
+    config = load_config(args.config)
+    with driver_factory(config.plcs[args.plc]) as plc:
+        tags = {name: type_name(info) for name, info in plc.tags.items()}
+    with open(args.out, "w", encoding="utf-8") as file:
+        json.dump(tags, file, indent=2)
+    print(f"wrote {len(tags)} tags to {args.out}")
+
+
+def fetch_tags(url, token, plc):
+    """GET <url>/tags?plc=NAME; returns the "tags" list."""
+    query = f"/tags?plc={urllib.parse.quote(plc)}" if plc else "/tags"
+    request = urllib.request.Request(url.rstrip("/") + query, headers={"Authorization": f"Bearer {token}"})
+    with urllib.request.urlopen(request) as response:
+        return json.load(response)["tags"]
+
+
+def tag_names(tags):
+    """Readable names: each tag, but for an AOI its readable members (Inst.Member) instead of the instance."""
+    names = []
+    for tag in tags:
+        if "aoi_readable" in tag:
+            names += [f"{tag['name']}.{member}" for member in tag["aoi_readable"]]
+        else:
+            names.append(tag["name"])
+    return names
+
+
+def types(args):
+    """Writes a TypeScript union of the tag names served by a running tag server."""
+    plcs = args.plc or [None]
+    names = []
+    for plc in plcs:
+        prefix = f"{plc}/" if len(plcs) > 1 else ""
+        names += [prefix + name for name in tag_names(fetch_tags(args.url, args.token, plc))]
+    names = list(dict.fromkeys(names))
+    lines = "".join(f"\n  | {json.dumps(name)}" for name in names) or " never"
+    with open(args.out, "w", encoding="utf-8") as file:
+        file.write(f"// Generated by ciplink-tagserver types. Do not edit.\nexport type TagName ={lines};\n")
+    print(f"wrote {len(names)} tag names to {args.out}")
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="ciplink-tagserver")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    p = commands.add_parser("run", help="serve tag values over a WebSocket")
+    p.add_argument("--config", default="tagserver.toml")
+    p.add_argument("--mock", action="store_true", help="serve fake values from each PLC's mock_tags file")
+    p.add_argument("--log-file", help="write logs to this file (rotated at 10 MB, 5 kept) instead of the console")
+    p.set_defaults(func=run)
+
+    p = commands.add_parser("service", help="run at Windows startup (install/remove need an administrator terminal)")
+    p.add_argument("action", choices=["install", "remove", "status", "run"])
+    p.add_argument("--config", default="tagserver.toml")
+    p.add_argument("--name", default="ciplink-tagserver", help="Task Scheduler task name")
+    p.add_argument("--log-file", help="default: tagserver.log next to the config")
+    p.set_defaults(func=service)
+
+    p = commands.add_parser("dump-tags", help="write a PLC's tag list as a mock_tags file")
+    p.add_argument("--config", default="tagserver.toml")
+    p.add_argument("--plc", required=True)
+    p.add_argument("--out", required=True)
+    p.set_defaults(func=dump_tags)
+
+    p = commands.add_parser("types", help="write the tag names of a running server as a TypeScript type")
+    p.add_argument("--url", default="http://127.0.0.1:8765")
+    p.add_argument("--token", required=True)
+    p.add_argument("--plc", action="append", help="repeat for several PLCs; names are then qualified as PLC/tag")
+    p.add_argument("--out", required=True)
+    p.set_defaults(func=types)
+
+    args = parser.parse_args(argv)
+    setup_logging(getattr(args, "log_file", None))
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ciplink_tagserver-0.1.0/ciplink_tagserver/config.py

@@ -0,0 +1,76 @@
+"""Reads the TOML config file."""
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class PlcConfig:
+    name: str
+    path: str
+    tag_cache_file: str | None = None
+    mock_tags: str | None = None
+
+
+@dataclass
+class TokenConfig:
+    name: str
+    secret: str
+    write: list[str] = field(default_factory=list)  # fnmatch patterns on qualified names
+
+
+@dataclass
+class Config:
+    host: str = "127.0.0.1"
+    port: int = 8765
+    cycle_ms: int = 250
+    audit_log: str = "audit.log"
+    plcs: dict[str, PlcConfig] = field(default_factory=dict)
+    tokens: dict[str, TokenConfig] = field(default_factory=dict)
+
+    def qualify(self, name: str) -> tuple[str, str]:
+        """Splits ``<plc>/<tag>`` into (plc, tag); an unqualified name means the only PLC, if there is one."""
+        if "/" in name:
+            plc, tag = name.split("/", 1)
+            if plc not in self.plcs:
+                raise ValueError(f"unknown PLC {plc!r}")
+        elif len(self.plcs) == 1:
+            plc, tag = next(iter(self.plcs)), name
+        else:
+            raise ValueError(f"tag {name!r} must be qualified as <plc>/<tag>")
+        if not tag:
+            raise ValueError(f"empty tag name in {name!r}")
+        return plc, tag
+
+
+def load_config(path) -> Config:
+    path = Path(path)
+    with open(path, "rb") as file:
+        return parse_config(tomllib.load(file), path.parent)
+
+
+def parse_config(data: dict, base_dir=".") -> Config:
+    """Builds a Config from the parsed TOML; relative file paths are relative to ``base_dir``."""
+    base = Path(base_dir)
+
+    def resolve(value):
+        return str(base / value) if value else None
+
+    server = data.get("server", {})
+    config = Config(
+        host=server.get("host", "127.0.0.1"),
+        port=server.get("port", 8765),
+        cycle_ms=server.get("cycle_ms", 250),
+        audit_log=resolve(server.get("audit_log", "audit.log")),
+    )
+    for name, plc in data.get("plc", {}).items():
+        config.plcs[name] = PlcConfig(
+            name=name,
+            path=plc["path"],
+            tag_cache_file=resolve(plc.get("tag_cache_file")),
+            mock_tags=resolve(plc.get("mock_tags")),
+        )
+    for name, token in data.get("token", {}).items():
+        config.tokens[name] = TokenConfig(name=name, secret=token["secret"], write=list(token.get("write", [])))
+    return config

ciplink_tagserver-0.1.0/ciplink_tagserver/mock.py

@@ -0,0 +1,76 @@
+"""A fake driver for --mock: serves the tags listed in the PLC's ``mock_tags`` JSON file."""
+
+import json
+import random
+
+from ciplink import Tag
+
+INTS = {"SINT", "INT", "DINT", "LINT", "USINT", "UINT", "UDINT", "ULINT"}
+FLOATS = {"REAL", "LREAL"}
+
+
+def initial(data_type):
+    if data_type == "BOOL":
+        return False
+    if data_type in INTS:
+        return 0
+    if data_type in FLOATS:
+        return 0.0
+    if data_type == "STRING":
+        return ""
+    return None
+
+
+class MockDriver:
+    """Same calls as LogixDriver as far as the worker uses them; numbers random-walk, BOOLs toggle."""
+
+    def __init__(self, cfg):
+        types = {}
+        if cfg.mock_tags:
+            with open(cfg.mock_tags, encoding="utf-8") as file:
+                types = json.load(file)
+        self.types = types
+        self.values = {name: initial(data_type) for name, data_type in types.items()}
+        self.data_types = {}
+        self._tag_table_version = 1
+        self._random = random.Random()
+
+    @property
+    def tags(self):
+        return {name: {"tag_name": name, "tag_type": "atomic", "data_type": t, "data_type_name": t}
+                for name, t in self.types.items()}
+
+    def open(self):
+        return True
+
+    def close(self):
+        pass
+
+    def _step(self, name):
+        data_type, value = self.types[name], self.values[name]
+        if data_type == "BOOL":
+            if self._random.random() < 0.1:
+                value = not value
+        elif data_type in INTS:
+            value += self._random.choice((-1, 0, 1))
+        elif data_type in FLOATS:
+            value = round(value + self._random.uniform(-1, 1), 3)
+        self.values[name] = value
+        return value
+
+    def read(self, *tags):
+        results = []
+        for name in tags:
+            if name not in self.types:
+                results.append(Tag(name, None, None, f"Tag doesn't exist - {name}"))
+            elif self.values[name] is None:
+                results.append(Tag(name, None, self.types[name], f"mock does not simulate {self.types[name]}"))
+            else:
+                results.append(Tag(name, self._step(name), self.types[name], None))
+        return results[0] if len(results) == 1 else results
+
+    def write(self, name, value):
+        if name not in self.types:
+            return Tag(name, None, None, f"Tag doesn't exist - {name}")
+        self.values[name] = value
+        return Tag(name, value, self.types[name], None)