opengearwire 0.3.0__tar.gz

opengearwire-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Romanenko
+
+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.

opengearwire-0.3.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: opengearwire
+Version: 0.3.0
+Summary: Python library for openGear frames (Ross OGX) over the openGear Protocol, TCP 5253: frame health, every card's parameters, pushed changes
+Author: Lucas Romanenko
+License-Expression: MIT
+Project-URL: Repository, https://github.com/lucas-romanenko/opengearwire
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# opengearwire
+
+Python library for **openGear frames** (Ross OGX and the partner cards in
+them) over the openGear Protocol, OGP, on TCP 5253: the frame's health
+and every card's parameters, read the way Ross DashBoard reads them.
+
+[![CI](https://github.com/lucas-romanenko/opengearwire/actions/workflows/ci.yml/badge.svg)](https://github.com/lucas-romanenko/opengearwire/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
+
+Everything here was decoded from a packet capture of DashBoard 10 reading
+a real frame, checked against Ross's public OGP application note, and is
+tested by replaying that capture (sanitized) against the client. The
+wire format is in [`opengearwire/docs/PROTOCOL.md`](opengearwire/docs/PROTOCOL.md).
+
+## Status
+
+- **0.3.0, read-only.** Verified against one capture: an OGX frame with
+  an MFC-8322-S controller and ten DRA-8804 reclocking DAs. 3,940 of its
+  3,941 messages decode completely; the client rebuilds the same
+  parameter tree DashBoard got.
+- **No writes** except the connection hello DashBoard itself sends
+  (it sets nothing). Setting changes come once one is captured.
+- Run against the live frame: its snapshot has every parameter the
+  capture has.
+
+## One client at a time
+
+An **MFC-8322-S controller takes one control connection at a time**.
+While DashBoard is connected, the frame hangs up on this library, and
+while the library is connected, DashBoard is locked out. Confirmed both
+ways on a live frame; Ross's MFC manual (Table 1, Feature Comparison)
+lists more than one concurrent TCP control connection for the MFC-OG3-N
+only.
+
+So: **connect, read, disconnect quickly.** Keep a `Frame` open only
+while someone is looking at what it reads, never in the background, and
+keep `watch` short; close DashBoard before running the CLI. When the frame hangs up before answering anything after the hello,
+the library raises `FrameBusy` (a `FrameError`) saying so; a hang-up
+later in a read is the plain `FrameError`.
+
+## Install
+
+```sh
+pip install opengearwire
+```
+
+Python 3.10 or newer. Standard library only.
+
+## Usage
+
+```python
+from opengearwire import Frame
+
+with Frame("192.0.2.10") as f:
+    f.discover()  # [0, 2, 4, ...]: slots that answered (0 = controller)
+    f.identify()  # {0: "MFC-8322-S", 2: "DRA-8804", ...}
+    f.describe()  # every parameter, value and menu of every slot
+    card = f.device(4)
+    print(card.find("Enable Equalizer").display)  # ['Enabled', 'Enabled']  (channel A, B)
+    print(card.find(0x0704).display)  # 'Locked - 1.5G'
+    for change in f.watch(10):  # what the frame pushed in 10 s
+        print(change.slot, change.name, change.old, "->", change.new)
+    snap = f.snapshot()  # plain dicts: frame health + every card, json.dumps-ready
+```
+
+- `Frame(host, port=5253, timeout=5.0, retry_after=2.5, retries=3)`.
+  `timeout` is **no-progress**: seconds without a byte from the frame
+  (which reports its status every second), not a total. An unanswered
+  request is resent after `retry_after` seconds, as DashBoard does;
+  after `retries` the rest goes on, and it is asked again in one final
+  round at the end. What still has no answer is listed in
+  `Frame.unanswered` (slot, request, OID and name, or menu / object) and
+  in the snapshot's `unanswered`.
+- `discover()` listens: every card reports on its own within about a
+  second, and it stops as soon as the controller's Active Cards count is
+  reached. It assumes no layout: any of the 20 slots, single- or
+  double-width cards.
+- `describe(slots=None, menus=True)`, `describe_oids(slot, oids)`,
+  `read(slot, *oids_or_names)` (fresh values), `watch(seconds)`,
+  `snapshot()`.
+- `Parameter.value` is the decoded value; `.display` is what DashBoard
+  shows (choice labels, active alarm names, IP addresses); `.severity`
+  is 0/1/2 for alarm tables. In the snapshot each parameter has
+  `value` and, where they differ, `display` beside it (Channel A Status:
+  `"value": 16, "display": ["No input"]`).
+- `Tree.apply(message)` builds the same tree from any message source (a
+  capture, a test), with no network.
+
+Nothing runs on a timer: each call does what it says on one connection
+and returns. One request in flight per device, all devices in parallel.
+
+## Command line
+
+```sh
+opengearwire 192.0.2.10 slots            # occupied slots and their products
+opengearwire 192.0.2.10 params 4         # every parameter of slot 4
+opengearwire 192.0.2.10 read 4 0x0b04    # fresh value(s) by OID or exact name
+opengearwire 192.0.2.10 watch 10         # pushed changes for 10 s
+opengearwire 192.0.2.10 snapshot         # the whole frame as JSON
+```
+
+`--json` for machine output, `--timeout` for the silence limit.
+Requests the frame never answered are listed on stderr (and in the
+snapshot's `unanswered`).
+`python -m opengearwire` works too.
+
+## Testing without a frame
+
+`opengearwire.testing` is a fake frame for your own tests and for
+developing an app: it listens on 127.0.0.1 and answers from the bundled
+capture (sanitized), including the frame's one-client-at-a-time
+behaviour.
+
+```python
+from opengearwire import Frame, FrameBusy
+from opengearwire.testing import FakeFrame
+
+fake = FakeFrame()  # a free port on 127.0.0.1: fake.port
+with Frame("127.0.0.1", fake.port) as f:
+    f.discover()
+    fake.report(18, 0x0705, b"12 (1694A) / 8 (1855A)\x00")  # a card pushes a change
+    print(f.watch(0.5))
+fake.busy = True  # "DashBoard is connected": every client is turned away (FrameBusy)
+fake.close()
+```
+
+```sh
+python -m opengearwire.testing --port 5253   # a fake frame to point an app at
+```
+
+## Development
+
+```sh
+pip install -e ".[dev]"
+python -m pytest
+ruff check . && ruff format --check .
+```
+
+The suite needs no hardware: it runs `opengearwire.testing`'s fake
+frame on 127.0.0.1, answering from the captured session. To make a
+fixture from a new capture (it replaces serials, MAC, names, passwords and
+IP addresses and refuses to write if any original survives):
+
+```sh
+python tools/fixture_from_capture.py CAPTURE.pcapng opengearwire/fixtures/NAME.jsonl
+```
+
+Raw captures never go into git (`.gitignore` blocks them).
+
+A release is a tag `v<version>` matching `project.version`: the tag push
+publishes it to PyPI (`.github/workflows/publish.yml`, trusted
+publishing, no token in the repository).
+
+Not affiliated with or endorsed by Ross Video Ltd. openGear, DashBoard
+and OGX are trademarks of Ross Video.

opengearwire-0.3.0/README.md

@@ -0,0 +1,154 @@
+# opengearwire
+
+Python library for **openGear frames** (Ross OGX and the partner cards in
+them) over the openGear Protocol, OGP, on TCP 5253: the frame's health
+and every card's parameters, read the way Ross DashBoard reads them.
+
+[![CI](https://github.com/lucas-romanenko/opengearwire/actions/workflows/ci.yml/badge.svg)](https://github.com/lucas-romanenko/opengearwire/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
+
+Everything here was decoded from a packet capture of DashBoard 10 reading
+a real frame, checked against Ross's public OGP application note, and is
+tested by replaying that capture (sanitized) against the client. The
+wire format is in [`opengearwire/docs/PROTOCOL.md`](opengearwire/docs/PROTOCOL.md).
+
+## Status
+
+- **0.3.0, read-only.** Verified against one capture: an OGX frame with
+  an MFC-8322-S controller and ten DRA-8804 reclocking DAs. 3,940 of its
+  3,941 messages decode completely; the client rebuilds the same
+  parameter tree DashBoard got.
+- **No writes** except the connection hello DashBoard itself sends
+  (it sets nothing). Setting changes come once one is captured.
+- Run against the live frame: its snapshot has every parameter the
+  capture has.
+
+## One client at a time
+
+An **MFC-8322-S controller takes one control connection at a time**.
+While DashBoard is connected, the frame hangs up on this library, and
+while the library is connected, DashBoard is locked out. Confirmed both
+ways on a live frame; Ross's MFC manual (Table 1, Feature Comparison)
+lists more than one concurrent TCP control connection for the MFC-OG3-N
+only.
+
+So: **connect, read, disconnect quickly.** Keep a `Frame` open only
+while someone is looking at what it reads, never in the background, and
+keep `watch` short; close DashBoard before running the CLI. When the frame hangs up before answering anything after the hello,
+the library raises `FrameBusy` (a `FrameError`) saying so; a hang-up
+later in a read is the plain `FrameError`.
+
+## Install
+
+```sh
+pip install opengearwire
+```
+
+Python 3.10 or newer. Standard library only.
+
+## Usage
+
+```python
+from opengearwire import Frame
+
+with Frame("192.0.2.10") as f:
+    f.discover()  # [0, 2, 4, ...]: slots that answered (0 = controller)
+    f.identify()  # {0: "MFC-8322-S", 2: "DRA-8804", ...}
+    f.describe()  # every parameter, value and menu of every slot
+    card = f.device(4)
+    print(card.find("Enable Equalizer").display)  # ['Enabled', 'Enabled']  (channel A, B)
+    print(card.find(0x0704).display)  # 'Locked - 1.5G'
+    for change in f.watch(10):  # what the frame pushed in 10 s
+        print(change.slot, change.name, change.old, "->", change.new)
+    snap = f.snapshot()  # plain dicts: frame health + every card, json.dumps-ready
+```
+
+- `Frame(host, port=5253, timeout=5.0, retry_after=2.5, retries=3)`.
+  `timeout` is **no-progress**: seconds without a byte from the frame
+  (which reports its status every second), not a total. An unanswered
+  request is resent after `retry_after` seconds, as DashBoard does;
+  after `retries` the rest goes on, and it is asked again in one final
+  round at the end. What still has no answer is listed in
+  `Frame.unanswered` (slot, request, OID and name, or menu / object) and
+  in the snapshot's `unanswered`.
+- `discover()` listens: every card reports on its own within about a
+  second, and it stops as soon as the controller's Active Cards count is
+  reached. It assumes no layout: any of the 20 slots, single- or
+  double-width cards.
+- `describe(slots=None, menus=True)`, `describe_oids(slot, oids)`,
+  `read(slot, *oids_or_names)` (fresh values), `watch(seconds)`,
+  `snapshot()`.
+- `Parameter.value` is the decoded value; `.display` is what DashBoard
+  shows (choice labels, active alarm names, IP addresses); `.severity`
+  is 0/1/2 for alarm tables. In the snapshot each parameter has
+  `value` and, where they differ, `display` beside it (Channel A Status:
+  `"value": 16, "display": ["No input"]`).
+- `Tree.apply(message)` builds the same tree from any message source (a
+  capture, a test), with no network.
+
+Nothing runs on a timer: each call does what it says on one connection
+and returns. One request in flight per device, all devices in parallel.
+
+## Command line
+
+```sh
+opengearwire 192.0.2.10 slots            # occupied slots and their products
+opengearwire 192.0.2.10 params 4         # every parameter of slot 4
+opengearwire 192.0.2.10 read 4 0x0b04    # fresh value(s) by OID or exact name
+opengearwire 192.0.2.10 watch 10         # pushed changes for 10 s
+opengearwire 192.0.2.10 snapshot         # the whole frame as JSON
+```
+
+`--json` for machine output, `--timeout` for the silence limit.
+Requests the frame never answered are listed on stderr (and in the
+snapshot's `unanswered`).
+`python -m opengearwire` works too.
+
+## Testing without a frame
+
+`opengearwire.testing` is a fake frame for your own tests and for
+developing an app: it listens on 127.0.0.1 and answers from the bundled
+capture (sanitized), including the frame's one-client-at-a-time
+behaviour.
+
+```python
+from opengearwire import Frame, FrameBusy
+from opengearwire.testing import FakeFrame
+
+fake = FakeFrame()  # a free port on 127.0.0.1: fake.port
+with Frame("127.0.0.1", fake.port) as f:
+    f.discover()
+    fake.report(18, 0x0705, b"12 (1694A) / 8 (1855A)\x00")  # a card pushes a change
+    print(f.watch(0.5))
+fake.busy = True  # "DashBoard is connected": every client is turned away (FrameBusy)
+fake.close()
+```
+
+```sh
+python -m opengearwire.testing --port 5253   # a fake frame to point an app at
+```
+
+## Development
+
+```sh
+pip install -e ".[dev]"
+python -m pytest
+ruff check . && ruff format --check .
+```
+
+The suite needs no hardware: it runs `opengearwire.testing`'s fake
+frame on 127.0.0.1, answering from the captured session. To make a
+fixture from a new capture (it replaces serials, MAC, names, passwords and
+IP addresses and refuses to write if any original survives):
+
+```sh
+python tools/fixture_from_capture.py CAPTURE.pcapng opengearwire/fixtures/NAME.jsonl
+```
+
+Raw captures never go into git (`.gitignore` blocks them).
+
+A release is a tag `v<version>` matching `project.version`: the tag push
+publishes it to PyPI (`.github/workflows/publish.yml`, trusted
+publishing, no token in the repository).
+
+Not affiliated with or endorsed by Ross Video Ltd. openGear, DashBoard
+and OGX are trademarks of Ross Video.

opengearwire-0.3.0/opengearwire/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+"""opengearwire: read openGear frames (Ross OGX and partners) over OGP.
+
+Read-only for now. ``Frame`` connects and reads; ``Tree`` holds what was
+read; ``snapshot`` turns it into plain data. ``docs/PROTOCOL.md`` is the
+wire format.
+"""
+
+__version__ = "0.3.0"
+
+from ._protocol import ProtocolError, RemoteError
+from .client import Frame, FrameBusy, FrameError
+from .model import Change, Device, Parameter, Tree, address_of, slot_of
+from .snapshot import snapshot
+
+__all__ = [
+    "Change",
+    "Device",
+    "Frame",
+    "FrameBusy",
+    "FrameError",
+    "Parameter",
+    "ProtocolError",
+    "RemoteError",
+    "Tree",
+    "address_of",
+    "slot_of",
+    "snapshot",
+]

opengearwire-0.3.0/opengearwire/__main__.py

@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: MIT
+"""opengearwire HOST COMMAND: read a frame from the command line.
+
+    opengearwire 192.0.2.10 slots            occupied slots and their products
+    opengearwire 192.0.2.10 params 4         every parameter of slot 4
+    opengearwire 192.0.2.10 read 4 0x0b04    fresh value(s) by OID or name
+    opengearwire 192.0.2.10 watch 10         pushed changes for 10 s
+    opengearwire 192.0.2.10 snapshot         the whole frame as JSON
+
+Slot 0 is the frame controller. Every command opens one connection,
+does what it says and closes; nothing is ever written to the frame.
+The frame takes one client at a time: close DashBoard first.
+"""
+
+import argparse
+import json
+import sys
+
+from . import _protocol as P
+from .client import PORT, Frame, FrameError
+
+
+def _fmt(v) -> str:
+    if isinstance(v, list):
+        return ", ".join(str(x) for x in v)
+    return str(v)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="opengearwire", description=__doc__.split("\n")[0])
+    ap.add_argument("host")
+    ap.add_argument("--port", type=int, default=PORT)
+    ap.add_argument(
+        "--timeout",
+        type=float,
+        default=5.0,
+        help="seconds of silence from the frame before giving up (default 5)",
+    )
+    ap.add_argument("--json", action="store_true", help="JSON output")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("slots")
+    p = sub.add_parser("params")
+    p.add_argument("slot", type=int)
+    p = sub.add_parser("read")
+    p.add_argument("slot", type=int)
+    p.add_argument("keys", nargs="+", help="OIDs (0x0b04) or exact names")
+    p = sub.add_parser("watch")
+    p.add_argument("seconds", type=float)
+    sub.add_parser("snapshot")
+    a = ap.parse_args(argv)
+
+    try:
+        with Frame(a.host, a.port, timeout=a.timeout) as f:
+            return _run(f, a)
+    except (OSError, FrameError, P.ProtocolError) as e:
+        print(f"opengearwire: {a.host}: {e}", file=sys.stderr)
+        return 1
+
+
+def _run(f: Frame, a) -> int:
+    out = sys.stdout
+    if a.cmd == "slots":
+        f.discover()
+        rows = list(f.identify().items())
+        if a.json:
+            json.dump([{"slot": s, "product": p} for s, p in rows], out, indent=2)
+            out.write("\n")
+        else:
+            for s, p in rows:
+                out.write(f"{s:>3}  {p}\n")
+    elif a.cmd == "params":
+        f.describe([a.slot])
+        dev = f.device(a.slot)
+        if a.json:
+            json.dump(dev.to_dict(), out, indent=2)
+            out.write("\n")
+        else:
+            for o in dev.oids:
+                p = dev.params[o]
+                d = p.descriptor
+                rw = "rw" if d and d.writable else "ro"
+                kind = d.type_name if d else "?"
+                out.write(f"0x{o:04x} {rw} {kind:9} {p.name!r:32} {_fmt(p.display)}\n")
+    elif a.cmd == "read":
+        keys = [int(k, 16) if k.lower().startswith("0x") else k for k in a.keys]
+        if all(isinstance(k, int) for k in keys):
+            f.describe_oids(a.slot, keys)  # descriptors decode the values
+        else:
+            f.describe([a.slot], menus=False)  # names need the whole list
+        vals = f.read(a.slot, *keys)
+        dev = f.device(a.slot)
+        rows = [(o, dev.params[o]) for o in vals]
+        if a.json:
+            json.dump([p.to_dict() for _, p in rows], out, indent=2)
+            out.write("\n")
+        else:
+            for o, p in rows:
+                out.write(f"0x{o:04x} {p.name!r}: {_fmt(p.display)}\n")
+    elif a.cmd == "watch":
+        f.discover()
+        for ch in f.watch(a.seconds):
+            if a.json:
+                out.write(
+                    json.dumps(
+                        {
+                            "slot": ch.slot,
+                            "oid": f"0x{ch.oid:04x}",
+                            "name": ch.name,
+                            "old": ch.old,
+                            "new": ch.new,
+                        }
+                    )
+                    + "\n"
+                )
+            else:
+                out.write(f"slot {ch.slot} 0x{ch.oid:04x} {ch.name!r}: {ch.old!r} -> {ch.new!r}\n")
+    elif a.cmd == "snapshot":
+        f.discover()
+        f.describe()
+        json.dump(f.snapshot(), out, indent=2)
+        out.write("\n")
+    if f.unanswered:
+        print(f"opengearwire: {len(f.unanswered)} request(s) never answered", file=sys.stderr)
+        for u in f.unanswered:
+            what = u.get("oid") or ", ".join(
+                f"{k} {u[k]}" for k in ("menuset", "menu", "object", "offset") if k in u
+            )
+            name = f" {u['name']!r}" if "name" in u else ""
+            print(f"  slot {u['slot']} {u['request']} {what}{name}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())