[SX1262] Support deep sleep by allowing ::begin(...) without reset of module.

.github/workflows/main.yml

@@ -47,17 +47,17 @@ jobs:
           - id: arduino:avr:mega
             run: |
               echo "options=':cpu=atmega2560'" >> $GITHUB_OUTPUT
-              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update|_ESP32_)" >> $GITHUB_OUTPUT
           - id: arduino:mbed:nano33ble
           - id: arduino:mbed:envie_m4
           - id: arduino:megaavr:uno2018
             run: |
               echo "options=':mode=on'" >> $GITHUB_OUTPUT
-              echo "skip-pattern=(STM32WL|LoRaWAN|LR11x0_Firmware_Update)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LoRaWAN|LR11x0_Firmware_Update|_ESP32_)" >> $GITHUB_OUTPUT
           - id: arduino:sam:arduino_due_x
           - id: arduino:samd:arduino_zero_native
             run: |
-              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update|_ESP32_)" >> $GITHUB_OUTPUT
           - id: adafruit:samd:adafruit_feather_m0
             run: |
               echo "options=':usbstack=arduino,debug=off'" >> $GITHUB_OUTPUT
@@ -72,55 +72,55 @@ jobs:
               echo "/home/runner/.local/bin" >> $GITHUB_PATH
               echo "options=':softdevice=s132v6,debug=l0'" >> $GITHUB_OUTPUT
               echo "index-url=--additional-urls https://adafruit.github.io/arduino-board-index/package_adafruit_index.json" >> $GITHUB_OUTPUT
-              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update|_ESP32_)" >> $GITHUB_OUTPUT
           - id: esp32:esp32:esp32
             run: |
               python -m pip install pyserial
               echo "version=2.0.17" >> $GITHUB_OUTPUT
               echo "index-url=--additional-urls https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json" >> $GITHUB_OUTPUT
           - id: esp8266:esp8266:generic
             run: |
-              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update|_ESP32_)" >> $GITHUB_OUTPUT
               echo "options=':xtal=80,ResetMethod=ck,CrystalFreq=26,FlashFreq=40,FlashMode=qio,eesz=512K'" >> $GITHUB_OUTPUT
               echo "index-url=--additional-urls http://arduino.esp8266.com/stable/package_esp8266com_index.json" >> $GITHUB_OUTPUT
           - id: STMicroelectronics:stm32:GenF3
             run: |
               echo "options=':pnum=BLACKPILL_F303CC'" >> $GITHUB_OUTPUT
               echo "index-url=--additional-urls https://raw.githubusercontent.com/stm32duino/BoardManagerFiles/main/package_stmicroelectronics_index.json" >> $GITHUB_OUTPUT
-              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update|_ESP32_)" >> $GITHUB_OUTPUT
           - id: STMicroelectronics:stm32:Nucleo_64
             run: |
               echo "options=':pnum=NUCLEO_WL55JC1'" >> $GITHUB_OUTPUT
               # Do *not* skip STM32WL examples
-              echo "skip-pattern=(LR11x0_Firmware_Update)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(LR11x0_Firmware_Update|_ESP32_)" >> $GITHUB_OUTPUT
               echo "index-url=--additional-urls https://raw.githubusercontent.com/stm32duino/BoardManagerFiles/main/package_stmicroelectronics_index.json" >> $GITHUB_OUTPUT
           - id: stm32duino:STM32F1:mapleMini
             run: |
               echo "options=':bootloader_version=original,cpu_speed=speed_72mhz'" >> $GITHUB_OUTPUT
-              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update|_ESP32_)" >> $GITHUB_OUTPUT
               echo "index-url=--additional-urls http://dan.drown.org/stm32duino/package_STM32duino_index.json" >> $GITHUB_OUTPUT
           - id: MegaCoreX:megaavr:4809
             run: |
               echo "index-url=--additional-urls https://mcudude.github.io/MegaCoreX/package_MCUdude_MegaCoreX_index.json" >> $GITHUB_OUTPUT
-              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update|LoRaWAN)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update|LoRaWAN|_ESP32_)" >> $GITHUB_OUTPUT
           - id: arduino:mbed_rp2040:pico
           - id: rp2040:rp2040:rpipico
             run: echo "index-url=--additional-urls https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json" >> $GITHUB_OUTPUT
           - id: CubeCell:CubeCell:CubeCell-Board
             run: |
-              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update|_ESP32_)" >> $GITHUB_OUTPUT
               echo "index-url=--additional-urls https://resource.heltec.cn/download/package_CubeCell_index.json" >> $GITHUB_OUTPUT
           - id: MegaCore:avr:1281
             run: |
               echo "index-url=--additional-urls https://mcudude.github.io/MegaCore/package_MCUdude_MegaCore_index.json" >> $GITHUB_OUTPUT
