chromebox-fan-control-win/README.md

Chromebox Fan Control (Windows)

Read CPU core temperature via LibreHardwareMonitor, set fanduty through Coolstar crosec's ectool, and read fan RPM from ectool. The UI shows three real-time charts: temperature, target duty, and RPM. On Chromebox with coreboot.

Background

My Acer Chromebox CXI4 has only a board-mounted temperature sensor; there is no sensor near the CPU. On Chrome OS, the kernel uses CPU core temperature for fan control and thermal management works well. After flashing coreboot, Linux also uses CPU core temp for fan control. On Windows, however, the system relies on the motherboard temperature sensor for fan control, not CPU temperature. During sudden high load, heat has not yet reached the board sensor when the CPU already overheats, causing Windows to shut down before the fan can respond. I tried configuring coreboot, recompiling the EC firmware, and other approaches—none succeeded in connecting CPU core temperature to Chromebox EC fan control. Hence this project.

Also included: FanControl.ChromeboxEC — a plugin for Fan Control (Rémi Mercier) that adds Chromebox EC fan control. Use this if you prefer Fan Control’s UI and curve editor.

Fan Control setup

1. Install plugin: Copy FanControl.ChromeboxEC.dll to Fan Control's Plugins folder; start Fan Control as Administrator.
2. Recommended config: CPU core temp + board temp (EC Temp) dual curves, take max to set fan.
   • Create curve CPU Package: temp source = CPU Package, output 0–100% duty.
   • Create curve Board Temp: temp source = Chromebox EC Temperature, output 0–100% duty.
   • Create Mix curve: function = Max, inputs = both curves above.
   • Set Chromebox EC Fan control to use Mix curve.

See FanControl.ChromeboxEC README for details.

Dependencies

1. Install Coolstar CROS-EC driver (or your crosec package). The default executable is:
   C:\Program Files\crosec\ectool.exe
   Change it in the program’s Advanced tab if needed.
2. Run as Administrator (manifest requests elevation; LHM and EC access usually need admin).
3. Deployment: .\build.ps1 -publish (and with -msi) defaults to self-contained single-file, including .NET 8 runtime. dist\ has only a few exes. Use -multiFile or -frameworkDependent to avoid bundling the runtime.

Build

.\build.ps1

Publish MSI installer (recommended)

.\build.ps1 -publish -msi

-publish produces dist\; -msi uses WiX to build installers (requires WiX). Two MSIs are produced:

File	Description
dist-installer\ChromeboxFanControl-Setup.msi	Desktop: GUI + optional Windows service (checkbox in feature tree)
dist-installer\ChromeboxFanControlService-Setup.msi	Service only: background service for headless deployment

Build machine needs .NET 8 SDK and WiX Toolset 3. Close ChromeboxFanControl.exe before building.

Run the MSI as Administrator. If ectool is not installed yet, see Chrultrabook ectool installation. See also ectool 命令参考（中文）. In service mode, config is read from %ProgramData%\ChromeboxFanControl\config.json.

Publish to dist\ only (debugging or manual packaging)

Command	Description
.\build.ps1 -publish	Publish both desktop and service to dist\ (single-file by default)
.\build.ps1 -publishGui	Desktop only
.\build.ps1 -publishService	Service only, merged into dist\
.\build.ps1 -publish -multiFile	Keep multiple DLLs (instead of single exe)
.\build.ps1 -publish -frameworkDependent	Rely on system .NET 8 (no bundled runtime)

Configuration

• appsettings.json beside the install directory: default options.
• %AppData%\ChromeboxFanControl\config.json: user config; saved from GUI in desktop mode.
• %ProgramData%\ChromeboxFanControl\config.json: used in Windows service mode; can share config with GUI.

Important fields:

Field	Description
Language	UI language: auto (system), en, zh-Hans, zh-Hant. Restart to apply.
RampUpSteps	Steps for gradual fan speed change (1–10, default 3).
RampUpMinDeltaPercent	Change below this % is applied in one step (0–50, default 20).
FanRpmArgs	ectool args to read RPM (default pwmgetfanrpm 0). Check with ectool help for your board.
FanDutyArgs	ectool args to read duty (e.g. pwmget 0); empty = skip, show target duty.
AutoFanCtrlArgs	Command to restore EC auto fan on exit (default autofanctrl).
TempSource	AverageCore or MaxCore.
CurvePoints	14 duty values 0–100 for temp breakpoints 0,40,45,…,100°C (linear interpolation).

Usage

• Tray icon after startup. Pause control to stop sending fanduty; EC keeps the last state.
• On exit, the program tries to run the auto fan restore command (see config).
• After several consecutive CPU temp read failures, fail-safe mode activates (fixed duty or autofanctrl, see UI options).

Disclaimer

Software is provided “as is”. Incorrect fan settings may cause overheating or hardware damage; use at your own risk.

License

Original code written for this project. Fan curve logic follows the public description in Chrultrabook-Tools; no GPL source code was copied.

---

中文 / Chinese

在刷了 coreboot 的 Chromebox 上，用 LibreHardwareMonitor 读取 CPU 核心温度，通过 Coolstar crosec 自带的 ectool 设置 fanduty，并从 ectool 读取 风扇转速（RPM）。主界面提供三条实时曲线：温度、目标占空比、转速。

项目缘由

