Back to Details

jetson-customize-fan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Modify nvfancontrol Fan Profile (BSP-side)

修改nvfancontrol风扇配置文件（BSP侧）

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).
编辑每个板卡的nvfancontrol配置，使设备启动时使用所需的风扇曲线/控制模式/调控器/默认配置文件。仅限BSP侧操作——所有写入操作都记录在覆盖跟踪器中，上游的
bsp_image
副本为只读状态。
本技能负责处理BSP侧对板卡专属nvfancontrol配置文件的编辑操作：添加配置文件、删除配置文件、编辑温度→PWM/RPM曲线、更改启动默认配置文件/控制模式/调控器，以及列出已定义的配置文件。适用于Jetson/Tegra平台（T234 Orin、T264 Thor）。

File format (canonical, per the BSP file header)

文件格式（标准格式，来自BSP文件头部）

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.
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> { ... }       # 一个或多个配置文件
    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>
规则：
  • 配置曲线元组为4列：
    TEMP HYST PWM RPM
    。按
    TEMP
    升序排列数据点；守护进程会在这些点之间进行插值计算。
  • PWM
    取值范围为
    0..255
    （8位占空比）；**
    RPM
    **是闭环控制的目标转速。在高温端添加一行
    0 0
    可使风扇在超过
    GROUP_MAX_TEMP
    时停止运转。
  • **
    HYST
    **是该点的滞后值（°C）——控制器会等待温度降低
    HYST
    摄氏度后，才会降低风扇转速。
  • **
    FAN_DEFAULT_PROFILE
    **必须引用同一
    <FAN N>
    块中已存在的
    FAN_PROFILE
    块。如果默认配置文件名称指向不存在的配置，nvfancontrol将无法启动。
  • **
    FAN_DEFAULT_CONTROL
    **可选值为
    close_loop
    （向目标转速调整，需要转速计）或
    open_loop
    （直接写入PWM值）。
  • **
    FAN_DEFAULT_GOVERNOR
    **可选值包括
    cont
    （连续插值）以及其他平台专属值；修改时请直接复制现有板卡文件中的值。
  • **
    THERMAL_GROUP
    **将热区映射到控制器的输入。系数为20元素的CSV——直接复制现有条目即可；数值因芯片系列和热区而异。
  • **
    <FAN N>
    **对应每个风扇索引的配置块（通常为
    <FAN 1>
    ）。块边界
    <...>
    和
    {...}
    格式严格；请保持与相邻行一致的缩进。
  • 曲线需基于实测数据，而非凭空生成。添加或编辑曲线时，请使用平台实际的热声学数据；请勿从相邻配置文件插值或跨芯片系列复制曲线。

Prerequisites

前提条件

Resolve the active profile per 
../../context/target-platform-contract.md
. Refuse and route in these cases:
ConditionRefuse 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.
根据
../../context/target-platform-contract.md
确定当前激活的配置文件。在以下情况下拒绝操作并引导至对应流程：
条件拒绝提示并引导至
无激活配置文件，或
active: NA
引导至
/jetson-set-target
或
/jetson-init-target
。
配置文件缺少
bsp_image:
块		引导至
/jetson-init-image
。
<bsp_image.root_path>/Linux_for_Tegra/
不存在		引导至
/jetson-init-image
。
<source.root_path>/Linux_for_Tegra/
不存在或不是git仓库		引导至
/jetson-init-source
。
解析路径：
  • <bsp_image.root_path>
    ：若存在
    bsp_image.root_path:
    则使用该值，否则使用
    <workspace>/Image
    。
  • <source.root_path>
    ：若存在
    source.root_path:
    则使用该值，否则使用
    <workspace>/Source
    。
<bsp_image.root_path>
对本技能而言是只读的；所有写入操作均在
<source.root_path>
（覆盖跟踪器）下进行。这是
../../context/bsp-customization-workflow.md#workflow-invariants
中定义的工作流不变量——手动编辑上游文件会无声破坏差异跟踪，导致
/jetson-promote-image
无法生效。

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:
RoleLocationSkill 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.
本技能编辑的配置文件相对路径为：
Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/nvfancontrol_<active-sku>.conf
该文件存在于两个根目录中；本技能会遍历这两个目录：
角色位置技能是否写入？
检测+原始源文件
<bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/
否——只读
覆盖编辑目标+git提交
<source.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/
是
后续章节中提到的板卡专属文件均指
<source.root_path>
下的覆盖副本。操作1-4均针对该覆盖副本进行读取、编辑和保存。
<bsp_image.root_path>
下的副本仅在"解析
<active-sku>
"检测步骤和覆盖编辑流程的原始导入步骤中读取一次，之后不再触碰。