-              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LR11x0_Firmware_Update|_ESP32_)" >> $GITHUB_OUTPUT
           - id: teensy:avr:teensy41
             run: |
-              echo "skip-pattern=(STM32WL|LoRaWAN)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LoRaWAN|_ESP32_)" >> $GITHUB_OUTPUT
               echo "index-url=--additional-urls https://www.pjrc.com/teensy/package_teensy_index.json" >> $GITHUB_OUTPUT
           - id: arduino:renesas_uno:minima
             run: |
-              echo "skip-pattern=(STM32WL|LoRaWAN|LR11x0_Firmware_Update)" >> $GITHUB_OUTPUT
+              echo "skip-pattern=(STM32WL|LoRaWAN|LR11x0_Firmware_Update|_ESP32_)" >> $GITHUB_OUTPUT
           - id: SiliconLabs:silabs:xg24explorerkit
             run: | 
               echo "index-url=--additional-urls https://siliconlabs.github.io/arduino/package_arduinosilabs_index.json" >> $GITHUB_OUTPUT

examples/SX126x/SX126x_ESP32_Deep_Sleep/SX126x_ESP32_Deep_Sleep.ino

@@ -0,0 +1,201 @@
+#if !defined(ESP32)
+  #error This example is only for ESP32-based boards!
+#endif
+/*
+  RadioLib SX126x ESP32 Deep Sleep Example
+
+  This example listens and receives LoRa transmissions while
+  deep sleeping the ESP32 MCU. Once a packet is received, an
+  interrupt is triggered that awakens the ESP32. To successfully
+  receive data, the following settings have to be the same on
+  both transmitter and receiver:
+  - carrier frequency
+  - bandwidth
+  - spreading factor
+  - coding rate
+  - sync word
+
+  Other modules from SX126x family can also be used.
+
+  For default module settings, see the wiki page
+  https://github.com/jgromes/RadioLib/wiki/Default-configuration#sx126x---lora-modem
+
+  For full API reference, see the GitHub Pages
+  https://jgromes.github.io/RadioLib/
+*/
+
+// include the library
+#include <RadioLib.h>
+#include <driver/rtc_io.h>
+
+// SX1262 has the following connections:
+#define SX1262_NSS 10
+#define SX1262_DIO1 2 // MUST be a RTC GPIO to support deep sleep
+#define SX1262_NRST 3
+#define SX1262_BUSY 9
+SX1262 radio = new Module(SX1262_NSS, SX1262_DIO1, SX1262_NRST, SX1262_BUSY);
+
+// or detect the pinout automatically using RadioBoards
+// https://github.com/radiolib-org/RadioBoards
+/*
+#define RADIO_BOARD_AUTO
+#include <RadioBoards.h>
+Radio radio = new RadioModule();
+*/
+
+// timer to prevent sleep
+#define SLEEP_AFTER_MS 5000
+unsigned long sleepAfter = 0;
+
+// flag to indicate that a packet was received
+volatile bool receivedFlag = false;
+
+// this function is called when a complete packet
+// is received by the module
+// IMPORTANT: this function MUST be 'void' type
+//            and MUST NOT have any arguments!
+ICACHE_RAM_ATTR void setFlag(void) {
+  // we got a packet, set the flag
+  receivedFlag = true;
+}
+
+void setup() {
+  Serial.begin(9600);
+  // give some time for the serial to connect
+  delay(2000);
+  sleepAfter = millis() + SLEEP_AFTER_MS; // Deep sleep ESP32 after 5 seconds of inactivity
+
+  if (!rtc_gpio_is_valid_gpio((gpio_num_t)SX1262_DIO1)) {
+    Serial.println(F("[ESP32] Deep sleep requires DIO1 be wired to a RTC GPIO"));
+    while (true) { delay(10); }
+  }
+
+  auto wakeupReason = esp_sleep_get_wakeup_cause();
+  if (wakeupReason == ESP_SLEEP_WAKEUP_EXT1) {
+    Serial.println(F("[ESP32] Woke from deep sleep by radio interrupt"));
+  } else if (wakeupReason == ESP_SLEEP_WAKEUP_TIMER) {
+    Serial.println(F("[ESP32] Woke from deep sleep by timer"));
+  } else if (wakeupReason == ESP_SLEEP_WAKEUP_UNDEFINED) {
+    Serial.println(F("[ESP32] Power-on or hard reset"));
+  } else {
+    Serial.print(F("[ESP32] Woke from deep sleep by other reason: "));
+    Serial.println(wakeupReason);
+  }
+
+  bool resetModule = true;
+  if (wakeupReason != ESP_SLEEP_WAKEUP_UNDEFINED) {
+    // Only reset the module after a power-on/hard reset
+    resetModule = false;
+    // For any reason except a power-on/hard reset, check if DIO1 is high and set
+    // the interrupt flag. Even if we woke due to a timer or another pin, DIO1
+    // may be high if a packet arrived shortly after wakeup was triggered.
+    pinMode(SX1262_DIO1, INPUT_PULLDOWN);
+    if (digitalRead(SX1262_DIO1) == HIGH) {
+      Serial.println(F("[ESP32] DIO1 is high, setting received flag"));
+      setFlag();
+    }
+  }
+
+  // initialize SX1262
+  Serial.print(F("[SX1262] Initializing ... "));
+  int state = radio.begin(434.0, 125.0, 9, 7, RADIOLIB_SX126X_SYNC_WORD_PRIVATE, 10, 8, 1.6, false, resetModule);
+  if (state == RADIOLIB_ERR_NONE) {
+    Serial.println(F("success!"));
+  } else {
+    Serial.print(F("failed, code "));
+    Serial.println(state);
+    while (true) { delay(10); }
+  }
+
+  // set the function that will be called
+  // when new packet is received
+  radio.setPacketReceivedAction(setFlag);
+
+  // start listening for LoRa packets
+  Serial.print(F("[SX1262] Starting to listen ... "));
+  state = radio.startReceive();
+  if (state == RADIOLIB_ERR_NONE) {
+    Serial.println(F("success!"));
+  } else {
+    Serial.print(F("failed, code "));
+    Serial.println(state);
+    while (true) { delay(10); }
+  }
+}
+
+void loop() {
+  // check if the flag is set
+  if(receivedFlag) {
+    // reset flag
+    receivedFlag = false;
+    // reset sleep timer
+    sleepAfter = millis() + SLEEP_AFTER_MS;
+
+    // you can read received data as an Arduino String
+    String str;
+    int state = radio.readData(str);
+
+    // you can also read received data as byte array
+    /*
+      byte byteArr[8];
+      int numBytes = radio.getPacketLength();
+      int state = radio.readData(byteArr, numBytes);
+    */
+
+    if (state == RADIOLIB_ERR_NONE) {
+      // packet was successfully received
+      Serial.println(F("[SX1262] Received packet!"));
+
+      // print data of the packet
+      Serial.print(F("[SX1262] Data:\t\t"));
+      Serial.println(str);
+
+      // print RSSI (Received Signal Strength Indicator)
+      Serial.print(F("[SX1262] RSSI:\t\t"));
+      Serial.print(radio.getRSSI());
+      Serial.println(F(" dBm"));
+
+      // print SNR (Signal-to-Noise Ratio)
+      Serial.print(F("[SX1262] SNR:\t\t"));
+      Serial.print(radio.getSNR());
+      Serial.println(F(" dB"));
+
+      // print frequency error
+      Serial.print(F("[SX1262] Frequency error:\t"));
+      Serial.print(radio.getFrequencyError());
+      Serial.println(F(" Hz"));
+
+    } else if (state == RADIOLIB_ERR_CRC_MISMATCH) {
+      // packet was received, but is malformed
+      Serial.println(F("[SX1262] CRC error!"));
+
+    } else {
+      // some other error occurred
+      Serial.print(F("[SX1262] readData failed, code "));
+      Serial.println(state);
+
+    }
+  }
+
+  if ((long)(millis() - sleepAfter) > 0) {
+    Serial.println(F("[ESP32] Going to sleep now!"));
+
+    radio.clearPacketReceivedAction(); // Disable interrupt on DIO1 pin
+
+    uint64_t io_mask = 0;
+    io_mask |= (1ULL << SX1262_DIO1);
+    esp_err_t result = esp_sleep_enable_ext1_wakeup(io_mask, ESP_EXT1_WAKEUP_ANY_HIGH);
+    if (result != ESP_OK) {
+        Serial.print(F("[ESP32] Failed to configure ext1 wakeup, error code: "));
+        Serial.println(result);
+        sleepAfter = millis() + 1000; // don't try again immediately
+        return;
+    }
+
+    Serial.flush();
+
+    // put ESP32 into deep sleep - this will not return
+    esp_deep_sleep_start();
+    // not reached
+  }
+}

