IronOS 焊台固件设置菜单深度解析：完整参数指南与固件设置系统实现

• 嵌入式
• 固件
• 硬件开发
• 智能硬件

本文基于 IronOS 仓库中自动生成的设置菜单文档 Documentation/Settings.md，逐一讲解焊台设置菜单中五大分类下全部设置项的含义、在机帮助文本与取值范围，并结合 source/Settings/settings.yaml、source/Core/Inc/Settings.h 等源码，剖析这些设置项在固件中如何被定义、存储到 Flash、以及通过仓库自带工具离线读写。读完本文后，你可以理解每个设置项背后的默认值与硬件约束，并能用仓库工具为 TS100/Pinecil/Pinecil V2/MHP30 等设备批量生成设置文件。

一、文档来源：自动生成的设置菜单参考

Documentation/Settings.md 文件头部注明：

<!-- This is an automatically generated file. DO NOT EDIT. Edit gen_menu_docs.py instead -->

也就是说，这份“设置菜单字典”并非手写维护，而是由 Translations/gen_menu_docs.py 从两个数据源自动拼装生成：

• Translations/translations_definitions.json：定义每个菜单组（menuGroups）、每个菜单项（menuOptions）的英文描述，以及该菜单项在哪些硬件条件下可见（如include: ["POW_PD"]、exclude: ["NO_SLEEP_MODE"]）；
• Translations/translation_EN.json：提供菜单项显示名称与“在机帮助文本”（description）。

生成脚本main()按“头部 → 菜单分类 → 菜单项”三段式写入文件，因此文档中的“On device help text”与设备上实际滚动显示的提示文本完全同源。这带来一个实用结论：当固件新增或修改设置项时，文档会随之自动更新，文档与设备行为天然保持一致。

文档同时给出两条通用使用说明，适用于所有设置项：

1. 并非所有设置对每个设备都可见。例如 TS100 没有 USB-PD 设置。从定义文件可见，可见性由编译期硬件特性控制：POW_DC（DC 供电）、POW_QC（QC3.0）、POW_PD（USB-PD）、HALL_SENSOR（霍尔传感器）、BLE_ENABLED、PROFILE_SUPPORT（多阶段预热 Profile 模式）、NO_SLEEP_MODE、NO_DISPLAY_ROTATE等特性开关决定某个设置项是否出现在对应设备的菜单里。
2. 在机上求助：停留在某个设置项上不做任何操作，延迟片刻后屏幕上会滚动显示该设置项的帮助文本，即文档中所称的 “on device help text”。

二、菜单分类（Menu Categories）

设置菜单被划分为五个大类以保持列表可管理（分类定义来自translations_definitions.json的menuGroups）：

三、全部设置项详解（按分类继承文档并补充取值）

以下逐条继承 Documentation/Settings.md 的设置说明，并在“取值/默认值”一列结合 source/Settings/settings.yaml（设置项定义的唯一可读来源）补充范围与默认值。

3.1 电源类（Power settings）

Power source（DC 低电压截止）设备由电池/DC 供电时，调整单元关闭加热以保护电池的低压阈值。 在机帮助文本：Set cutoff voltage to prevent battery overdischarge (DC=10V) (S=3.3V per cell, disable PWR limit)对应设置MinDCVoltageCells：取值 0–4（默认CUT_OUT_SETTING，即默认“禁用限制”语义的截止档位）。

Minimum voltage（单格最低电压）电池供电时，关机前允许的每格最低电压（实际值 = 该值 × 电池串数）。 在机帮助文本：Minimum allowed voltage per battery cell (3S: 3 - 3.7V | 4-6S: 2.4 - 3.7V)对应MinVoltageCells：取值 24–38，默认RECOM_VOL_CELL（单位 0.1V/格）。

QC voltage（QC3.0 目标电压）调整 QC 协商允许达到的最大电压；不影响 USB-PD。应根据电源适配器的电流额定值安全设置。 在机帮助文本：Max QC voltage the iron should negotiate for对应QCIdealVoltage：默认 90（即 9.0V），范围 90–QC_VOLTAGE_MAX，步长 2（单位 0.1V）。

PD timeout（USB-PD 协商超时）固件停止尝试 USB-PD 协商、转而去尝试 QC 前的等待时长，单位为 100ms。更长的超时可能兼容老旧/劣质 PD 适配器，更短则更快回退到 QC。文档建议保持较小值。 在机帮助文本：PD negotiation timeout in 100ms steps for compatibility with some QC chargers对应PDNegTimeout：默认 20（2 秒），范围 0–50。

