Merge pull request #3613 from agessaman/feat/rak13302-auto-onboard-sleep

feat(rak3401): automatically sleep the RAK4631’s onboard SX1262 when paired with a RAK13302
This commit is contained in:
fdlamotte authored and GitHub committed 2026-11-10 09:01:51 -04:00
commit 4b71ed4498
11 files changed
+353 -1

No files matched your search

+1 -1
View File
@@ -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.
+10
View File
@@ -168,6 +168,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>
@@ -177,6 +178,15 @@ build_src_filter =
lib_deps =
google/googletest @ 1.17.0
[env:native_rak3401_onboard_radio]
; Board startup needs isolated GPIO and power-management mocks.
extends = env:native
test_build_src = no
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
test_framework = googletest
@@ -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);
@@ -0,0 +1,6 @@
#pragma once
struct StartupWire {
void begin() {}
};
inline StartupWire Wire;
@@ -0,0 +1,44 @@
#pragma once
#include <Arduino.h>
#include <string>
#include <vector>
#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<std::string> 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() {}
};
@@ -0,0 +1,70 @@
#include <gtest/gtest.h>
#include <array>
// Exercise the real startup code with a power-management stub that stops at SYSTEMOFF.
#include "../../variants/rak3401/RAK3401Board.cpp"
namespace startup_test {
std::vector<std::string> events;
bool permitBoot;
std::array<uint32_t, 48> 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<std::string>{"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<std::string>{"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<std::string>{"onboard", "voltage", "off"}));
}
}
int main(int argc, char** argv) {
testing::InitGoogleTest(&argc, argv);
return RUN_ALL_TESTS();
}
@@ -0,0 +1,66 @@
#include <gtest/gtest.h>
#include <array>
#include <string>
#include "../../variants/rak3401/OnboardRadioSleep.h"
namespace {
struct FakeRadioIO {
std::string version = "SX1261";
std::array<bool, 3> 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();
}
+37
View File
@@ -0,0 +1,37 @@
#pragma once
#include <string.h>
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 <typename IO>
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;
}
}
+3
View File
@@ -2,6 +2,7 @@
#include <Wire.h>
#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);
+88
View File
@@ -1,6 +1,8 @@
#include <Arduino.h>
#include "target.h"
#include <helpers/ArduinoHelpers.h>
#include "OnboardRadioSleep.h"
#include <nrf_gpio.h>
RAK3401Board board;
@@ -33,6 +35,92 @@ AutoDiscoverRTCClock rtc_clock(fallback_clock);
EnvironmentSensorManager sensors;
#endif
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);
}
void reset() {
digitalWrite(ONBOARD_LORA_RESET, LOW);
delay(1);
digitalWrite(ONBOARD_LORA_RESET, HIGH);
delay(5);
}
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;
}
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();
}
void releaseProbePulls() {
pinMode(ONBOARD_LORA_BUSY, INPUT);
pinMode(ONBOARD_LORA_MISO, INPUT);
}
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);
}
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);
}
};
}
rak3401::OnboardRadioState rak3401::sleepOnboardRadio() {
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 state;
}
bool radio_init() {
rtc_clock.begin(Wire);
return radio.std_init(&SPI);
+10
View File
@@ -175,6 +175,16 @@ static const uint8_t AREF = PIN_AREF;
#define P_LORA_BUSY SX126X_BUSY
#define P_LORA_RESET SX126X_RESET
// 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
#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
// enables 3.3V periphery like GPS or IO Module
// Do not toggle this for GPS power savings
#define PIN_3V3_EN (34)