# Pikvm-studio Setup Detail

Documentation and system management guide for the dedicated studio KVM-over-IP appliance (**`pikvm-studio`**).

* **Repository:** [link](https://git.drheck.dev/luke/pikvm_studio)
* **Hardware Model:** PiKVM V4 Plus (Raspberry Pi Compute Module 4 Rev 1.1)
* **Target Workstation:** `bmo95` (Linux Audio / DAW Workstation)

---

## 1. Video Architecture: 1080p @ 60.000 Hz Pass-Through

PiKVM V4 Plus features a built-in HDMI hardware pass-through port (`OUT2`) and a TC358743 HDMI-to-CSI capture bridge. By default, PiKVM V4 advertises a 1920x1200 EDID. When connected to a standard 1080p physical display, the image would be cropped from the bottom.

### Applied Video Optimizations
1. **1080p EDID Preset (No 1920x1200 Mode):**
   * Imported and applied the `v4plus.no-1920x1200` EDID preset to `/etc/kvmd/tc358743-edid.hex` via `kvmd-edidconf`.
   * Ensures the target host (`bmo95`) negotiates uncropped 1920x1080 @ 60.000 Hz for both remote web streaming and the physical monitor on `OUT2`.
2. **GPU Clock & H.264 60 FPS Boost:**
   * Added `gpu_freq=700` to `/boot/config.txt` to provide sufficient GPU clock headroom for full 60fps hardware H.264 encoding.
   * Configured KVMD streamer overrides in `/etc/kvmd/override.yaml`:
     ```yaml
     kvmd:
         streamer:
             h264_boost: true
             desired_fps:
                 default: 60
     ```

### Physical Wiring
* **HDMI Input (Rear Bottom Right):** Connected to `bmo95` AMD Radeon GPU HDMI output.
* **HDMI Output 2 (`OUT2`):** Connected to the local physical studio monitor (pass-through).
* **USB-C OTG (Rear):** Connected to `bmo95` USB port for keyboard/mouse HID emulation and mass storage drive.
* **RJ45 Ethernet (Front):** Connected to local studio LAN.

---

## 2. Configuration Management: Chezmoi

Configuration files across `/etc` (ext4) and `/boot` (FAT32) are tracked in Git using **[Chezmoi](https://www.chezmoi.io/)**.

### Why Chezmoi on PiKVM?
1. **FAT32 `/boot` Compatibility:** The Raspberry Pi bootloader partition (`/boot`) uses a VFAT filesystem which does not support Linux symlinks. Chezmoi uses a **Source $\rightarrow$ Target Copy Model**, rendering physical files without symlink errors.
2. **Security & Ownership Compliance:** Security-sensitive utilities (such as `sudo` and PAM) require configuration files to be owned by `root:root` with strict permissions (e.g. `0440`). Chezmoi preserves exact permissions and system UIDs rather than pointing symlinks to user-owned directories.
3. **Drift Detection:** `chezmoi diff` provides instant comparison between Git state and the live appliance filesystem.

### Chezmoi Configuration
Located in `/home/luke/.config/chezmoi/chezmoi.yaml`:
```yaml
destDir: "/"
sourceDir: "/home/luke/git/pikvm_studio"
```

### Git History Structure
The repository at [https://git.drheck.dev/luke/pikvm_studio](https://git.drheck.dev/luke/pikvm_studio) maintains a 2-stage commit baseline:
1. `feat(pikvm): baseline vanilla system configuration` — Stock OS overrides, default 1920x1200 EDID, and stock `/boot/config.txt`.
2. `feat(video): configure 1080p60 pass-through, H.264 boost, and GPU frequency` — All active studio customizations.

Running `git diff HEAD~1` clearly documents all modifications relative to factory OS defaults.

---

## 3. PiKVM Read-Only Lifecycle & Chezmoi Workflow

PiKVM OS operates with read-only root (`/`) and boot (`/boot`) partitions to protect flash storage from corruption. When managing configurations with Chezmoi, follow these standard workflows:

### A. Checking for Configuration Drift
To compare the Git repository against the live system:
```bash
chezmoi diff
```

### B. Editing and Applying Changes
To edit a tracked file and deploy it to the live system:
```bash
# 1. Remount filesystem as read-write
sudo rw

# 2. Edit the file in Chezmoi
chezmoi edit /etc/kvmd/override.yaml

# 3. Preview changes
chezmoi diff

# 4. Apply changes to disk
sudo chezmoi apply

# 5. Commit and push to Forgejo
cd ~/git/pikvm_studio
git add .
git commit -S -m "feat: description of change"
gpush pikvm_studio

# 6. Return filesystem to read-only
sudo ro
```

### C. Ingesting Modifications Made Directly on Disk
If a file was modified outside Chezmoi (e.g. via `kvmd-override` or `kvmd-edidconf`):
```bash
sudo rw
chezmoi re-add /etc/kvmd/override.yaml
chezmoi re-add /etc/kvmd/tc358743-edid.hex

cd ~/git/pikvm_studio
git add .
git commit -S -m "feat: update kvmd settings"
gpush pikvm_studio

sudo ro
```

---

## 4. SSH & GPG Key Management

1. **Terminal Pinentry:** `~/.gnupg/gpg-agent.conf` is configured with `pinentry-program /usr/bin/pinentry-curses` to ensure GPG password prompts display cleanly over headless SSH sessions.
2. **Password Store:** Forgejo API tokens (`forgejo/token/*`) are managed via `pass` and pushed using `~/bin/gpush pass`.