mesk 0.1.0__tar.gz

mesk-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: mesk
+Version: 0.1.0
+Summary: Unified power and reset control for Concord, N1-auto, Yukon, and Tango platforms
+Author-email: Miley Zhang <mileyz@nvidia.com>
+License-Expression: LicenseRef-NvidiaProprietary
+Project-URL: Repository, https://gitlab-master.nvidia.com/mileyz/mesk
+Keywords: nvidia,board,reset,power,ci
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: System :: Hardware
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pyusb
+Provides-Extra: dev
+Requires-Dist: ruff==0.16.6; extra == "dev"
+Requires-Dist: ty==0.0.78; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest==8.3.1; extra == "test"
+Requires-Dist: pytest-cov==5.0.0; extra == "test"
+Requires-Dist: pytest-timeout==2.3.1; extra == "test"
+Requires-Dist: pytest-xdist==3.6.1; python_version >= "3.9" and extra == "test"
+Requires-Dist: coverage==7.6.0; extra == "test"
+Provides-Extra: n1-auto
+Requires-Dist: Phidget22; extra == "n1-auto"
+
+# mesk
+
+Unified power and reset control for Concord, N1-auto, Yukon, and Tango platforms.
+Designed for use in DLA compiler CI/CD pipelines.
+
+## Install and run
+
+```bash
+git clone https://gitlab-master.nvidia.com/mileyz/mesk.git
+cd mesk
+./mesk concord power_off
+./mesk concord power_on
+./mesk concord reset
+./mesk concord recovery
+```
+
+On Windows (Yukon / Tango), from cmd or PowerShell:
+
+```bat
+git clone https://gitlab-master.nvidia.com/mileyz/mesk.git
+cd mesk
+.\mesk yukon power_off
+.\mesk yukon power_on
+.\mesk yukon reset
+.\mesk yukon recovery
+```
+
+First run creates `.venv` and installs the package. Later runs skip that.
+Do not activate the venv yourself; `./mesk` (Linux) and `.\mesk` (Windows `mesk.cmd`) do that.
+On Linux, the first `./mesk concord <action>` writes `/etc/sudoers.d/mesk` (prompts for sudo once) so all later runs are passwordless. Set `MESK_NO_SUDO=1` to skip sudo entirely.
+`./mesk n1-auto ...` installs `Phidget22` into the venv if it is missing.
+
+Developers who want lint/test tools can still use:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,test]"
+```
+
+**Examples:**
+
+```bash
+mesk concord reset
+mesk concord recovery
+mesk concord power_on
+mesk concord power_off
+
+mesk n1-auto reset
+mesk n1-auto recovery
+mesk n1-auto power_on
+mesk n1-auto power_off
+
+mesk yukon reset
+mesk yukon recovery
+mesk yukon power_on
+mesk yukon power_off
+
+mesk tango reset
+mesk tango recovery
+mesk tango power_on
+mesk tango power_off
+```
+
+## Library Usage
+
+```python
+from mesk import run
+
+run("concord", "reset")
+run("n1-auto", "power_on")
+run("yukon", "recovery")
+run("tango", "reset")
+```
+
+`run()` returns 0 on success and a non-zero exit code on failure.
+
+## Project Layout
+
+```
+mesk/
+├── pyproject.toml           # build config + all tool settings
+├── setup.py                 # legacy pip editable compatibility
+├── mesk                     # Linux/L4T bootstrap launcher
+├── mesk.cmd                 # Windows bootstrap launcher
+├── .pre-commit-config.yaml
+├── README.md
+├── src/mesk/
+│   ├── __init__.py          # public API: run, ACTIONS, __version__
+│   ├── __version__.py
+│   ├── __main__.py          # CLI entry
+│   ├── runner.py            # action execution + logging
+│   ├── py.typed
+│   └── vendor/              # bundled board control tools
+│       ├── topo/            # Concord (boardctl)
+│       ├── boardctrl_phidget/  # N1-auto
+│       └── topo_yukon/      # Yukon and Tango (boardctl)
+└── tests/
+```
+
+## Logging
+
+Each run appends to `logs/YYYY-MM-DD.log` under the current working directory
+(timestamp, platform, action, exit code, and full output).
+Override with `MESK_LOG_DIR`.
+
+## Prerequisites
+
+Actions call vendor Python APIs in-process (`import`), not shell/`subprocess`.
+
+### Concord (Linux host)
+
+- Needs the NVIDIA TOPO USB device (`0955:7045`). The first run of `./mesk concord <action>` installs a NOPASSWD sudoers rule automatically; subsequent runs need no password.
+- `pyusb` is installed with mesk for recovery detection.
+- After `concord recovery`, mesk checks USB for `0955:7023` (APX) and fails if it is missing. boardctl may still print `NOT IN RECOVERY MODE`.
+
+### N1-auto (Linux host)
+
+`./mesk n1-auto <action>` installs `Phidget22` into the venv and, if needed, `libphidget22` via apt (sudo). Set `MESK_NO_SUDO=1` to skip the system-library install.
+
+### Yukon / Tango (Windows host)
+
+`.\mesk yukon <action>` or `.\mesk tango <action>` creates `.venv` and installs mesk on first run. Needs Python 3.8+ on PATH (or `py -3`) and the TOPO USB device. No sudo.
+
+## Platforms & Supported Operations
+
+| Action | Concord (L4T) | N1-auto (Auto-Linux) | Yukon / Tango (WoA) |
+|--------|---------------|----------------------|---------------------|
+| `reset` | `nv_topo(target="topo").target_reset()` | `ResetControl(1).execute_reset()` | `nv_topo(target="yukon").target_reset()` |
+| `recovery` | `nv_topo(target="topo").target_recovery_mode()` | `RecoveryControl(1, 0).execute_recovery()` | `nv_topo(target="yukon").target_recovery_mode()` |
+| `power_on` | `nv_topo(target="topo").target_power_on()` | `PowerMonitor(2, False)` then `relay_off(2)` | `nv_topo(target="yukon").target_power_on()` |
+| `power_off` | `nv_topo(target="topo").target_power_off()` | `PowerMonitor(2, True)` then `relay_on(2)` | `nv_topo(target="yukon").target_power_off()` |
+
+Tango uses the same `topo_yukon` `nv_topo` target as Yukon (`target="yukon"`).
+N1-auto power is a one-shot relay set (no background `monitor.py` process).
+
+## Contribute
+
+Suggested local Python: 3.12+ (pre-commit assumes > 3.8 for `pytest -n auto`).
+
+pre-commit runs Ruff (format + lint), ty, and pytest. All of these skip
+`vendor/` directories (bundled third-party board tools) so upstream trees
+are not rewritten and can be replaced as drop-in upgrades.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,test]"
+pip install pre-commit
+pre-commit install
+# Optionally run all hooks
+pre-commit run --all-files
+```
+
+```bash
+pytest
+ruff check .
+ty check
+```
+
+## Test Status
+
+| Platform | reset | power_on | power_off | recovery |
+|----------|-------|----------|-----------|----------|
+| Concord (L4T) | PASS | PASS | PASS | PASS* |
+| N1-auto (Auto-Linux) | PASS | PASS | PASS | PASS |
+| Yukon (WoA) | PASS | PASS | PASS | PASS |
+| Tango (WoA) | same as Yukon | same as Yukon | same as Yukon | same as Yukon |
+
+\* Concord recovery is checked in-process for USB `0955:7023` (APX).

