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

. 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

— 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'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>

List

<bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/

Filter to filenames that contain
```
<module.id>_<module.sku>
```
from the active profile.
If multiple candidates remain, refine with
```
<carrier.id>_<carrier.sku>
```
and (when relevant) the carrier revision tag.
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.

Verify the chosen file actually exists under

<bsp_image.root_path>/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 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).

Concrete substitutions for this skill:

<rel>/<file>

rootfs/etc/nvpower/nvfancontrol/<conf>

Suggested pristine-import message:

import pristine: <comma-separated rel paths of imported confs>

, body

Source: <bsp_image.root_path>/Linux_for_Tegra/ (BSP <bsp_image.version>)

Suggested customization-commit header:

jetson-customize-fan: <summary>

, 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.

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 first.

In the per-board file, inside the
```
<FAN N>
```
block, add a new
```
FAN_PROFILE <name> { ... }
```
between existing profiles. Daemon parse order doesn't matter, but grouping with siblings keeps the file scannable.
Pick
```
<name>
```
lowercase, no whitespace (e.g.
```
quiet
```
,
```
cool
```
,
```
aggressive
```
).
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 first.

In the per-board file, delete the entire
```
FAN_PROFILE <name> { ... }
```
block including all curve rows and the closing
```
}
```
.
If the deleted
```
<name>
```
matches the trailing
```
FAN_DEFAULT_PROFILE
```
, point
```
FAN_DEFAULT_PROFILE
```
at a remaining profile — otherwise the daemon fails to start.

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 first.

In the per-board file, modify the curve rows of the target
```
FAN_PROFILE <name>
```
. Keep the 4-column
```
TEMP HYST PWM RPM
```
shape.
Maintain ascending
```
TEMP
```
ordering; insert or remove rows as needed.
Adjust
```
HYST
```
to tune anti-oscillation: too low → fan thrashes near a curve point; too high → fan lags reality.
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 first.

Edit the trailing default lines inside the

<FAN N>

block:

FAN_DEFAULT_CONTROL  <close_loop|open_loop>
FAN_DEFAULT_PROFILE  <name>
FAN_DEFAULT_GOVERNOR <type>

FAN_DEFAULT_PROFILE

must reference an existing

FAN_PROFILE

in the same

<FAN N>

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 (

<bsp_image.root_path>/...

for the pristine state,

<source.root_path>/...

for the post-edit state):

bash

grep -E '^[[:space:]]*FAN_PROFILE ' <per-board file>
grep -E '^[[:space:]]*FAN_DEFAULT_'  <per-board file>

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
```
<source.root_path>
```
only; the
```
<bsp_image.root_path>
```
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 <name>` in the same `<FAN N>` .
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 `<bsp_image.root_path>` instead of `<source.root_path>` overlay	Re-apply via the Overlay edit recipe 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; 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:

/jetson-promote-image
— copies every tracked file in the overlay into
```
<bsp_image.root_path>/Linux_for_Tegra/
```
. Diff-aware (skip byte-identical); uses
```
sudo cp -p
```
for
```
rootfs/*
```
destinations.
/jetson-flash-image
— flashes the updated
```
bsp_image
```
to the device.

(Alternate, no flash) Copy

<source.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/<conf>

directly to the running target's

/etc/nvpower/nvfancontrol/<conf>

, then

sudo systemctl restart nvfancontrol.service

(or reboot).

Editing

<source.root_path>/...

without committing — or editing

<bsp_image.root_path>/...

directly — does nothing for

/jetson-promote-image

and is silently lost on the next

/jetson-init-image

re-extract.

jetson-customize-fan

NPX Install

Tags

SKILL.md Content

Modify nvfancontrol Fan Profile (BSP-side)

Purpose

File format (canonical, per the BSP file header)

Prerequisites

The per-board file

Resolving
`<active-sku>`
— which file to edit

Propagation set — confs to keep in sync

Overlay edit recipe (apply before any Operation)

Instructions

Examples

Operation 1 — Add a new fan profile

Operation 2 — Remove a fan profile

Operation 3 — Edit an existing fan profile

Operation 4 — Change the boot default

Operation 5 — List defined fan profiles

Limitations

Troubleshooting

Deploy