chromebox-fan-control-win/docs/ectool-commands-zh.md

ectool 命令参考（中文）

ectool 是 Chrome OS 嵌入式控制器（EC）的命令行工具，用于从用户空间与 EC 通信。在刷了 coreboot 的 Chromebox/Chromebook 上，可通过 Coolstar CROS-EC 驱动的 ectool.exe 使用。

基本用法

ectool [选项] <命令> [参数]

常用选项

选项	说明
--dev=n	指定设备号
--interface=dev|i2c|lpc	指定接口类型
--i2c_bus=n	指定 I2C 总线号（如 --i2c_bus=7 使用 /dev/i2c-7），隐含 --interface=i2c
--device=vid:pid	指定 USB 端点（如 18d1:5022）
--name=cros_ec|cros_fp|cros_pd|cros_scp|cros_ish	指定 EC 类型
--ascii	以 ASCII 格式输出

---

风扇相关命令

fanduty [idx] <percent>

强制将风扇 PWM 设为固定占空比（0–100）。

ectool fanduty 75           # 所有风扇 75%
ectool fanduty 0 50         # 风扇 0 设为 50%

autofanctrl <on>

开启 EC 自动风扇转速控制。取消手动 fanduty 后，应调用此命令恢复 EC 自动控速。

ectool autofanctrl

pwmgetfanrpm [<index> | all]

读取风扇转速（RPM）。

ectool pwmgetfanrpm 0     # 读取第 0 号风扇，输出如 "Fan 0 RPM: 2621"
ectool pwmgetfanrpm all   # 读取所有风扇

pwmgetnumfans

显示风扇数量。

pwmsetfanrpm <targetrpm>

设定目标风扇转速（RPM）。部分 EC 支持基于目标转速的控制。

pwmgetduty <pwm_idx> | kb | disp

读取当前 PWM 占空比（16 位，0–65535）。

ectool pwmgetduty 0       # 风扇 0，输出如 "Current PWM duty: 50462"（约 77%）

百分比 = 数值 / 65535 × 100

pwmsetduty

设置 PWM 占空比（16 位）。需配合具体参数使用。

---

温度相关命令

temps <sensorid>

读取指定温度传感器的温度，以及与 fan_off / fan_max 的比值。

ectool temps 0    # 输出如 "Core 336 K (= 63 C) 100% (313 K and 333 K)"

输出为开尔文（K）及摄氏（C）。传感器 ID 因主板而异，用 tempsinfo 查看。

tempsinfo <sensorid>

显示温度传感器信息，用于确认本机支持的传感器 ID 和名称。

ectool tempsinfo 0

---

电源与电池

battery

显示电池信息。

powerinfo

显示电源相关信息。

---

系统与固件

chipinfo

显示 EC 芯片信息。

version

显示 EC 固件版本。

hello

检测与 EC 的基本通信是否正常。

console

显示 EC 调试控制台最新输出。

sysinfo [flags|reset_flags|firmware_copy]

显示系统信息。

---

其他常用命令

switches

显示 EC 开关状态（如盖板、电源等）。

boardversion

显示板级版本。

flashinfo

显示 EC Flash 信息。

rtcget / rtcset

读取/设置 EC 内部 RTC。

led <name> <query|auto|off|color>

控制 LED 颜色或查询亮度范围。

---

与 Chromebox 风扇温控的对应关系

本仓库中的 ChromeboxFanControl 和 FanControl.ChromeboxEC 插件主要使用以下命令：

功能	命令	说明
设定风扇占空比	ectool fanduty <0-100>	手动控速
恢复自动控速	ectool autofanctrl	退出时恢复
读取转速	ectool pwmgetfanrpm 0	显示 RPM
读取温度	ectool temps	从 EC 读取温度

不同主板的 pwmgetfanrpm、temps 参数可能不同，请用 ectool help 和 ectool tempsinfo 确认本机用法。

---

完整命令列表（英文字母序）

