| name | mcu-timer-calc |
|---|---|
| description | 计算 8051/STC89 系列单片机定时器初值。当用户询问"51 定时器初值怎么算""TH0/TL0 是多少""定时 10ms 初值是多少""12MHz 12T 方式1 的初值""给定初值能定时多久"，或需要核对一段 8051 定时器初始化代码中的初值是否正确时，应使用本技能调用脚本计算，而不是自行心算。支持方式 0/1/2、12T/6T/1T 分频，输出初值、TH0/TL0 字节、实际定时时间与量化误差。 |
| agent_created | True |
MCU Timer Calc — 8051 定时器初值计算器
用途
按"机器周期 → 计数值 → 初值"的确定性公式，计算 8051 系列单片机（含 STC89 等 12T/6T/1T 兼容型号）定时器的工作初值，并给出实际定时时间与量化误差。
定时器初值涉及机器周期换算与 2^n 补码运算，且方式 0 的 13 位编码（TL0 仅低 5 位） 极易写错。不要凭记忆心算，始终调用本技能提供的脚本。
何时使用
- 用户询问 8051 定时器初值、TH0/TL0 取值、定时时间与初值的换算
- 用户给出晶振频率与目标定时时间，要求生成定时器初始化代码
- 用户给出初值，要求反算实际定时时间
- 需要核对已有代码中
TH0 = 0x..; TL0 = 0x..;的初值是否正确
如何使用
脚本路径：scripts/timer_calc.py，仅依赖 Python 标准库，无需安装任何依赖。
# 由目标定时时间计算初值
python scripts/timer_calc.py --fosc 12MHz --mode 1 --prescaler 12T --time 10ms
# 经典验证：11.0592MHz 晶振 10ms 定时，初值应为 0xDC00
python scripts/timer_calc.py --fosc 11.0592MHz --mode 1 --prescaler 12T --time 10ms
# 由初值反算定时时间
python scripts/timer_calc.py --fosc 12MHz --mode 1 --prescaler 12T --init 55536
# 机器可读输出，便于程序化处理
python scripts/timer_calc.py --fosc 12MHz --mode 1 --prescaler 12T --time 10ms --json
参数说明
| 参数 | 必填 | 说明 |
|---|---|---|
--fosc | 是 | 晶振频率，接受 12MHz / 12M / 11059200 / 8kHz 等写法 |
--mode | 是 | 定时器工作方式，取值 0 / 1 / 2（方式 3 不支持） |
--prescaler | 是 | 分频模式，取值 12T / 6T / 1T |
--time | 二选一 | 目标定时时间，须带单位：ns / us / ms / s |
--init | 二选一 | 定时器初值（反向计算模式） |
--json | 否 | 以 JSON 格式输出 |
退出码
0计算成功2输入非法或超出所选方式的能力范围（错误信息输出到 stderr）
关键约束
- 分频必须显式指定。 标准 8051 为 12T，STC 系列出厂默认 12T，但可通过 STC-ISP 改写为 6T/1T。脚本不设默认值，避免整倍错误。
- 方式 0 是 13 位计数器。 TH0 存高 8 位，TL0 只存低 5 位，写入时勿占高 3 位。
- 方式 2 是 8 位自动重装。 TH0 与 TL0 必须写入同一初值。
- 超出能力范围会报错。 例如方式 1 在 12MHz/12T 下最大只能定时 65.536ms。
- 误差是客观存在的。 目标时间不是机器周期整数倍时必然产生量化误差，脚本会 如实输出误差百分比，误差超过 2% 时给出提示，不隐藏、不"凑整"。
公式依据
机器周期 T = 分频系数 / fosc
计数值 N = round(目标定时时间 / T)
初值 = 2^位数 - N
实际定时时间 = N × T
误差 = (实际 - 目标) / 目标 × 100%
测试
python -m unittest discover -s tests -v
测试覆盖经典手算基准（12MHz/11.0592MHz 等）、三种方式的上边界与越界、量化误差 上报、反向计算往返一致性，以及 CLI 的文本/JSON 输出与退出码。