From 61ae0920df567f97ad16565ff9ee446d390e3872 Mon Sep 17 00:00:00 2001 From: agessaman Date: Mon, 17 Aug 2026 21:04:06 -0700 Subject: [PATCH 1/4] feat(rak3401): cold-sleep RAK4631 onboard SX1262 on RAK13302 builds A RAK4631 core paired with a RAK13302 leaves the core's own SX1262 powered but never initialized, idling in STDBY_RC for the life of the board. Firmware cannot cut its supply -- P1.05 is the RF switch rail, not the radio's -- so bring it up on its own pins just long enough to issue a cold sleep, before std_init() repins SPI onto the RAK13302. Gated behind RAK4631_ONBOARD_SX1262_SLEEP and exposed through seven RAK_4631_13302_* envs, so RAK_3401_* artifacts are unchanged. The sleep is issued regardless of what begin() returns: Module::init() runs first, so SPI stays usable even if TCXO calibration fails. NSS is then held high, since the SX1262 wakes on an NSS falling edge. Verified on RAK19007 + RAK4631 + RAK13302: begin=0 sleep=0, RAK13302 init clean (device_errors=0x0000), TX and RX both confirmed. The current saving itself is derived from the datasheet (600 uA STDBY_RC -> 160 nA cold sleep) and is not measured. --- variants/rak3401/platformio.ini | 125 ++++++++++++++++++++++++++++++++ variants/rak3401/target.cpp | 33 +++++++++ variants/rak3401/variant.h | 15 ++++ 3 files changed, 173 insertions(+) diff --git a/variants/rak3401/platformio.ini b/variants/rak3401/platformio.ini index 48e719226..56883e752 100644 --- a/variants/rak3401/platformio.ini +++ b/variants/rak3401/platformio.ini @@ -134,3 +134,128 @@ build_src_filter = ${rak3401.build_src_filter} extends = rak3401 build_src_filter = ${rak3401.build_src_filter} +<../examples/kiss_modem/> + +; ------------------------- RAK4631 core + RAK13302 ------------------------- +; Same RF hardware as the RAK3401 1W kit, but the RAK4631 core carries a second, +; unused SX1262 that would otherwise idle in standby forever. These envs match +; the RAK_3401_* ones and additionally cold-sleep that radio at boot. +; Do not flash them to a genuine RAK3401 -- there is no onboard radio to sleep. + +[rak4631_13302] +extends = rak3401 +board = rak4631 +build_flags = ${rak3401.build_flags} + -D RAK4631_ONBOARD_SX1262_SLEEP +build_src_filter = ${rak3401.build_src_filter} +lib_deps = ${rak3401.lib_deps} + +[env:RAK_4631_13302_repeater] +extends = rak4631_13302 +build_flags = + ${rak4631_13302.build_flags} + -D DISPLAY_CLASS=SSD1306Display + -D ADVERT_NAME='"RAK4631 1W Repeater"' + -D ADVERT_LAT=0.0 + -D ADVERT_LON=0.0 + -D ADMIN_PASSWORD='"password"' + -D MAX_NEIGHBOURS=50 + ;-D MESH_PACKET_LOGGING=1 + ;-D MESH_DEBUG=1 +build_src_filter = ${rak4631_13302.build_src_filter} + + + +<../examples/simple_repeater> + +[env:RAK_4631_13302_room_server] +extends = rak4631_13302 +build_flags = + ${rak4631_13302.build_flags} + -D DISPLAY_CLASS=SSD1306Display + -D ADVERT_NAME='"Test Room"' + -D ADVERT_LAT=0.0 + -D ADVERT_LON=0.0 + -D ADMIN_PASSWORD='"password"' + -D ROOM_PASSWORD='"hello"' + ;-D MESH_PACKET_LOGGING=1 + ;-D MESH_DEBUG=1 +build_src_filter = ${rak4631_13302.build_src_filter} + + + +<../examples/simple_room_server> + +[env:RAK_4631_13302_companion_radio_usb] +extends = rak4631_13302 +board_build.ldscript = boards/nrf52840_s140_v6_extrafs.ld +board_upload.maximum_size = 712704 +build_flags = + ${rak4631_13302.build_flags} + -I examples/companion_radio/ui-new + -D PIN_USER_BTN_ANA=31 + -D DISPLAY_CLASS=SSD1306Display + -D MAX_CONTACTS=350 + -D MAX_GROUP_CHANNELS=40 + -D ENABLE_USB_INTERFACE +; NOTE: DO NOT ENABLE --> -D MESH_PACKET_LOGGING=1 +; NOTE: DO NOT ENABLE --> -D MESH_DEBUG=1 +build_src_filter = ${rak4631_13302.build_src_filter} + +<../examples/companion_radio/*.cpp> + +<../examples/companion_radio/ui-new/*.cpp> +lib_deps = + ${rak4631_13302.lib_deps} + densaugeo/base64 @ ~1.4.0 + +[env:RAK_4631_13302_companion_radio_ble] +extends = rak4631_13302 +board_build.ldscript = boards/nrf52840_s140_v6_extrafs.ld +board_upload.maximum_size = 712704 +build_flags = + ${rak4631_13302.build_flags} + -I examples/companion_radio/ui-new + -D PIN_USER_BTN_ANA=31 + -D DISPLAY_CLASS=SSD1306Display + -D MAX_CONTACTS=350 + -D MAX_GROUP_CHANNELS=40 + -D BLE_PIN_CODE=123456 + -D BLE_DEBUG_LOGGING=1 + -D OFFLINE_QUEUE_SIZE=256 + ;-D MESH_PACKET_LOGGING=1 + ;-D MESH_DEBUG=1 +build_src_filter = ${rak4631_13302.build_src_filter} + + + +<../examples/companion_radio/*.cpp> + +<../examples/companion_radio/ui-new/*.cpp> +lib_deps = + ${rak4631_13302.lib_deps} + densaugeo/base64 @ ~1.4.0 + +[env:RAK_4631_13302_terminal_chat] +extends = rak4631_13302 +build_flags = + ${rak4631_13302.build_flags} + -D MAX_CONTACTS=100 + -D MAX_GROUP_CHANNELS=1 + ;-D MESH_PACKET_LOGGING=1 + ;-D MESH_DEBUG=1 +build_src_filter = ${rak4631_13302.build_src_filter} + +<../examples/simple_secure_chat/main.cpp> +lib_deps = + ${rak4631_13302.lib_deps} + densaugeo/base64 @ ~1.4.0 + +[env:RAK_4631_13302_sensor] +extends = rak4631_13302 +build_flags = + ${rak4631_13302.build_flags} + -D DISPLAY_CLASS=SSD1306Display + -D ADVERT_NAME='"RAK4631 Sensor"' + -D ADVERT_LAT=0.0 + -D ADVERT_LON=0.0 + -D ADMIN_PASSWORD='"password"' + ;-D MESH_PACKET_LOGGING=1 + ;-D MESH_DEBUG=1 +build_src_filter = ${rak4631_13302.build_src_filter} + + + +<../examples/simple_sensor> + +[env:RAK_4631_13302_kiss_modem] +extends = rak4631_13302 +build_src_filter = ${rak4631_13302.build_src_filter} + +<../examples/kiss_modem/> diff --git a/variants/rak3401/target.cpp b/variants/rak3401/target.cpp index 5309e6b22..640b4d027 100644 --- a/variants/rak3401/target.cpp +++ b/variants/rak3401/target.cpp @@ -32,8 +32,41 @@ AutoDiscoverRTCClock rtc_clock(fallback_clock); EnvironmentSensorManager sensors; #endif +#ifdef RAK4631_ONBOARD_SX1262_SLEEP +// With a RAK13302 fitted the RAK4631's own SX1262 never gets initialized, so it +// sits in STDBY_RC drawing standby current for the life of the board. Firmware +// cannot cut its supply -- P1.05 is the RF switch rail, not the radio's -- so +// bring it up on its own pins just long enough to put it into cold sleep. +static void sleep_onboard_radio() { + pinMode(ONBOARD_LORA_ANT_SW, OUTPUT); + digitalWrite(ONBOARD_LORA_ANT_SW, LOW); // nothing downstream needs the RF switch + + SPI.setPins(ONBOARD_LORA_MISO, ONBOARD_LORA_SCLK, ONBOARD_LORA_MOSI); + SPI.begin(); + + Module mod(ONBOARD_LORA_NSS, ONBOARD_LORA_DIO_1, ONBOARD_LORA_RESET, ONBOARD_LORA_BUSY, SPI); + SX1262 onboard(&mod); + + // begin() resets the chip and leaves it in standby. A TCXO calibration failure + // still leaves SPI usable, so issue the sleep regardless of what it returns. + int status = onboard.begin(434.0f, 125.0f, 9, 7, RADIOLIB_SX126X_SYNC_WORD_PRIVATE, + 0, 8, ONBOARD_LORA_TCXO_VOLTAGE, false); + int slept = onboard.sleep(false); // cold sleep: config discarded, RTC off + MESH_DEBUG_PRINTLN("onboard SX1262: begin=%d sleep=%d", status, slept); + + SPI.end(); // release SPIM3 so std_init() can repin it onto the RAK13302 + + // The SX1262 wakes on an NSS falling edge, so keep NSS driven high from here on. + digitalWrite(ONBOARD_LORA_NSS, HIGH); + pinMode(ONBOARD_LORA_NSS, OUTPUT); +} +#endif + bool radio_init() { rtc_clock.begin(Wire); +#ifdef RAK4631_ONBOARD_SX1262_SLEEP + sleep_onboard_radio(); +#endif return radio.std_init(&SPI); } diff --git a/variants/rak3401/variant.h b/variants/rak3401/variant.h index 988278860..0576dadb8 100644 --- a/variants/rak3401/variant.h +++ b/variants/rak3401/variant.h @@ -175,6 +175,21 @@ static const uint8_t AREF = PIN_AREF; #define P_LORA_BUSY SX126X_BUSY #define P_LORA_RESET SX126X_RESET +// The RAK4631 core carries its own SX1262, which is unused when a RAK13302 +// supplies the RF path. RAK4631_ONBOARD_SX1262_SLEEP builds put it into cold +// sleep at boot; on a genuine RAK3401 these pins are unconnected. +#ifdef RAK4631_ONBOARD_SX1262_SLEEP +#define ONBOARD_LORA_NSS (42) // P1.10 +#define ONBOARD_LORA_SCLK (43) // P1.11 +#define ONBOARD_LORA_MOSI (44) // P1.12 +#define ONBOARD_LORA_MISO (45) // P1.13 +#define ONBOARD_LORA_BUSY (46) // P1.14 +#define ONBOARD_LORA_DIO_1 (47) // P1.15 +#define ONBOARD_LORA_RESET (38) // P1.06 +#define ONBOARD_LORA_ANT_SW (37) // P1.05, powers the onboard RF switch +#define ONBOARD_LORA_TCXO_VOLTAGE 1.8 +#endif + // enables 3.3V periphery like GPS or IO Module // Do not toggle this for GPS power savings #define PIN_3V3_EN (34) From 51cbab53110fea91a63f5fb77d97d20b07240d6b Mon Sep 17 00:00:00 2001 From: agessaman Date: Mon, 17 Aug 2026 22:19:49 -0700 Subject: [PATCH 2/4] feat(rak3401): report onboard SX1262 sleep state via BUSY BUSY is driven low in STDBY_RC and high while asleep, so reading it either side of the sleep gives a non-invasive readback of the state the chip was found in and the state it was left in. Confirmed on hardware. This is what makes the sleep observable at all. The only other symptom of a failed sleep is ~600 uA, which is below what an inline USB meter can resolve, so without this a regression would be silent. It immediately earned itself: busy_before reads 0 on every boot, showing the cold sleep does not survive an MCU reset. GPIOs revert to input during reset, NSS stops being driven high, and the falling edge wakes the chip. The helper re-sleeps it, so this is self-healing, but it means the chip is never found already asleep. --- variants/rak3401/target.cpp | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/variants/rak3401/target.cpp b/variants/rak3401/target.cpp index 640b4d027..dac12ede7 100644 --- a/variants/rak3401/target.cpp +++ b/variants/rak3401/target.cpp @@ -47,12 +47,20 @@ static void sleep_onboard_radio() { Module mod(ONBOARD_LORA_NSS, ONBOARD_LORA_DIO_1, ONBOARD_LORA_RESET, ONBOARD_LORA_BUSY, SPI); SX1262 onboard(&mod); + // BUSY is driven low in STDBY_RC and high while asleep, so it doubles as a + // non-invasive readback of what state we found the chip in and left it in. + pinMode(ONBOARD_LORA_BUSY, INPUT); + int busy_before = digitalRead(ONBOARD_LORA_BUSY); + // begin() resets the chip and leaves it in standby. A TCXO calibration failure // still leaves SPI usable, so issue the sleep regardless of what it returns. int status = onboard.begin(434.0f, 125.0f, 9, 7, RADIOLIB_SX126X_SYNC_WORD_PRIVATE, 0, 8, ONBOARD_LORA_TCXO_VOLTAGE, false); int slept = onboard.sleep(false); // cold sleep: config discarded, RTC off - MESH_DEBUG_PRINTLN("onboard SX1262: begin=%d sleep=%d", status, slept); + delay(2); + int busy_after = digitalRead(ONBOARD_LORA_BUSY); + MESH_DEBUG_PRINTLN("onboard SX1262: begin=%d sleep=%d busy %d->%d", + status, slept, busy_before, busy_after); SPI.end(); // release SPIM3 so std_init() can repin it onto the RAK13302 From de5d6697d1bd502942140cf4f72b3ecb197009fb Mon Sep 17 00:00:00 2001 From: agessaman Date: Fri, 16 Oct 2026 19:02:23 -0700 Subject: [PATCH 3/4] feat(rak3401): auto-sleep optional onboard SX1262 Use the existing RAK3401 firmware roles for RAK4631 cores paired with a RAK13302. Probe the optional onboard radio and put it into cold sleep before handing SPI to the primary radio, removing seven duplicate build environments. Preserve BUSY startup readiness, release probe pulls before sleep, and disconnect unused GPIO input buffers during cleanup. Add focused tests for sequencing, missing signatures, timeouts, and failed sleep readback. Validated with four native tests, seven firmware-role builds, and repeater boot checks on RAK4631 + RAK13302. Supply current was not measured. --- platformio.ini | 6 + .../test_onboard_radio.cpp | 66 +++++++++ variants/rak3401/OnboardRadioSleep.h | 34 +++++ variants/rak3401/platformio.ini | 125 ------------------ variants/rak3401/target.cpp | 110 ++++++++++----- variants/rak3401/variant.h | 7 +- 6 files changed, 184 insertions(+), 164 deletions(-) create mode 100644 test/test_rak3401_onboard_radio/test_onboard_radio.cpp create mode 100644 variants/rak3401/OnboardRadioSleep.h diff --git a/platformio.ini b/platformio.ini index e78124a40..e305d177d 100644 --- a/platformio.ini +++ b/platformio.ini @@ -173,6 +173,12 @@ build_src_filter = lib_deps = google/googletest @ 1.17.0 +[env:native_rak3401_onboard_radio] +; Header-only tests without unrelated production sources; also included in env:native CI. +extends = env:native +test_build_src = no +test_filter = test_rak3401_onboard_radio + [env:native_kiss_modem] platform = native test_framework = googletest diff --git a/test/test_rak3401_onboard_radio/test_onboard_radio.cpp b/test/test_rak3401_onboard_radio/test_onboard_radio.cpp new file mode 100644 index 000000000..cc6166129 --- /dev/null +++ b/test/test_rak3401_onboard_radio/test_onboard_radio.cpp @@ -0,0 +1,66 @@ +#include +#include +#include +#include "../../variants/rak3401/OnboardRadioSleep.h" + +namespace { +struct FakeRadioIO { + std::string version = "SX1261"; + std::array ready = {true, true, true}; + std::string calls; + unsigned waits = 0; + bool probePulls = true; + + void begin() { calls += "begin "; } + void reset() { calls += "reset "; } + bool waitBusy(bool high, unsigned timeout) { + calls += high ? "busy-high " : "busy-low "; + EXPECT_EQ(timeout, 20u); + if (high) EXPECT_FALSE(probePulls); + const bool result = ready.at(waits++); + return result; + } + void readVersion(char* out) { calls += "version "; memcpy(out, version.data(), 6); } + void releaseProbePulls() { calls += "release-pulls "; probePulls = false; } + void sleep() { EXPECT_FALSE(probePulls); calls += "sleep "; } + void end() { calls += "end "; } +}; +} + +TEST(RakOnboardRadio, PresentRadioSleepsBeforeBusRelease) { + FakeRadioIO io; + EXPECT_EQ(rak3401::sleepOnboardRadio(io, "SX1261"), rak3401::OnboardRadioState::Asleep); + EXPECT_EQ(io.calls, "begin reset busy-low version release-pulls busy-low sleep busy-high end "); +} + +TEST(RakOnboardRadio, AbsentAndFloatingResponsesNeverReceiveSleep) { + for (const std::string version : {std::string(6, '\0'), std::string(6, '\xff'), std::string("SX126X")}) { + FakeRadioIO io; + io.version = version; + EXPECT_EQ(rak3401::sleepOnboardRadio(io, "SX1261"), rak3401::OnboardRadioState::Absent); + EXPECT_EQ(io.calls, "begin reset busy-low version end "); + } +} + +TEST(RakOnboardRadio, BusyTimeoutsReleaseBusWithoutSleep) { + for (unsigned failure = 0; failure < 2; failure++) { + FakeRadioIO io; + io.ready[failure] = false; + EXPECT_EQ(rak3401::sleepOnboardRadio(io, "SX1261"), rak3401::OnboardRadioState::BusyTimeout); + EXPECT_EQ(io.calls.find("sleep "), std::string::npos); + EXPECT_EQ(io.calls, failure == 0 ? "begin reset busy-low end " : + "begin reset busy-low version release-pulls busy-low end "); + } +} + +TEST(RakOnboardRadio, MissingSleepReadbackIsReportedAndBusReleased) { + FakeRadioIO io; + io.ready[2] = false; + EXPECT_EQ(rak3401::sleepOnboardRadio(io, "SX1261"), rak3401::OnboardRadioState::SleepFailed); + EXPECT_EQ(io.calls.substr(io.calls.size() - 4), "end "); +} + +int main(int argc, char** argv) { + ::testing::InitGoogleTest(&argc, argv); + return RUN_ALL_TESTS(); +} diff --git a/variants/rak3401/OnboardRadioSleep.h b/variants/rak3401/OnboardRadioSleep.h new file mode 100644 index 000000000..7f6d1c55a --- /dev/null +++ b/variants/rak3401/OnboardRadioSleep.h @@ -0,0 +1,34 @@ +#pragma once + +#include + +namespace rak3401 { + +enum class OnboardRadioState { Absent, Asleep, BusyTimeout, SleepFailed }; + +// IO owns the temporary SPI pin assignment; every outcome must release it. +template +OnboardRadioState sleepOnboardRadio(IO& io, const char* expectedVersion) { + io.begin(); + io.reset(); + const auto state = [&]() { + // A missing chip also times out: BUSY is pulled high until a radio drives it low. + if (!io.waitBusy(false, 20)) return OnboardRadioState::BusyTimeout; + + char version[6]; + io.readVersion(version); + if (memcmp(version, expectedVersion, sizeof(version)) != 0) { + return OnboardRadioState::Absent; + } + io.releaseProbePulls(); + if (!io.waitBusy(false, 20)) return OnboardRadioState::BusyTimeout; + + io.sleep(); + // Reading over SPI here would wake the radio again. BUSY is a passive check. + return io.waitBusy(true, 20) ? OnboardRadioState::Asleep : OnboardRadioState::SleepFailed; + }(); + io.end(); + return state; +} + +} diff --git a/variants/rak3401/platformio.ini b/variants/rak3401/platformio.ini index 56883e752..48e719226 100644 --- a/variants/rak3401/platformio.ini +++ b/variants/rak3401/platformio.ini @@ -134,128 +134,3 @@ build_src_filter = ${rak3401.build_src_filter} extends = rak3401 build_src_filter = ${rak3401.build_src_filter} +<../examples/kiss_modem/> - -; ------------------------- RAK4631 core + RAK13302 ------------------------- -; Same RF hardware as the RAK3401 1W kit, but the RAK4631 core carries a second, -; unused SX1262 that would otherwise idle in standby forever. These envs match -; the RAK_3401_* ones and additionally cold-sleep that radio at boot. -; Do not flash them to a genuine RAK3401 -- there is no onboard radio to sleep. - -[rak4631_13302] -extends = rak3401 -board = rak4631 -build_flags = ${rak3401.build_flags} - -D RAK4631_ONBOARD_SX1262_SLEEP -build_src_filter = ${rak3401.build_src_filter} -lib_deps = ${rak3401.lib_deps} - -[env:RAK_4631_13302_repeater] -extends = rak4631_13302 -build_flags = - ${rak4631_13302.build_flags} - -D DISPLAY_CLASS=SSD1306Display - -D ADVERT_NAME='"RAK4631 1W Repeater"' - -D ADVERT_LAT=0.0 - -D ADVERT_LON=0.0 - -D ADMIN_PASSWORD='"password"' - -D MAX_NEIGHBOURS=50 - ;-D MESH_PACKET_LOGGING=1 - ;-D MESH_DEBUG=1 -build_src_filter = ${rak4631_13302.build_src_filter} - + - +<../examples/simple_repeater> - -[env:RAK_4631_13302_room_server] -extends = rak4631_13302 -build_flags = - ${rak4631_13302.build_flags} - -D DISPLAY_CLASS=SSD1306Display - -D ADVERT_NAME='"Test Room"' - -D ADVERT_LAT=0.0 - -D ADVERT_LON=0.0 - -D ADMIN_PASSWORD='"password"' - -D ROOM_PASSWORD='"hello"' - ;-D MESH_PACKET_LOGGING=1 - ;-D MESH_DEBUG=1 -build_src_filter = ${rak4631_13302.build_src_filter} - + - +<../examples/simple_room_server> - -[env:RAK_4631_13302_companion_radio_usb] -extends = rak4631_13302 -board_build.ldscript = boards/nrf52840_s140_v6_extrafs.ld -board_upload.maximum_size = 712704 -build_flags = - ${rak4631_13302.build_flags} - -I examples/companion_radio/ui-new - -D PIN_USER_BTN_ANA=31 - -D DISPLAY_CLASS=SSD1306Display - -D MAX_CONTACTS=350 - -D MAX_GROUP_CHANNELS=40 - -D ENABLE_USB_INTERFACE -; NOTE: DO NOT ENABLE --> -D MESH_PACKET_LOGGING=1 -; NOTE: DO NOT ENABLE --> -D MESH_DEBUG=1 -build_src_filter = ${rak4631_13302.build_src_filter} - +<../examples/companion_radio/*.cpp> - +<../examples/companion_radio/ui-new/*.cpp> -lib_deps = - ${rak4631_13302.lib_deps} - densaugeo/base64 @ ~1.4.0 - -[env:RAK_4631_13302_companion_radio_ble] -extends = rak4631_13302 -board_build.ldscript = boards/nrf52840_s140_v6_extrafs.ld -board_upload.maximum_size = 712704 -build_flags = - ${rak4631_13302.build_flags} - -I examples/companion_radio/ui-new - -D PIN_USER_BTN_ANA=31 - -D DISPLAY_CLASS=SSD1306Display - -D MAX_CONTACTS=350 - -D MAX_GROUP_CHANNELS=40 - -D BLE_PIN_CODE=123456 - -D BLE_DEBUG_LOGGING=1 - -D OFFLINE_QUEUE_SIZE=256 - ;-D MESH_PACKET_LOGGING=1 - ;-D MESH_DEBUG=1 -build_src_filter = ${rak4631_13302.build_src_filter} - + - +<../examples/companion_radio/*.cpp> - +<../examples/companion_radio/ui-new/*.cpp> -lib_deps = - ${rak4631_13302.lib_deps} - densaugeo/base64 @ ~1.4.0 - -[env:RAK_4631_13302_terminal_chat] -extends = rak4631_13302 -build_flags = - ${rak4631_13302.build_flags} - -D MAX_CONTACTS=100 - -D MAX_GROUP_CHANNELS=1 - ;-D MESH_PACKET_LOGGING=1 - ;-D MESH_DEBUG=1 -build_src_filter = ${rak4631_13302.build_src_filter} - +<../examples/simple_secure_chat/main.cpp> -lib_deps = - ${rak4631_13302.lib_deps} - densaugeo/base64 @ ~1.4.0 - -[env:RAK_4631_13302_sensor] -extends = rak4631_13302 -build_flags = - ${rak4631_13302.build_flags} - -D DISPLAY_CLASS=SSD1306Display - -D ADVERT_NAME='"RAK4631 Sensor"' - -D ADVERT_LAT=0.0 - -D ADVERT_LON=0.0 - -D ADMIN_PASSWORD='"password"' - ;-D MESH_PACKET_LOGGING=1 - ;-D MESH_DEBUG=1 -build_src_filter = ${rak4631_13302.build_src_filter} - + - +<../examples/simple_sensor> - -[env:RAK_4631_13302_kiss_modem] -extends = rak4631_13302 -build_src_filter = ${rak4631_13302.build_src_filter} - +<../examples/kiss_modem/> diff --git a/variants/rak3401/target.cpp b/variants/rak3401/target.cpp index dac12ede7..b9d142b3d 100644 --- a/variants/rak3401/target.cpp +++ b/variants/rak3401/target.cpp @@ -1,6 +1,8 @@ #include #include "target.h" #include +#include "OnboardRadioSleep.h" +#include RAK3401Board board; @@ -32,49 +34,91 @@ AutoDiscoverRTCClock rtc_clock(fallback_clock); EnvironmentSensorManager sensors; #endif -#ifdef RAK4631_ONBOARD_SX1262_SLEEP -// With a RAK13302 fitted the RAK4631's own SX1262 never gets initialized, so it -// sits in STDBY_RC drawing standby current for the life of the board. Firmware -// cannot cut its supply -- P1.05 is the RF switch rail, not the radio's -- so -// bring it up on its own pins just long enough to put it into cold sleep. -static void sleep_onboard_radio() { - pinMode(ONBOARD_LORA_ANT_SW, OUTPUT); - digitalWrite(ONBOARD_LORA_ANT_SW, LOW); // nothing downstream needs the RF switch +namespace { +class OnboardRadioIO { +public: + void begin() { + digitalWrite(ONBOARD_LORA_NSS, HIGH); + pinMode(ONBOARD_LORA_NSS, OUTPUT); + digitalWrite(ONBOARD_LORA_RESET, HIGH); + pinMode(ONBOARD_LORA_RESET, OUTPUT); + digitalWrite(ONBOARD_LORA_ANT_SW, LOW); + pinMode(ONBOARD_LORA_ANT_SW, OUTPUT); + // BUSY is weakly pulled high during startup; never override it with a pull-down. + pinMode(ONBOARD_LORA_BUSY, INPUT_PULLUP); + SPI.setPins(ONBOARD_LORA_MISO, ONBOARD_LORA_SCLK, ONBOARD_LORA_MOSI); + SPI.begin(); + pinMode(ONBOARD_LORA_MISO, INPUT_PULLDOWN); + } - SPI.setPins(ONBOARD_LORA_MISO, ONBOARD_LORA_SCLK, ONBOARD_LORA_MOSI); - SPI.begin(); + void reset() { + digitalWrite(ONBOARD_LORA_RESET, LOW); + delay(1); + digitalWrite(ONBOARD_LORA_RESET, HIGH); + delay(5); + } - Module mod(ONBOARD_LORA_NSS, ONBOARD_LORA_DIO_1, ONBOARD_LORA_RESET, ONBOARD_LORA_BUSY, SPI); - SX1262 onboard(&mod); + bool waitBusy(bool high, uint32_t timeout) { + uint32_t start = millis(); + while ((digitalRead(ONBOARD_LORA_BUSY) != LOW) != high) { + if (millis() - start >= timeout) return false; + delay(1); + } + return true; + } - // BUSY is driven low in STDBY_RC and high while asleep, so it doubles as a - // non-invasive readback of what state we found the chip in and left it in. - pinMode(ONBOARD_LORA_BUSY, INPUT); - int busy_before = digitalRead(ONBOARD_LORA_BUSY); + void readVersion(char* version) { + SPI.beginTransaction(SPISettings(2000000, MSBFIRST, SPI_MODE0)); + digitalWrite(ONBOARD_LORA_NSS, LOW); + SPI.transfer(RADIOLIB_SX126X_CMD_READ_REGISTER); + SPI.transfer(RADIOLIB_SX126X_REG_VERSION_STRING >> 8); + SPI.transfer(RADIOLIB_SX126X_REG_VERSION_STRING & 0xFF); + SPI.transfer(0); + for (unsigned i = 0; i < 6; i++) version[i] = SPI.transfer(0); + digitalWrite(ONBOARD_LORA_NSS, HIGH); + SPI.endTransaction(); + } - // begin() resets the chip and leaves it in standby. A TCXO calibration failure - // still leaves SPI usable, so issue the sleep regardless of what it returns. - int status = onboard.begin(434.0f, 125.0f, 9, 7, RADIOLIB_SX126X_SYNC_WORD_PRIVATE, - 0, 8, ONBOARD_LORA_TCXO_VOLTAGE, false); - int slept = onboard.sleep(false); // cold sleep: config discarded, RTC off - delay(2); - int busy_after = digitalRead(ONBOARD_LORA_BUSY); - MESH_DEBUG_PRINTLN("onboard SX1262: begin=%d sleep=%d busy %d->%d", - status, slept, busy_before, busy_after); + void releaseProbePulls() { + pinMode(ONBOARD_LORA_BUSY, INPUT); + pinMode(ONBOARD_LORA_MISO, INPUT); + } - SPI.end(); // release SPIM3 so std_init() can repin it onto the RAK13302 + void sleep() { + SPI.beginTransaction(SPISettings(2000000, MSBFIRST, SPI_MODE0)); + digitalWrite(ONBOARD_LORA_NSS, LOW); + SPI.transfer(RADIOLIB_SX126X_CMD_SET_SLEEP); + SPI.transfer(RADIOLIB_SX126X_SLEEP_START_COLD | RADIOLIB_SX126X_SLEEP_RTC_OFF); + digitalWrite(ONBOARD_LORA_NSS, HIGH); + SPI.endTransaction(); + delay(1); + } - // The SX1262 wakes on an NSS falling edge, so keep NSS driven high from here on. - digitalWrite(ONBOARD_LORA_NSS, HIGH); - pinMode(ONBOARD_LORA_NSS, OUTPUT); + void end() { + SPI.end(); + // INPUT leaves buffers enabled on floating pins; restore Nordic's disconnected default. + nrf_gpio_cfg_default(g_ADigitalPinMap[ONBOARD_LORA_SCLK]); + nrf_gpio_cfg_default(g_ADigitalPinMap[ONBOARD_LORA_MOSI]); + nrf_gpio_cfg_default(g_ADigitalPinMap[ONBOARD_LORA_MISO]); + nrf_gpio_cfg_default(g_ADigitalPinMap[ONBOARD_LORA_BUSY]); + // An NSS falling edge wakes the radio, so leave it driven high. + digitalWrite(ONBOARD_LORA_NSS, HIGH); + } +}; } -#endif bool radio_init() { rtc_clock.begin(Wire); -#ifdef RAK4631_ONBOARD_SX1262_SLEEP - sleep_onboard_radio(); -#endif + // Called once from setup, before SPI is started for the RAK13302. + OnboardRadioIO onboard; + const uint32_t started = millis(); + // The SX1262 version register shares the "SX1261" prefix used by RadioLib. + const auto state = rak3401::sleepOnboardRadio(onboard, RADIOLIB_SX1262_CHIP_TYPE); + const char* outcome = state == rak3401::OnboardRadioState::Absent ? "absent" : + state == rak3401::OnboardRadioState::Asleep ? "asleep" : + state == rak3401::OnboardRadioState::BusyTimeout ? "busy-timeout" : "sleep-failed"; + MESH_DEBUG_PRINTLN("onboard SX1262: %s elapsed=%lu ms", outcome, + (unsigned long)(millis() - started)); return radio.std_init(&SPI); } diff --git a/variants/rak3401/variant.h b/variants/rak3401/variant.h index 0576dadb8..779cb3cd5 100644 --- a/variants/rak3401/variant.h +++ b/variants/rak3401/variant.h @@ -175,10 +175,7 @@ static const uint8_t AREF = PIN_AREF; #define P_LORA_BUSY SX126X_BUSY #define P_LORA_RESET SX126X_RESET -// The RAK4631 core carries its own SX1262, which is unused when a RAK13302 -// supplies the RF path. RAK4631_ONBOARD_SX1262_SLEEP builds put it into cold -// sleep at boot; on a genuine RAK3401 these pins are unconnected. -#ifdef RAK4631_ONBOARD_SX1262_SLEEP +// Optional RAK4631 onboard radio; these internal pins are unused on RAK3401. #define ONBOARD_LORA_NSS (42) // P1.10 #define ONBOARD_LORA_SCLK (43) // P1.11 #define ONBOARD_LORA_MOSI (44) // P1.12 @@ -187,8 +184,6 @@ static const uint8_t AREF = PIN_AREF; #define ONBOARD_LORA_DIO_1 (47) // P1.15 #define ONBOARD_LORA_RESET (38) // P1.06 #define ONBOARD_LORA_ANT_SW (37) // P1.05, powers the onboard RF switch -#define ONBOARD_LORA_TCXO_VOLTAGE 1.8 -#endif // enables 3.3V periphery like GPS or IO Module // Do not toggle this for GPS power savings From d58042d8d25fbc9177f1b393ba0e393e3e5b276f Mon Sep 17 00:00:00 2001 From: agessaman Date: Fri, 16 Oct 2026 20:46:04 -0700 Subject: [PATCH 4/4] fix(rak3401): sleep onboard SX1262 before boot voltage check Move the onboard radio probe into RAK3401Board::begin() so a low-voltage SYSTEMOFF at boot no longer leaves the RAK4631's onboard SX1262 in standby. Add board startup tests and run them in CI. --- .github/workflows/run-unit-tests.yml | 2 +- platformio.ini | 8 ++- .../mocks/Arduino.h | 18 +++++ test/test_rak3401_board_startup/mocks/Wire.h | 6 ++ .../mocks/helpers/NRF52Board.h | 44 ++++++++++++ .../test_board_startup.cpp | 70 +++++++++++++++++++ variants/rak3401/OnboardRadioSleep.h | 3 + variants/rak3401/RAK3401Board.cpp | 3 + variants/rak3401/target.cpp | 9 ++- 9 files changed, 157 insertions(+), 6 deletions(-) create mode 100644 test/test_rak3401_board_startup/mocks/Arduino.h create mode 100644 test/test_rak3401_board_startup/mocks/Wire.h create mode 100644 test/test_rak3401_board_startup/mocks/helpers/NRF52Board.h create mode 100644 test/test_rak3401_board_startup/test_board_startup.cpp diff --git a/.github/workflows/run-unit-tests.yml b/.github/workflows/run-unit-tests.yml index 5d48f4c67..f8145ecd2 100644 --- a/.github/workflows/run-unit-tests.yml +++ b/.github/workflows/run-unit-tests.yml @@ -20,7 +20,7 @@ jobs: uses: ./.github/actions/setup-build-environment - name: Run Unit Tests - run: pio test -e native -e native_kiss_modem -vv + run: pio test -e native -e native_kiss_modem -e native_rak3401_onboard_radio -vv - name: Upload Test Results # Upload test results even if the test step failed. diff --git a/platformio.ini b/platformio.ini index e305d177d..ef6b1f39e 100644 --- a/platformio.ini +++ b/platformio.ini @@ -165,6 +165,7 @@ build_flags = -std=c++17 -I test/mocks test_build_src = yes test_ignore = test_kiss_modem + test_rak3401_board_startup build_src_filter = -<*> +<../src/Utils.cpp> @@ -174,10 +175,13 @@ lib_deps = google/googletest @ 1.17.0 [env:native_rak3401_onboard_radio] -; Header-only tests without unrelated production sources; also included in env:native CI. +; Board startup needs isolated GPIO and power-management mocks. extends = env:native test_build_src = no -test_filter = test_rak3401_onboard_radio +test_filter = test_rak3401_* +test_ignore = +build_flags = -I test/test_rak3401_board_startup/mocks + ${env:native.build_flags} [env:native_kiss_modem] platform = native diff --git a/test/test_rak3401_board_startup/mocks/Arduino.h b/test/test_rak3401_board_startup/mocks/Arduino.h new file mode 100644 index 000000000..d505af36a --- /dev/null +++ b/test/test_rak3401_board_startup/mocks/Arduino.h @@ -0,0 +1,18 @@ +#pragma once + +#include "../../mocks/Arduino.h" + +#define NRF52_POWER_MANAGEMENT 1 +#define PWRMGT_LPCOMP_AIN 3 +#define PWRMGT_LPCOMP_REFSEL 4 +#define PWRMGT_VOLTAGE_BOOTLOCK 3300 +#define SX126X_POWER_EN 21 +#define INPUT 0 +#define OUTPUT 1 +#define LOW 0 +#define HIGH 1 + +void pinMode(uint32_t pin, uint32_t mode); +void digitalWrite(uint32_t pin, uint32_t value); +void analogReadResolution(uint32_t bits); +uint32_t analogRead(uint32_t pin); diff --git a/test/test_rak3401_board_startup/mocks/Wire.h b/test/test_rak3401_board_startup/mocks/Wire.h new file mode 100644 index 000000000..c24e63065 --- /dev/null +++ b/test/test_rak3401_board_startup/mocks/Wire.h @@ -0,0 +1,6 @@ +#pragma once + +struct StartupWire { + void begin() {} +}; +inline StartupWire Wire; diff --git a/test/test_rak3401_board_startup/mocks/helpers/NRF52Board.h b/test/test_rak3401_board_startup/mocks/helpers/NRF52Board.h new file mode 100644 index 000000000..96c892ae2 --- /dev/null +++ b/test/test_rak3401_board_startup/mocks/helpers/NRF52Board.h @@ -0,0 +1,44 @@ +#pragma once + +#include +#include +#include + +#define SHUTDOWN_REASON_LOW_VOLTAGE 0x4C +#define SHUTDOWN_REASON_BOOT_PROTECT 0x42 + +struct PowerMgtConfig { + uint8_t lpcomp_ain_channel; + uint8_t lpcomp_refsel; + uint16_t voltage_bootlock; +}; + +namespace startup_test { +extern std::vector events; +extern bool permitBoot; +struct SystemOff { uint8_t reason; }; +} + +class NRF52Board { +protected: + bool checkBootVoltage(const PowerMgtConfig*) { + startup_test::events.push_back("voltage"); + if (!startup_test::permitBoot) initiateShutdown(SHUTDOWN_REASON_BOOT_PROTECT); + return true; + } + virtual void initiateShutdown(uint8_t reason) { enterSystemOff(reason); } + void configureVoltageWake(uint8_t, uint8_t) {} + void enterSystemOff(uint8_t reason) { + startup_test::events.push_back("off"); + throw startup_test::SystemOff{reason}; + } +public: + explicit NRF52Board(const char* = nullptr) {} + virtual uint16_t getBattMilliVolts() = 0; + virtual const char* getManufacturerName() const = 0; +}; + +class NRF52BoardDCDC : virtual public NRF52Board { +public: + void begin() {} +}; diff --git a/test/test_rak3401_board_startup/test_board_startup.cpp b/test/test_rak3401_board_startup/test_board_startup.cpp new file mode 100644 index 000000000..0bbf2e5aa --- /dev/null +++ b/test/test_rak3401_board_startup/test_board_startup.cpp @@ -0,0 +1,70 @@ +#include +#include +// Exercise the real startup code with a power-management stub that stops at SYSTEMOFF. +#include "../../variants/rak3401/RAK3401Board.cpp" + +namespace startup_test { +std::vector events; +bool permitBoot; +std::array outputs; +rak3401::OnboardRadioState radioState; +} + +void pinMode(uint32_t, uint32_t) {} +void digitalWrite(uint32_t pin, uint32_t value) { startup_test::outputs.at(pin) = value; } +void analogReadResolution(uint32_t) {} +uint32_t analogRead(uint32_t) { return 2500; } + +rak3401::OnboardRadioState rak3401::sleepOnboardRadio() { + startup_test::events.push_back("onboard"); + return startup_test::radioState; +} + +class RakBoardStartup : public testing::Test { +protected: + void SetUp() override { + startup_test::events.clear(); + startup_test::outputs.fill(HIGH); + startup_test::permitBoot = true; + startup_test::radioState = rak3401::OnboardRadioState::Asleep; + } +}; + +TEST_F(RakBoardStartup, OnboardRadioHandledBeforeVoltageCheck) { + RAK3401Board board; + board.begin(); + EXPECT_EQ(startup_test::events, (std::vector{"onboard", "voltage"})); + EXPECT_EQ(startup_test::outputs.at(SX126X_POWER_EN), HIGH); + EXPECT_EQ(startup_test::outputs.at(PIN_3V3_EN), HIGH); +} + +TEST_F(RakBoardStartup, LowVoltageExitStillHandlesOnboardRadio) { + startup_test::permitBoot = false; + RAK3401Board board; + try { + board.begin(); + FAIL() << "Expected protective shutdown"; + } catch (const startup_test::SystemOff& off) { + EXPECT_EQ(off.reason, SHUTDOWN_REASON_BOOT_PROTECT); + } + EXPECT_EQ(startup_test::events, (std::vector{"onboard", "voltage", "off"})); + EXPECT_EQ(startup_test::outputs.at(SX126X_POWER_EN), LOW); + EXPECT_EQ(startup_test::outputs.at(PIN_3V3_EN), LOW); +} + +TEST_F(RakBoardStartup, OptionalRadioFailuresDoNotBypassBootProtection) { + for (auto state : {rak3401::OnboardRadioState::Absent, rak3401::OnboardRadioState::BusyTimeout, + rak3401::OnboardRadioState::SleepFailed}) { + startup_test::events.clear(); + startup_test::permitBoot = false; + startup_test::radioState = state; + RAK3401Board board; + EXPECT_THROW(board.begin(), startup_test::SystemOff); + EXPECT_EQ(startup_test::events, (std::vector{"onboard", "voltage", "off"})); + } +} + +int main(int argc, char** argv) { + testing::InitGoogleTest(&argc, argv); + return RUN_ALL_TESTS(); +} diff --git a/variants/rak3401/OnboardRadioSleep.h b/variants/rak3401/OnboardRadioSleep.h index 7f6d1c55a..a9690cbf8 100644 --- a/variants/rak3401/OnboardRadioSleep.h +++ b/variants/rak3401/OnboardRadioSleep.h @@ -6,6 +6,9 @@ namespace rak3401 { enum class OnboardRadioState { Absent, Asleep, BusyTimeout, SleepFailed }; +// Board startup only, before the primary radio starts SPI. +OnboardRadioState sleepOnboardRadio(); + // IO owns the temporary SPI pin assignment; every outcome must release it. template OnboardRadioState sleepOnboardRadio(IO& io, const char* expectedVersion) { diff --git a/variants/rak3401/RAK3401Board.cpp b/variants/rak3401/RAK3401Board.cpp index cbf7c1087..6f59be409 100644 --- a/variants/rak3401/RAK3401Board.cpp +++ b/variants/rak3401/RAK3401Board.cpp @@ -2,6 +2,7 @@ #include #include "RAK3401Board.h" +#include "OnboardRadioSleep.h" #ifdef NRF52_POWER_MANAGEMENT // Static configuration for power management @@ -30,6 +31,8 @@ void RAK3401Board::initiateShutdown(uint8_t reason) { void RAK3401Board::begin() { NRF52BoardDCDC::begin(); + // Voltage protection can enter SYSTEMOFF before radio_init() is reached. + rak3401::sleepOnboardRadio(); pinMode(PIN_VBAT_READ, INPUT); #ifdef PIN_USER_BTN pinMode(PIN_USER_BTN, INPUT_PULLUP); diff --git a/variants/rak3401/target.cpp b/variants/rak3401/target.cpp index b9d142b3d..bd971c551 100644 --- a/variants/rak3401/target.cpp +++ b/variants/rak3401/target.cpp @@ -107,9 +107,7 @@ public: }; } -bool radio_init() { - rtc_clock.begin(Wire); - // Called once from setup, before SPI is started for the RAK13302. +rak3401::OnboardRadioState rak3401::sleepOnboardRadio() { OnboardRadioIO onboard; const uint32_t started = millis(); // The SX1262 version register shares the "SX1261" prefix used by RadioLib. @@ -119,6 +117,11 @@ bool radio_init() { state == rak3401::OnboardRadioState::BusyTimeout ? "busy-timeout" : "sleep-failed"; MESH_DEBUG_PRINTLN("onboard SX1262: %s elapsed=%lu ms", outcome, (unsigned long)(millis() - started)); + return state; +} + +bool radio_init() { + rtc_clock.begin(Wire); return radio.std_init(&SPI); }