mesk-0.1.0/README.md

@@ -0,0 +1,170 @@
+# mesk
+
+Unified power and reset control for Concord, N1-auto, Yukon, and Tango platforms.
+Designed for use in DLA compiler CI/CD pipelines.
+
+## Install and run
+
+```bash
+git clone https://gitlab-master.nvidia.com/mileyz/mesk.git
+cd mesk
+./mesk concord power_off
+./mesk concord power_on
+./mesk concord reset
+./mesk concord recovery
+```
+
+On Windows (Yukon / Tango), from cmd or PowerShell:
+
+```bat
+git clone https://gitlab-master.nvidia.com/mileyz/mesk.git
+cd mesk
+.\mesk yukon power_off
+.\mesk yukon power_on
+.\mesk yukon reset
+.\mesk yukon recovery
+```
+
+First run creates `.venv` and installs the package. Later runs skip that.
+Do not activate the venv yourself; `./mesk` (Linux) and `.\mesk` (Windows `mesk.cmd`) do that.
+On Linux, the first `./mesk concord <action>` writes `/etc/sudoers.d/mesk` (prompts for sudo once) so all later runs are passwordless. Set `MESK_NO_SUDO=1` to skip sudo entirely.
+`./mesk n1-auto ...` installs `Phidget22` into the venv if it is missing.
+
+Developers who want lint/test tools can still use:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,test]"
+```
+
+**Examples:**
+
+```bash
+mesk concord reset
+mesk concord recovery
+mesk concord power_on
+mesk concord power_off
+
+mesk n1-auto reset
+mesk n1-auto recovery
+mesk n1-auto power_on
+mesk n1-auto power_off
+
+mesk yukon reset
+mesk yukon recovery
+mesk yukon power_on
+mesk yukon power_off
+
+mesk tango reset
+mesk tango recovery
+mesk tango power_on
+mesk tango power_off
+```
+
+## Library Usage
+
+```python
+from mesk import run
+
+run("concord", "reset")
+run("n1-auto", "power_on")
+run("yukon", "recovery")
+run("tango", "reset")
+```
+
+`run()` returns 0 on success and a non-zero exit code on failure.
+
+## Project Layout
+
+```
+mesk/
+├── pyproject.toml           # build config + all tool settings
+├── setup.py                 # legacy pip editable compatibility
+├── mesk                     # Linux/L4T bootstrap launcher
+├── mesk.cmd                 # Windows bootstrap launcher
+├── .pre-commit-config.yaml
+├── README.md
+├── src/mesk/
+│   ├── __init__.py          # public API: run, ACTIONS, __version__
+│   ├── __version__.py
+│   ├── __main__.py          # CLI entry
+│   ├── runner.py            # action execution + logging
+│   ├── py.typed
+│   └── vendor/              # bundled board control tools
+│       ├── topo/            # Concord (boardctl)
+│       ├── boardctrl_phidget/  # N1-auto
+│       └── topo_yukon/      # Yukon and Tango (boardctl)
+└── tests/
+```
+
+## Logging
+
+Each run appends to `logs/YYYY-MM-DD.log` under the current working directory
+(timestamp, platform, action, exit code, and full output).
+Override with `MESK_LOG_DIR`.
+
+## Prerequisites
+
+Actions call vendor Python APIs in-process (`import`), not shell/`subprocess`.
+
+### Concord (Linux host)
+
+- Needs the NVIDIA TOPO USB device (`0955:7045`). The first run of `./mesk concord <action>` installs a NOPASSWD sudoers rule automatically; subsequent runs need no password.
+- `pyusb` is installed with mesk for recovery detection.
+- After `concord recovery`, mesk checks USB for `0955:7023` (APX) and fails if it is missing. boardctl may still print `NOT IN RECOVERY MODE`.
+
+### N1-auto (Linux host)
+
+`./mesk n1-auto <action>` installs `Phidget22` into the venv and, if needed, `libphidget22` via apt (sudo). Set `MESK_NO_SUDO=1` to skip the system-library install.
+
+### Yukon / Tango (Windows host)
+
+`.\mesk yukon <action>` or `.\mesk tango <action>` creates `.venv` and installs mesk on first run. Needs Python 3.8+ on PATH (or `py -3`) and the TOPO USB device. No sudo.
+
+## Platforms & Supported Operations
+
+| Action | Concord (L4T) | N1-auto (Auto-Linux) | Yukon / Tango (WoA) |
+|--------|---------------|----------------------|---------------------|
+| `reset` | `nv_topo(target="topo").target_reset()` | `ResetControl(1).execute_reset()` | `nv_topo(target="yukon").target_reset()` |
+| `recovery` | `nv_topo(target="topo").target_recovery_mode()` | `RecoveryControl(1, 0).execute_recovery()` | `nv_topo(target="yukon").target_recovery_mode()` |
+| `power_on` | `nv_topo(target="topo").target_power_on()` | `PowerMonitor(2, False)` then `relay_off(2)` | `nv_topo(target="yukon").target_power_on()` |
+| `power_off` | `nv_topo(target="topo").target_power_off()` | `PowerMonitor(2, True)` then `relay_on(2)` | `nv_topo(target="yukon").target_power_off()` |
+
+Tango uses the same `topo_yukon` `nv_topo` target as Yukon (`target="yukon"`).
+N1-auto power is a one-shot relay set (no background `monitor.py` process).
+
+## Contribute
+
+Suggested local Python: 3.12+ (pre-commit assumes > 3.8 for `pytest -n auto`).
+
+pre-commit runs Ruff (format + lint), ty, and pytest. All of these skip
+`vendor/` directories (bundled third-party board tools) so upstream trees
+are not rewritten and can be replaced as drop-in upgrades.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,test]"
+pip install pre-commit
+pre-commit install
+# Optionally run all hooks
+pre-commit run --all-files
+```
+
+```bash
+pytest
+ruff check .
+ty check
+```
+
+## Test Status
+
+| Platform | reset | power_on | power_off | recovery |
+|----------|-------|----------|-----------|----------|
+| Concord (L4T) | PASS | PASS | PASS | PASS* |
+| N1-auto (Auto-Linux) | PASS | PASS | PASS | PASS |
+| Yukon (WoA) | PASS | PASS | PASS | PASS |
+| Tango (WoA) | same as Yukon | same as Yukon | same as Yukon | same as Yukon |
+
+\* Concord recovery is checked in-process for USB `0955:7023` (APX).

