diff --git a/README.md b/README.md index 0f63b50..b78d692 100644 --- a/README.md +++ b/README.md @@ -11,21 +11,137 @@ NVCurve brings MSI Afterburner-style per-point voltage-frequency curve control t > [!WARNING] > **Experimental software.** Undocumented NvAPI functions may change between driver releases. Write operations alter GPU operational parameters. Always run `nvcurve setup` before applying changes. +> [!IMPORTANT] +> **Blackwell GPU Fork** — This is a specialized fork with extended memory offset support (> +1000 MHz) and custom fan curve control for Blackwell GPUs (RTX 50-series). Installing the pre-built PyPI package will NOT include these features. You must build from source. + ![NVCurve curve editor](.github/screenshots/curve-editor.png) -## Installation +## Prerequisites + +- **Linux** with NVIDIA proprietary drivers +- **Python 3.12+** +- **Node.js 18+** and **npm** (for building the React frontend) +- **[uv](https://docs.astral.sh/uv/)** — Python package manager +- **Root/sudo access** (required for GPU hardware interactions) + +## Installation from Source ```bash -uv tool install nvcurve +git clone .git +cd nvcurve + +# Build the React frontend +cd frontend +npm install +npm run build +cd .. + +# Install the Python package (includes bundled frontend) +uv tool install . +``` + +After installation, verify hardware compatibility: + +```bash +nvcurve setup ``` ## Getting Started ```bash -nvcurve setup # Verify hardware compatibility (do not skip) nvcurve # Launch web UI at http://localhost:8042 +nvcurve read # Quick curve read from CLI ``` +## Systemd Service + +Install the daemon for automatic profile loading on boot and optional web server auto-start: + +### Install with web server auto-start + +```bash +nvcurve service install --auto-serve --host 0.0.0.0 --port 8042 +``` + +### Install daemon only (start web server on demand) + +```bash +nvcurve service install +``` + +### Manage + +```bash +nvcurve service start|stop|restart|status +nvcurve service uninstall +``` + +### Reconfigure + +```bash +nvcurve service configure --auto-serve # Enable web server auto-start +nvcurve service configure --no-auto-serve # Disable web server auto-start +nvcurve service configure --host 0.0.0.0 --port 8042 +``` + +### Manual systemd Unit + +If you prefer managing the unit file directly, here is the template installed by `nvcurve service install`: + +```ini +[Unit] +Description=NVCurve NVIDIA GPU V/F Curve Daemon +After=nvidia-persistenced.service +Wants=nvidia-persistenced.service + +[Service] +Type=simple +ExecStart=/usr/bin/python3 -m nvcurve daemon +Restart=on-failure +RestartSec=5 +Environment=PYTHONDONTWRITEBYTECODE=1 + +[Install] +WantedBy=multi-user.target +``` + +Place at `/etc/systemd/system/nvcurve.service`, then: + +```bash +sudo systemctl daemon-reload +sudo systemctl enable --now nvcurve +``` + +### Persistent Configuration + +The daemon reads settings from `/etc/nvcurve/config.json`: + +```json +{ + "host": "127.0.0.1", + "port": 8042, + "auto_serve": false, + "max_delta_khz": 3000000, + "auto_snapshot": true, + "max_snapshots": 20, + "auto_load_profiles": { + "idx:0": "my_profile" + } +} +``` + +| Setting | Description | +|---|---| +| `host` | Web server bind address (`0.0.0.0` for network access) | +| `port` | Web server port (default `8042`) | +| `auto_serve` | Auto-start web server on boot | +| `max_delta_khz` | Safety cap for frequency offsets (default 3000 MHz) | +| `auto_snapshot` | Save snapshot before every write | +| `max_snapshots` | Max snapshots to keep (`0` = unlimited) | +| `auto_load_profiles` | Per-GPU profile to apply on boot (`{gpu_key: profile_name}`) | + +The GPU key can be a UUID, `pci:XXXX`, or `idx:N` fallback. Find your GPU key with `nvcurve gpus`. + ## Documentation - **[Overview](docs/Overview.md)** — What it does, capabilities, architecture @@ -36,7 +152,16 @@ nvcurve # Launch web UI at http://localhost:8042 ## Upgrading ```bash -uv tool upgrade nvcurve +cd nvcurve +git pull +cd frontend && npm run build && cd .. +uv tool install . +``` + +If running as a systemd service: + +```bash +nvcurve service restart ``` ## Changelog diff --git a/docs/Installation.md b/docs/Installation.md index 989c713..ee3fcad 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -2,90 +2,64 @@ This guide covers installing NVCurve from source, including building the frontend. +> [!IMPORTANT] +> **Blackwell GPU Fork** — This repository contains Blackwell-specific features (extended memory offset > +1000 MHz, fan curve control). The pre-built PyPI package does NOT include these. You must build from source. + ## Prerequisites -Make sure your system has the following before proceeding: - -- **Linux** (any distribution) -- **NVIDIA GPU** with proprietary drivers installed +- **Linux** with NVIDIA proprietary drivers - **Python 3.12+** -- **Node.js 18+** and **pnpm** (for frontend development) -- **Root/sudo access** (required for hardware interactions) +- **Node.js 18+** and **npm** +- **[uv](https://docs.astral.sh/uv/)** — Python package manager +- **Root/sudo access** (required for GPU hardware interactions) -## Quick Install (Pre-built) - -The recommended way to install NVCurve for end-use is via [uv](https://docs.astral.sh/uv/): +### Installing uv ```bash -uv tool install nvcurve +curl -LsSf https://astral.sh/uv/install.sh | sh ``` -This installs the CLI tool with the pre-built frontend bundled inside. After installation, verify everything works: +Or via your package manager: ```bash -nvcurve setup +# Arch Linux +sudo pacman -S uv + +# Debian/Ubuntu +pip install uv ``` ## Installation from Source -Building from source is necessary if you want to modify the frontend, contribute to the project, or run a development build. - ### Step 1: Clone the Repository ```bash -git clone https://github.com/your-username/nvcurve.git +git clone .git cd nvcurve ``` -### Step 2: Set Up the Python Environment +### Step 2: Build the Frontend -Create a virtual environment and install the Python dependencies: - -```bash -python -m venv .venv -source .venv/bin/activate -pip install -e . -``` - -Or if you use `uv`: - -```bash -uv venv -source .venv/bin/activate -uv pip install -e . -``` - -### Step 3: Build the Frontend - -The frontend is a React + TypeScript + Vite application located in the `frontend/` directory. - -Navigate to the frontend directory and install its dependencies: +The frontend is a React + TypeScript + Vite application in the `frontend/` directory. ```bash cd frontend -pnpm install -``` - -Build the production bundle: - -```bash -pnpm run build -``` - -This produces a `dist/` directory containing the compiled static assets. The hatch build system automatically includes `frontend/dist` in the Python package under `nvcurve/frontend/dist`. - -### Step 4: Reinstall the Python Package - -After building the frontend, reinstall the Python package so it picks up the new frontend assets: - -```bash +npm install +npm run build cd .. -pip install -e . ``` -### Step 5: Verify the Installation +This produces a `dist/` directory with the compiled static assets. The hatch build system bundles `frontend/dist` into the Python package. -Run the hardware compatibility check: +### Step 3: Install the Python Package + +```bash +uv tool install . +``` + +This installs `nvcurve` as a system-wide tool with the bundled frontend. + +### Step 4: Verify ```bash nvcurve setup @@ -105,7 +79,7 @@ For active frontend development, run the Vite dev server instead of building: ```bash cd frontend -pnpm run dev +npm run dev ``` This starts a hot-reload development server. The backend server runs separately: @@ -117,36 +91,32 @@ nvcurve serve start ## Upgrading -### Pre-built Install - ```bash -uv tool upgrade nvcurve +cd nvcurve +git pull +cd frontend && npm run build && cd .. +uv tool install . ``` -If you're running NVCurve as a systemd service, restart it after upgrading: +If running as a systemd service: ```bash nvcurve service restart ``` -### Source Install - -```bash -git pull -pip install -e . -cd frontend && pnpm install && pnpm run build -cd .. && pip install -e . -``` - ## Troubleshooting ### `nvcurve` command not found -Ensure your virtual environment is activated, or that the package installation directory is on your `PATH`. +Ensure `uv` tools directory is on your `PATH`. After installing `uv`, log out and back in, or run: + +```bash +source ~/.local/bin/env # or wherever uv installed +``` ### Frontend not loading in the web UI -Verify that `frontend/dist` exists and contains built assets. If the directory is empty or missing, rebuild with `pnpm run build` and reinstall the Python package. +Verify that `frontend/dist` exists and contains built assets. If the directory is empty or missing, rebuild with `npm run build` and reinstall with `uv tool install .`. ### NvAPI functions not found @@ -155,3 +125,7 @@ Your NVIDIA driver may not expose the required undocumented functions. Try updat ### Permission denied on hardware operations All hardware-interacting commands require root. The CLI will automatically escalate via `sudo` when needed. If `sudo` is not configured for your user, run commands with `sudo` explicitly. + +### Blackwell memory offset limited to +1000 MHz + +The standard NVCurve on PyPI caps memory offset at +1000 MHz. This fork raises the cap to +3000 MHz for Blackwell GPUs. If you installed from PyPI, uninstall and rebuild from source. diff --git a/docs/Overview.md b/docs/Overview.md index 13dc450..6ae157b 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -16,6 +16,8 @@ NVCurve provides two ways to interact with your GPU: ## Key Capabilities - **Per-Point Curve Editing** — Adjust the frequency offset for any individual voltage point on the V/F curve. +- **Extended Memory Offset** — Memory clock offset up to +3000 MHz (Blackwell GPUs). Standard NVCurve caps at +1000 MHz. +- **Fan Curve Control** — Custom temperature-to-fan-speed curves via NVML, adjustable through the web UI and savable in profiles. - **Curve Flattening** — Select multiple points and flatten them to a common frequency using anchor-point targeting. - **Live Monitoring** — Track GPU voltage, clock speed, temperature, and power draw in real time via NvAPI and NVML. - **Profile Management** — Save, load, and switch between named profiles. Set a default profile that auto-applies on startup.