ultimattewire 0.1.0.dev1__tar.gz → 0.2.0.dev0__tar.gz

{ultimattewire-0.1.0.dev1/ultimattewire.egg-info → ultimattewire-0.2.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultimattewire
-Version: 0.1.0.dev1
+Version: 0.2.0.dev0
 Summary: Blackmagic Ultimatte 12 archive and restore over its native TCP protocol (Smart Remote 4 compatible zips)
 Author: Lucas Romanenko
 License: MIT
@@ -24,10 +24,12 @@ Dynamic: license-file
 
 # ultimattewire
 
-Python library that archives and restores the configuration of a Blackmagic
-**Ultimatte 12** or **Ultimatte 12 4K** keyer over its native TCP protocol,
-producing and consuming the same zip archives the vendor's Smart Remote 4
-writes with **Archive All** and reads with **Restore**.
+Python library for the Blackmagic **Ultimatte 12** and **Ultimatte 12 4K**
+keyers over their native TCP protocol. It archives and restores unit
+configuration — producing and consuming the same zip archives the vendor's
+Smart Remote 4 writes with **Archive All** and reads with **Restore** — and
+reads and sets the unit's **network interface** (address, netmask, gateway,
+DNS, static or DHCP), which is what the vendor's Ultimatte Setup does.
 
 [![CI](https://github.com/lucas-romanenko/bmdwire/actions/workflows/ci.yml/badge.svg)](https://github.com/lucas-romanenko/bmdwire/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/ultimattewire.svg)](https://pypi.org/project/ultimattewire/) [![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) [![Latest tag](https://img.shields.io/github/v/tag/lucas-romanenko/bmdwire?filter=ultimattewire-v*&label=release)](https://github.com/lucas-romanenko/bmdwire/tags)
 
@@ -40,7 +42,7 @@ established and what is still a guess.
 
 ## Status
 
-- **Pre-release** (`0.1.0.dev1`), extracted from a broadcast control
+- **Pre-release** (`0.2.0.dev0`), extracted from a broadcast control
   application where operators archive and restore keyer configurations from a
   web page.
 - Verified against an Ultimatte 12 4K (the unit the captures came from). The
@@ -65,6 +67,7 @@ Python 3.10 or newer. No other dependencies.
 
 ## Features
 
+- `read_network(host)` / `set_network(host, address=…, netmask=…, gateway=…, dns=…, dynamic=…)`: the unit's network interface — what Ultimatte Setup configures. `set_network` verifies by reading back the *settled* interface, not by trusting the unit's acknowledgement.
 - `archive_unit_to_bytes(host)`: pull every saved preset slot plus the `GPISettings` and `SavedSettings` resources into an in-memory zip in Smart Remote's exact layout, with a human-readable annotated state dump riding along.
 - `restore_unit_from_bytes(host, zip_bytes)`: push such a zip back, in the order the vendor app uses, aborting at the first rejected write.
 - Reads the unit's text prelude on TCP 9998 (label, firmware release, live control values, the preset FILE LIST) and does binary slot/resource reads and writes on TCP 9996.
@@ -96,6 +99,19 @@ A zip produced by this library can be opened with Smart Remote 4's Restore
 unchanged, and a Smart Remote "Archive All" zip can be passed straight to
 `restore_unit_from_bytes`.
 
+```python
+from ultimattewire import read_network, set_network
+
+iface = read_network("192.0.2.21")
+print(iface.static_address, iface.static_netmask, iface.static_gateway, iface.mac)
+
+# Widen the mask, keeping the address and gateway. Returns the settled
+# interface as the unit reports it — not what was asked for.
+iface = set_network("192.0.2.21", address=iface.static_address,
+                    netmask="255.255.248.0", gateway=iface.static_gateway)
+assert iface.netmask == "255.255.248.0"
+```
+
 ## Protocol notes
 
 This is the reverse-engineered part and the most useful thing to read before
@@ -144,6 +160,50 @@ already hit and fixed are recorded in `_preamble.py` (a `$` anchor that
 truncated multi-line FILE LISTs, and a `\s*` that let an empty section
 swallow the next one).
 
+### Setting values: the 9998 block protocol
+
+The 9998 channel is not only a prelude. After it, the unit accepts **blocks**:
+an upper-case section header ending in a colon, then `key: value` lines, then
+a **blank line — and the blank line is what submits the block.** Nothing
+happens until it arrives, which is why single-line probes (`IDENTITY?`,
+`help`, `ping`, with either line ending) draw no reply at all and look like
+the unit ignoring the client. That is the one fact the whole feature rests on.
+
+The unit answers `ACK\n\n` followed by the section echoed back, or a bare
+`NAK\n\n` for an unknown section or a value it will not take.
+
+Three properties worth knowing:
+
+- **An empty block is a query.** Header, blank line, no fields: sets nothing
+  and echoes the full section. Read and write are therefore one code path,
+  and reading network state needs no prelude parsing.
+- **The echo after a set carries only the fields that were sent**, not the
+  section. A query echoes all eleven lines of `NETWORK INTERFACE 0`; a set of
+  two fields echoes those two. So the echo proves the unit *accepted* the
+  fields and says nothing about what it now holds — it must not be treated as
+  verification.
+- **`Static Addresses` is `<ip>/<dotted-netmask>` as one field**
+  (`192.168.1.10/255.255.252.0`), not a prefix length and not two fields.
+  Sending the address alone tells the unit to drop the mask, so `set_network`
+  refuses an address without its mask before anything reaches the wire.
+
+Changing an address makes the interface reapply, and for about a second the
+unit answers normally while reporting `Current Addresses: 0.0.0.0/255.255.0.0`
+with `Static Addresses` already holding the new value. Verifying against the
+current fields in that window reads garbage; verifying against the static
+fields declares success before the interface is running the value. So
+`set_network` polls until the unit is live on what it was configured with —
+current present, not `0.0.0.0`, and equal to static — and raises rather than
+reporting a success it cannot stand behind. A set that touches no address
+reapplies nothing and is not made to wait.
+
+`exchange`, `build_block` and `parse_interface` are public, so any other
+section the unit exposes can be driven the same way.
+
+There is deliberately no policy in the library: `set_network` writes what it
+is told. Whether a change is safe belongs to the caller — re-addressing a
+unit over the network can put it out of reach until someone visits it.
+
 ### The 9996 binary channel
 
 Every request opens its own TCP connection; the unit closes it after

{ultimattewire-0.1.0.dev1 → ultimattewire-0.2.0.dev0}/README.md

@@ -1,9 +1,11 @@
 # ultimattewire
 
-Python library that archives and restores the configuration of a Blackmagic
-**Ultimatte 12** or **Ultimatte 12 4K** keyer over its native TCP protocol,
-producing and consuming the same zip archives the vendor's Smart Remote 4
-writes with **Archive All** and reads with **Restore**.
+Python library for the Blackmagic **Ultimatte 12** and **Ultimatte 12 4K**
+keyers over their native TCP protocol. It archives and restores unit
+configuration — producing and consuming the same zip archives the vendor's
+Smart Remote 4 writes with **Archive All** and reads with **Restore** — and
+reads and sets the unit's **network interface** (address, netmask, gateway,
+DNS, static or DHCP), which is what the vendor's Ultimatte Setup does.
 
 [![CI](https://github.com/lucas-romanenko/bmdwire/actions/workflows/ci.yml/badge.svg)](https://github.com/lucas-romanenko/bmdwire/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/ultimattewire.svg)](https://pypi.org/project/ultimattewire/) [![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) [![Latest tag](https://img.shields.io/github/v/tag/lucas-romanenko/bmdwire?filter=ultimattewire-v*&label=release)](https://github.com/lucas-romanenko/bmdwire/tags)
 
@@ -16,7 +18,7 @@ established and what is still a guess.
 
 ## Status
 
-- **Pre-release** (`0.1.0.dev1`), extracted from a broadcast control
+- **Pre-release** (`0.2.0.dev0`), extracted from a broadcast control
   application where operators archive and restore keyer configurations from a
   web page.
 - Verified against an Ultimatte 12 4K (the unit the captures came from). The
@@ -41,6 +43,7 @@ Python 3.10 or newer. No other dependencies.
 
 ## Features
 
+- `read_network(host)` / `set_network(host, address=…, netmask=…, gateway=…, dns=…, dynamic=…)`: the unit's network interface — what Ultimatte Setup configures. `set_network` verifies by reading back the *settled* interface, not by trusting the unit's acknowledgement.
 - `archive_unit_to_bytes(host)`: pull every saved preset slot plus the `GPISettings` and `SavedSettings` resources into an in-memory zip in Smart Remote's exact layout, with a human-readable annotated state dump riding along.
 - `restore_unit_from_bytes(host, zip_bytes)`: push such a zip back, in the order the vendor app uses, aborting at the first rejected write.
 - Reads the unit's text prelude on TCP 9998 (label, firmware release, live control values, the preset FILE LIST) and does binary slot/resource reads and writes on TCP 9996.
@@ -72,6 +75,19 @@ A zip produced by this library can be opened with Smart Remote 4's Restore
 unchanged, and a Smart Remote "Archive All" zip can be passed straight to
 `restore_unit_from_bytes`.
 
+```python
+from ultimattewire import read_network, set_network
+
+iface = read_network("192.0.2.21")
+print(iface.static_address, iface.static_netmask, iface.static_gateway, iface.mac)
+
+# Widen the mask, keeping the address and gateway. Returns the settled
+# interface as the unit reports it — not what was asked for.
+iface = set_network("192.0.2.21", address=iface.static_address,
+                    netmask="255.255.248.0", gateway=iface.static_gateway)
+assert iface.netmask == "255.255.248.0"
+```
+
 ## Protocol notes
 
 This is the reverse-engineered part and the most useful thing to read before
@@ -120,6 +136,50 @@ already hit and fixed are recorded in `_preamble.py` (a `$` anchor that
 truncated multi-line FILE LISTs, and a `\s*` that let an empty section
 swallow the next one).
 
+### Setting values: the 9998 block protocol
+
+The 9998 channel is not only a prelude. After it, the unit accepts **blocks**:
+an upper-case section header ending in a colon, then `key: value` lines, then
+a **blank line — and the blank line is what submits the block.** Nothing
+happens until it arrives, which is why single-line probes (`IDENTITY?`,
+`help`, `ping`, with either line ending) draw no reply at all and look like
+the unit ignoring the client. That is the one fact the whole feature rests on.
+
+The unit answers `ACK\n\n` followed by the section echoed back, or a bare
+`NAK\n\n` for an unknown section or a value it will not take.
+
+Three properties worth knowing:
+
+- **An empty block is a query.** Header, blank line, no fields: sets nothing
+  and echoes the full section. Read and write are therefore one code path,
+  and reading network state needs no prelude parsing.
+- **The echo after a set carries only the fields that were sent**, not the
+  section. A query echoes all eleven lines of `NETWORK INTERFACE 0`; a set of
+  two fields echoes those two. So the echo proves the unit *accepted* the
+  fields and says nothing about what it now holds — it must not be treated as
+  verification.
+- **`Static Addresses` is `<ip>/<dotted-netmask>` as one field**
+  (`192.168.1.10/255.255.252.0`), not a prefix length and not two fields.
+  Sending the address alone tells the unit to drop the mask, so `set_network`
+  refuses an address without its mask before anything reaches the wire.
+
+Changing an address makes the interface reapply, and for about a second the
+unit answers normally while reporting `Current Addresses: 0.0.0.0/255.255.0.0`
+with `Static Addresses` already holding the new value. Verifying against the
+current fields in that window reads garbage; verifying against the static
+fields declares success before the interface is running the value. So
+`set_network` polls until the unit is live on what it was configured with —
+current present, not `0.0.0.0`, and equal to static — and raises rather than
+reporting a success it cannot stand behind. A set that touches no address
+reapplies nothing and is not made to wait.
+
+`exchange`, `build_block` and `parse_interface` are public, so any other
+section the unit exposes can be driven the same way.
+
+There is deliberately no policy in the library: `set_network` writes what it
+is told. Whether a change is safe belongs to the caller — re-addressing a
+unit over the network can put it out of reach until someone visits it.
+
 ### The 9996 binary channel
 
 Every request opens its own TCP connection; the unit closes it after

{ultimattewire-0.1.0.dev1 → ultimattewire-0.2.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ultimattewire"
-version = "0.1.0.dev1"
+version = "0.2.0.dev0"
 description = "Blackmagic Ultimatte 12 archive and restore over its native TCP protocol (Smart Remote 4 compatible zips)"
 readme = "README.md"
 license = { text = "MIT" }

{ultimattewire-0.1.0.dev1 → ultimattewire-0.2.0.dev0}/ultimattewire/__init__.py

@@ -9,9 +9,15 @@ Remote-compatible Archive/Restore feature (the first public
 implementation of it outside BMD's own tools).
 """
 
+from ultimattewire.network import (NetworkInterface, UltimatteNetworkError,
+                                   read_network, set_network)
 from ultimattewire.profile import archive_unit_to_bytes, restore_unit_from_bytes
 
 __all__ = [
     "archive_unit_to_bytes",
     "restore_unit_from_bytes",
+    "read_network",
+    "set_network",
+    "NetworkInterface",
+    "UltimatteNetworkError",
 ]

ultimattewire-0.2.0.dev0/ultimattewire/network.py

@@ -0,0 +1,283 @@
+# SPDX-License-Identifier: MIT
+"""
+Ultimatte 9998 text channel: read and set the unit's network interface.
+
+This is the Ultimatte half of what ATEM Setup does over its REST API —
+address, netmask, gateway, DNS and static-vs-DHCP — for units that are
+reachable on the network but not in front of you. Reverse-engineered from
+an Ultimatte 12 4K (protocol version 2.1, software 2.1) in 2026-09.
+
+**The block protocol.** After the prelude, the 9998 channel takes blocks:
+a CAPS section header ending in a colon, then ``key: value`` lines, then a
+BLANK LINE which is what actually submits the block. Nothing happens until
+that blank line arrives — a lone command line just sits in the unit's
+buffer, which is why single-line probes look like the unit is ignoring you.
+
+The unit answers::
+
+    ACK\\n\\n<the section, echoed back with its CURRENT values>
+    NAK\\n\\n                      (unknown section, or a value it won't take)
+
+so a write is self-verifying: the echo is the unit telling you what it now
+holds, and callers should believe the echo rather than the ACK.
+
+An EMPTY block — header, blank line, no fields — sets nothing and returns
+the same echo, so the read path and the write path are one code path.
+
+**Addresses are one combined field.** ``Static Addresses`` carries
+``<ip>/<dotted-netmask>`` (``192.168.1.10/255.255.252.0``) — not a prefix
+length, and not two fields. Sending the address without the mask, or with
+a ``/21``-style suffix, is rejected.
+
+**No policy here.** ``set_network`` writes what it is told; deciding whether
+a change is safe belongs to the caller. Re-addressing a unit over the
+network can put it out of reach until someone visits it with a monitor.
+"""
+
+import re
+import socket
+import time
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from ultimattewire._protocol import (CONNECT_TIMEOUT, CONTROL_PORT,
+                                     _connect_with_retry)
+
+ACK = "ACK"
+NAK = "NAK"
+PRELUDE_END = b"END PRELUDE:"
+REPLY_QUIET_TIMEOUT = 2.0
+PRELUDE_QUIET_TIMEOUT = 2.0
+READBACK_TIMEOUT = 15.0      # an interface that reapplies is briefly unreachable
+READBACK_POLL = 0.5
+UNCONFIGURED = "0.0.0.0"     # what Current Addresses reads mid-reapply
+
+
+class UltimatteNetworkError(Exception):
+    """The unit refused a block (NAK), or never answered one."""
+
+
+@dataclass
+class NetworkInterface:
+    """One ``NETWORK INTERFACE n`` section, as the unit reports it.
+
+    ``address`` / ``netmask`` are the CURRENT ones (what the unit is using);
+    ``static_address`` / ``static_netmask`` are the CONFIGURED ones. They
+    differ while a unit is on DHCP, or between setting a static address and
+    the interface reapplying.
+    """
+    index: int = 0
+    name: str = ""
+    mac: str = ""
+    priority: Optional[int] = None
+    dynamic: Optional[bool] = None
+    address: str = ""
+    netmask: str = ""
+    gateway: str = ""
+    dns: List[str] = field(default_factory=list)
+    static_address: str = ""
+    static_netmask: str = ""
+    static_gateway: str = ""
+    static_dns: List[str] = field(default_factory=list)
+    raw: str = ""
+
+
+def section_name(index=0):
+    return f"NETWORK INTERFACE {int(index)}"
+
+
+def _split_address(value):
+    """``'192.168.1.10/255.255.252.0'`` -> ``('192.168.1.10', '255.255.252.0')``.
+
+    The unit may list more than one address; the first is the one that
+    matters to callers. An address with no mask yields an empty mask rather
+    than raising — reading must never fail on an odd unit.
+    """
+    first = (value or "").replace(",", " ").split()
+    if not first:
+        return "", ""
+    head = first[0]
+    if "/" in head:
+        ip, _, mask = head.partition("/")
+        return ip.strip(), mask.strip()
+    return head.strip(), ""
+
+
+def _split_list(value):
+    return [p for p in (value or "").replace(",", " ").split() if p]
+
+
+def parse_interface(text, index=0):
+    """Parse an echoed ``NETWORK INTERFACE n`` section into a dataclass."""
+    def get(key):
+        m = re.search(rf"^{re.escape(key)}:[ \t]*(.*)$", text, re.MULTILINE)
+        return m.group(1).strip() if m else ""
+
+    iface = NetworkInterface(index=index, raw=text)
+    iface.name = get("Name")
+    iface.mac = get("MAC Address")
+    priority = get("Priority")
+    iface.priority = int(priority) if priority.isdigit() else None
+    dynamic = get("Dynamic IP").lower()
+    iface.dynamic = True if dynamic == "true" else False if dynamic == "false" else None
+    iface.address, iface.netmask = _split_address(get("Current Addresses"))
+    iface.gateway = get("Current Gateway")
+    iface.dns = _split_list(get("Current DNS Servers"))
+    iface.static_address, iface.static_netmask = _split_address(get("Static Addresses"))
+    iface.static_gateway = get("Static Gateway")
+    iface.static_dns = _split_list(get("Static DNS Servers"))
+    return iface
+
+
+def build_block(index=0, **fields):
+    """Render a submittable block. Field ORDER is preserved; an empty
+    ``fields`` gives the query form (header + the submitting blank line)."""
+    lines = [f"{section_name(index)}:"]
+    lines += [f"{key}: {value}" for key, value in fields.items()]
+    return "\n".join(lines) + "\n\n"
+
+
+def _drain_prelude(sock, quiet_timeout):
+    sock.settimeout(quiet_timeout)
+    buf = bytearray()
+    while True:
+        try:
+            chunk = sock.recv(65536)
+        except socket.timeout:
+            break
+        if not chunk:
+            break
+        buf.extend(chunk)
+        if PRELUDE_END in buf:
+            break
+    return bytes(buf)
+
+
+def _read_reply(sock, quiet_timeout):
+    sock.settimeout(quiet_timeout)
+    buf = bytearray()
+    while True:
+        try:
+            chunk = sock.recv(65536)
+        except socket.timeout:
+            break
+        if not chunk:
+            break
+        buf.extend(chunk)
+        text = buf.decode("utf-8", errors="replace")
+        # NAK is the whole reply; ACK is followed by the echoed section,
+        # which ends with its own blank line.
+        if text.startswith(NAK):
+            break
+        if text.startswith(ACK) and text.rstrip().endswith(("\n", ":")) and text.count("\n\n") >= 2:
+            break
+    return buf.decode("utf-8", errors="replace")
+
+
+def exchange(host, block, connect_timeout=CONNECT_TIMEOUT,
+             quiet_timeout=REPLY_QUIET_TIMEOUT,
+             prelude_timeout=PRELUDE_QUIET_TIMEOUT):
+    """Send one block on a fresh 9998 session; return the echoed body.
+
+    Raises ``UltimatteNetworkError`` on NAK or on no reply at all.
+    """
+    sock = _connect_with_retry(host, CONTROL_PORT, timeout=connect_timeout)
+    try:
+        _drain_prelude(sock, prelude_timeout)
+        sock.sendall(block.encode("utf-8"))
+        reply = _read_reply(sock, quiet_timeout)
+    finally:
+        try:
+            sock.close()
+        except Exception:                                      # noqa: BLE001
+            pass
+    stripped = reply.lstrip()
+    if stripped.startswith(NAK):
+        raise UltimatteNetworkError(
+            f"unit refused the block (NAK):\n{block.strip()}")
+    if not stripped.startswith(ACK):
+        raise UltimatteNetworkError(
+            f"no ACK from {host} (got {reply[:80]!r})")
+    return stripped[len(ACK):].lstrip("\n")
+
+
+def read_network(host, index=0, **kw):
+    """Read ``NETWORK INTERFACE <index>`` from the unit at ``host``.
+
+    Uses the query form of the block protocol — one short session, no
+    prelude parsing, nothing written.
+    """
+    return parse_interface(exchange(host, build_block(index), **kw), index)
+
+
+def set_network(host, index=0, *, address=None, netmask=None, gateway=None,
+                dns=None, dynamic=None, readback_timeout=READBACK_TIMEOUT, **kw):
+    """Set static network parameters and return the unit's state READ BACK.
+
+    ``address`` and ``netmask`` travel together in one ``Static Addresses``
+    field, so supplying one without the other is an error — the unit would
+    be told to drop the half you left out. Pass ``dns=[]`` to clear the DNS
+    list; ``dns=None`` leaves it alone.
+
+    The returned interface comes from a fresh query, not from the set's own
+    echo (which carries only the fields that were sent — see the module
+    docstring). Changing an address can make the unit briefly unreachable
+    while the interface reapplies, so the read-back is retried until
+    ``readback_timeout``; if it never answers, this raises rather than
+    reporting a success it cannot stand behind.
+
+    Writes what it is told: the caller owns the question of whether a change
+    is safe.
+    """
+    if (address is None) != (netmask is None):
+        raise ValueError(
+            "address and netmask are one field on the wire — pass both or neither")
+    fields = {}
+    if dynamic is not None:
+        fields["Dynamic IP"] = "true" if dynamic else "false"
+    if address is not None:
+        fields["Static Addresses"] = f"{address}/{netmask}"
+    if gateway is not None:
+        fields["Static Gateway"] = gateway
+    if dns is not None:
+        fields["Static DNS Servers"] = " ".join(dns)
+    if not fields:
+        raise ValueError("nothing to set")
+
+    exchange(host, build_block(index, **fields), **kw)     # raises on NAK
+
+    deadline = time.time() + readback_timeout
+    last = None
+    while True:
+        try:
+            iface = read_network(host, index, **kw)
+            if _settled(iface, address is not None):
+                return iface
+            last = f"interface still reapplying (Current {iface.address}/{iface.netmask})"
+        except (UltimatteNetworkError, OSError) as exc:
+            last = exc
+        if time.time() >= deadline:
+            break
+        time.sleep(READBACK_POLL)
+    raise UltimatteNetworkError(
+        f"{host}: the unit accepted {sorted(fields)} but did not settle "
+        f"within {readback_timeout:g}s — CHECK THIS UNIT ({last})")
+
+
+def _settled(iface, address_was_set):
+    """Has the interface finished reapplying?
+
+    Measured on hardware: for about a second after an address change the unit
+    answers happily but reports ``Current Addresses: 0.0.0.0/255.255.0.0``
+    while ``Static Addresses`` already holds the new value. A caller that
+    verified against the CURRENT fields in that window would read garbage —
+    and one that verified against the STATIC fields would declare success
+    before the interface had actually taken them. So "settled" means the unit
+    is live on what it was configured with.
+    """
+    if not address_was_set:
+        return True
+    if not iface.address or iface.address == UNCONFIGURED:
+        return False
+    return (iface.address == iface.static_address
+            and iface.netmask == iface.static_netmask)

{ultimattewire-0.1.0.dev1 → ultimattewire-0.2.0.dev0/ultimattewire.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultimattewire
-Version: 0.1.0.dev1
+Version: 0.2.0.dev0
 Summary: Blackmagic Ultimatte 12 archive and restore over its native TCP protocol (Smart Remote 4 compatible zips)
 Author: Lucas Romanenko
 License: MIT
@@ -24,10 +24,12 @@ Dynamic: license-file
 
 # ultimattewire
 
-Python library that archives and restores the configuration of a Blackmagic
-**Ultimatte 12** or **Ultimatte 12 4K** keyer over its native TCP protocol,
-producing and consuming the same zip archives the vendor's Smart Remote 4
-writes with **Archive All** and reads with **Restore**.
+Python library for the Blackmagic **Ultimatte 12** and **Ultimatte 12 4K**
+keyers over their native TCP protocol. It archives and restores unit
+configuration — producing and consuming the same zip archives the vendor's
+Smart Remote 4 writes with **Archive All** and reads with **Restore** — and
+reads and sets the unit's **network interface** (address, netmask, gateway,
+DNS, static or DHCP), which is what the vendor's Ultimatte Setup does.
 
 [![CI](https://github.com/lucas-romanenko/bmdwire/actions/workflows/ci.yml/badge.svg)](https://github.com/lucas-romanenko/bmdwire/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/ultimattewire.svg)](https://pypi.org/project/ultimattewire/) [![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) [![Latest tag](https://img.shields.io/github/v/tag/lucas-romanenko/bmdwire?filter=ultimattewire-v*&label=release)](https://github.com/lucas-romanenko/bmdwire/tags)
 
@@ -40,7 +42,7 @@ established and what is still a guess.
 
 ## Status
 
-- **Pre-release** (`0.1.0.dev1`), extracted from a broadcast control
+- **Pre-release** (`0.2.0.dev0`), extracted from a broadcast control
   application where operators archive and restore keyer configurations from a
   web page.
 - Verified against an Ultimatte 12 4K (the unit the captures came from). The
@@ -65,6 +67,7 @@ Python 3.10 or newer. No other dependencies.
 
 ## Features
 
+- `read_network(host)` / `set_network(host, address=…, netmask=…, gateway=…, dns=…, dynamic=…)`: the unit's network interface — what Ultimatte Setup configures. `set_network` verifies by reading back the *settled* interface, not by trusting the unit's acknowledgement.
 - `archive_unit_to_bytes(host)`: pull every saved preset slot plus the `GPISettings` and `SavedSettings` resources into an in-memory zip in Smart Remote's exact layout, with a human-readable annotated state dump riding along.
 - `restore_unit_from_bytes(host, zip_bytes)`: push such a zip back, in the order the vendor app uses, aborting at the first rejected write.
 - Reads the unit's text prelude on TCP 9998 (label, firmware release, live control values, the preset FILE LIST) and does binary slot/resource reads and writes on TCP 9996.
@@ -96,6 +99,19 @@ A zip produced by this library can be opened with Smart Remote 4's Restore
 unchanged, and a Smart Remote "Archive All" zip can be passed straight to
 `restore_unit_from_bytes`.
 
+```python
+from ultimattewire import read_network, set_network
+
+iface = read_network("192.0.2.21")
+print(iface.static_address, iface.static_netmask, iface.static_gateway, iface.mac)
+
+# Widen the mask, keeping the address and gateway. Returns the settled
+# interface as the unit reports it — not what was asked for.
+iface = set_network("192.0.2.21", address=iface.static_address,
+                    netmask="255.255.248.0", gateway=iface.static_gateway)
+assert iface.netmask == "255.255.248.0"
+```
+
 ## Protocol notes
 
 This is the reverse-engineered part and the most useful thing to read before
@@ -144,6 +160,50 @@ already hit and fixed are recorded in `_preamble.py` (a `$` anchor that
 truncated multi-line FILE LISTs, and a `\s*` that let an empty section
 swallow the next one).
 
+### Setting values: the 9998 block protocol
+
+The 9998 channel is not only a prelude. After it, the unit accepts **blocks**:
+an upper-case section header ending in a colon, then `key: value` lines, then
+a **blank line — and the blank line is what submits the block.** Nothing
+happens until it arrives, which is why single-line probes (`IDENTITY?`,
+`help`, `ping`, with either line ending) draw no reply at all and look like
+the unit ignoring the client. That is the one fact the whole feature rests on.
+
+The unit answers `ACK\n\n` followed by the section echoed back, or a bare
+`NAK\n\n` for an unknown section or a value it will not take.
+
+Three properties worth knowing:
+
+- **An empty block is a query.** Header, blank line, no fields: sets nothing
+  and echoes the full section. Read and write are therefore one code path,
+  and reading network state needs no prelude parsing.
+- **The echo after a set carries only the fields that were sent**, not the
+  section. A query echoes all eleven lines of `NETWORK INTERFACE 0`; a set of
+  two fields echoes those two. So the echo proves the unit *accepted* the
+  fields and says nothing about what it now holds — it must not be treated as
+  verification.
+- **`Static Addresses` is `<ip>/<dotted-netmask>` as one field**
+  (`192.168.1.10/255.255.252.0`), not a prefix length and not two fields.
+  Sending the address alone tells the unit to drop the mask, so `set_network`
+  refuses an address without its mask before anything reaches the wire.
+
+Changing an address makes the interface reapply, and for about a second the
+unit answers normally while reporting `Current Addresses: 0.0.0.0/255.255.0.0`
+with `Static Addresses` already holding the new value. Verifying against the
+current fields in that window reads garbage; verifying against the static
+fields declares success before the interface is running the value. So
+`set_network` polls until the unit is live on what it was configured with —
+current present, not `0.0.0.0`, and equal to static — and raises rather than
+reporting a success it cannot stand behind. A set that touches no address
+reapplies nothing and is not made to wait.
+
+`exchange`, `build_block` and `parse_interface` are public, so any other
+section the unit exposes can be driven the same way.
+
+There is deliberately no policy in the library: `set_network` writes what it
+is told. Whether a change is safe belongs to the caller — re-addressing a
+unit over the network can put it out of reach until someone visits it.
+
 ### The 9996 binary channel
 
 Every request opens its own TCP connection; the unit closes it after

{ultimattewire-0.1.0.dev1 → ultimattewire-0.2.0.dev0}/ultimattewire.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 ultimattewire/__init__.py
 ultimattewire/_preamble.py
 ultimattewire/_protocol.py
+ultimattewire/network.py
 ultimattewire.egg-info/PKG-INFO
 ultimattewire.egg-info/SOURCES.txt
 ultimattewire.egg-info/dependency_links.txt