--- name: jetson-customize-fan description: >- Use when you need to add, remove, edit, list, or change the boot default of an nvfancontrol fan profile on a Jetson/Tegra (Orin, Thor) target. Triggers: edit fan profile, tune fan curve. version: 0.0.1 license: "Apache-2.0" metadata: data-classification: public author: "Jetson Team" tags: - thermal - fan - nvfancontrol - profile domain: thermal --- # Modify nvfancontrol Fan Profile (BSP-side) ## Purpose Edit the per-board nvfancontrol configuration so the device boots with the desired fan curve / control mode / governor / default profile. BSP-side only — all writes land in the overlay tracker, the upstream `bsp_image` copy is read-only. This skill handles BSP-side edits to the per-board nvfancontrol configuration file: adding profiles, removing profiles, editing the temp → PWM / RPM curves, changing the boot default profile / control mode / governor, and listing defined profiles. Applies on Jetson / Tegra platforms (T234 Orin, T264 Thor). ## File format (canonical, per the BSP file header) ``` POLLING_INTERVAL > TMARGIN FAN_GOVERNOR { STEP_SIZE } FAN_CONTROL { RPM_TOLERANCE } FAN_PROFILE { # TEMP HYST PWM RPM ... } FAN_PROFILE { ... } # one or more profiles THERMAL_GROUP { GROUP_MAX_TEMP # zone-name ... } FAN_DEFAULT_CONTROL FAN_DEFAULT_PROFILE FAN_DEFAULT_GOVERNOR KICKSTART_PWM <0..255> ``` Rules: - **Profile curve tuples are 4-column**: `TEMP HYST PWM RPM`. Sort points by ascending `TEMP`; the daemon interpolates between them. - **`PWM` is `0..255`** (8-bit duty cycle); **`RPM`** is the close-loop target speed. A trailing `0 0` row at the high end pins the fan off above `GROUP_MAX_TEMP`. - **`HYST`** is hysteresis (°C) at that point — the controller waits `HYST` degrees of cooling before stepping the curve down. - **`FAN_DEFAULT_PROFILE`** must reference an existing `FAN_PROFILE` block in the same ``. nvfancontrol fails to start if the default names a missing profile. - **`FAN_DEFAULT_CONTROL`** = `close_loop` (drives toward target RPM, requires tach) or `open_loop` (writes PWM directly). - **`FAN_DEFAULT_GOVERNOR`** = `cont` (continuous interpolation) and other family-specific values; copy verbatim from existing per-board files when introducing one. - **`THERMAL_GROUP`** maps thermal zones to the controller's input. Coefficients are a 20-element CSV — copy verbatim from existing entries; values vary by chip family and zone. - **``** is one block per fan index (typical: ``). Block boundaries `<...>` and `{...}` are strict; preserve indentation matching neighboring lines. - **Curves are characterised, not invented.** Add or edit curves from real thermal-acoustic data for the platform; do not interpolate from neighbouring profiles or copy across chip families. ## Prerequisites Resolve the active profile per [`../../context/target-platform-contract.md`](../../context/target-platform-contract.md). Refuse and route in these cases: | Condition | Refuse with | |---|---| | No active profile, or `active: NA` | Route to `/jetson-set-target` or `/jetson-init-target`. | | Profile lacks `bsp_image:` block | Route to `/jetson-init-image`. | | `/Linux_for_Tegra/` missing | Route to `/jetson-init-image`. | | `/Linux_for_Tegra/` missing or not a git repo | Route to `/jetson-init-source`. | Resolve paths: - `` from `bsp_image.root_path:` if present, else `/Image`. - `` from `source.root_path:` if present, else `/Source`. `` is **read-only** for this skill; every write lands under `` (the overlay tracker). This is the workflow invariant in [`../../context/bsp-customization-workflow.md#workflow-invariants`](../../context/bsp-customization-workflow.md#workflow-invariants) — hand-editing upstream silently destroys the diff trail and makes `/jetson-promote-image` a noop. ## The per-board file The conf this skill edits has the relative path: ``` Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/nvfancontrol_.conf ``` It lives in **two** roots; the skill walks both: | Role | Location | Skill writes? | |---|---|---| | Detection + pristine source | `/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/` | no — read-only | | Overlay edit target + git commit | `/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/` | yes | Subsequent sections refer to **the per-board file** to mean the overlay copy under ``. Operations 1–4 all read, edit, and save against that overlay copy. The `` copy is read once during the "Resolving ``" detection step and once during the [Overlay edit recipe](#overlay-edit-recipe-apply-before-any-operation)'s pristine-import step, then never touched again. ### Resolving `` — which file to edit Filename conventions vary per product family: - `nvfancontrol__.conf` — most Orin parts (e.g. `nvfancontrol_p3767_0000.conf`, `nvfancontrol_p3701_0008.conf`). - `nvfancontrol____.conf` — Thor variants where the carrier disambiguates (e.g. `nvfancontrol_p3834_0008_p4071_0000.conf`). - `nvfancontrol___.conf` — IGX revision variants (e.g. `nvfancontrol_p3740_0002_b01.conf`). The nvfancontrol daemon resolves the right file at startup based on the booted hardware's DT compatible plus board IDs (no helper script — it's done inside the binary). To map BSP-side without a running target, against ``: 1. List `/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/`. 2. Filter to filenames that contain `_` from the active profile. 3. If multiple candidates remain, refine with `_` and (when relevant) the carrier revision tag. 4. If still ambiguous, run the per-board flash conf dispatch chain to read the kernel DTB's `compatible` and pick the file whose name aligns with the resolved board / carrier. 5. Verify the chosen file actually exists under `/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/`. Don't blindly compose a filename — the naming convention varies by product family. ### Propagation set — confs to keep in sync The active-SKU file is rarely the only conf that should carry a customization. After editing it, **apply the same edit to every sibling in the propagation set** so the change survives regardless of which module / baseboard SKU is booted: - **The reference platform's nvfancontrol conf** — the upstream conf the active file was forked from (resolve via `reference_devkit` in the active profile, or `jetson-derive-carrier` fork ancestry). For a BSP that contains only the reference (no derived carriers), this is the same file as the active and the rule reduces to a no-op. - **Every carrier-derived nvfancontrol conf** — each `nvfancontrol_*.conf` produced by `jetson-derive-carrier` for a custom carrier on top of the same module SKU. **"Apply the same edit" ≠ blanket file copy.** Port the changed `FAN_PROFILE` / control lines into each sibling; preserve every other line. Sibling confs often hold carrier-specific deltas (different `THERMAL_GROUP` coefficients for a different thermal solution, different tach `RPM` ceilings) that must stay intact — a blanket overwrite would mis-tune the fan on those carriers. Blanket-copying is safe **only** when both confs were byte-identical before the edit. ## Overlay edit recipe (apply before any Operation) Follow the canonical [Off-skill edits recipe](../../context/bsp-customization-workflow.md#off-skill-edits) in the workflow doc — pristine import + customization commit pair, both gated by the preview gate. Apply once per run, covering every per-board file the run touches (the active conf plus every sibling in the [Propagation set](#propagation-set--confs-to-keep-in-sync)). Concrete substitutions for this skill: - `/` is `rootfs/etc/nvpower/nvfancontrol/`. - Suggested pristine-import message: `import pristine: `, body `Source: /Linux_for_Tegra/ (BSP )`. - Suggested customization-commit header: `jetson-customize-fan: `, body lines like `nvfancontrol_p3767_0000.conf: added FAN_PROFILE static (open-loop, PWM=255 flat), FAN_DEFAULT_CONTROL close_loop -> open_loop, FAN_DEFAULT_PROFILE quiet -> static`. ## Instructions Pick the operation that matches the user's intent and follow the matching subsection. All write-side operations (1–4) must first apply the [Overlay edit recipe](#overlay-edit-recipe-apply-before-any-operation). - Operation 1 — Add a new fan profile. - Operation 2 — Remove a fan profile. - Operation 3 — Edit an existing fan profile (curve, hysteresis). - Operation 4 — Change the boot default (control / profile / governor). - Operation 5 — List defined fan profiles (read-only). After any write-side operation, run the Deploy chain (`## Deploy`) to land the change on the device. ## Examples Add an aggressive profile to a P3767-0000 (Orin Nano dev kit) target and pin it as the boot default: ``` /jetson-customize-fan > add a profile called "aggressive" with the curve {0:255, 40:150, 80:0} > set FAN_DEFAULT_PROFILE to aggressive ``` Soften the fan ramp on the existing `quiet` profile (raise HYST, lower mid-PWM): ``` /jetson-customize-fan > edit FAN_PROFILE quiet — raise HYST to 5 from 30 °C up, drop PWM at 60 °C to 80 ``` List which profiles the active SKU currently defines and which is the boot default: ``` /jetson-customize-fan > list defined fan profiles ``` ## Operation 1 — Add a new fan profile Apply the [Overlay edit recipe](#overlay-edit-recipe-apply-before-any-operation) first. 1. In the per-board file, inside the `` block, add a new `FAN_PROFILE { ... }` between existing profiles. Daemon parse order doesn't matter, but grouping with siblings keeps the file scannable. 2. Pick `` lowercase, no whitespace (e.g. `quiet`, `cool`, `aggressive`). 3. Fill the curve table — 4-column `TEMP HYST PWM RPM` tuples, ascending `TEMP`. End with at least one row above `GROUP_MAX_TEMP` so behavior at over-temp is defined. Example skeleton: ``` FAN_PROFILE aggressive { #TEMP HYST PWM RPM 0 0 255 6000 20 2 255 6000 40 2 150 3500 60 2 50 1500 80 0 0 0 105 0 0 0 } ``` Validate (see Rules): - Every `TEMP` lies within `0..GROUP_MAX_TEMP` of the `THERMAL_GROUP`. - `PWM` ∈ `[0, 255]`; `RPM` ≤ the platform's tach-reported max (varies by fan part). - Tuples are sorted ascending by `TEMP`. If you intend the new profile to be the boot default, follow Operation 4. ## Operation 2 — Remove a fan profile Apply the [Overlay edit recipe](#overlay-edit-recipe-apply-before-any-operation) first. 1. In the per-board file, delete the entire `FAN_PROFILE { ... }` block including all curve rows and the closing `}`. 2. If the deleted `` matches the trailing `FAN_DEFAULT_PROFILE`, point `FAN_DEFAULT_PROFILE` at a remaining profile — otherwise the daemon fails to start. 3. Search for hard-coded references in the rootfs before declaring the change safe: ```bash grep -rn "nvfancontrol.*profile\|FAN_PROFILE" \ Linux_for_Tegra/rootfs/etc 2>/dev/null ``` The remaining profiles do not need renaming. ## Operation 3 — Edit an existing fan profile Apply the [Overlay edit recipe](#overlay-edit-recipe-apply-before-any-operation) first. 1. In the per-board file, modify the curve rows of the target `FAN_PROFILE `. Keep the 4-column `TEMP HYST PWM RPM` shape. 2. Maintain ascending `TEMP` ordering; insert or remove rows as needed. 3. Adjust `HYST` to tune anti-oscillation: too low → fan thrashes near a curve point; too high → fan lags reality. 4. Validate per Operation 1's rules. Edits to `KICKSTART_PWM`, `RPM_TOLERANCE` (inside `FAN_CONTROL`), or `STEP_SIZE` (inside `FAN_GOVERNOR`) sit outside the profiles but tune the same fan; same per-board file. ## Operation 4 — Change the boot default Apply the [Overlay edit recipe](#overlay-edit-recipe-apply-before-any-operation) first. Edit the trailing default lines inside the `` block: ``` FAN_DEFAULT_CONTROL FAN_DEFAULT_PROFILE FAN_DEFAULT_GOVERNOR ``` `FAN_DEFAULT_PROFILE` must reference an existing `FAN_PROFILE` in the same `` block. `FAN_DEFAULT_CONTROL` and `FAN_DEFAULT_GOVERNOR` must reference values the binary supports — copy from existing per-board files when changing. ## Operation 5 — List defined fan profiles This is a read-only operation; no overlay-tracker setup is needed. Run against whichever copy you want to inspect (`/...` for the pristine state, `/...` for the post-edit state): ```bash grep -E '^[[:space:]]*FAN_PROFILE ' grep -E '^[[:space:]]*FAN_DEFAULT_' ``` The first prints every profile name in the file; the second prints the boot defaults (control / profile / governor). ## Limitations - BSP-side scope only — this skill never touches a running target's `/etc/nvpower/nvfancontrol/` directly. Live tuning requires reboot via Deploy, or the side-channel `scp + systemctl restart` flow described in `## Deploy`. - Edits land in the overlay copy under `` only; the `` copy is read-only and is rewritten by `/jetson-promote-image`. Hand-editing `bsp_image` is silently lost on the next `/jetson-init-image` re-extract. - Curve tuples must reflect characterised thermal-acoustic data for the platform — this skill does not interpolate or copy curves across chip families. - Propagation across sibling carriers (same module SKU) is partial by design: only the changed `FAN_PROFILE` / control lines are ported, never a blanket file overwrite, since sibling confs may hold carrier-specific `THERMAL_GROUP` / RPM ceilings. - Curve point limits are family-specific; copy verbatim from existing confs when introducing new `THERMAL_GROUP` coefficients or `FAN_DEFAULT_GOVERNOR` values. ## Troubleshooting | Error | Cause | Solution | |---|---|---| | nvfancontrol.service fails to start after edit | `FAN_DEFAULT_PROFILE` references a profile that was removed or renamed | Set `FAN_DEFAULT_PROFILE` to an existing `FAN_PROFILE ` in the same ``. | | Fan thrashes near a curve point | `HYST` too low | Raise `HYST` on the affected row (typical 2–5 °C). | | Fan lags reality | `HYST` too high | Lower `HYST` on the affected row. | | Fan never spins up at high temp | Curve missing a row above `GROUP_MAX_TEMP`, or trailing `0 0` truncates above ambient | Add a high-temp tuple with non-zero PWM/RPM; pin the over-temp row only above `GROUP_MAX_TEMP`. | | Daemon parse error referencing column count | Curve row not 4-column `TEMP HYST PWM RPM` | Restore 4-column shape; remove trailing whitespace and stray columns. | | `RPM` target never reached in close-loop | Target above tach-reported max, or `FAN_CONTROL` set to `open_loop` | Lower `RPM` to within the fan's mechanical max, or switch `FAN_DEFAULT_CONTROL` to `close_loop`. | | Change vanished after `/jetson-init-image` re-extract | Edit landed in `` instead of `` overlay | Re-apply via the [Overlay edit recipe](#overlay-edit-recipe-apply-before-any-operation) so the change is committed in the overlay tracker. | | Sibling carrier boots with wrong tach ceiling after propagation | Blanket file copy clobbered carrier-specific `THERMAL_GROUP` / `RPM` rows | Port only the changed lines per [Propagation set](#propagation-set--confs-to-keep-in-sync); restore the carrier's original `THERMAL_GROUP`. | ## Deploy The customization commit in the overlay tracker does not reach the device on its own. The Deploy chain: 1. **`/jetson-promote-image`** — copies every tracked file in the overlay into `/Linux_for_Tegra/`. Diff-aware (skip byte-identical); uses `sudo cp -p` for `rootfs/*` destinations. 2. **`/jetson-flash-image`** — flashes the updated `bsp_image` to the device. 3. (Alternate, no flash) Copy `/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/` directly to the running target's `/etc/nvpower/nvfancontrol/`, then `sudo systemctl restart nvfancontrol.service` (or reboot). Editing `/...` without committing — or editing `/...` directly — does nothing for `/jetson-promote-image` and is silently lost on the next `/jetson-init-image` re-extract.