fpga-isv 0.1.0__tar.gz

fpga_isv-0.1.0/LICENSE

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

fpga_isv-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: fpga-isv
+Version: 0.1.0
+Summary: fpga-isv (ISV = Interactive Sim Viewer): a config-driven graphical panel viewer for interactive-sim.
+Author-email: Oron Port <oron.port@dfiant.works>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/DFiantWorks/interactive-sim-viewer
+Project-URL: interactive-sim, https://github.com/DFiantWorks/interactive-sim
+Keywords: fpga,simulation,viewer,hdl,interactive-sim,ulx3s
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pillow
+Dynamic: license-file
+
+# fpga-isv — Interactive Sim Viewer
+
+A cross-platform **graphical panel viewer** for
+[interactive-sim](https://github.com/DFiantWorks/interactive-sim). It draws a board *photo* (or a
+blank *panel* you mock up), overlays the LEDs and buttons at their pixel positions, and connects
+that virtual panel to a running HDL simulation: **design-driven flags light the LEDs**, and
+**clicking a button feeds a control back into the design**.
+
+`fpga-isv` is a *pure client of the interactive-sim socket API* — it knows nothing about HDL or
+simulators. Anything that speaks the same newline-delimited-JSON protocol works with it. The
+[ULX3S](https://github.com/ulx3s/ulx3s) board ships as the bundled reference example.
+
+```sh
+fpga-isv --example ulx3s
+```
+
+## How it connects
+
+The viewer **listens** on a TCP port; the simulation **connects to it** (set
+`INTERACTIVE_STREAM=host:port` for the sim). This means you can:
+
+- **open and close the viewer at any time** — the sim's backend keeps reconnecting;
+- **stop or restart the simulation** while the viewer stays up — on each (re)connect the sim
+  replays its full state (every component + last values), so the panel repopulates automatically.
+
+```sh
+fpga-isv --example ulx3s --host 0.0.0.0 --port 7777
+# then run a simulation with INTERACTIVE_STREAM=127.0.0.1:7777
+```
+
+## Install
+
+Three ways, depending on whether you have Python:
+
+| Method | Command | Needs |
+|--------|---------|-------|
+| **Standalone binary** (zero prereqs) | download from [Releases](https://github.com/DFiantWorks/interactive-sim-viewer/releases) | nothing |
+| **pipx** (Python users) | `pipx install fpga-isv` | a Python that ships `tkinter` |
+| **Homebrew** (macOS / Linux) | `brew tap DFiantWorks/fpga-isv https://github.com/DFiantWorks/homebrew-fpga-isv && brew install fpga-isv` | Homebrew |
+
+The standalone binary bundles its own Python + Tcl/Tk + Pillow, so it runs with no prerequisites.
+`pipx`/source installs need a Python with `tkinter` (stdlib, but a separate OS package on some
+Linux distros, e.g. `apt install python3-tk`); Pillow is pulled in automatically and is required
+for JPEG photos and cropped / non-integer-scaled images (PNG/GIF panels work on stdlib Tk alone).
+
+> **macOS note:** the released binaries are currently **unsigned**. Launched by another process
+> directly they run fine; launched via Finder/`open` from a browser-downloaded copy, Gatekeeper
+> blocks them until you clear quarantine — `xattr -dr com.apple.quarantine ./fpga-isv` or
+> right-click → Open once. **Homebrew** installs strip quarantine, so `brew install` avoids the
+> prompt entirely; `pipx` has no binary to quarantine.
+
+## Config
+
+A panel is described by one JSON file. All coordinates are in **original-image pixels**;
+`image.scale` scales the photo/panel and every coordinate together for display, and `image.crop`
+trims a photo to the board — the map stays in original-image pixels so it is independent of crop
+and window size.
+
+A **photo** panel:
+
+```jsonc
+{
+  "title": "ULX3S",
+  "image":  { "url": "board.png", "crop": [160, 195, 1650, 1010], "scale": 0.72 },
+  "leds":   { "on_color": "#ff5a36", "shape": "rect", "w": 26, "h": 32,
+              "items": [ { "name": "leds", "bit": 0, "x": 632, "y": 480 }, /* ... */ ] },
+  "buttons":[ { "name": "btn_pwr", "shape": "circle", "x": 1375, "y": 401, "r": 42, "key": "p" } ]
+}
+```
+
+A **blank panel** mockup (no photo — lay controls out from scratch):
+
+```jsonc
+{
+  "title": "My Panel",
+  "image":  { "width": 1200, "height": 800, "bg": "#101418" },
+  "leds":   { "on_color": "#56d364", "items": [ { "name": "led_err", "bit": 0, "x": 100, "y": 80 } ] },
+  "buttons":[ { "name": "btn_run", "shape": "rect", "x": 200, "y": 300, "w": 120, "h": 60, "toggle": true } ]
+}
+```
+
+- `image.url` may be a remote URL (optionally with `cache`), an absolute path, or a path
+  **relative to the config file**. Use `width`/`height`/`bg` instead of `url` for a blank panel.
+- An LED **item** lights when bit `bit` of flag `name` is `1`, so an N-bit bus is N items with
+  different bit indices and a 1-bit flag is one item.
+- A **button** sends `1` on press and `0` on release (momentary); `"toggle": true` flips and
+  latches. `"key"` mirrors it to a keyboard key (Tk keysym, e.g. `p`, `space`, `Up`).
+
+### Mapping a new photo
+
+Run with `--calibrate` and click the image: each click prints the original-image pixel coordinate
+(and marks it on the canvas), so you can read off the x/y for every LED and button.
+
+```sh
+fpga-isv --config my_board.json --calibrate
+```
+
+## CLI
+
+```
+fpga-isv (--example NAME | --config PATH) [--host 0.0.0.0] [--port 7777] [--refresh] [--calibrate]
+fpga-isv --list-examples
+fpga-isv --version
+```
+
+## Wire protocol
+
+Newline-delimited JSON, one message per line (defined by interactive-sim; every sim→viewer
+message carries `t`, the simulation time in µs):
+
+```
+sim    -> viewer   {"ev":"reg",  "t":1234.5,"name":"btn_run","kind":"ctrl","width":1}
+                   {"ev":"flag", "t":1234.5,"name":"leds","val":42}
+                   {"ev":"time", "t":1234.5}
+                   {"ev":"close","t":1234.5,"name":"btn_run"}
+viewer -> sim      {"name":"btn_run","val":1}
+```
+
+## Develop
+
+```sh
+pip install -e . pytest
+python -m pytest -q            # headless protocol/config/geometry tests
+python -m fpga_isv --example ulx3s
+pyinstaller packaging/fpga_isv.spec   # build the standalone binary into dist/
+```
+
+## License
+
+MIT (see [LICENSE](LICENSE)). The bundled ULX3S photo is from the
+[ULX3S project](https://github.com/ulx3s/ulx3s).

fpga_isv-0.1.0/README.md

@@ -0,0 +1,131 @@
+# fpga-isv — Interactive Sim Viewer
+
+A cross-platform **graphical panel viewer** for
+[interactive-sim](https://github.com/DFiantWorks/interactive-sim). It draws a board *photo* (or a
+blank *panel* you mock up), overlays the LEDs and buttons at their pixel positions, and connects
+that virtual panel to a running HDL simulation: **design-driven flags light the LEDs**, and
+**clicking a button feeds a control back into the design**.
+
+`fpga-isv` is a *pure client of the interactive-sim socket API* — it knows nothing about HDL or
+simulators. Anything that speaks the same newline-delimited-JSON protocol works with it. The
+[ULX3S](https://github.com/ulx3s/ulx3s) board ships as the bundled reference example.
+
+```sh
+fpga-isv --example ulx3s
+```
+
+## How it connects
+
+The viewer **listens** on a TCP port; the simulation **connects to it** (set
+`INTERACTIVE_STREAM=host:port` for the sim). This means you can:
+
+- **open and close the viewer at any time** — the sim's backend keeps reconnecting;
+- **stop or restart the simulation** while the viewer stays up — on each (re)connect the sim
+  replays its full state (every component + last values), so the panel repopulates automatically.
+
+```sh
+fpga-isv --example ulx3s --host 0.0.0.0 --port 7777
+# then run a simulation with INTERACTIVE_STREAM=127.0.0.1:7777
+```
+
+## Install
+
+Three ways, depending on whether you have Python:
+
+| Method | Command | Needs |
+|--------|---------|-------|
+| **Standalone binary** (zero prereqs) | download from [Releases](https://github.com/DFiantWorks/interactive-sim-viewer/releases) | nothing |
+| **pipx** (Python users) | `pipx install fpga-isv` | a Python that ships `tkinter` |
+| **Homebrew** (macOS / Linux) | `brew tap DFiantWorks/fpga-isv https://github.com/DFiantWorks/homebrew-fpga-isv && brew install fpga-isv` | Homebrew |
+
+The standalone binary bundles its own Python + Tcl/Tk + Pillow, so it runs with no prerequisites.
+`pipx`/source installs need a Python with `tkinter` (stdlib, but a separate OS package on some
+Linux distros, e.g. `apt install python3-tk`); Pillow is pulled in automatically and is required
+for JPEG photos and cropped / non-integer-scaled images (PNG/GIF panels work on stdlib Tk alone).
+
+> **macOS note:** the released binaries are currently **unsigned**. Launched by another process
+> directly they run fine; launched via Finder/`open` from a browser-downloaded copy, Gatekeeper
+> blocks them until you clear quarantine — `xattr -dr com.apple.quarantine ./fpga-isv` or
+> right-click → Open once. **Homebrew** installs strip quarantine, so `brew install` avoids the
+> prompt entirely; `pipx` has no binary to quarantine.
+
+## Config
+
+A panel is described by one JSON file. All coordinates are in **original-image pixels**;
+`image.scale` scales the photo/panel and every coordinate together for display, and `image.crop`
+trims a photo to the board — the map stays in original-image pixels so it is independent of crop
+and window size.
+
+A **photo** panel:
+
+```jsonc
+{
+  "title": "ULX3S",
+  "image":  { "url": "board.png", "crop": [160, 195, 1650, 1010], "scale": 0.72 },
+  "leds":   { "on_color": "#ff5a36", "shape": "rect", "w": 26, "h": 32,
+              "items": [ { "name": "leds", "bit": 0, "x": 632, "y": 480 }, /* ... */ ] },
+  "buttons":[ { "name": "btn_pwr", "shape": "circle", "x": 1375, "y": 401, "r": 42, "key": "p" } ]
+}
+```
+
+A **blank panel** mockup (no photo — lay controls out from scratch):
+
+```jsonc
+{
+  "title": "My Panel",
+  "image":  { "width": 1200, "height": 800, "bg": "#101418" },
+  "leds":   { "on_color": "#56d364", "items": [ { "name": "led_err", "bit": 0, "x": 100, "y": 80 } ] },
+  "buttons":[ { "name": "btn_run", "shape": "rect", "x": 200, "y": 300, "w": 120, "h": 60, "toggle": true } ]
+}
+```
+
+- `image.url` may be a remote URL (optionally with `cache`), an absolute path, or a path
+  **relative to the config file**. Use `width`/`height`/`bg` instead of `url` for a blank panel.
+- An LED **item** lights when bit `bit` of flag `name` is `1`, so an N-bit bus is N items with
+  different bit indices and a 1-bit flag is one item.
+- A **button** sends `1` on press and `0` on release (momentary); `"toggle": true` flips and
+  latches. `"key"` mirrors it to a keyboard key (Tk keysym, e.g. `p`, `space`, `Up`).
+
+### Mapping a new photo
+
+Run with `--calibrate` and click the image: each click prints the original-image pixel coordinate
+(and marks it on the canvas), so you can read off the x/y for every LED and button.
+
+```sh
+fpga-isv --config my_board.json --calibrate
+```
+
+## CLI
+
+```
+fpga-isv (--example NAME | --config PATH) [--host 0.0.0.0] [--port 7777] [--refresh] [--calibrate]
+fpga-isv --list-examples
+fpga-isv --version
+```
+
+## Wire protocol
+
+Newline-delimited JSON, one message per line (defined by interactive-sim; every sim→viewer
+message carries `t`, the simulation time in µs):
+
+```
+sim    -> viewer   {"ev":"reg",  "t":1234.5,"name":"btn_run","kind":"ctrl","width":1}
+                   {"ev":"flag", "t":1234.5,"name":"leds","val":42}
+                   {"ev":"time", "t":1234.5}
+                   {"ev":"close","t":1234.5,"name":"btn_run"}
+viewer -> sim      {"name":"btn_run","val":1}
+```
+
+## Develop
+
+```sh
+pip install -e . pytest
+python -m pytest -q            # headless protocol/config/geometry tests
+python -m fpga_isv --example ulx3s
+pyinstaller packaging/fpga_isv.spec   # build the standalone binary into dist/
+```
+
+## License
+
+MIT (see [LICENSE](LICENSE)). The bundled ULX3S photo is from the
+[ULX3S project](https://github.com/ulx3s/ulx3s).

fpga_isv-0.1.0/fpga_isv/__init__.py

@@ -0,0 +1,7 @@
+"""fpga-isv -- Interactive Sim Viewer.
+
+A config-driven graphical panel viewer that is a pure client of the interactive-sim
+newline-delimited-JSON socket API. See viewer.py for the application and protocol.
+"""
+
+__version__ = "0.1.0"

fpga_isv-0.1.0/fpga_isv/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m fpga_isv`."""
+
+from fpga_isv.viewer import main
+
+if __name__ == "__main__":
+    main()

fpga_isv-0.1.0/fpga_isv/examples/ulx3s/README.md

@@ -0,0 +1,21 @@
+# ULX3S reference example
+
+The bundled reference panel for **fpga-isv**: a photo of the
+[ULX3S](https://github.com/ulx3s/ulx3s) FPGA board with the 8 user LEDs and the
+direction / fire / power buttons mapped to their positions on the board.
+
+```sh
+fpga-isv --example ulx3s
+```
+
+Then run a matching interactive-sim simulation (e.g. the `ulx3s_demo` in the
+[interactive-sim](https://github.com/DFiantWorks/interactive-sim) repo) so the sim
+connects to the viewer (`INTERACTIVE_STREAM=host:port`). The 8-bit `leds` flag lights
+the LED row; clicking a button (or its mirrored key) sends a momentary `1`/`0`.
+
+- `ulx3s.json` — the panel config (LED/button pixel map, in original-image pixels).
+- `ULX3S_v303_top.png` — the board photo (from the ULX3S project), committed so the
+  example is self-contained and works offline.
+
+To map a different photo, copy this config, point `image.url` at your image, and run
+`fpga-isv --config your.json --calibrate` to read off pixel coordinates by clicking.

fpga_isv-0.1.0/fpga_isv/examples/ulx3s/ulx3s.json

@@ -0,0 +1,39 @@
+{
+  "_comment": "Reference example for fpga-isv: a photo of the ULX3S board with the 8 user LEDs and the buttons mapped. Coordinates are in ORIGINAL image pixels (this photo is 1852x1214); image.crop trims the photo and image.scale scales it, but the map stays in original-image pixels so it is independent of crop/scale. The image is the committed local PNG (resolved against this config's dir). Run with --calibrate and click the photo to read off pixel coordinates for retuning or mapping a different photo.",
+
+  "title": "ULX3S",
+
+  "image": {
+    "url": "ULX3S_v303_top.png",
+    "crop": [160, 195, 1650, 1010],
+    "scale": 0.72
+  },
+
+  "leds": {
+    "on_color": "#ff5a36",
+    "shape": "rect",
+    "w": 26,
+    "h": 32,
+    "glow": true,
+    "items": [
+      { "name": "leds", "bit": 0, "x": 632, "y": 480 },
+      { "name": "leds", "bit": 1, "x": 595, "y": 480 },
+      { "name": "leds", "bit": 2, "x": 558, "y": 480 },
+      { "name": "leds", "bit": 3, "x": 521, "y": 480 },
+      { "name": "leds", "bit": 4, "x": 484, "y": 480 },
+      { "name": "leds", "bit": 5, "x": 447, "y": 480 },
+      { "name": "leds", "bit": 6, "x": 410, "y": 480 },
+      { "name": "leds", "bit": 7, "x": 373, "y": 480 }
+    ]
+  },
+
+  "buttons": [
+    { "name": "btn_pwr",   "shape": "circle", "x": 1375, "y": 401, "r": 42, "key": "p" },
+    { "name": "btn_fire1", "shape": "circle", "x": 406,  "y": 623, "r": 34, "key": "space" },
+    { "name": "btn_fire2", "shape": "circle", "x": 572,  "y": 628, "r": 34, "key": "Return" },
+    { "name": "btn_up",    "shape": "circle", "x": 1210, "y": 777, "r": 36, "key": "Up" },
+    { "name": "btn_down",  "shape": "circle", "x": 1206, "y": 907, "r": 36, "key": "Down" },
+    { "name": "btn_left",  "shape": "circle", "x": 1039, "y": 906, "r": 36, "key": "Left" },
+    { "name": "btn_right", "shape": "circle", "x": 1377, "y": 910, "r": 36, "key": "Right" }
+  ]
+}

fpga_isv-0.1.0/fpga_isv/examples.py

@@ -0,0 +1,39 @@
+"""Locate the bundled example panels.
+
+Each example is a subdirectory of ``examples/`` holding ``<name>.json`` (the board/panel
+config) plus any assets it references (e.g. a board photo). The directory resolves three ways:
+
+  * frozen by PyInstaller     -> ``<_MEIPASS>/fpga_isv/examples`` (see packaging/fpga_isv.spec)
+  * installed / run from src  -> ``<this package dir>/examples``
+"""
+
+import os
+import sys
+
+
+def examples_dir():
+    """Absolute path to the bundled examples directory."""
+    if getattr(sys, "frozen", False) and hasattr(sys, "_MEIPASS"):
+        return os.path.join(sys._MEIPASS, "fpga_isv", "examples")
+    return os.path.join(os.path.dirname(os.path.abspath(__file__)), "examples")
+
+
+def list_examples():
+    """Sorted names of bundled examples (subdirs that contain ``<name>.json``)."""
+    root = examples_dir()
+    if not os.path.isdir(root):
+        return []
+    names = []
+    for name in sorted(os.listdir(root)):
+        if os.path.isfile(os.path.join(root, name, name + ".json")):
+            names.append(name)
+    return names
+
+
+def example_config_path(name):
+    """Path to ``examples/<name>/<name>.json``; raises ValueError if it doesn't exist."""
+    path = os.path.join(examples_dir(), name, name + ".json")
+    if not os.path.isfile(path):
+        available = ", ".join(list_examples()) or "(none bundled)"
+        raise ValueError(f"unknown example {name!r}; available: {available}")
+    return path