PD Mode（USB-PD 工作模式）调整 USB-PD 逻辑选择电压的方式：No Dynamic 禁用 EPR 与 PPS 协议；Safe 模式不使用压降补偿电阻（会选出略低的电压）。 在机帮助文本：No Dynamic disables EPR & PPS, Safe mode does not use padding resistance对应USBPDMode：0–2，默认 0。source/Core/Inc/Settings.h 中枚举usbpdMode_t明确了语义：NO_DYNAMIC=0（仅固定 PDO，禁 PPS/EPR）、DEFAULT=1（PPS+EPR，并通过约 +0.5Ω 的压降补偿请求更高电压以补偿线缆/PCB 损耗）、SAFE=2（PPS+EPR，不做补偿请求）。

3.2 焊接类（Soldering settings）

Boost temp（Boost 温度）焊接模式下长按设备前端按钮可临时把温度覆盖到该值。注意它是设定温度而非在现值上叠加。 在机帮助文本：Tip temperature used in "boost mode"对应BoostTemp：默认BOOST_TEMP，步长 10，上限MAX_TEMP_F。

Start-up behaviour（开机行为）决定通电后进入哪种模式：直接进入焊接模式、睡眠模式，或自动模式（首次检测到移动才进入焊接）。 在机帮助文本：S=heat to soldering temp | Z=standby at sleep temp until moved | R=standby without heating until moved对应AutoStartMode：0–3，默认AUTO_START_MODE。source/Core/Inc/Settings.h 中autoStartMode_t给出四种取值：OFF（禁用）、SOLDER（加热到焊接温度）、SLEEP（以睡眠温度待机，移动后激活）、ZERO（只上电不加热，移动后激活）。

Temp change short（短按温变步长）快速按一下按钮时温度改变的步长。 在机帮助文本：Temperature-change-increment on short button press对应TempChangeShortStep：1–TEMP_CHANGE_SHORT_STEP_MAX，步长 1。

Temp change long（长按温变步长）按住按钮不放时温度改变的步长。 在机帮助文本：Temperature-change-increment on long button press对应TempChangeLongStep：5–TEMP_CHANGE_LONG_STEP_MAX，步长 5。

Allow locking buttons（允许锁定按键）是否启用按键防误触锁定。 在机帮助文本：While soldering, hold down both buttons to toggle locking them (B=boost mode only | F=full locking)对应LockingMode：0–2，默认 0。lockingMode_t枚举：DISABLED=0（不锁定）、BOOST=1（仅锁定 Boost 键）、FULL=2（Boost 与焊接模式全锁定）。

Profile 系列设置（多阶段预热模式，仅PROFILE_SUPPORT设备）Profile 模式让焊台按“预热 → 阶段 1…5 → 冷却”的曲线运行温度，适合需要分阶段升温的场景（如 BGA/大面积敷铜的预热流程）。

文档对各阶段温度的解释是“该阶段结束时的目标温度”、时长为“目标时长（秒）”。文档特别强调：实际阶段耗时会比设定值更长——若达到目标温度所需时间超过设定时长，阶段会等待到温度到位为止。另外原文档中 “Phase 4” 两条的描述写作 “phase 5”，属于生成源中的笔误；source/Core/Inc/Settings.h 的注释（Temperature to target for the end of phase 4/Target duration for phase 4）可作准确参照。

3.3 睡眠与省电（Sleep mode）

Motion sensitivity（运动灵敏度）设备对运动的敏感程度，数值越高越灵敏，0 表示关闭运动检测。 在机帮助文本：1=least sensitive | ... | 9=most sensitive对应Sensitivity：0–9，默认SENSITIVITY（加速度计灵敏度）。

Sleep temp（睡眠温度）设备入睡后降温保持的温度，通常取关机与焊接温度之间的中间值。 在机帮助文本：Tip temperature while in "sleep mode"对应SleepTemp：默认 150，范围MIN_TEMP_C–MAX_TEMP_F，步长 5。

Sleep timeout（睡眠超时）多少时间没有运动/按键操作后降到睡眠温度。 在机帮助文本：Interval before "sleep mode" starts (s=seconds | m=minutes)对应SleepTime：0–15，默认SLEEP_TIME。

Shutdown timeout（关机超时）多少时间无运动/按键后彻底关闭烙铁头加热并回到主待机界面。 在机帮助文本：Interval before the iron shuts down (m=minutes)对应ShutdownTime：0–60（分钟），默认SHUTDOWN_TIME。

Hall sensor sensitivity（霍尔传感器灵敏度，仅 Pinecil 等带霍尔传感器的设备）调整磁铁触发睡眠模式的灵敏度。 在机帮助文本：Sensitivity to magnets (1=least sensitive | ... | 9=most sensitive)对应HallEffectSensitivity：0–9，默认 7。