mesk-0.1.0/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+requires = ["setuptools >= 60"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mesk"
+dynamic = ["version"]
+authors = [
+    {name = "Miley Zhang", email = "mileyz@nvidia.com"},
+]
+description = "Unified power and reset control for Concord, N1-auto, Yukon, and Tango platforms"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "LicenseRef-NvidiaProprietary"
+keywords = ["nvidia", "board", "reset", "power", "ci"]
+classifiers = [
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Hardware",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pyusb",
+]
+
+[project.urls]
+Repository = "https://gitlab-master.nvidia.com/mileyz/mesk"
+
+[project.optional-dependencies]
+dev = [
+    "ruff == 0.16.6",
+    "ty == 0.0.78",
+]
+test = [
+    "pytest == 8.3.1",
+    "pytest-cov == 5.0.0",
+    "pytest-timeout == 2.3.1",
+    "pytest-xdist == 3.6.1; python_version >= '3.9'",
+    "coverage == 7.6.0",
+]
+n1-auto = [
+    "Phidget22",
+]
+
+[project.scripts]
+mesk = "mesk.__main__:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["mesk*"]
+exclude = [
+    "mesk.vendor.boardctrl_phidget.venv*",
+]
+
+[tool.setuptools.package-data]
+"*" = ["*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "mesk.__version__"}
+
+[tool.ty.environment]
+python-version = "3.8"
+
+[tool.ty.src]
+include = ["src"]
+exclude = ["src/mesk/vendor", "src/vendor"]
+
+[tool.ty.terminal]
+error-on-warning = false
+
+[tool.ruff]
+src = ["src"]
+target-version = "py38"
+# Third-party vendor trees; keep them unmodified for drop-in upgrades.
+extend-exclude = ["src/mesk/vendor", "src/vendor"]
+
+[tool.ruff.lint]
+ignore = [
+    # Below ignored to avoid conflict with Ruff format
+    # Refer https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules
+    "W191",   # tab-indentation
+    "E111",   # indentation-with-invalid-multiple
+    "E114",   # indentation-with-invalid-multiple-comment
+    "E117",   # over-indented
+    "D206",   # indent-with-spaces
+    "D300",   # triple-single-quotes
+    "Q000",   # bad-quotes-inline-string
+    "Q001",   # bad-quotes-multiline-string
+    "Q002",   # bad-quotes-docstring
+    "Q003",   # avoidable-escaped-quote
+    "COM812", # missing-trailing-comma
+    "COM819", # prohibited-trailing-comma
+    "ISC001", # single-line-implicit-string-concatenation
+    "ISC002", # multi-line-implicit-string-concatenation
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+norecursedirs = [".*", "build", "dist", "vendor"]
+
+[tool.coverage.paths]
+source = ["src/"]
+
+[tool.coverage.run]
+source = ["src/mesk"]
+relative_files = true
+omit = ["tests/*", "src/mesk/vendor/*", "src/vendor/*"]
+
+[tool.coverage.report]
+exclude_lines = ["NotImplementedError", "pragma: no cover"]
+
+[tool.coverage.json]
+pretty_print = true

mesk-0.1.0/setup.cfg

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

mesk-0.1.0/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

mesk-0.1.0/src/mesk/__init__.py

@@ -0,0 +1,10 @@
+"""Unified power and reset control for Concord, N1-auto, Yukon, and Tango platforms."""
+
+from .__version__ import __version__
+from .runner import ACTIONS, run
+
+__all__ = [
+    "ACTIONS",
+    "run",
+    "__version__",
+]

mesk-0.1.0/src/mesk/__main__.py

@@ -0,0 +1,80 @@
+"""CLI entry point for mesk."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from mesk.runner import _PLATFORMS, ACTIONS, run
+
+_SUDO_PLATFORMS = frozenset({"concord"})
+
+
+def _needs_sudo(platform: str) -> bool:
+    if platform not in _SUDO_PLATFORMS:
+        return False
+    if os.environ.get("MESK_NO_SUDO"):
+        return False
+    try:
+        return os.geteuid() != 0
+    except AttributeError:
+        return False
+
+
+def _reexec_with_sudo() -> None:
+    os.execvp("sudo", ["sudo", sys.executable, "-m", "mesk", *sys.argv[1:]])
+
+
+def _phidget_lib_present() -> bool:
+    from ctypes.util import find_library
+
+    return find_library("phidget22") is not None
+
+
+def _ensure_libphidget22() -> None:
+    if _phidget_lib_present():
+        return
+    if os.environ.get("MESK_NO_SUDO"):
+        raise RuntimeError("libphidget22 is missing; install it or unset MESK_NO_SUDO")
+    import subprocess
+
+    print("Installing libphidget22 (may prompt for sudo)...")
+    apt = subprocess.run(["sudo", "apt-get", "install", "-y", "libphidget22"])
+    if apt.returncode == 0 and _phidget_lib_present():
+        return
+    print("Adding Phidget apt repository...")
+    setup = subprocess.run(
+        ["curl", "-fsSL", "https://www.phidgets.com/downloads/setup_linux"],
+        check=True,
+        stdout=subprocess.PIPE,
+    )
+    subprocess.run(["sudo", "bash"], input=setup.stdout, check=True)
+    subprocess.check_call(["sudo", "apt-get", "install", "-y", "libphidget22"])
+    if not _phidget_lib_present():
+        raise RuntimeError("libphidget22 is still missing after install")
+
+
+def _ensure_phidget22() -> None:
+    import importlib.util
+    import subprocess
+
+    if importlib.util.find_spec("Phidget22") is None:
+        print("Installing Phidget22 into this environment...")
+        subprocess.check_call([sys.executable, "-m", "pip", "install", "Phidget22"])
+    _ensure_libphidget22()
+
+
+def main() -> None:
+    platforms = list(_PLATFORMS)
+    if len(sys.argv) != 3 or sys.argv[1] not in platforms or sys.argv[2] not in ACTIONS:
+        print(f"Usage: mesk <{'|'.join(platforms)}> <{'|'.join(ACTIONS)}>")
+        sys.exit(1)
+    if sys.argv[1] == "n1-auto":
+        _ensure_phidget22()
+    if _needs_sudo(sys.argv[1]):
+        _reexec_with_sudo()
+    sys.exit(run(sys.argv[1], sys.argv[2]))
+
+
+if __name__ == "__main__":
+    main()

mesk-0.1.0/src/mesk/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"