Acer Chromebox CXI4 仅配有板载温度传感器，CPU 附近没有独立测温点。Chrome OS 和刷 coreboot 后的 Linux 都能用 CPU 核心温度驱动风扇，温控正常；而 Windows 只认主板传感器，高负载下热量未传到主板时 CPU 就已过热，系统直接关机，风扇反应不及。我试过改 coreboot、重编 EC 固件等办法，仍无法让 CPU 温度直接参与 EC 控扇。加之本人曾重编 EC 解除长期 25W 功耗墙以跑高性能，发热压力更大，传统控扇更显不足。于是有了这个项目。

另含 FanControl.ChromeboxEC 插件，用于 Fan Control，可在 Fan Control 中控制 Chromebox EC 风扇。

Fan Control 配置说明

1. 安装插件：将 FanControl.ChromeboxEC.dll 复制到 Fan Control 的 Plugins 文件夹，以管理员身份启动 Fan Control。
2. 推荐配置：CPU 核心温度 + 板载温度（EC Temp）双曲线，取最大值设置风扇。
   • 新建曲线 CPU Package：温度源选「CPU Package」，输出 0–100% 占空比。
   • 新建曲线 Board Temp：温度源选「Chromebox EC Temperature」，输出 0–100% 占空比。
   • 新建 Mix 曲线：函数选「最大」，输入上述两条曲线。
   • 将 Chromebox EC Fan 控制的曲线设为 Mix。

详见 FanControl.ChromeboxEC 说明。

依赖

1. 安装 Coolstar CROS-EC 驱动（或您当前使用的 crosec 安装包），确保存在默认可执行文件：
   C:\Program Files\crosec\ectool.exe
   若路径不同，在程序「高级」选项卡中修改。
2. 以管理员身份运行本程序（清单已要求提升权限；LHM 与 EC 通信通常需要管理员）。
3. 客户机：.\build.ps1 -publish（及带 -msi 时）默认自包含单文件发布，已内含 .NET 8 运行时，dist\ 仅含数个 exe，无需再装运行时。若需多 DLL 或依赖系统 .NET 8 以减小体积，可加 -multiFile 或 -frameworkDependent。

编译

.\build.ps1

发布 MSI 安装包（推荐）

.\build.ps1 -publish -msi

-publish 只生成 dist\；加上 -msi 才用 WiX 生成安装包（需已安装 WiX）。输出两个 MSI：

文件	说明
dist-installer\ChromeboxFanControl-Setup.msi	桌面版：GUI + 可选 Windows 服务（功能树中可勾选）
dist-installer\ChromeboxFanControlService-Setup.msi	服务版：仅后台服务，适合无头部署

构建机需 .NET 8 SDK 与 WiX Toolset 3。构建前请关闭正在运行的 ChromeboxFanControl.exe。

以管理员身份运行 MSI。若尚未安装 ectool，可访问 Chrultrabook 的 ectool 安装说明。另见 ectool 命令参考。服务模式下配置从 %ProgramData%\ChromeboxFanControl\config.json 读取。

仅发布到 dist\（用于调试或手动打包）

命令	说明
.\build.ps1 -publish	同时发布桌面版与服务版到 dist\（默认单文件）
.\build.ps1 -publishGui	仅发布 GUI
.\build.ps1 -publishService	仅发布服务并合并进 dist\
.\build.ps1 -publish -multiFile	保留多 DLL 输出（默认单 exe）
.\build.ps1 -publish -frameworkDependent	依赖系统 .NET 8（无 bundled 运行时）

配置

• 安装目录旁的 appsettings.json：默认选项。
• %AppData%\ChromeboxFanControl\config.json：GUI 模式下保存后覆盖（用户配置）。
• %ProgramData%\ChromeboxFanControl\config.json：Windows 服务模式下读取的配置；可与 GUI 共用同一份配置逻辑。

重要字段：

项	说明
Language	界面语言：auto（跟随系统）、en、zh-Hans、zh-Hant。修改后需重启生效。
RampUpSteps	升/降速分步数（1–10，默认 3）。
RampUpMinDeltaPercent	变化幅度低于此百分比则一步到位（0–50，默认 20）。
FanRpmArgs	读取转速时传给 ectool 的参数（默认 pwmgetfanrpm 0），请用本机 ectool help 核对。
FanDutyArgs	读取占空比时传给 ectool 的参数（如 pwmget 0）；空则跳过，显示目标占空比。
AutoFanCtrlArgs	退出程序时恢复 EC 自动风扇（默认 autofanctrl），若命令名不同请修改。
TempSource	AverageCore 或 MaxCore。
CurvePoints	14 个 0–100 的占空比控制点（对应温度断点 0,40,45,…,100°C，线性插值）。

使用说明

• 启动后任务栏托盘有图标；可「暂停控制」（不再下发 fanduty，EC 保持上次状态）。
• 退出或关闭前会尝试执行 自动风扇恢复命令（见配置）。
• 若连续多次读不到 CPU 温度，将进入安全模式（固定占空比或 autofanctrl，见界面选项）。

免责声明

软件按「原样」提供。错误的风扇策略可能导致过热或硬件损坏；请自行承担使用风险。

许可

本项目为实现计划而编写的原创代码；风扇曲线算法行为参考 Chrultrabook-Tools 的公开逻辑描述，未复制其 GPL 源码。