# ectool 命令参考（中文）

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

## 基本用法

```text
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）。

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

### autofanctrl \<on\>

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

```text
ectool autofanctrl
```

### pwmgetfanrpm [\<index\> | all]

读取风扇转速（RPM）。

```text
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）。

```text
ectool pwmgetduty 0       # 风扇 0，输出如 "Current PWM duty: 50462"（约 77%）
```
百分比 = 数值 / 65535 × 100

### pwmsetduty

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

---

## 温度相关命令

### temps \<sensorid\>

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

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

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

### tempsinfo \<sensorid\>

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

```text
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 安装说明](https://docs.chrultrabook.com/docs/installing/ectool.html)
- [Coolstar CROS-EC 驱动](https://github.com/coolstar/crwindows)