HallSensor SleepTime（霍尔传感器睡眠超时）霍尔信号超过阈值后，多久才降到睡眠温度。 在机帮助文本：Interval before "sleep mode" starts when hall effect is above threshold对应HallEffectSleepTime：0–12，默认 0。source/Core/Inc/Settings.h 注释将其单位标注为Seconds (/5)，可按源码注释理解为以 1/5 秒为最小单位的计时。

3.4 用户界面（User interface）

Temperature unit（温度单位）：°C 或 °F。在机帮助文本：C=°Celsius | F=°Fahrenheit。对应TemperatureInF（0/1，上限与HasFahrenheit构建特性绑定）。

Display orientation（显示方向）：屏幕是否随加速度计自动旋转，或固定为左手/右手方向。在机帮助文本：R=right-handed | L=left-handed | A=automatic。对应OrientationMode：0–2，orientationMode_t枚举为RIGHT=0、LEFT=1、AUTO=2；带NO_DISPLAY_ROTATE特性的设备不显示此项。

Cooldown flashing（冷却闪烁提示）：待机界面在烙铁头高于 50°C 时是否闪烁显示温度，作为“烙铁头仍很烫”的提醒。在机帮助文本：Flash temp reading at idle while tip is hot。对应CoolingTempBlink（0/1）。

Scrolling speed（帮助文本滚动速度）：菜单悬停说明文字滚动的速度。更快的速度可能导致画面撕裂，但能更快读完整段描述。在机帮助文本：Scrolling speed of info text (S=slow | F=fast)。对应DescriptionScrollSpeed（0/1）。

Swap + - keys（交换 +/− 键）：交换温度调整界面中“加”“减”的按钮分配。在机帮助文本：Reverse assignment of buttons for temperature adjustment。对应ReverseButtonTempChangeEnabled（0/1）。

Swap A B keys（交换 A/B 键）：交换设置菜单中“确认/修改”与“滚动/返回”的按钮分配。在机帮助文本：Reverse assignment of buttons for Settings menu。对应ReverseButtonSettings（0/1）。

Anim. speed（动画速度）：菜单图标动画的循环节奏，或不循环。在机帮助文本：Pace of icon animations in menu (S=slow | M=medium | F=fast)。对应AnimationSpeed：0–3，settingOffSpeed_t枚举为OFF/SLOW/MEDIUM/FAST。

Anim. loop（动画循环）：菜单动画是否循环，仅当动画速度不是 “Off” 时可见。在机帮助文本：Loop icon animations in main menu。对应AnimationLoop（0/1）。

Screen brightness（屏幕亮度）：OLED 亮度。文档提示：更高亮度会加速 OLED 烧屏老化（不过这些屏幕大多先因其他原因失效）。在机帮助文本：Adjust the OLED screen brightness。对应OLEDBrightness：MIN_BRIGHTNESS–MAX_BRIGHTNESS，默认DEFAULT_BRIGHTNESS。

Invert screen（反色显示）：翻转整个 OLED 颜色。在机帮助文本：Invert the OLED screen colors。对应OLEDInversion（0/1）。

Boot logo duration（启动 Logo 时长）：启动 Logo 显示时长，单位为秒。在机帮助文本：Set boot logo duration (s=seconds)。对应LOGOTime：0–6；source/Core/Inc/Settings.h 中logoMode_t表明取值有特殊语义：0=SKIP（跳过 Logo）、5=ONETIME（播放一次动画后停在末帧，按键跳过）、6=INFINITY（循环播放直到按键）。

Detailed idle screen（详细待机界面）：待机界面是否用更小字号的文本显示更多细节（代替图标）。在机帮助文本：Display detailed info in a smaller font on idle screen。对应DetailedIDLE（0/1）。

Detailed solder screen（详细焊接界面）：焊接界面是否使用纯文本的详细视图，以牺牲图形效果换取更多信息。在机帮助文本：Display detailed info in a smaller font on soldering screen。对应DetailedSoldering（0/1）。

3.5 高级设置（Advanced settings）

Bluetooth（蓝牙/BLE）：BLE 模式——关闭、完整读写（+）、只读（R，屏蔽所有经 BLE 的写入）。在机帮助文本：Enables BLE (+=full access | R=read-only)。对应BluetoothLE：0–2，默认 0，仅在BLE_ENABLED设备上可见（如 Pinecil V2）。

