diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3d20ca974ff..0dac8628fbc 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -695,6 +695,7 @@ Unit tests in `test/` directory. The canonical suite count is detected on the fl - `test_packet_signing/` - Packet signing - `test_position_module/` - Position module behaviour - `test_position_precision/` - Position precision helpers +- `test_power_fsm/` - PowerFSM timeout helpers - `test_radio/` - Radio interface - `test_rtc/` - RTC / time handling - `test_serial/` - Serial communication diff --git a/src/PowerFSM.cpp b/src/PowerFSM.cpp index 2ef5b2ea1cf..0290c18691b 100644 --- a/src/PowerFSM.cpp +++ b/src/PowerFSM.cpp @@ -72,7 +72,28 @@ static uint32_t getBluetoothWaitMs() if (!isBluetoothEnabledForPowerFSM()) return 0; - return Default::getConfiguredOrDefaultMs(config.power.wait_bluetooth_secs, default_wait_bluetooth_secs); + return Default::getTimeoutMs(config.power.wait_bluetooth_secs, default_wait_bluetooth_secs); +} + +// A zero display timeout means "keep the screen on". As an ON -> DARK transition period it would +// do the opposite and fire immediately, so the caller leaves those transitions unregistered. +bool screenStaysOn(uint32_t screenOnSecs) +{ +#ifdef USE_EINK + // E-Ink read a literal 0 as "suppress the screensaver" before the sentinel existed, and nothing + // migrates saved configs, so that spelling keeps working alongside the sentinel. + if (screenOnSecs == 0) + return true; +#endif + return Default::getTimeoutMs(screenOnSecs, default_screen_on_secs) == 0; +} + +// A zero display timeout means "go dark immediately", which as a DARK self-transition period +// would re-enter DARK on every FSM tick, so fall back to the default period. +uint32_t getDarkRecheckMs() +{ + uint32_t timeoutMs = Default::getTimeoutMs(config.display.screen_on_secs, default_screen_on_secs); + return timeoutMs > 0 ? timeoutMs : Default::getConfiguredOrDefaultMs(0, default_screen_on_secs); } #if defined(T5_S3_EPAPER_PRO) @@ -327,6 +348,7 @@ void PowerFSM_setup() ? 1 : 0); bool hasPower = isPowered(); + uint32_t displayTimeoutMs = Default::getTimeoutMs(config.display.screen_on_secs, default_screen_on_secs); LOG_INFO("PowerFSM init, USB power=%d", hasPower ? 1 : 0); powerFSM.add_timed_transition(&stateBOOT, hasPower ? &statePOWER : &stateON, 3 * 1000, NULL, "boot timeout"); @@ -417,17 +439,9 @@ void PowerFSM_setup() powerFSM.add_transition(&stateDARK, &stateDARK, EVENT_CONTACT_FROM_PHONE, NULL, "Contact from phone"); -#ifdef USE_EINK - // Allow E-Ink devices to suppress the screensaver, if screen timeout set to 0 - if (config.display.screen_on_secs > 0) -#endif - { - powerFSM.add_timed_transition(&stateON, &stateDARK, - Default::getConfiguredOrDefaultMs(config.display.screen_on_secs, default_screen_on_secs), - NULL, "Screen-on timeout"); - powerFSM.add_timed_transition(&statePOWER, &stateDARK, - Default::getConfiguredOrDefaultMs(config.display.screen_on_secs, default_screen_on_secs), - NULL, "Screen-on timeout"); + if (!screenStaysOn(config.display.screen_on_secs)) { + powerFSM.add_timed_transition(&stateON, &stateDARK, displayTimeoutMs, NULL, "Screen-on timeout"); + powerFSM.add_timed_transition(&statePOWER, &stateDARK, displayTimeoutMs, NULL, "Screen-on timeout"); } // We never enter light-sleep or NB states on NRF52 (because the CPU uses so little power normally) @@ -443,7 +457,7 @@ void PowerFSM_setup() if ((isRouter || config.power.is_power_saving) && !isWifiAvailable() && !isTrackerOrSensor) { powerFSM.add_timed_transition(&stateNB, &stateLS, - Default::getConfiguredOrDefaultMs(config.power.min_wake_secs, default_min_wake_secs), NULL, + Default::getTimeoutMs(config.power.min_wake_secs, default_min_wake_secs), NULL, "Min wake timeout"); // If ESP32 and using power-saving, timer mover from DARK to light-sleep @@ -451,17 +465,13 @@ void PowerFSM_setup() powerFSM.add_timed_transition(&stateDARK, &stateLS, getBluetoothWaitMs(), NULL, "Bluetooth timeout"); } else { // If ESP32, but not using power-saving, check periodically if config has drifted out of stateDark - powerFSM.add_timed_transition(&stateDARK, &stateDARK, - Default::getConfiguredOrDefaultMs(config.display.screen_on_secs, default_screen_on_secs), - NULL, "Screen-on timeout"); + powerFSM.add_timed_transition(&stateDARK, &stateDARK, getDarkRecheckMs(), NULL, "Screen-on timeout"); } #endif // HAS_WIFI || !defined(MESHTASTIC_EXCLUDE_WIFI) #else // (not) ARCH_ESP32 // If not ESP32, light-sleep not used. Check periodically if config has drifted out of stateDark - powerFSM.add_timed_transition(&stateDARK, &stateDARK, - Default::getConfiguredOrDefaultMs(config.display.screen_on_secs, default_screen_on_secs), NULL, - "Screen-on timeout"); + powerFSM.add_timed_transition(&stateDARK, &stateDARK, getDarkRecheckMs(), NULL, "Screen-on timeout"); #endif powerFSM.run_machine(); // run one iteration of the state machine, so we run our on enter tasks for the initial DARK state diff --git a/src/PowerFSM.h b/src/PowerFSM.h index 182ac082a71..c0038b03c43 100644 --- a/src/PowerFSM.h +++ b/src/PowerFSM.h @@ -54,4 +54,10 @@ extern Fsm powerFSM; extern State stateON, statePOWER, stateSERIAL, stateDARK; void PowerFSM_setup(); +/// True when the configured screen timeout asks for the screen to stay on, so the ON -> DARK +/// transitions must not be registered at all. +bool screenStaysOn(uint32_t screenOnSecs); + +/// Period of the DARK self-transition that re-checks for config drift. Never zero. +uint32_t getDarkRecheckMs(); #endif \ No newline at end of file diff --git a/src/graphics/niche/InkHUD/Applets/System/Menu/MenuApplet.cpp b/src/graphics/niche/InkHUD/Applets/System/Menu/MenuApplet.cpp index 863c1e85d4c..7c122a0449e 100644 --- a/src/graphics/niche/InkHUD/Applets/System/Menu/MenuApplet.cpp +++ b/src/graphics/niche/InkHUD/Applets/System/Menu/MenuApplet.cpp @@ -2,6 +2,7 @@ #include "./MenuApplet.h" +#include "Default.h" #include "DisplayFormatters.h" #include "GPS.h" #include "MeshRadio.h" @@ -42,8 +43,13 @@ struct UInt32Option { }; static constexpr DisplayTimeoutOption DISPLAY_TIMEOUT_OPTIONS[] = { - {0, "Forever"}, {30, "30 secs"}, {60, "1 min"}, {5 * 60, "5 min"}, - {15 * 60, "15 min"}, {30 * 60, "30 min"}, {60 * 60, "1 hr"}, + {DECAF_ZERO_TIMEOUT_SECS, "Forever"}, + {30, "30 secs"}, + {60, "1 min"}, + {5 * 60, "5 min"}, + {15 * 60, "15 min"}, + {30 * 60, "30 min"}, + {60 * 60, "1 hr"}, }; static constexpr UInt32Option POSITION_BROADCAST_OPTIONS[] = { @@ -78,6 +84,14 @@ static constexpr PositionPrecisionOption POSITION_PRECISION_OPTIONS[] = { {12, "5.8 km", "3.6 mi"}, {11, "12 km", "7.3 mi"}, {10, "23 km", "15 mi"}, }; +// E-Ink read a stored 0 as "keep the screen on" long before the timeout sentinel existed, and +// nothing migrates those saved configs. Normalise it so such a device still lands on the Forever +// row rather than reading as "Custom" with nothing selected. +static uint32_t normaliseDisplayTimeout(uint32_t seconds) +{ + return seconds == 0 ? (uint32_t)DECAF_ZERO_TIMEOUT_SECS : seconds; +} + static const char *getDisplayTimeoutLabel(uint32_t timeoutSeconds) { constexpr uint8_t optionCount = sizeof(DISPLAY_TIMEOUT_OPTIONS) / sizeof(DISPLAY_TIMEOUT_OPTIONS[0]); @@ -1523,7 +1537,8 @@ void InkHUD::MenuApplet::showPage(MenuPage page) items.push_back(MenuItem("12-Hour Clock", MenuAction::TOGGLE_12H_CLOCK, MenuPage::NODE_CONFIG_DISPLAY, &config.display.use_12h_clock)); - nodeConfigLabels.emplace_back("Screen Timeout: " + std::string(getDisplayTimeoutLabel(config.display.screen_on_secs))); + nodeConfigLabels.emplace_back( + "Screen Timeout: " + std::string(getDisplayTimeoutLabel(normaliseDisplayTimeout(config.display.screen_on_secs)))); items.push_back(MenuItem(nodeConfigLabels.back().c_str(), MenuAction::NO_ACTION, MenuPage::NODE_CONFIG_DISPLAY_TIMEOUT)); const char *unitsLabel = @@ -2325,7 +2340,8 @@ void InkHUD::MenuApplet::populateDisplayTimeoutPage() { constexpr uint8_t optionCount = sizeof(DISPLAY_TIMEOUT_OPTIONS) / sizeof(DISPLAY_TIMEOUT_OPTIONS[0]); for (uint8_t i = 0; i < optionCount; i++) { - displayTimeoutSelected[i] = (config.display.screen_on_secs == DISPLAY_TIMEOUT_OPTIONS[i].seconds); + displayTimeoutSelected[i] = + (normaliseDisplayTimeout(config.display.screen_on_secs) == DISPLAY_TIMEOUT_OPTIONS[i].seconds); nodeConfigLabels.emplace_back(DISPLAY_TIMEOUT_OPTIONS[i].label); items.push_back(MenuItem(nodeConfigLabels.back().c_str(), MenuAction::SET_DISPLAY_TIMEOUT, MenuPage::NODE_CONFIG_DISPLAY, &displayTimeoutSelected[i])); diff --git a/src/mesh/Default.cpp b/src/mesh/Default.cpp index 95e4132bf0f..f3d1f737491 100644 --- a/src/mesh/Default.cpp +++ b/src/mesh/Default.cpp @@ -19,6 +19,11 @@ uint32_t Default::getConfiguredOrDefaultMs(uint32_t configuredInterval) return secondsToMsClamped(configuredInterval > 0 ? configuredInterval : default_broadcast_interval_secs); } +uint32_t Default::getTimeoutMs(uint32_t configuredInterval, uint32_t defaultInterval) +{ + return configuredInterval == DECAF_ZERO_TIMEOUT_SECS ? 0 : getConfiguredOrDefaultMs(configuredInterval, defaultInterval); +} + uint32_t Default::getConfiguredOrDefault(uint32_t configured, uint32_t defaultValue) { if (configured > 0) diff --git a/src/mesh/Default.h b/src/mesh/Default.h index e5e8b8ab192..076995b0d87 100644 --- a/src/mesh/Default.h +++ b/src/mesh/Default.h @@ -13,6 +13,8 @@ #define FIVE_SECONDS_MS 5 * 1000 #define TEN_SECONDS_MS 10 * 1000 #define MAX_INTERVAL INT32_MAX // FIXME: INT32_MAX to avoid overflow issues with Apple clients but should be UINT32_MAX +// 0x000DECAF means "actual zero"; 0 still means default. +#define DECAF_ZERO_TIMEOUT_SECS 0x000DECAF #define min_default_telemetry_interval_secs IF_ROUTER(ONE_DAY / 2, 30 * 60) #define default_gps_update_interval IF_ROUTER(ONE_DAY, 2 * 60) @@ -92,6 +94,7 @@ class Default static uint32_t getConfiguredOrDefaultMs(uint32_t configuredInterval); static uint32_t getConfiguredOrDefaultMs(uint32_t configuredInterval, uint32_t defaultInterval); + static uint32_t getTimeoutMs(uint32_t configuredInterval, uint32_t defaultInterval); static uint32_t getConfiguredOrDefault(uint32_t configured, uint32_t defaultValue); // Note: numOnlineNodes uses uint32_t to match the public API and allow flexibility, // even though internal node counts use uint16_t (max 65535 nodes) diff --git a/test/README.md b/test/README.md index ceb81920614..b0423bf46cf 100644 --- a/test/README.md +++ b/test/README.md @@ -499,6 +499,7 @@ do not infer completeness from the row count. | `test_mqtt` | MQTT integration | | `test_packet_history` | Packet history tracking | | `test_position_precision` | Position precision helpers | +| `test_power_fsm` | PowerFSM timeout helpers | | `test_radio` | Radio interface | | `test_serial` | Serial communication | | `test_module_config` | AdminModule module config | diff --git a/test/test_default/test_main.cpp b/test/test_default/test_main.cpp index 36c06e97738..3b7638b91c7 100644 --- a/test/test_default/test_main.cpp +++ b/test/test_default/test_main.cpp @@ -170,6 +170,13 @@ void test_ms_result_is_int32_safe() TEST_ASSERT_GREATER_OR_EQUAL_INT32(0, result); } +void test_ms_decaf_zero_timeout() +{ + TEST_ASSERT_EQUAL_UINT32(0U, Default::getTimeoutMs(DECAF_ZERO_TIMEOUT_SECS, 10)); + TEST_ASSERT_EQUAL_UINT32(10000U, Default::getTimeoutMs(0, 10)); + TEST_ASSERT_EQUAL_UINT32(2000U, Default::getTimeoutMs(2, 10)); +} + void test_scaled_overflow_saturates() { // long_fast (SF11/BW250) with a 24h base and heavy congestion overflows @@ -300,6 +307,7 @@ void setup() RUN_TEST(test_ms_uint32_max); RUN_TEST(test_ms_default_clamps); RUN_TEST(test_ms_result_is_int32_safe); + RUN_TEST(test_ms_decaf_zero_timeout); RUN_TEST(test_scaled_overflow_saturates); RUN_TEST(test_configured_or_default_hop_limit); RUN_TEST(test_trafficType_noRegion_returnsUnthrottled); diff --git a/test/test_power_fsm/test_main.cpp b/test/test_power_fsm/test_main.cpp new file mode 100644 index 00000000000..df9f617e11c --- /dev/null +++ b/test/test_power_fsm/test_main.cpp @@ -0,0 +1,77 @@ +// Unit tests for PowerFSM timeout helpers +#include "Default.h" +#include "PowerFSM.h" +#include "TestUtil.h" +#include + +void test_dark_recheck_uses_configured_screen_on() +{ + config.device.role = meshtastic_Config_DeviceConfig_Role_CLIENT; + config.display.screen_on_secs = 30; + + TEST_ASSERT_EQUAL_UINT32(30000U, getDarkRecheckMs()); +} + +void test_dark_recheck_uses_default_when_unset() +{ + config.device.role = meshtastic_Config_DeviceConfig_Role_CLIENT; + config.display.screen_on_secs = 0; + + TEST_ASSERT_EQUAL_UINT32(600000U, getDarkRecheckMs()); +} + +void test_dark_recheck_never_zero_and_never_sentinel() +{ + config.device.role = meshtastic_Config_DeviceConfig_Role_CLIENT; + config.display.screen_on_secs = DECAF_ZERO_TIMEOUT_SECS; + + // The sentinel means "no screen-on time", but it is not a usable poll period: the + // re-check must be neither zero nor the sentinel interpreted as a seconds count. + TEST_ASSERT_EQUAL_UINT32(0U, Default::getTimeoutMs(config.display.screen_on_secs, default_screen_on_secs)); + TEST_ASSERT_EQUAL_UINT32(600000U, getDarkRecheckMs()); +} + +void test_dark_recheck_sentinel_uses_router_default() +{ + config.device.role = meshtastic_Config_DeviceConfig_Role_ROUTER; + config.display.screen_on_secs = DECAF_ZERO_TIMEOUT_SECS; + + TEST_ASSERT_EQUAL_UINT32(1000U, getDarkRecheckMs()); +} + +// The ON -> DARK transitions must not be registered when the timeout asks for the screen to stay +// on, because a zero period fires immediately rather than never. Only the sentinel spells that on +// a non-E-Ink build; a plain 0 still means "use the default". +static void test_screenStaysOn_onlyForTheSentinel(void) +{ + TEST_ASSERT_TRUE_MESSAGE(screenStaysOn(DECAF_ZERO_TIMEOUT_SECS), "the sentinel must keep the screen on"); + TEST_ASSERT_FALSE_MESSAGE(screenStaysOn(0), "an unset timeout must fall back to the default, not stay on"); + TEST_ASSERT_FALSE_MESSAGE(screenStaysOn(60), "a configured timeout must still go dark"); +} + +// The value the InkHUD menu writes for "Forever" has to be the one screenStaysOn() honours, +// otherwise picking Forever silently selects the default timeout instead. +static void test_screenStaysOn_matchesTheMenuForeverValue(void) +{ + TEST_ASSERT_EQUAL_UINT32_MESSAGE(DECAF_ZERO_TIMEOUT_SECS, (uint32_t)DECAF_ZERO_TIMEOUT_SECS, + "menu Forever and the sentinel must be the same value"); + TEST_ASSERT_TRUE(screenStaysOn(DECAF_ZERO_TIMEOUT_SECS)); + TEST_ASSERT_EQUAL_UINT32_MESSAGE(0, Default::getTimeoutMs(DECAF_ZERO_TIMEOUT_SECS, default_screen_on_secs), + "the sentinel must resolve to a zero timeout"); +} + +void setup() +{ + delay(10); + initializeTestEnvironment(); + UNITY_BEGIN(); + RUN_TEST(test_dark_recheck_uses_configured_screen_on); + RUN_TEST(test_dark_recheck_uses_default_when_unset); + RUN_TEST(test_dark_recheck_never_zero_and_never_sentinel); + RUN_TEST(test_dark_recheck_sentinel_uses_router_default); + RUN_TEST(test_screenStaysOn_onlyForTheSentinel); + RUN_TEST(test_screenStaysOn_matchesTheMenuForeverValue); + exit(UNITY_END()); +} + +void loop() {}