diff --git a/Usage-Guide.md b/Usage-Guide.md new file mode 100644 index 0000000..5d0d034 --- /dev/null +++ b/Usage-Guide.md @@ -0,0 +1,204 @@ +This guide covers the day-to-day use of NVCurve, from launching the web UI to managing profiles and using the CLI. + +## First-Time Setup + +Before using NVCurve, always run the hardware compatibility check: + +```bash +nvcurve setup +``` + +This verifies that your GPU and driver support the required NvAPI functions, performs a safe test write, and restores your GPU to its original state. Only proceed if the result is **Compatible**. + +## Web UI + +The web UI is the primary interface for curve editing and monitoring. + +### Launching the Web UI + +```bash +nvcurve +``` + +This starts the backend server and opens your browser at `http://127.0.0.1:8042`. + +### Server Management + +```bash +nvcurve serve start # Start the web server +nvcurve serve start --detach # Start in the background +nvcurve serve status # Check if the server is running +nvcurve serve stop # Stop the server +``` + +### Curve Editor + +The curve editor displays your GPU's V/F curve as an interactive graph with draggable points. + +| Action | How | +|---|---| +| Select a point | Click on it | +| Multi-select | Shift+click to add/remove points | +| Select all active points | Ctrl/Cmd+A | +| Clear selection | Escape | +| Edit a point | Drag it to stage a frequency offset | +| Move multiple points | Drag with multiple points selected | +| Exact value input | Select one point, press Enter | +| Nudge ±1 MHz | Arrow keys (↑ / ↓) | +| Nudge ±10 MHz | Ctrl/Cmd + arrow keys | +| Step through points | Tab / Shift+Tab | +| Box select | Shift+drag on the background | +| Pan the graph | Drag on the background | +| Zoom | Alt+scroll | + +### Point Table + +The point table provides a spreadsheet-like view of all curve points with their frequency, voltage, and offset values. + +| Action | How | +|---|---| +| Select a point | Click a row | +| Toggle selection | Ctrl/Cmd+click | +| Range select | Shift+click or drag across rows | +| Select before/after | Click "Select Before" or "Select After" (appears for single selection) | + +### Toolbar + +The toolbar provides bulk operations: + +- **Global Offset Slider** — Appears when all active points share a uniform delta. Adjusts every point simultaneously. +- **Flatten** — When two or more points are selected, flattens them to the anchor point's frequency. The anchor is the last explicitly clicked point (highlighted with an amber halo). +- **Apply** — Commits staged changes to the GPU. +- **Reset** — Clears all offsets back to zero. + +### Live Monitoring + +The monitoring panel shows real-time GPU metrics: + +- Voltage +- Clock speed +- Temperature +- Power draw + +Data is streamed via WebSocket from the backend at a configurable poll interval (default: 1 second). + +### Multi-GPU + +When multiple NVIDIA GPUs are detected, a GPU selector dropdown appears in the status bar. Switching GPUs resets pending edits, selection state, and monitoring for the new target. + +## CLI Reference + +The CLI is designed for scripting, headless use, and quick operations. All write commands support `--dry-run` to preview changes. + +### Reading the Curve + +```bash +nvcurve read # Condensed V/F curve +nvcurve read --full # All points including zeros +nvcurve read --json # JSON output for scripting +``` + +### Writing Offsets + +```bash +# Preview changes without applying +nvcurve write --global --delta 50 --dry-run +nvcurve write --point 80 --delta 100 --dry-run + +# Apply changes +nvcurve write --global --delta 50 # All active GPU points +nvcurve write --point 80 --delta 100 # Single point +nvcurve write --range 70-90 --delta 75 # Range of points +nvcurve write --reset # Reset all to zero +``` + +> If you use LACT or similar tools, disable them before writing. Concurrent writes will overwrite each other. + +### Snapshots + +Snapshots are saved automatically before every write. You can also manage them manually: + +```bash +nvcurve snapshot save +nvcurve snapshot list +nvcurve snapshot restore +``` + +Snapshots are stored in `/var/cache/nvcurve/snapshots`. + +### Profiles + +Profiles save a named set of curve offsets (plus optional memory offset and power limit settings). Profile commands work whether or not the server is running. + +```bash +nvcurve profile save my_profile # Save current curve state +nvcurve profile apply my_profile # Apply a saved profile +nvcurve profile list # List all profiles +nvcurve profile default my_profile # Set as auto-load on startup +nvcurve profile default --clear # Clear auto-load setting +``` + +Profiles are stored as JSON files in `/etc/nvcurve/profiles`. + +### Diagnostics + +```bash +nvcurve read --diag # Full NvAPI function probe + system info +nvcurve inspect --point 80 # Raw ClockBoostTable fields +nvcurve inspect --range 78-82 # Inspect a range of points +nvcurve gpus # List detected GPUs +``` + +### Global Arguments + +The `--gpu N` flag can be placed before or after any subcommand to target a specific GPU in multi-GPU setups: + +```bash +nvcurve --gpu 1 read +nvcurve read --gpu 1 +nvcurve --gpu 1 profile default perf +``` + +## Systemd Service + +Install NVCurve as a systemd service for automatic profile loading on boot: + +### Install + +```bash +nvcurve service install +``` + +With optional web server auto-start: + +```bash +nvcurve service install --auto-serve --host 0.0.0.0 --port 8042 +``` + +### Manage + +```bash +nvcurve service start +nvcurve service stop +nvcurve service restart +nvcurve service status +nvcurve service uninstall +``` + +### Reconfigure + +```bash +sudo nvcurve service configure --auto-serve +sudo nvcurve service configure --no-auto-serve +sudo nvcurve service configure --host 0.0.0.0 --port 8042 +``` + +## Configuration Files + +| File | Purpose | +|---|---| +| `/etc/nvcurve/config.json` | Persistent config (host, port, auto-serve, default profiles) | +| `/etc/nvcurve/profiles/*.json` | Saved profiles | +| `/var/cache/nvcurve/snapshots/` | Auto-saved snapshots before writes | +| `/run/nvcurve.json` | Runtime server info (host, port, PID) | +| `/etc/systemd/system/nvcurve.service` | Systemd unit file | \ No newline at end of file