Resolving 
<active-sku>
— which file to edit

解析
<active-sku>
——确定要编辑的文件

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. List 
    <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/
    .
  2. Filter to filenames that contain 
    <module.id>_<module.sku>
    from the active profile.
  3. If multiple candidates remain, refine with 
    <carrier.id>_<carrier.sku>
    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 
    <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/
    .
Don't blindly compose a filename — the naming convention varies by product family.
文件名规则因产品系列而异：
  • nvfancontrol_<module.id>_<module.sku>.conf
    ——大多数Orin型号（例如
    nvfancontrol_p3767_0000.conf
    、
    nvfancontrol_p3701_0008.conf
    ）。
  • nvfancontrol_<module.id>_<module.sku>_<carrier.id>_<carrier.sku>.conf
    ——Thor变体（需要通过载板区分，例如
    nvfancontrol_p3834_0008_p4071_0000.conf
    ）。
  • nvfancontrol_<carrier>_<sku>_<rev>.conf
    ——IGX修订版变体（例如
    nvfancontrol_p3740_0002_b01.conf
    ）。
nvfancontrol守护进程在启动时会根据已启动硬件的DT兼容属性和板卡ID自动选择正确的文件（无辅助脚本——由二进制文件内部处理）。要在无运行目标的情况下在BSP侧映射文件，请针对
<bsp_image.root_path>
执行以下步骤：
  1. 列出
    <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/
    下的文件。
  2. 筛选包含激活配置文件中
    <module.id>_<module.sku>
    的文件名。
  3. 如果仍有多个候选文件，进一步通过
    <carrier.id>_<carrier.sku>
    和（如适用）载板修订标签进行筛选。
  4. 如果仍存在歧义，运行板卡专属闪存配置调度链读取内核DTB的
    compatible
    属性，并选择名称与解析出的板卡/载板匹配的文件。
  5. 验证所选文件确实存在于
    <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/
    下。
请勿盲目拼接文件名——命名规则因产品系列而异。

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.
激活SKU的文件很少是唯一需要应用自定义的配置文件。编辑完成后，请对同步集合中的所有同级文件应用相同的编辑操作，确保无论启动哪个模块/基板SKU，更改都能生效：
  • 参考平台的nvfancontrol配置文件——激活文件派生自的上游配置文件（通过激活配置文件中的
    reference_devkit
    或
    jetson-derive-carrier
    派生谱系解析）。对于仅包含参考平台（无派生载板）的BSP，该文件与激活文件相同，此规则可简化为无操作。
  • 所有载板派生的nvfancontrol配置文件——每个由
    jetson-derive-carrier
    为同一模块SKU上的自定义载板生成的
    nvfancontrol_*.conf
    文件。
"应用相同的编辑操作"≠全盘复制文件。仅将更改的
FAN_PROFILE
/控制行移植到每个同级文件中；保留其他所有行。同级配置文件通常包含载板专属的差异（例如不同热解决方案的
THERMAL_GROUP
系数、不同的转速计
RPM
上限），这些内容必须保持不变——全盘覆盖会导致这些载板上的风扇调优错误。只有在编辑前两个配置文件字节完全相同时，全盘复制才是安全的。

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>
    is 
    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
    .
遵循工作流文档中的标准离线编辑流程——原始导入+自定义提交配对，均受预览门控。每次运行执行一次，覆盖本次运行涉及的所有板卡专属文件（激活配置文件以及同步集合中的所有同级文件）。
针对本技能的具体替换项：
  • <rel>/<file>
    为
    rootfs/etc/nvpower/nvfancontrol/<conf>
    。
  • 建议的原始导入提交信息：
    import pristine: <逗号分隔的导入配置文件相对路径>
    ，正文为
    Source: <bsp_image.root_path>/Linux_for_Tegra/ (BSP <bsp_image.version>)
    。
  • 建议的自定义提交标题：
    jetson-customize-fan: <摘要>
    ，正文格式示例为
    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.
选择与用户意图匹配的操作，并遵循对应的子章节。所有写入类操作（1-4）必须先执行覆盖编辑流程。
  • 操作1——添加新的风扇配置文件。
  • 操作2——删除风扇配置文件。
  • 操作3——编辑现有风扇配置文件（曲线、滞后值）。
  • 操作4——更改启动默认项（控制模式/配置文件/调控器）。
  • 操作5——列出已定义的风扇配置文件（只读）。
