/jetson-customize-fan

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 <seconds>

<FAN <index>>
    TMARGIN <ENABLED|DISABLED>
    FAN_GOVERNOR <type> {
        STEP_SIZE <int>
    }
    FAN_CONTROL <close_loop|open_loop> {
        RPM_TOLERANCE <rpm>
    }
    FAN_PROFILE <name> {
        # TEMP HYST PWM RPM
        <T0> <H0> <P0> <R0>
        ...
    }
    FAN_PROFILE <name> { ... }       # one or more profiles
    THERMAL_GROUP <id> {
        GROUP_MAX_TEMP <C>
        # zone-name <coeffs csv> <max-temp>
        <zone> <coeffs> <max-temp>
        ...
    }
    FAN_DEFAULT_CONTROL  <close_loop|open_loop>
    FAN_DEFAULT_PROFILE  <name>
    FAN_DEFAULT_GOVERNOR <type>
    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 `<FAN N>`. 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.
• **`<FAN N>`** is one block per fan index (typical: `<FAN 1>`). 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`. | | `<bsp_image.root_path>/Linux_for_Tegra/` missing | Route to `/jetson-init-image`. | | `<source.root_path>/Linux_for_Tegra/` missing or not a git repo | Route to `/jetson-init-source`. |

Resolve paths:

• `<bsp_image.root_path>` from `bsp_image.root_path:` if present, else `<workspace>/Image`.
• `<source.root_path>` from `source.root_path:` if present, else `<workspace>/Source`.

`<bsp_image.root_path>` is **read-only** for this skill; every write lands under `<source.root_path>` (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_<active-sku>.conf

It lives in **two** roots; the skill walks both:

| Role | Location | Skill writes? | |---|---|---| | Detection + pristine source | `<bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/` | no — read-only | | Overlay edit target + git commit | `<source.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/` | yes |

Subsequent sections refer to **the per-board file** to mean the overlay copy under `<source.root_path>`. Operations 1–4 all read, edit, and save against that overlay copy. The `<bsp_image.root_path>` copy is read once during the "Resolving `<active-sku>`" 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 `<active-sku>` — which file to edit

Filename conventions vary per product family:

• `nvfancontrol_<module.id>_<module.sku>.conf` — most Orin parts (e.g. `nvfancontrol_p3767_0000.conf`, `nvfancontrol_p3701_0008.conf`).
• `nvfancontrol_<module.id>_<module.sku>_<carrier.id>_<carrier.sku>.conf` — Thor variants where the carrier disambiguates (e.g. `nvfancontrol_p3834_0008_p4071_0000.conf`).
• `nvfancontrol_<carrier>_<sku>_<rev>.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 `<bsp_image.root_path>`:

1