mesk 0.1.0__py3-none-any.whl

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/__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/__version__.py

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

mesk/runner.py

@@ -0,0 +1,224 @@
+"""Execute platform power/reset actions via in-process vendor libraries."""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import os
+import sys
+import time
+from datetime import datetime
+from importlib import import_module
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Callable
+
+_VENDOR_ROOT = Path(__file__).resolve().parent / "vendor"
+_log_dir_env = os.environ.get("MESK_LOG_DIR")
+_LOG_DIR = Path(_log_dir_env) if _log_dir_env else Path.cwd() / "logs"
+
+# platform -> (vendor subdirectory, nv_topo target name or None for phidget)
+_PLATFORMS: dict[str, tuple[str, str | None]] = {
+    "concord": ("topo", "topo"),
+    "n1-auto": ("boardctrl_phidget", None),
+    "yukon": ("topo_yukon", "yukon"),
+    "tango": ("topo_yukon", "yukon"),
+}
+
+ACTIONS = ("reset", "recovery", "power_on", "power_off")
+
+_N1_RESET_RELAY = 1
+_N1_RECOVERY_RELAY = 0
+_N1_POWER_RELAY = 2
+
+_NVIDIA_VID = 0x0955
+_CONCORD_APX_PID = 0x7023
+
+_TOPO_MODULE_PREFIXES = (
+    "nvtopo",
+    "libnvtopo_wrapper",
+    "board_info",
+    "_targets",
+)
+
+
+def _module_file(mod: object) -> str | None:
+    path = getattr(mod, "__file__", None)
+    return str(Path(path).resolve()) if path else None
+
+
+def _evict_modules_from(vendor_dir: Path) -> None:
+    prefix = str(vendor_dir.resolve())
+    doomed = []
+    for name, mod in sys.modules.items():
+        file = _module_file(mod)
+        if file is not None and file.startswith(prefix + os.sep):
+            doomed.append(name)
+        elif name in _TOPO_MODULE_PREFIXES or name.startswith("_targets."):
+            doomed.append(name)
+    for name in doomed:
+        sys.modules.pop(name, None)
+
+
+def _activate_vendor_path(vendor_dir: Path) -> None:
+    path = str(vendor_dir)
+    sys.path = [p for p in sys.path if p != path]
+    sys.path.insert(0, path)
+
+
+def _load_vendor_module(vendor_subdir: str, module_name: str) -> ModuleType:
+    vendor_dir = _VENDOR_ROOT / vendor_subdir
+    _evict_modules_from(vendor_dir)
+    _activate_vendor_path(vendor_dir)
+    return import_module(module_name)
+
+
+def _load_nv_topo(vendor_subdir: str) -> Callable[..., Any]:
+    nvtopo = _load_vendor_module(vendor_subdir, "nvtopo")
+    return nvtopo.nv_topo
+
+
+def _load_monitor() -> ModuleType:
+    return _load_vendor_module("boardctrl_phidget", "monitor")
+
+
+def _run_topo(vendor_subdir: str, target: str, action: str) -> None:
+    nv_topo = _load_nv_topo(vendor_subdir)
+    board = nv_topo(target=target)
+    if action == "reset":
+        board.target_reset(None)
+    elif action == "recovery":
+        board.target_recovery_mode(None)
+    elif action == "power_on":
+        board.target_power_on(None)
+    else:
+        board.target_power_off()
+
+
+def _run_n1_auto(action: str) -> None:
+    monitor = _load_monitor()
+    lock = Path("/tmp/phidget.lock")
+
+    if action in ("reset", "recovery"):
+        print("Cleaning up any existing Phidget processes...")
+        print("Removing any stale lock files...")
+
+    try:
+        lock.unlink()
+    except OSError:
+        pass
+
+    if action == "reset":
+        if not monitor.ResetControl(_N1_RESET_RELAY).execute_reset():
+            raise RuntimeError("n1-auto reset failed")
+        print("Reset sequence completed successfully")
+        print("Soft RESET performed")
+    elif action == "recovery":
+        if not monitor.RecoveryControl(
+            _N1_RESET_RELAY, _N1_RECOVERY_RELAY
+        ).execute_recovery():
+            raise RuntimeError("n1-auto recovery failed")
+        print("Recovery sequence completed successfully")
+        print("Board is now in RECOVERY")
+    else:
+        desired_closed = action == "power_off"
+        ctl = monitor.PowerMonitor(_N1_POWER_RELAY, desired_closed)
+        if not ctl.initialize():
+            raise RuntimeError("n1-auto power control failed to initialize")
+        try:
+            print(
+                f"Controlling power relay ({_N1_POWER_RELAY})"
+                " - Normally Open configuration"
+            )
+            if desired_closed:
+                print("Closing circuit (turning power OFF)...")
+                ctl.phidget.relay_on(_N1_POWER_RELAY)
+            else:
+                print("Opening circuit (turning power ON)...")
+                ctl.phidget.relay_off(_N1_POWER_RELAY)
+            time.sleep(0.1)
+            if desired_closed:
+                print("Power circuit is CLOSED (OFF)")
+                print("SOC power OFF")
+            else:
+                print("Power circuit is OPEN (ON)")
+                print("SOC power ON")
+        finally:
+            ctl.cleanup()
+
+
+def _nvidia_usb_devices() -> list[Any]:
+    import usb.core
+
+    found = usb.core.find(find_all=True, idVendor=_NVIDIA_VID)
+    return list(found) if found else []
+
+
+def _verify_concord_recovery() -> None:
+    """Confirm APX (0955:7023) after Concord recovery; boardctl status is unreliable."""
+    devices: list[Any] = []
+    for _ in range(5):
+        devices = _nvidia_usb_devices()
+        if any(int(dev.idProduct) == _CONCORD_APX_PID for dev in devices):
+            break
+        time.sleep(1)
+    print("lsusb check (NVIDIA 0955:*):")
+    if devices:
+        for dev in devices:
+            pid = int(dev.idProduct)
+            label = " NVIDIA Corp. APX" if pid == _CONCORD_APX_PID else ""
+            print(f"  0955:{pid:04x}{label}")
+    else:
+        print("  (none)")
+    if not any(int(dev.idProduct) == _CONCORD_APX_PID for dev in devices):
+        raise RuntimeError(
+            "Concord recovery check failed: 0955:7023 (APX) not found in lsusb"
+        )
+    print("enter into recovery mode pass")
+
+
+def _dispatch(platform: str, action: str) -> None:
+    vendor_subdir, target = _PLATFORMS[platform]
+    if target is None:
+        _run_n1_auto(action)
+        return
+    _run_topo(vendor_subdir, target, action)
+    if platform == "concord" and action == "recovery":
+        _verify_concord_recovery()
+
+
+def _exit_code(exc: SystemExit) -> int:
+    if exc.code is None:
+        return 0
+    if isinstance(exc.code, int):
+        return exc.code
+    return 1
+
+
+def run(platform: str, action: str) -> int:
+    """Execute an action on the given platform. Returns 0 on success."""
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    buf = io.StringIO()
+    code = 0
+    try:
+        with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
+            _dispatch(platform, action)
+    except SystemExit as exc:
+        if exc.code not in (None, 0):
+            buf.write(f"{exc.code}\n")
+        code = _exit_code(exc)
+    except Exception as exc:
+        buf.write(f"{type(exc).__name__}: {exc}\n")
+        code = 1
+
+    output = buf.getvalue()
+    print(output, end="")
+
+    _LOG_DIR.mkdir(parents=True, exist_ok=True)
+    log_file = _LOG_DIR / (timestamp[:10] + ".log")
+    with open(log_file, "a", encoding="utf-8") as f:
+        f.write(f"[{timestamp}] platform={platform} action={action} exit_code={code}\n")
+        f.write(output)
+        f.write("\n")
+
+    return code