Power limit（功率限制）设定一个目标平均功率上限（瓦），让设备尽量维持在该值以下。文档强调：无论如何设置，设备都无法控制峰值功率（MHP30 是个例外，可以较好地收敛到该限制）；若正在使用 USB-PD，实际限值会取“该设置”与“电源标称功率”的较小者。 在机帮助文本：Average maximum power the iron can use (W=watt)对应PowerLimit：0–MAX_POWER_LIMIT，步长POWER_LIMIT_STEPS。

Calibrate CJC at next boot（下次启动时校准冷端补偿）这是高级设置中说明最详细的一项，文档原文要点如下，需严格遵守：

• 若目标温度与实测温度差小于 5°C，则完全无需校准；
• 该复选框用于校准烙铁头 ADC 与运算放大器之间的偏移，且只在下一次启动时执行（理想情况是在开机时、内部元件升温之前完成）。校准成功后复选框会自动取消；若需重复校准，必须再次勾选、拔掉电源、让设备冷却到室温后再上电，理想状态是设备平放在桌面上；
• 校准还需同时满足两个条件才会执行：烙铁头已安装，且烙铁头与手柄温差小于 10°C（约等于室温）。条件不满足时，校准会推迟到下一次同时满足两条件的开机，除非复选框被取消；
• 因此切勿连续快速重复校准。

在机帮助文本：Calibrate Cold Junction Compensation at next boot (not required if Delta T is < 5°C)对应CalibrateCJC（0/1，默认 0）。

Calibrate input voltage（输入电压校准）进入调整模式，可逐步修正测得电压以补偿各设备之间分压电阻的个体差异。 在机帮助文本：Start VIN calibration (long press to exit)对应VoltageDiv：360–900，默认VOLTAGE_DIV（分压系数，内部以 0.1% 精度表达）。

Power pulse（保活脉冲功率）开启并设定保活脉冲的功率。脉冲会让设备短暂开启加热丝拉取负载，防止充电宝/移动电源进入睡眠。 在机帮助文本：Intensity of power of keep-awake-pulse (W=watt)对应KeepAwakePulse：0–99（单位 0.1W），默认POWER_PULSE_DEFAULT。

Power pulse delay（保活脉冲间隔）调整两次脉冲之间的时间间隔。间隔越长烙铁头意外升温越少，但必须足够短才能维持充电宝唤醒状态。 在机帮助文本：Delay before keep-awake-pulse is triggered (x 2.5s)对应KeepAwakePulseWait：1–POWER_PULSE_WAIT_MAX（每单位 2.5 秒），默认POWER_PULSE_WAIT_DEFAULT。

Power pulse duration（保活脉冲时长）每次脉冲持续多久。部分充电宝需要看到持续一段时间的取电才保持唤醒；应尽量短以减少浪费与发热。 在机帮助文本：Keep-awake-pulse duration (x 250ms)对应KeepAwakePulseDuration：1–POWER_PULSE_DURATION_MAX（每单位 250ms），默认POWER_PULSE_DURATION_DEFAULT。

Restore default settings（恢复出厂设置）把全部设置与校准恢复为工厂默认值；不会擦除用户自定义的开机 Logo。 在机帮助文本：Reset all settings to default它不是普通数值项，而是触发resetSettings()的操作项。

Language（语言）多语言固件上切换设备语言。对应UILanguage：默认41431（英文 EN 的代码），范围 0–0xFFFF；source/Core/Inc/Settings.h 注释指出该字段在长度小于 8 字符时以空字符结尾存储语言代码。

Soldering Tip Type（烙铁头类型）手动选择所装烙铁头的类型。 在机帮助文本：Select the tip type fitted对应SolderingTipType：0–TIP_TYPE_MAX-1。source/Core/Inc/Settings.h 中tipType_t定义了可选类型（带TIP_TYPE_SUPPORT特性时）：T12_8_OHM（TS100 型或 Hakko T12 头加适配器）、T12_6_2_OHM（Pine64 短头）、T12_4_OHM（PTS200 用低阻长头），以及硬件支持自动识别时的TIP_TYPE_AUTO。选择类型后getUserSelectedTipResistance()返回匹配的烙铁头电阻，供热模型计算使用。

另外，source/Core/Inc/Settings.h 中还有两个不出现在菜单里的内部计数项：AccelMissingWarningCounter、PDMissingWarningCounter，分别记录“加速度计未检出”“PD 接口未检出”警告的已提示次数，用于避免重复轰炸式警告。

四、设置系统固件实现：定义、存储与访问

4.1 统一枚举与常量表