src/modules/LLCC68/LLCC68.cpp

@@ -6,14 +6,14 @@ LLCC68::LLCC68(Module* mod) : SX1262(mod) {
   this->XTAL = true;
 }
 
-int16_t LLCC68::begin(float freq, float bw, uint8_t sf, uint8_t cr, uint8_t syncWord, int8_t pwr, uint16_t preambleLength, float tcxoVoltage, bool useRegulatorLDO) {
+int16_t LLCC68::begin(float freq, float bw, uint8_t sf, uint8_t cr, uint8_t syncWord, int8_t pwr, uint16_t preambleLength, float tcxoVoltage, bool useRegulatorLDO, bool resetModule) {
   // execute common part
-  int16_t state = SX126x::begin(cr, syncWord, preambleLength, tcxoVoltage, useRegulatorLDO);
+  int16_t state = SX126x::begin(cr, syncWord, preambleLength, tcxoVoltage, useRegulatorLDO, resetModule);
   if(state == RADIOLIB_ERR_CHIP_NOT_FOUND) {
     // bit of a hack, but some LLCC68 chips report as "SX1261", try that
     // for full discussion, see https://github.com/jgromes/RadioLib/issues/1329
     chipType = RADIOLIB_SX1261_CHIP_TYPE;
-    state = SX126x::begin(cr, syncWord, preambleLength, tcxoVoltage, useRegulatorLDO);
+    state = SX126x::begin(cr, syncWord, preambleLength, tcxoVoltage, useRegulatorLDO, resetModule);
     RADIOLIB_DEBUG_PRINTLN("LLCC68 version string not found, using SX1261 instead");
   }
   RADIOLIB_ASSERT(state);

src/modules/LLCC68/LLCC68.h

@@ -38,10 +38,12 @@ class LLCC68: public SX1262 {
       If you are seeing -706/-707 error codes, it likely means you are using a module with TCXO.
       To use TCXO, either set this value to its reference voltage, or set SX126x::XTAL to false.
       \param useRegulatorLDO Whether to use only LDO regulator (true) or DC-DC regulator (false). Defaults to false.
+      \param resetModule Whether to perform a module reset during initialization. Defaults to true.
+      Setting this to false assumes that the module is already in a known state.
       \returns \ref status_codes
     */
-    int16_t begin(float freq = 434.0, float bw = 125.0, uint8_t sf = 9, uint8_t cr = 7, uint8_t syncWord = RADIOLIB_SX126X_SYNC_WORD_PRIVATE, int8_t power = 10, uint16_t preambleLength = 8, float tcxoVoltage = 0, bool useRegulatorLDO = false) override;
-    
+    int16_t begin(float freq = 434.0, float bw = 125.0, uint8_t sf = 9, uint8_t cr = 7, uint8_t syncWord = RADIOLIB_SX126X_SYNC_WORD_PRIVATE, int8_t power = 10, uint16_t preambleLength = 8, float tcxoVoltage = 0, bool useRegulatorLDO = false, bool resetModule = true) override;
+
     /*!
       \brief Initialization method for FSK modem.
       \param freq Carrier frequency in MHz. Defaults to 434.0 MHz.

src/modules/SX126x/SX1262.cpp

@@ -7,9 +7,9 @@ SX1262::SX1262(Module* mod) : SX126x(mod) {
   chipType = RADIOLIB_SX1262_CHIP_TYPE;
 }
 
-int16_t SX1262::begin(float freq, float bw, uint8_t sf, uint8_t cr, uint8_t syncWord, int8_t power, uint16_t preambleLength, float tcxoVoltage, bool useRegulatorLDO) {
+int16_t SX1262::begin(float freq, float bw, uint8_t sf, uint8_t cr, uint8_t syncWord, int8_t power, uint16_t preambleLength, float tcxoVoltage, bool useRegulatorLDO, bool resetModule) {
   // execute common part
-  int16_t state = SX126x::begin(cr, syncWord, preambleLength, tcxoVoltage, useRegulatorLDO);
+  int16_t state = SX126x::begin(cr, syncWord, preambleLength, tcxoVoltage, useRegulatorLDO, resetModule);
   RADIOLIB_ASSERT(state);
 
   // configure publicly accessible settings

src/modules/SX126x/SX1262.h

@@ -43,9 +43,11 @@ class SX1262: public SX126x {
       If you are seeing -706/-707 error codes, it likely means you are using non-0 value for module with XTAL.
       To use XTAL, either set this value to 0, or set SX126x::XTAL to true.
       \param useRegulatorLDO Whether to use only LDO regulator (true) or DC-DC regulator (false). Defaults to false.
+      \param resetModule Whether to perform a module reset during initialization. Defaults to true.
+      Setting this to false assumes that the module is already in a known state.
       \returns \ref status_codes
     */
-    virtual int16_t begin(float freq = 434.0, float bw = 125.0, uint8_t sf = 9, uint8_t cr = 7, uint8_t syncWord = RADIOLIB_SX126X_SYNC_WORD_PRIVATE, int8_t power = 10, uint16_t preambleLength = 8, float tcxoVoltage = 1.6, bool useRegulatorLDO = false);
+    virtual int16_t begin(float freq = 434.0, float bw = 125.0, uint8_t sf = 9, uint8_t cr = 7, uint8_t syncWord = RADIOLIB_SX126X_SYNC_WORD_PRIVATE, int8_t power = 10, uint16_t preambleLength = 8, float tcxoVoltage = 1.6, bool useRegulatorLDO = false, bool resetModule = true);
 
     /*!
       \brief Initialization method for FSK modem.