mesk/vendor/boardctrl_phidget/README.md

@@ -0,0 +1,244 @@
+# Phidget Relay Control Suite
+
+This project provides a robust, scriptable interface for controlling Phidget relay devices, supporting operations such as reset, recovery, and power cycling. It is designed for safe, automated hardware control, with both Python and shell script interfaces.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [File Structure](#file-structure)
+- [Setup](#setup)
+- [Usage](#usage)
+  - [phidget_control.sh](#phidget_controlsh)
+  - [monitor.py](#monitorpy)
+  - [phidget.py](#phidgetpy)
+- [Detailed Code Reference](#detailed-code-reference)
+  - [monitor.py](#monitorpy-1)
+  - [phidget.py](#phidgetpy-1)
+  - [phidget_control.sh](#phidget_controlsh-1)
+- [Extending and Maintaining](#extending-and-maintaining)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+This suite is intended for environments where Phidget relay boards are used to control hardware (e.g., for automated testing, power cycling, or recovery operations). It provides:
+
+- Safe, exclusive access to the hardware (via lock files)
+- High-level operations (reset, recovery, power control)
+- Low-level relay control and detection
+- Easy command-line interface with environment setup
+
+---
+
+## File Structure
+
+```
+monitor.py           # High-level control and monitoring logic
+phidget.py           # Low-level Phidget relay interface
+phidget_control.sh   # User-facing shell script for all operations
+```
+
+---
+
+## Setup
+
+1. **Install Python 3** (if not already installed).
+2. **Run the shell script**:  
+   ```bash
+   ./phidget_control.sh [command] [options]
+   ```
+   The script will automatically create a virtual environment and install the required Python package (`Phidget22`).
+
+---
+
+## Usage
+
+### phidget_control.sh
+
+This is the main entry point for users. It supports the following commands:
+
+- `detect` — Detect connected Phidget relays.
+- `relay [on|off|toggle] <relay_num>` — Control a specific relay.
+- `sequence "<relay:action,...>"` — Execute a sequence of relay actions.
+- `reset` — Perform a reset sequence (Relay 1).
+- `recovery` — Perform a recovery sequence (Relays 0 & 1).
+- `poweron` / `poweroff` — Control the power relay (Relay 2).
+
+**Examples:**
+```bash
+./phidget_control.sh detect
+./phidget_control.sh relay on 1
+./phidget_control.sh sequence "1:on,2:off"
+./phidget_control.sh reset
+./phidget_control.sh poweroff
+```
+
+### monitor.py
+
+This script provides high-level operations and should not be run directly except for advanced use. It supports:
+
+- `reset <relay_num>`
+- `recovery <reset_relay> <recovery_relay>`
+- `power <relay_num> <true|false>`
+
+**Example:**
+```bash
+python3 monitor.py reset 1
+python3 monitor.py recovery 1 0
+python3 monitor.py power 2 true
+```
+
+### phidget.py
+
+This is a library for direct relay control. It can also be run directly for testing relay sequences.
+
+**Example:**
+```bash
+python3 phidget.py -seq "1:on,2:off"
+```
+
+---
+
+## Detailed Code Reference
+
+### monitor.py
+
+#### Classes
+
+- **BaseMonitor**
+  - Handles device locking (`/tmp/phidget.lock`) to prevent concurrent access.
+  - Manages Phidget device initialization and cleanup.
+  - Methods:
+    - `acquire_lock()`: Ensures exclusive access to the device.
+    - `release_lock()`: Releases the lock and cleans up.
+    - `cleanup()`: Closes the Phidget device and releases the lock.
+    - `initialize()`: Acquires lock and initializes the Phidget device.
+
+- **ResetControl(BaseMonitor)**
+  - For performing a reset sequence on a specified relay.
+  - Methods:
+    - `execute_reset()`: Closes and then opens the relay, simulating a reset pulse.
+
+- **RecoveryControl(BaseMonitor)**
+  - For performing a recovery sequence involving two relays.
+  - Methods:
+    - `execute_reset()`: (Internal) Performs a reset while recovery relay is held.
+    - `execute_recovery()`: Closes recovery relay, performs reset, then opens recovery relay.
+
+- **PowerMonitor(BaseMonitor)**
+  - Maintains a relay in a desired state (on/off) in a loop.
+  - Methods:
+    - `maintain_state()`: Continuously checks and restores the relay state.
+
+#### Main Script Logic
+
+- Parses command-line arguments to select the operation (`reset`, `recovery`, `power`).
+- Instantiates the appropriate control class and executes the requested operation.
+
+---
+
+### phidget.py
+
+#### Classes and Functions
+
+- **PhidgetDevice**
+  - Represents a Phidget device (not heavily used in the rest of the code).
+  - Attributes: `name`, `serial_number`, `channels`.
+
+- **Phidget**
+  - Main interface to the Phidget relay hardware.
+  - Attributes:
+    - `relays`: Dictionary of relay objects (0-3).
+  - Methods:
+    - `initialize_relays()`: Initializes up to 4 relays.
+    - `relay_on(relay_num)`: Turns a relay ON (closes circuit).
+    - `relay_off(relay_num)`: Turns a relay OFF (opens circuit).
+    - `relay_toggle(relay_num)`: Toggles relay state.
+    - `execute_sequence(sequence)`: Executes a comma-separated sequence of relay actions.
+    - `close()`: Closes all relay connections.
+    - `detect_all()`: Static method to detect which relays are connected.
+
+- **between(s, opat, cpat, last_closing)**
+  - Utility function to extract a substring between two delimiters (not used elsewhere).
+
+#### Main Script Logic
+
+- Supports command-line arguments for serial number and relay sequence.
+- Can be used to test relay sequences directly.
+
+---
+
+### phidget_control.sh
+
+#### Key Features
+
+- **Environment Setup**
+  - Creates a Python virtual environment if not present.
+  - Installs the `Phidget22` library if missing.
+
+- **Command Functions**
+  - `detect_devices()`: Uses `phidget.py` to list connected relays.
+  - `control_relay(action, relay)`: Turns a relay on, off, or toggles it.
+  - `execute_sequence(sequence)`: Runs a sequence of relay actions.
+  - `execute_reset()`: Runs a reset sequence using `monitor.py`.
+  - `execute_recovery()`: Runs a recovery sequence using `monitor.py`.
+  - `control_power(action)`: Maintains the power relay in the desired state using `monitor.py` in the background.
+
+- **Process and Lock Management**
+  - Kills any running `monitor.py` processes before starting new operations.
+  - Removes stale lock files to prevent deadlocks.
+
+- **User Guidance**
+  - Provides colored output and usage instructions for ease of use.
+
+---
+
+## Extending and Maintaining
+
+- **Adding New Operations:**  
+  Add new methods to `monitor.py` (inheriting from `BaseMonitor` if needed), and expose them via `phidget_control.sh`.
+
+- **Relay Mapping:**  
+  Update relay numbers in `phidget_control.sh` as needed for your hardware.
+
+- **Error Handling:**  
+  Both Python and shell scripts print detailed error messages. For more robust error handling, consider logging errors to a file.
+
+- **Dependencies:**  
+  The only Python dependency is `Phidget22`. If you add more, update the install section in the shell script.
+
+- **Testing:**  
+  You can test new relay sequences directly using `phidget.py` before integrating them into higher-level scripts.
+
+---
+
+## Troubleshooting
+
+- **Device Busy/Locked:**  
+  If you see errors about the device being in use, ensure no other process is running and remove `/tmp/phidget.lock` if necessary.
+
+- **Phidget22 Not Installed:**  
+  The shell script should handle this, but you can manually install with `pip install Phidget22` in the `venv`.
+
+- **Relay Not Responding:**  
+  Use the `detect` command to check relay connectivity.
+
+---
+
+## Contact
+
+For further information, refer to the [Phidget Python API documentation](https://www.phidgets.com/docs/Language_-_Python).
+
+---
+
+**For any issues, contact:**
+
+**Ekjot Singh**  
+eksingh@nvidia.com
+
+---
+
+This README should provide a comprehensive reference for using, maintaining, and extending your Phidget relay control suite. If you need a more visual diagram or have specific questions about enhancements, let me know!