seymourlib 0.1.0__tar.gz

seymourlib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Richard Berg
+
+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.

seymourlib-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: seymourlib
+Version: 0.1.0
+Summary: Python client for Seymour masking screens, connected via direct serial or Global Caché iTach IP2SL
+Author-email: Richard Berg <ars@richardberg.net>
+License-Expression: MIT
+Project-URL: omepage, https://github.com/richard-berg/seymourlib
+Project-URL: source, https://github.com/richard-berg/seymourlib.git
+Project-URL: issues, https://github.com/richard-berg/seymourlib/issues
+Keywords: seymour,masking,screen,serial,itach,ip2sl,home-assistant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anyio>=3.4
+Requires-Dist: attrs>=25.4.0
+Requires-Dist: tenacity>=8.0
+Requires-Dist: async-typer>=0.1.10
+Provides-Extra: serial
+Requires-Dist: pyserial_asyncio>=0.6; extra == "serial"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-timeout>=2; extra == "dev"
+Requires-Dist: coverage>=7; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: pyserial_asyncio>=0.6; extra == "dev"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.6; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.10; extra == "typecheck"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: pytest-timeout>=2; extra == "test"
+Requires-Dist: coverage>=7; extra == "test"
+Requires-Dist: pyserial_asyncio>=0.6; extra == "test"
+Dynamic: license-file
+
+# seymourlib
+
+[![CI](https://img.shields.io/github/actions/workflow/status/richard-berg/seymourlib/ci.yml?label=CI&logo=github)](https://github.com/richard-berg/seymourlib/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/richard-berg/seymourlib?logo=codecov)](https://codecov.io/gh/richard-berg/seymourlib)
+[![PyPI](https://img.shields.io/pypi/v/seymourlib?logo=pypi)](https://pypi.org/project/seymourlib/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Python client for Seymour masking screens, connected via direct serial or Global Caché iTach IP2SL. Built for rock-solid control loops, [Home Assistant](https://www.home-assistant.io/) integrations, and quick bench testing. 😎
+
+---
+
+## Highlights
+
+- Async-first client and transport abstractions (TCP/IP2SL vs native serial) with consistent APIs.
+- Protocol helpers that mirror the official Seymour RS232 spec, including parsing/validation utilities.
+- `seymourctl` CLI for one-off commands, scripting, and smoke tests in CI.
+- Batteries-included retry logic (`tenacity`), timeout handling, and graceful cancellation via `anyio`.
+
+## Architecture at a Glance
+
+```mermaid
+flowchart TB
+     App[Your automation / HA stack] -->|async API| Client[SeymourClient]
+     Client --> Protocol[Protocol helpers]
+     Client --> Transport
+     Transport -->|TCP 4999| IP2SL[Global Caché IP2SL]
+     Transport -->|RS232| Screen[Seymour Masking Screen]
+     IP2SL -->|RS232| Screen
+```
+
+## Installation
+
+### Requirements
+
+- Python 3.11+
+- `uv` >= 0.2 (recommended) or classic `pip`
+
+### Using uv (dev + extras)
+
+```bash
+uv sync --all-extras
+```
+
+### Using pip (runtime only)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+pip install "seymourlib[serial]"
+```
+
+> 💡 The optional `serial` extra pulls in `pyserial-asyncio` so the same client works over USB/RS232 without the IP bridge.
+
+---
+
+## First-Time Setup Checklist
+
+1. **Clone & bootstrap**
+    - `git clone https://github.com/richard-berg/seymourlib && cd seymourlib`
+    - `uv sync --all-extras`
+2. **Sanity-test the library**
+    - `uv run pytest` for local regression.
+    - `uv run seymourctl -v status` to hit your target once hardware is reachable.
+3. **Wire up hardware**
+    - Confirm straight-through RS232 between IP2SL and the Seymour control port.
+    - For direct USB serial, a FTDI-based adapter keeps timing stable.
+4. **Pick your transport**
+    - `TCPTransport(host, port=4999)` for IP2SL.
+    - `SerialTransport(port="COM5")` for direct connection (requires `[serial]`).
+
+---
+
+## Usage Examples
+
+### Python API
+
+```python
+import asyncio
+from seymourlib.client import SeymourClient
+from seymourlib.transport import TCPTransport
+
+async def main() -> None:
+     async with SeymourClient(TCPTransport("192.168.1.70")) as client:
+          status = await client.get_status()
+          print(status)
+
+asyncio.run(main())
+```
+
+### CLI
+
+```bash
+uv run seymourctl --host 192.168.1.70 status
+uv run seymourctl --host 192.168.1.70 preset apply 235
+uv run seymourctl --help
+```
+
+---
+
+## IP2SL Setup & Diagnostics
+
+### 1. Test direct serial first
+
+- Connect a laptop directly to the Seymour RS232 port with a known-good USB adapter.
+- Use `RealTerm`, `CoolTerm`, or any tty tool (115200 8N1 by default - verify via Seymour docs) to send a `PS?` (position status) command.
+- Once commands succeed locally, you know the projector + cable + command syntax are correct before adding the network hop.
+
+### 2. Discover the IP2SL via iHelp
+
+- Download [Global Caché iHelp](https://www.globalcache.com/files/software/iHelp.zip) and run it on the same subnet.
+- Press **Scan** to locate the IP2SL; note the MAC, firmware, and current IP.
+- If nothing shows up, temporarily disable host firewalls or plug directly into a laptop + small DHCP scope.
+
+### 3. Pin the network configuration
+
+- Point a browser at `http://<your-ip>/` (from step 2) if you want a point-and-click GUI for DHCP/static IP, firmware, and reboot controls.
+- Otherwise, install [Global Caché iTest](https://www.globalcache.com/files/software/iTest.zip).
+  - Use iTest or telnet into port **4998** (the configuration/control port).
+  - Send `set dhcp 0`, `set ip <static>`, `set mask <subnet>`, `set gateway <gw>`, then `save` to burn settings.
+- Reboot (power cycle or `reboot` command) and confirm the device responds on the static IP.
+- Document the MAC/IP in your DHCP reservations to avoid future collisions.
+
+### 4. Lock the serial parameters
+
+- Open the IP2SL web UI and switch to the **Serial** tab, or telnet/iTest into port **4998** for command-line configuration.
+- Ensure the port is set to **115200 baud, 8 data bits, no parity, 1 stop bit** to match Seymour’s RS232 spec.
+- Saving via the UI writes immediately; if you used the control port, run `set baud 115200`, `set data 8`, `set parity 0`, `set stop 1`, then `save` and reboot so the bridge always boots with the correct framing.
+
+### 5. Exercise the serial bridge with iTest
+
+- Open iTest (or `telnet`)
+- Target port **4999** on the static IP, choose **RAW** mode, and click **Connect**.
+- Send a few simple commands (e.g. `[01S]`, `[01P]`). The response should echo immediately.
+- If latency creeps in, verify telnet keep-alives/device busy LEDs. Keep the window open while you walk through automation flows to watch the live traffic.
+
+### 6. Promote to seymourlib
+
+- Update your `.env` / config with the same host/port verified above.
+- Start with `uv run seymourctl -v status` (verbose logging shows full request/response frames).
+- Flip to automation ([Home Assistant](https://www.home-assistant.io/), Homebridge, etc.) once CLI calls are boringly reliable.
+
+---
+
+## Troubleshooting & Field Notes
+
+- ⚡ **No response over TCP but serial works** - Ensure port 4999 is open on local firewalls and that the IP2SL LED blinks on connect; if not, recheck the static IP settings from step 3.
+- 🔌 **Commands hang after a day** - The IP2SL can queue stale sockets; send `set rs232disconnect 1` over port 4998 so idle TCP clients auto-close.
+- 🔁 **Race conditions from HA automations** - Wrap your automations with seymourlib's async context manager so only one command pipeline exists per transport.
+- 🧪 **Need deeper diagnostics** - Add `--verbose` to `seymourctl` to dump protocol frames, or [enable debug logging](https://docs.python.org/3/library/logging.html) to capture per-request timestamps.
+- 🛠️ **Firmware drift** - Global Caché publishes release notes; mismatched firmware sometimes defaults back to DHCP on reboot. Always export a config snapshot in iHelp after upgrades.
+
+---
+
+## Related Docs & Inspiration
+
+- [Seymour Screen Excellence RS232 Protocol PDF](https://www.seymourscreenexcellence.com/) (request via dealer portal).
+- [Global Caché Knowledge Base](https://globalcache.zendesk.com/).
+- [Home Assistant Template Switch Cookbook](https://www.home-assistant.io/integrations/template/) for inspiration on wiring seymourlib into HA.
+- [CoolTerm Serial Terminal](https://freeware.the-meiers.org/) - handy for the direct-serial smoke test.
+
+---
+
+## Contributing
+
+- Fork, create a feature branch, and open a PR (tests + type checks 🚦 required).
+- `pre-commit run` before pushing.
+- Issues and hardware findings are welcome - real-world serial logs are gold for regression tests.
+
+Need something else? Open a discussion or ping via Issues and we’ll figure it out together. 🙌

seymourlib-0.1.0/README.md

@@ -0,0 +1,169 @@
+# seymourlib
+
+[![CI](https://img.shields.io/github/actions/workflow/status/richard-berg/seymourlib/ci.yml?label=CI&logo=github)](https://github.com/richard-berg/seymourlib/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/richard-berg/seymourlib?logo=codecov)](https://codecov.io/gh/richard-berg/seymourlib)
+[![PyPI](https://img.shields.io/pypi/v/seymourlib?logo=pypi)](https://pypi.org/project/seymourlib/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Python client for Seymour masking screens, connected via direct serial or Global Caché iTach IP2SL. Built for rock-solid control loops, [Home Assistant](https://www.home-assistant.io/) integrations, and quick bench testing. 😎
+
+---
+
+## Highlights
+
+- Async-first client and transport abstractions (TCP/IP2SL vs native serial) with consistent APIs.
+- Protocol helpers that mirror the official Seymour RS232 spec, including parsing/validation utilities.
+- `seymourctl` CLI for one-off commands, scripting, and smoke tests in CI.
+- Batteries-included retry logic (`tenacity`), timeout handling, and graceful cancellation via `anyio`.
+
+## Architecture at a Glance
+
+```mermaid
+flowchart TB
+     App[Your automation / HA stack] -->|async API| Client[SeymourClient]
+     Client --> Protocol[Protocol helpers]
+     Client --> Transport
+     Transport -->|TCP 4999| IP2SL[Global Caché IP2SL]
+     Transport -->|RS232| Screen[Seymour Masking Screen]
+     IP2SL -->|RS232| Screen
+```
+
+## Installation
+
+### Requirements
+
+- Python 3.11+
+- `uv` >= 0.2 (recommended) or classic `pip`
+
+### Using uv (dev + extras)
+
+```bash
+uv sync --all-extras
+```
+
+### Using pip (runtime only)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+pip install "seymourlib[serial]"
+```
+
+> 💡 The optional `serial` extra pulls in `pyserial-asyncio` so the same client works over USB/RS232 without the IP bridge.
+
+---
+
+## First-Time Setup Checklist
+
+1. **Clone & bootstrap**
+    - `git clone https://github.com/richard-berg/seymourlib && cd seymourlib`
+    - `uv sync --all-extras`
+2. **Sanity-test the library**
+    - `uv run pytest` for local regression.
+    - `uv run seymourctl -v status` to hit your target once hardware is reachable.
+3. **Wire up hardware**
+    - Confirm straight-through RS232 between IP2SL and the Seymour control port.
+    - For direct USB serial, a FTDI-based adapter keeps timing stable.
+4. **Pick your transport**
+    - `TCPTransport(host, port=4999)` for IP2SL.
+    - `SerialTransport(port="COM5")` for direct connection (requires `[serial]`).
+
+---
+
+## Usage Examples
+
+### Python API
+
+```python
+import asyncio
+from seymourlib.client import SeymourClient
+from seymourlib.transport import TCPTransport
+
+async def main() -> None:
+     async with SeymourClient(TCPTransport("192.168.1.70")) as client:
+          status = await client.get_status()
+          print(status)
+
+asyncio.run(main())
+```
+
+### CLI
+
+```bash
+uv run seymourctl --host 192.168.1.70 status
+uv run seymourctl --host 192.168.1.70 preset apply 235
+uv run seymourctl --help
+```
+
+---
+
+## IP2SL Setup & Diagnostics
+
+### 1. Test direct serial first
+
+- Connect a laptop directly to the Seymour RS232 port with a known-good USB adapter.
+- Use `RealTerm`, `CoolTerm`, or any tty tool (115200 8N1 by default - verify via Seymour docs) to send a `PS?` (position status) command.
+- Once commands succeed locally, you know the projector + cable + command syntax are correct before adding the network hop.
+
+### 2. Discover the IP2SL via iHelp
+
+- Download [Global Caché iHelp](https://www.globalcache.com/files/software/iHelp.zip) and run it on the same subnet.
+- Press **Scan** to locate the IP2SL; note the MAC, firmware, and current IP.
+- If nothing shows up, temporarily disable host firewalls or plug directly into a laptop + small DHCP scope.
+
+### 3. Pin the network configuration
+
+- Point a browser at `http://<your-ip>/` (from step 2) if you want a point-and-click GUI for DHCP/static IP, firmware, and reboot controls.
+- Otherwise, install [Global Caché iTest](https://www.globalcache.com/files/software/iTest.zip).
+  - Use iTest or telnet into port **4998** (the configuration/control port).
+  - Send `set dhcp 0`, `set ip <static>`, `set mask <subnet>`, `set gateway <gw>`, then `save` to burn settings.
+- Reboot (power cycle or `reboot` command) and confirm the device responds on the static IP.
+- Document the MAC/IP in your DHCP reservations to avoid future collisions.
+
+### 4. Lock the serial parameters
+
+- Open the IP2SL web UI and switch to the **Serial** tab, or telnet/iTest into port **4998** for command-line configuration.
+- Ensure the port is set to **115200 baud, 8 data bits, no parity, 1 stop bit** to match Seymour’s RS232 spec.
+- Saving via the UI writes immediately; if you used the control port, run `set baud 115200`, `set data 8`, `set parity 0`, `set stop 1`, then `save` and reboot so the bridge always boots with the correct framing.
+
+### 5. Exercise the serial bridge with iTest
+
+- Open iTest (or `telnet`)
+- Target port **4999** on the static IP, choose **RAW** mode, and click **Connect**.
+- Send a few simple commands (e.g. `[01S]`, `[01P]`). The response should echo immediately.
+- If latency creeps in, verify telnet keep-alives/device busy LEDs. Keep the window open while you walk through automation flows to watch the live traffic.
+
+### 6. Promote to seymourlib
+
+- Update your `.env` / config with the same host/port verified above.
+- Start with `uv run seymourctl -v status` (verbose logging shows full request/response frames).
+- Flip to automation ([Home Assistant](https://www.home-assistant.io/), Homebridge, etc.) once CLI calls are boringly reliable.
+
+---
+
+## Troubleshooting & Field Notes
+
+- ⚡ **No response over TCP but serial works** - Ensure port 4999 is open on local firewalls and that the IP2SL LED blinks on connect; if not, recheck the static IP settings from step 3.
+- 🔌 **Commands hang after a day** - The IP2SL can queue stale sockets; send `set rs232disconnect 1` over port 4998 so idle TCP clients auto-close.
+- 🔁 **Race conditions from HA automations** - Wrap your automations with seymourlib's async context manager so only one command pipeline exists per transport.
+- 🧪 **Need deeper diagnostics** - Add `--verbose` to `seymourctl` to dump protocol frames, or [enable debug logging](https://docs.python.org/3/library/logging.html) to capture per-request timestamps.
+- 🛠️ **Firmware drift** - Global Caché publishes release notes; mismatched firmware sometimes defaults back to DHCP on reboot. Always export a config snapshot in iHelp after upgrades.
+
+---
+
+## Related Docs & Inspiration
+
+- [Seymour Screen Excellence RS232 Protocol PDF](https://www.seymourscreenexcellence.com/) (request via dealer portal).
+- [Global Caché Knowledge Base](https://globalcache.zendesk.com/).
+- [Home Assistant Template Switch Cookbook](https://www.home-assistant.io/integrations/template/) for inspiration on wiring seymourlib into HA.
+- [CoolTerm Serial Terminal](https://freeware.the-meiers.org/) - handy for the direct-serial smoke test.
+
+---
+
+## Contributing
+
+- Fork, create a feature branch, and open a PR (tests + type checks 🚦 required).
+- `pre-commit run` before pushing.
+- Issues and hardware findings are welcome - real-world serial logs are gold for regression tests.
+
+Need something else? Open a discussion or ping via Issues and we’ll figure it out together. 🙌

seymourlib-0.1.0/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["setuptools>=65", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seymourlib"
+version = "0.1.0"
+description = "Python client for Seymour masking screens, connected via direct serial or Global Caché iTach IP2SL"
+keywords = ["seymour", "masking", "screen", "serial", "itach", "ip2sl", "home-assistant"]
+authors = [{name = "Richard Berg", email = "ars@richardberg.net"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Home Automation",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "anyio>=3.4",
+    "attrs>=25.4.0",
+    "tenacity>=8.0",
+    "async-typer>=0.1.10",
+]
+
+[project.urls]
+omepage = "https://github.com/richard-berg/seymourlib"
+source = "https://github.com/richard-berg/seymourlib.git"
+issues = "https://github.com/richard-berg/seymourlib/issues"
+
+
+[project.optional-dependencies]
+serial = [
+    "pyserial_asyncio>=0.6",
+]
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.23",
+    "pytest-timeout>=2",
+    "coverage>=7",
+    "mypy>=1.10",
+    "ruff>=0.6",
+    "types-setuptools",
+    "pyserial_asyncio>=0.6",
+]
+lint = [
+    "ruff>=0.6",
+]
+typecheck = [
+    "mypy>=1.10",
+]
+test = [
+    "pytest>=7",
+    "pytest-asyncio>=0.23",
+    "pytest-timeout>=2",
+    "coverage>=7",
+    "pyserial_asyncio>=0.6",
+]
+
+[project.scripts]
+seymourctl = "seymourlib.cli:main"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+fix = true
+unsafe-fixes = false
+lint.select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "W",   # warnings
+    "I",   # import sorting
+    "UP",  # pyupgrade
+    "B",   # bugbear
+    "ASYNC", # async best practices
+]
+lint.ignore = [
+    "E501", # line length handled separately
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+# ----------------------------------------
+# mypy configuration
+# ----------------------------------------
+[tool.mypy]
+python_version = "3.12"
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+warn_unreachable = true
+strict = true
+
+# Ignore missing type hints in dependencies, except ours
+ignore_missing_imports = true
+
+[tool.setuptools.package-data]
+"seymourlib" = ["py.typed"]
+
+# ----------------------------------------
+# Pytest configuration
+# ----------------------------------------
+[tool.pytest.ini_options]
+addopts = "-q --timeout=10"
+asyncio_mode = "auto"
+testpaths = ["tests"]

seymourlib-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+