Fix docs gen check (#2139)

* Adding CI check to prevent settings docs drift
* Fixup gen_menu_docs
* Generate new settings docs
This commit is contained in:
Ben V. Brown
2025-07-16 16:03:26 +10:00
committed by GitHub
parent 260891b00b
commit 009aa10a53
4 changed files with 337 additions and 176 deletions

View File

@@ -173,6 +173,15 @@ jobs:
- name: Check format style with clang-format
run: make clean check-style
check-settings-docs:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
- name: Run the menu docs generator
run: python Translations/gen_menu_docs.py
- name: Check that Documentation/Settings.md didn't change
run: git diff --exit-code
check_python:
runs-on: ubuntu-24.04
container:

View File

@@ -43,7 +43,199 @@ When the device is powered by a battery, this adjusts the low voltage threshold
On device help text:
Set cutoff voltage to prevent battery over-drain. (DC 10V) (S=3.3V per cell, disable PWR limit)
Set cutoff voltage to prevent battery overdischarge (DC=10V) (S=3.3V per cell, disable PWR limit)
### Setting: Minimum voltage
When powered by a battery, this adjusts the minimum voltage per cell before shutdown. (This is multiplied by the cell count.)
On device help text:
Minimum allowed voltage per battery cell (3S: 3 - 3.7V | 4-6S: 2.4 - 3.7V)
### Setting: QC voltage
This adjusts the maximum voltage the QC negotiation will adjust to. Does NOT affect USB-PD. Should be set safely based on the current rating of your power supply.
On device help text:
Max QC voltage the iron should negotiate for
### Setting: PD timeout
How long until firmware stops trying to negotiate for USB-PD and tries QC instead. Longer times may help dodgy / old PD adapters, faster times move onto PD quickly. Units of 100ms. Recommended to keep small values.
On device help text:
PD negotiation timeout in 100ms steps for compatibility with some QC chargers
### Setting: PD Mode
Adjusts how the USB-PD Logic selects the voltage. No Dynamic disables EPR & PPS protocols, Safe mode does not use padding resistance (will select a slightly lower voltage).
On device help text:
No Dynamic disables EPR & PPS, Safe mode does not use padding resistance
### Setting: Boost temp
When the unit is in soldering mode. You can hold down the button at the front of the device to temporarily override the soldering temperature to this value. This SETS the temperature, it does not ADD to it.
On device help text:
Tip temperature used in "boost mode"
### Setting: Start-up behavior
When the device powers up, should it enter into a special mode. These settings set it to either start into soldering mode, sleeping mode or auto mode (Enters into soldering mode on the first movement).
On device help text:
S=heat to soldering temp | Z=standby at sleep temp until moved | R=standby without heating until moved
### Setting: Temp change short
Factor by which the temperature is changed with a quick press of the buttons.
On device help text:
Temperature-change-increment on short button press
### Setting: Temp change long
Factor by which the temperature is changed with a hold of the buttons.
On device help text:
Temperature-change-increment on long button press
### Setting: Allow locking buttons
If locking the buttons against accidental presses is enabled.
On device help text:
While soldering, hold down both buttons to toggle locking them (B=boost mode only | F=full locking)
### Setting: Profile Phases
set the number of phases for profile mode.
On device help text:
Number of phases in profile mode
### Setting: Preheat Temp
Preheat to this temperature at the start of profile mode.
On device help text:
Preheat to this temperature at the start of profile mode
### Setting: Preheat Speed
How fast the temperature is allowed to rise during the preheat phase at the start of profile mode.
On device help text:
Preheat at this rate (degrees per second)
### Setting: Phase 1 Temp
Target temperature for the end of phase 1 of profile mode.
On device help text:
Target temperature for the end of this phase
### Setting: Phase 1 Duration
Duration of phase 1 of profile mode. The phase might actually take longer if it takes longer to reach the target temperature.
On device help text:
Target duration of this phase (seconds)
### Setting: Phase 2 Temp
Target temperature for the end of phase 2 of profile mode.
On device help text:
### Setting: Phase 2 Duration
Duration of phase 2 of profile mode. The phase might actually take longer if it takes longer to reach the target temperature.
On device help text:
### Setting: Phase 3 Temp
Target temperature for the end of phase 3 of profile mode.
On device help text:
### Setting: Phase 3 Duration
Duration of phase 3 of profile mode. The phase might actually take longer if it takes longer to reach the target temperature.
On device help text:
### Setting: Phase 4 Temp
Target temperature for the end of phase 5 of profile mode.
On device help text:
### Setting: Phase 4 Duration
Duration of phase 5 of profile mode. The phase might actually take longer if it takes longer to reach the target temperature.
On device help text:
### Setting: Phase 5 Temp
Target temperature for the end of phase 5 of profile mode.
On device help text:
### Setting: Phase 5 Duration
Duration of phase 5 of profile mode. The phase might actually take longer if it takes longer to reach the target temperature.
On device help text:
### Setting: Cooldown Speed
How fast the temperature is allowed to drop during the cooldown phase at the end of profile mode.
On device help text:
Cooldown at this rate at the end of profile mode (degrees per second)
### Setting: Motion sensitivity
Scale of how sensitive the device is to movement. Higher numbers == more sensitive. 0 == motion detection turned off.
On device help text:
1=least sensitive | ... | 9=most sensitive
### Setting: Sleep temp
@@ -69,13 +261,21 @@ On device help text:
Interval before the iron shuts down (m=minutes)
### Setting: Motion sensitivity
### Setting: Hall sensor sensitivity
Scale of how sensitive the device is to movement. Higher numbers == more sensitive. 0 == motion detection turned off.
If the unit has a hall effect sensor (Pinecil), this adjusts how sensitive it is at detecting a magnet to put the device into sleep mode.
On device help text:
0=off | 1=least sensitive | ... | 9=most sensitive
Sensitivity to magnets (1=least sensitive | ... | 9=most sensitive)
### Setting: HallSensor SleepTime
If the unit has a hall effect sensor (Pinecil), this adjusts how long the device takes before it drops down to the sleep temperature when hall sensor is over threshold.
On device help text:
Interval before "sleep mode" starts when hall effect is above threshold
### Setting: Temperature unit
@@ -83,15 +283,7 @@ If the device shows temperatures in °C or °F.
On device help text:
C=Celsius | F=Fahrenheit
### Setting: Detailed idle screen
Should the device show an 'advanced' view on the idle screen. The advanced view uses text to show more details than the typical icons.
On device help text:
Display detailed info in a smaller font on idle screen
C=°Celsius | F=°Fahrenheit
### Setting: Display orientation
@@ -101,72 +293,13 @@ On device help text:
R=right-handed | L=left-handed | A=automatic
### Setting: Boost temp
When the unit is in soldering mode. You can hold down the button at the front of the device to temporarily override the soldering temperature to this value. This SETS the temperature, it does not ADD to it.
On device help text:
Tip temperature used in "boost mode"
### Setting: Start-up behavior
When the device powers up, should it enter into a special mode. These settings set it to either start into soldering mode, sleeping mode or auto mode (Enters into soldering mode on the first movement).
On device help text:
O=off | S=heat to soldering temp | Z=standby at sleep temp until moved | R=standby, heat-off until moved
### Setting: Cooldown flashing
If the idle screen should blink the tip temperature for attention while the tip is over 50°C. Intended as a 'tip is still hot' warning.
On device help text:
Flash temperature reading at idle if tip is hot
### Setting: Calibrate CJC at next boot
Note:
If the difference between the target temperature and the measured temperature is less than 5°C, **calibration is NOT required at all**.
This is used to calibrate the offset between ADC and Op-amp of the tip **at next boot** (Ideally it has to be done at boot, before internal components get warm.). If the checkbox is set, the calibration will only be performed at the next boot. After a successful calibration the checkbox will be unchecked again! If you need to repeat the calibration however, you have to set the checkbox *again*, unplug your device and let it cool down to room/ambient temperature & power it up, ideally while it sits on the desk.
Also, the calibration will only take place if both of the following conditions are met:
- The tip must be installed.
- The temperature difference between tip and handle must be less than 10°C. (~ ambient / room temperature)
Otherwise, the calibration will be performed the next time the device is started and both conditions are met, unless the corresponding checkbox is unchecked.
Hence, never repeat the calibration in quick succession!
On device help text:
Calibrate tip Cold Junction Compensation at the next boot (not required if Delta T is < 5°C)
### Setting: Restore default settings
Resets all settings and calibrations to factory defaults. Does NOT erase custom user boot up logo's.
On device help text:
Reset default settings for this firmware ver.
### Setting: Calibrate input voltage
Enters an adjustment mode where you can gradually adjust the measured voltage to compensate for any unit-to-unit variance in the voltage sense resistors.
On device help text:
Start VIN calibration (long press to exit)
### Setting: Detailed solder screen
Should the device show an 'advanced' soldering view. This is a text-based view that shows more information at the cost of no nice graphics.
On device help text:
Display detailed info in a smaller font on soldering screen
Flash temp reading at idle while tip is hot
### Setting: Scrolling speed
@@ -174,31 +307,7 @@ How fast the description text scrolls when hovering on a menu. Faster speeds may
On device help text:
Speed info text scrolls past at (S=slow | F=fast)
### Setting: QC voltage
This adjusts the maximum voltage the QC negotiation will adjust to. Does NOT affect USB-PD. Should be set safely based on the current rating of your power supply.
On device help text:
Max QC voltage the iron should negotiate for
### Setting: PD timeout
How long until firmware stops trying to negotiate for USB-PD and tries QC instead. Longer times may help dodgy / old PD adapters, faster times move onto PD quickly. Units of 100ms. Recommended to keep small values.
On device help text:
PD negotiation timeout in 100ms steps for compatibility with some QC chargers
### Setting: Power limit
Allows setting a custom wattage for the device to aim to keep the AVERAGE power below. The unit can't control its peak power no matter how you set this. (Except for MHP30 which will regulate nicely to this). If USB-PD is in use, the limit will be set to the lower of this and the supplies advertised wattage.
On device help text:
Maximum power the iron can use (W=watt)
Scrolling speed of info text (S=slow | F=fast)
### Setting: Swap + - keys
@@ -208,53 +317,21 @@ On device help text:
Reverse assignment of buttons for temperature adjustment
### Setting: Temp change short
### Setting: Swap A B keys
Factor by which the temperature is changed with a quick press of the buttons.
Swaps which button is used as Enter/Change and as Scroll/Back in Settings menu.
On device help text:
Temperature-change-increment on short button press
Reverse assignment of buttons for Settings menu
### Setting: Temp change long
### Setting: Anim. speed
Factor by which the temperature is changed with a hold of the buttons.
How fast should the menu animations loop, or if they should not loop at all.
On device help text:
Temperature-change-increment on long button press
### Setting: Power pulse
Enables and sets the wattage of the power pulse. Power pulse causes the device to briefly turn on the heater to draw power to avoid power banks going to sleep.
On device help text:
Intensity of power of keep-awake-pulse (watt)
### Setting: Hall sensor sensitivity
If the unit has a hall effect sensor (Pinecil), this adjusts how sensitive it is at detecting a magnet to put the device into sleep mode.
On device help text:
Sensitivity to magnets (0=off | 1=least sensitive | ... | 9=most sensitive)
### Setting: Allow locking buttons
If locking the buttons against accidental presses is enabled.
On device help text:
While soldering, hold down both buttons to toggle locking them (D=disable | B=boost mode only | F=full locking)
### Setting: Minimum voltage
When powered by a battery, this adjusts the minimum voltage per cell before shutdown. (This is multiplied by the cell count.)
On device help text:
Minimum allowed voltage per battery cell (3S: 3 - 3.7V | 4-6S: 2.4 - 3.7V)
Pace of icon animations in menu (S=slow | M=medium | F=fast)
### Setting: Anim. loop
@@ -264,38 +341,6 @@ On device help text:
Loop icon animations in main menu
### Setting: Anim. speed
How fast should the menu animations loop, or if they should not loop at all.
On device help text:
Pace of icon animations in menu (O=off | S=slow | M=medium | F=fast)
### Setting: Power pulse delay
Adjusts the time interval between power pulses. Longer gaps reduce undesired heating of the tip, but needs to be fast enough to keep your power bank awake.
On device help text:
Delay before keep-awake-pulse is triggered (x 2.5s)
### Setting: Power pulse duration
How long should the power pulse go for. Some power banks require seeing the power draw be sustained for a certain duration to keep awake. Should be kept as short as possible to avoid wasting power / undesired heating of the tip.
On device help text:
Keep-awake-pulse duration (x 250ms)
### Setting: Language: EN English
Changes the device language on multi-lingual builds.
On device help text:
Current firmware language
### Setting: Screen brightness
Display brightness. Higher values age the OLED faster due to burn-in. (However, it is notable that most of these screens die from other causes first.)
@@ -318,4 +363,111 @@ Sets the duration for the boot logo (s=seconds).
On device help text:
Set Boot logo duration (off | s=seconds | infinity)
Set boot logo duration (s=seconds)
### Setting: Detailed idle screen
Should the device show an 'advanced' view on the idle screen. The advanced view uses text to show more details than the typical icons.
On device help text:
Display detailed info in a smaller font on idle screen
### Setting: Detailed solder screen
Should the device show an 'advanced' soldering view. This is a text-based view that shows more information at the cost of no nice graphics.
On device help text:
Display detailed info in a smaller font on soldering screen
### Setting: Bluetooth
Should BLE be enabled at boot time.
On device help text:
Enables BLE
### Setting: Power limit
Allows setting a custom wattage for the device to aim to keep the AVERAGE power below. The unit can't control its peak power no matter how you set this. (Except for MHP30 which will regulate nicely to this). If USB-PD is in use, the limit will be set to the lower of this and the supplies advertised wattage.
On device help text:
Average maximum power the iron can use (W=watt)
### Setting: Calibrate CJC at next boot
Note:
If the difference between the target temperature and the measured temperature is less than 5°C, **calibration is NOT required at all**.
This is used to calibrate the offset between ADC and Op-amp of the tip **at next boot** (Ideally it has to be done at boot, before internal components get warm.). If the checkbox is set, the calibration will only be performed at the next boot. After a successful calibration the checkbox will be unchecked again! If you need to repeat the calibration however, you have to set the checkbox *again*, unplug your device and let it cool down to room/ambient temperature & power it up, ideally while it sits on the desk.
Also, the calibration will only take place if both of the following conditions are met:
- The tip must be installed.
- The temperature difference between tip and handle must be less than 10°C. (~ ambient / room temperature)
Otherwise, the calibration will be performed the next time the device is started and both conditions are met, unless the corresponding checkbox is unchecked.
Hence, never repeat the calibration in quick succession!
On device help text:
Calibrate Cold Junction Compensation at next boot (not required if Delta T is < 5°C)
### Setting: Calibrate input voltage
Enters an adjustment mode where you can gradually adjust the measured voltage to compensate for any unit-to-unit variance in the voltage sense resistors.
On device help text:
Start VIN calibration (long press to exit)
### Setting: Power pulse
Enables and sets the wattage of the power pulse. Power pulse causes the device to briefly turn on the heater to draw power to avoid power banks going to sleep.
On device help text:
Intensity of power of keep-awake-pulse (W=watt)
### Setting: Power pulse delay
Adjusts the time interval between power pulses. Longer gaps reduce undesired heating of the tip, but needs to be fast enough to keep your power bank awake.
On device help text:
Delay before keep-awake-pulse is triggered (x 2.5s)
### Setting: Power pulse duration
How long should the power pulse go for. Some power banks require seeing the power draw be sustained for a certain duration to keep awake. Should be kept as short as possible to avoid wasting power / undesired heating of the tip.
On device help text:
Keep-awake-pulse duration (x 250ms)
### Setting: Restore default settings
Resets all settings and calibrations to factory defaults. Does NOT erase custom user boot up logo's.
On device help text:
Reset all settings to default
### Setting: Language: EN English
Changes the device language on multi-lingual builds.
On device help text:
### Setting: Soldering Tip Type
For manually selecting the type of tip fitted
On device help text:
Select the tip type fitted

View File

@@ -51,7 +51,7 @@ In the menu there are a few main categories that are used to keep the list manag
for menu in defs.get("menuGroups", {}):
menu_id = menu.get("id", "")
entry = translation_data.get("menuGroups", {}).get(menu_id, "")
name = " ".join(entry.get("text2", []))
name = " ".join(entry.get("displayText").split("\n"))
desc = menu.get("description", "")
section = f"""
### Category: {name}
@@ -80,9 +80,9 @@ This is the "on device help text".
for menu in defs.get("menuOptions", {}):
menu_id = menu.get("id", "")
entry = translation_data.get("menuOptions", {}).get(menu_id, "")
name = " ".join(entry.get("text2", []))
name = " ".join(entry.get("displayText").split("\n"))
desc = menu.get("description", "")
on_device_desc = entry.get("desc", "")
on_device_desc = entry.get("description", "")
section = f"""
### Setting: {name}
@@ -99,8 +99,8 @@ def main() -> None:
json_dir = HERE
print(json_dir)
logging.info("Loading translation definitions")
defs = load_json(TRANSLATION_DEFS_PATH)
eng_translation = load_json(ENGLISH_TRANSLATION_PATH)
defs = load_json(TRANSLATION_DEFS_PATH, False)
eng_translation = load_json(ENGLISH_TRANSLATION_PATH, False)
with open(MENU_DOCS_FILE_PATH, "w") as outputf:
write_header(outputf)
write_menu_categories(outputf, defs, eng_translation)

View File

@@ -272,7 +272,7 @@
"maxLen": 7,
"maxLen2": 15,
"include": ["POW_PD"],
"description": "No Dynamic disables EPR & PPS, Safe mode does not use padding resistance"
"description": "Adjusts how the USB-PD Logic selects the voltage. No Dynamic disables EPR & PPS protocols, Safe mode does not use padding resistance (will select a slightly lower voltage)."
},
{
"id": "BoostTemperature",
@@ -538,7 +538,7 @@
"id": "CalibrateCJC",
"maxLen": 8,
"maxLen2": 15,
"description": "Used to calibrate the ADC+Op-amp offsets for the tip. This calibration must be performed when the tip temperature and the handle temperature are equal. Generally not required unless your device is reading more than 5°C off target."
"description": "Note:\r\nIf the difference between the target temperature and the measured temperature is less than 5°C, **calibration is NOT required at all**.\r\n\r\nThis is used to calibrate the offset between ADC and Op-amp of the tip **at next boot** (Ideally it has to be done at boot, before internal components get warm.). If the checkbox is set, the calibration will only be performed at the next boot. After a successful calibration the checkbox will be unchecked again! If you need to repeat the calibration however, you have to set the checkbox *again*, unplug your device and let it cool down to room/ambient temperature & power it up, ideally while it sits on the desk.\r\n\r\n\r\nAlso, the calibration will only take place if both of the following conditions are met:\r\n- The tip must be installed.\r\n- The temperature difference between tip and handle must be less than 10°C. (~ ambient / room temperature)\r\n\r\nOtherwise, the calibration will be performed the next time the device is started and both conditions are met, unless the corresponding checkbox is unchecked.\r\nHence, never repeat the calibration in quick succession!"
},
{
"id": "VoltageCalibration",