固件把所有设置项收敛到 source/Core/Inc/Settings.h 的enum SettingsOptions（共 56 项，SettingsOptionsLength = 56）。每项在 source/Settings/settings.yaml 中都有对应条目，声明其min、max、increment、default——这些正是菜单调节时上下限与步进的依据，也即上文各设置项取值表的来源。

每个设置项运行时需要一组常量：

typedef struct { const uint16_t min; // Inclusive minimum value const uint16_t max; // Inclusive maximum value const uint16_t increment; // Standard increment const uint16_t defaultValue; // Default vaue after reset } SettingConstants; extern const SettingConstants settingsConstants[(int)SettingsOptions::SettingsOptionsLength];

而settingsConstants数组正是构建时由 source/Settings/generate_settings.py 基于settings.yaml按模板 source/Settings/settings_gen.cpp.template 生成的 C++ 代码，构建链路保证“YAML 定义”与“固件常量表”永不漂移。

4.2 Flash 存储结构

设置持久化结构systemSettingsType同样定义在 source/Core/Inc/Settings.h：

typedef struct { uint16_t versionMarker; // 固件识别的版本标记 uint16_t length; // 后续有效字节数 uint16_t settingsValues[SettingsOptionsLength]; // 56 个 uint16_t 值 uint32_t padding; // 对齐到 32 字节，简化驱动代码 } systemSettingsType;

两个设计细节值得注意：

1. 注释明确该结构必须按 2 字节的整数倍组织，因为它是以 uint16_t 为单位读写 Flash的；
2. versionMarker使用固定的版本宏SETTINGSVERSION (0x55AA)（Pinecil V2 因某次设置重置 PR 使用0x55AB，且注释要求该数字冻结、不得修改）。当固件版本不匹配时，加载侧会检测到不一致并按需重置受影响的设置（配合 Translations/translations_definitions.json 中SettingsResetMessage的“因固件不兼容而重置部分设置”提示）。

读写入口函数为saveSettings()、loadSettings()、resetSettings()，单值访问则通过getSettingValue()/setSettingValue()/nextSettingValue()/prevSettingValue()（nextSettingValue返回“是否已到最大值，下次将回绕”）等 API 完成，菜单线程（如 source/Core/Threads/UI/logic/SettingsMenu.cpp）与 PID/供电等线程都通过这套统一接口取值。

4.3 各型号的 Flash 地址

设置块写入 Flash 的基址随设备不同。从 source/Settings/lib/settings_util.py 的get_base_address()可以看到完整映射：

这也解释了为何离线编辑工具必须知道目标型号——不同设备的设置块物理位置不同。

五、离线读取与批量写入：仓库自带设置工具

source/Settings/README.md 说明了工具链能力与限制：

• 读取：仅支持能经 USB 回读设备内存的设备；若设备在编程模式下表现为 USB 存储设备，则此方式不可用；
• 写入：使用edit_settings.py生成可直接写入设备的.bin或.hex文件；若设备支持读出当前内存，可先导入现有设置文件再修改。

工具结构（source/Settings 目录）：

• source/Settings/settings.yaml：设置项的“单一事实来源”，人类可读；
• source/Settings/generate_settings.py：构建期 C++ 代码生成（生成settingsConstants等）；
• source/Settings/edit_settings.py：交互式编辑二进制设置文件，按型号定位基址、解析表达式（如VOLTAGE_DIV这类符号默认值）后生成写入文件；
• source/Settings/lib/ 下的settings_types.py、settings_util.py、settings_model.py、settings_parser.py、settings_cli.py分别承担类型常量、基址/表达式解析、数据模型、YAML 解析与 CLI 入口，配套测试见 source/Settings/test_config_parser.py 等测试文件。

典型工作流是：从支持回读的设备导出当前设置文件 → 用edit_settings.py批量修改若干字段（如把KeepAwakePulse统一设为 10、ShutdownTime设为 30）→ 生成.hex/.bin→ 按 Documentation/Flashing/ 中对应型号的刷写指南写入。

六、小结

Documentation/Settings.md 以自动生成的方式保证了“文档—设备—源码”三者一致：五个菜单分类覆盖了 TS100 到 Pinecil V2、MHP30 等设备的全部可调项；每项的取值范围与默认值可在 source/Settings/settings.yaml 中查到；固件侧由 source/Core/Inc/Settings.h 的枚举、常量表与 Flash 结构完成定义与持久化；source/Settings 工具链则让设置支持离线读取、批量修改与回写。理解这套机制后，无论是为团队统一刷写配置，还是排查“某设置项在我的设备上不可见”（看include/exclude特性开关）这类问题，都能直接定位到相应文件。

• 嵌入式
• 固件
• 硬件开发
• 智能硬件