执行任何写入类操作后，运行部署链（
## 部署
）将更改应用到设备上。

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
为P3767-0000（Orin Nano开发套件）目标设备添加一个激进的配置文件，并将其设置为启动默认项：
/jetson-customize-fan
> add a profile called "aggressive" with the curve {0:255, 40:150, 80:0}
> set FAN_DEFAULT_PROFILE to aggressive
柔化现有
quiet
配置文件的风扇转速上升曲线（提高HYST值，降低中等温度下的PWM值）：
/jetson-customize-fan
> edit FAN_PROFILE quiet — raise HYST to 5 from 30 °C up, drop PWM at 60 °C to 80
列出当前激活SKU已定义的配置文件以及启动默认项：
/jetson-customize-fan
> list defined fan profiles

Operation 1 — Add a new fan profile

操作1——添加新的风扇配置文件

Apply the Overlay edit recipe first.
  1. 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.
  2. Pick 
    <name>
    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.
先执行覆盖编辑流程。
  1. 在板卡专属文件的
    <FAN N>
    块内，在现有配置文件之间添加一个新的
    FAN_PROFILE <name> { ... }
    块。守护进程的解析顺序无关紧要，但与同级配置文件分组可提高文件可读性。
  2. <name>
    使用小写字母，无空格（例如
    quiet
    、
    cool
    、
    aggressive
    ）。
  3. 填充曲线表——4列
    TEMP HYST PWM RPM
    元组，按
    TEMP
    升序排列。至少添加一行超过
    GROUP_MAX_TEMP
    的条目，以定义过热时的行为。
示例框架：
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
}
验证（遵循规则）：
  • 所有
    TEMP
    值均在
    THERMAL_GROUP
    的
    0..GROUP_MAX_TEMP
    范围内。
  • PWM
    ∈ 
    [0, 255]
    ；
    RPM
    ≤平台转速计报告的最大值（因风扇型号而异）。
  • 元组按
    TEMP
    升序排列。
如果希望将新配置文件设为启动默认项，请执行操作4。

Operation 2 — Remove a fan profile

操作2——删除风扇配置文件

Apply the Overlay edit recipe first.
  1. In the per-board file, delete the entire 
    FAN_PROFILE <name> { ... }
    block including all curve rows and the closing 
    }
    .
  2. If the deleted 
    <name>
    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.
先执行覆盖编辑流程。
  1. 在板卡专属文件中，删除整个
    FAN_PROFILE <name> { ... }
    块，包括所有曲线行和闭合的
    }
    。
  2. 如果删除的
    <name>
    与
    FAN_DEFAULT_PROFILE
    的值匹配，请将
    FAN_DEFAULT_PROFILE
    指向剩余的某个配置文件——否则守护进程将无法启动。
  3. 在rootfs中搜索硬编码引用，确认更改安全：
    bash
    grep -rn "nvfancontrol.*profile\|FAN_PROFILE" \
  Linux_for_Tegra/rootfs/etc 2>/dev/null
剩余的配置文件无需重命名。

Operation 3 — Edit an existing fan profile

操作3——编辑现有风扇配置文件

Apply the Overlay edit recipe first.
  1. In the per-board file, modify the curve rows of the target 
    FAN_PROFILE <name>
    . 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.
先执行覆盖编辑流程。
  1. 在板卡专属文件中，修改目标
    FAN_PROFILE <name>
    的曲线行。保持4列
    TEMP HYST PWM RPM
    的格式。
  2. 保持
    TEMP
    升序排列；根据需要插入或删除行。
  3. 调整
    HYST
    值以优化防振荡效果：值过低→风扇在曲线点附近频繁启停；值过高→风扇转速调整滞后于实际温度变化。
  4. 根据操作1的规则进行验证。
对
KICKSTART_PWM
、
RPM_TOLERANCE
（位于
FAN_CONTROL
块内）或
STEP_SIZE
（位于
FAN_GOVERNOR
块内）的编辑不属于配置文件的一部分，但会调整同一风扇的参数；操作对象为同一板卡专属文件。

Operation 4 — Change the boot default

操作4——更改启动默认项

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.
先执行覆盖编辑流程。
编辑
<FAN N>
块末尾的默认行：
FAN_DEFAULT_CONTROL  <close_loop|open_loop>
FAN_DEFAULT_PROFILE  <name>
FAN_DEFAULT_GOVERNOR <type>
FAN_DEFAULT_PROFILE
必须引用同一
<FAN N>
块中已存在的
FAN_PROFILE
。
FAN_DEFAULT_CONTROL
和
FAN_DEFAULT_GOVERNOR
必须使用二进制支持的值——修改时请直接复制现有板卡文件中的值。

Operation 5 — List defined fan profiles