命令	说明
adcread <channel>	读取 ADC 通道
addentropy [reset]	向设备秘密添加熵
apreset	发起 AP 复位
autofanctrl <on>	开启自动风扇控制
backlight <enabled>	启用/禁用 LCD 背光
basestate [attach|detach|reset]	强制底座状态
battery	电池信息
batterycutoff [at-shutdown]	切断电池输出
batteryparam	读写板级电池参数
boardversion	板级版本
button [vup|vdown|rec] <Delay-ms>	模拟按键
cbi	读写 Cros Board Info
chargecurrentlimit	设置最大充电电流
chargecontrol	强制停止充电或放电
chargeoverride	覆盖充电口选择逻辑
chargesplash	充电动画相关
chargestate	充电状态 v2+
chipinfo	芯片信息
cmdversions <cmd>	命令版本掩码
console	EC 调试控制台输出
cec	CEC 消息读写
echash [CMDS]	EC hash 相关
eventclear <mask>	清除 EC 主机事件
eventclearb <mask>	清除 EC 主机事件副本 B
eventget	原始 EC 主机事件标志
eventgetb	原始 EC 主机事件标志副本 B
eventgetscimask	SCI 掩码
eventgetsmimask	SMI 掩码
eventgetwakemask	唤醒掩码
eventsetscimask <mask>	设置 SCI 掩码
eventsetsmimask <mask>	设置 SMI 掩码
eventsetwakemask <mask>	设置唤醒掩码
extpwrlimit	外部功率限制
fanduty <percent>	固定风扇 PWM 占空比
flasherase <offset> <size>	擦除 EC Flash
flasheraseasync <offset> <size>	异步擦除 EC Flash
flashinfo	EC Flash 信息
flashspiinfo	EC SPI Flash 信息
flashpd <dev_id> <port> <filename>	通过 PD 刷写
flashprotect [now] [enable|disable]	Flash 写保护
flashread <offset> <size> <outfile>	从 EC Flash 读取
flashwrite <offset> <infile>	写入 EC Flash
forcelidopen <enable>	强制盖板为打开
fpcontext	指纹传感器上下文
fpencstatus	指纹加密引擎状态
fpframe	获取指纹图像
fpinfo	指纹传感器信息
fpmode [mode...]	指纹传感器模式
fpseed	设置 TPM seed
fpstats	指纹匹配时序统计
fptemplate [<infile>|<index>]	添加/导出指纹模板
gpioget <GPIO name>	读取 GPIO
gpioset <GPIO name>	设置 GPIO
hangdetect	挂起检测定时器
hello	检测 EC 通信
hibdelay [sec]	休眠前延时
hostsleepstate	主机睡眠状态
hostevent	主机事件掩码
i2cprotect <port>	I2C 总线保护
i2cread	I2C 读取
i2cspeed <port> [speed]	I2C 总线速率
i2cwrite	I2C 写入
i2cxfer <port> <addr> <read_count> [write bytes...]	I2C 传输
infopddev <port>	USB-C 配件信息
inventory	支持功能列表
kbfactorytest	键盘工厂测试
kbid	键盘 ID
kbinfo	键盘矩阵信息
kbpress	模拟按键
keyscan <beat_us> <filename>	按键扫描测试
led <name> <query|auto|off|color>	LED 控制
lightbar [CMDS]	灯条控制
locatechip <type> <index>	查找芯片地址
mkbpget <buttons|switches>	MKBP 按键/开关
mkbpwakemask	MKBP 唤醒掩码
motionsense [CMDS]	运动传感器
panicinfo	崩溃信息
pause_in_s5 [on|off]	S5 关机时是否暂停
pchg [<port>]	外设充电口
pdcontrol [suspend|resume|reset|disable|on]	PD 芯片控制
pdchipinfo <port>	PD 芯片信息
pdlog	PD 事件日志
pdwritelog <type> <port>	写入 PD 日志
pdgetmode <port>	获取 USB-PD 模式
pdsetmode <port> <svid> <opos>	设置 USB-PD 模式
port80flood	快速写 port 80
port80read	port 80 历史
powerinfo	电源信息
protoinfo	EC 主机协议信息
pse	PoE PSE 端口功率
pstoreinfo	持久存储信息
pstoreread <offset> <size> <outfile>	读取持久存储
pstorewrite <offset> <infile>	写入持久存储
pwmgetfanrpm [<index>|all]	风扇转速
pwmgetkblight	键盘背光百分比
pwmgetnumfans	风扇数量
pwmgetduty	当前 PWM 占空比
pwmsetfanrpm <targetrpm>	设定目标风扇转速
pwmsetkblight <percent>	键盘背光百分比
pwmsetduty	设置 PWM 占空比
rand <num_bytes>	生成随机数
readtest	EC 读取测试
reboot_ec <RO|RW|cold|...>	重启 EC
reboot_ap_on_g3 [<delay>]	G3 后自动重启 AP
rgbkbd ...	RGB 键盘
rollbackinfo	回滚块信息
rtcget	读取 RTC
rtcgetalarm	RTC 闹钟剩余秒数
rtcset <time>	设置 RTC
rtcsetalarm <sec>	设置 RTC 闹钟
rwhashpd	PD MCU rw_hash
rwsig <info|dump|action|status>	RW 签名相关
sertest	串口输出测试
smartdischarge	智能放电参数
stress [reboot] [help]	压力测试
sysinfo [flags|reset_flags|firmware_copy]	系统信息
switches	EC 开关状态
temps <sensorid>	温度传感器读数
tempsinfo <sensorid>	温度传感器信息
thermalget	读取热阈温
thermalset	设置热阈温
tpselftest	触摸板自检
tpframeget	触摸板帧数据
tmp006cal	TMP006 校准
tmp006raw	TMP006 原始数据
typeccontrol <port> <command>	USB PD 策略
typecdiscovery <port> <type>	USB-C 发现信息
typecstatus <port>	USB-C 状态
uptimeinfo	EC 运行时长与 AP 复位
usbchargemode <port> <mode>	USB 充电模式
usbmux <mux>	USB Mux 状态
usbpd	USB PD 控制（已弃用）
usbpddps [enable|disable]	动态 PDO 选择
usbpdmuxinfo [tsv]	USB-C SS Mux 信息
usbpdpower [port]	USB PD 功率
version	EC 版本
waitevent <type> [<timeout>]	等待 MKBP 事件
wireless <flags>	WLAN/蓝牙无线控制

---

常用命令速查（实测 Coolstar ectool）

操作	命令
读取温度	ectool temps 0
读取风扇转速 (RPM)	ectool pwmgetfanrpm 0 或 ectool pwmgetfanrpm all
读取占空比 (16 位)	ectool pwmgetduty 0，百分比 = 数值/65535×100
设置风扇占空比	ectool fanduty 75（所有风扇）或 ectool fanduty 0 50（风扇 0）
设置目标 RPM	ectool pwmsetfanrpm 2000
恢复 EC 自动控速	ectool autofanctrl

---

参考

• Chrultrabook ectool 安装说明
• Coolstar CROS-EC 驱动