操作5——列出已定义的风扇配置文件

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).
这是只读操作；无需设置覆盖跟踪器。可针对任意副本运行（
<bsp_image.root_path>/...
为原始状态，
<source.root_path>/...
为编辑后状态）：
bash
grep -E '^[[:space:]]*FAN_PROFILE ' <per-board file>
grep -E '^[[:space:]]*FAN_DEFAULT_'  <per-board file>
第一条命令会打印文件中的所有配置文件名称；第二条命令会打印启动默认项（控制模式/配置文件/调控器）。

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.
  • 仅限BSP侧范围——本技能绝不会直接修改运行中目标设备的
    /etc/nvpower/nvfancontrol/
    目录。实时调优需要通过部署流程重启设备，或使用
    ## 部署
    中描述的
    scp + systemctl restart
    旁路流程。
  • 编辑操作仅会保存到
    <source.root_path>
    下的覆盖副本中；
    <bsp_image.root_path>
    下的副本为只读，会被
    /jetson-promote-image
    重写。手动编辑
    bsp_image
    会在下次
    /jetson-init-image
    重新提取时无声丢失。
  • 曲线元组必须基于平台实测的热声学数据——本技能不会进行插值计算或跨芯片系列复制曲线。
  • 向同级载板（同一模块SKU）同步更改时会进行部分同步：仅移植更改的
    FAN_PROFILE
    /控制行，绝不会全盘覆盖文件，因为同级配置文件可能包含载板专属的
    THERMAL_GROUP
    /RPM上限。
  • 曲线点限制因产品系列而异；引入新的
    THERMAL_GROUP
    系数或
    FAN_DEFAULT_GOVERNOR
    值时，请直接复制现有配置文件中的值。

Troubleshooting

故障排除

ErrorCauseSolution
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 tempCurve 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 countCurve 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 propagationBlanket file copy clobbered carrier-specific 
THERMAL_GROUP
/ 
RPM
rows		Port only the changed lines per Propagation set; restore the carrier's original 
THERMAL_GROUP
.
错误原因解决方案
编辑后nvfancontrol.service无法启动
FAN_DEFAULT_PROFILE
引用了已删除或重命名的配置文件		将
FAN_DEFAULT_PROFILE
设置为同一
<FAN N>
块中已存在的
FAN_PROFILE <name>
。
风扇在曲线点附近频繁启停
HYST
值过低		提高受影响行的
HYST
值（典型值为2–5 °C）。
风扇转速调整滞后于实际温度变化
HYST
值过高		降低受影响行的
HYST
值。
高温时风扇从未启动曲线缺少超过
GROUP_MAX_TEMP
的行，或末尾的
0 0
行截断在环境温度以上		添加一个高温元组，设置非零的PWM/RPM值；仅在超过
GROUP_MAX_TEMP
时添加停止运转的行。
守护进程解析错误，提及列数问题曲线行不是4列的
TEMP HYST PWM RPM
格式		恢复4列格式；删除尾随空格和多余列。
闭环模式下无法达到
RPM
目标		目标值超过转速计报告的最大值，或
FAN_CONTROL
设置为
open_loop
将
RPM
降低到风扇机械最大值范围内，或将
FAN_DEFAULT_CONTROL
切换为
close_loop
。
/jetson-init-image
重新提取后更改消失		编辑操作写入了
<bsp_image.root_path>
而非
<source.root_path>
的覆盖副本		通过覆盖编辑流程重新应用更改，确保更改提交到覆盖跟踪器中。
同步后同级载板启动时转速上限错误全盘复制文件覆盖了载板专属的
THERMAL_GROUP
/
RPM
行		根据同步集合仅移植更改的行；恢复载板原始的
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 
    <bsp_image.root_path>/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 
    <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.
覆盖跟踪器中的自定义提交不会自动同步到设备上。部署链流程如下：
  1. /jetson-promote-image
    ——将覆盖跟踪器中的所有已跟踪文件复制到
    <bsp_image.root_path>/Linux_for_Tegra/
    中。支持差异识别（跳过字节相同的文件）；对
    rootfs/*
    目标使用
    sudo cp -p
    命令。
  2. /jetson-flash-image
    ——将更新后的
    bsp_image
    刷写到设备上。
  3. （替代方案，无需刷机）将
    <source.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/<conf>
    直接复制到运行中目标设备的
    /etc/nvpower/nvfancontrol/<conf>
    ，然后执行
    sudo systemctl restart nvfancontrol.service
    （或重启设备）。
编辑
<source.root_path>/...
但未提交——或直接编辑
<bsp_image.root_path>/...
——不会对
/jetson-promote-image
产生任何影响，并且会在下次
/jetson-init-image
重新提取时无声丢失。