Channel scan configuration

src/modules/LR11x0/LR11x0.cpp

@@ -278,12 +278,21 @@ int16_t LR11x0::receiveDirect() {
 }
 
 int16_t LR11x0::scanChannel() {
-  return(this->scanChannel(RADIOLIB_LR11X0_CAD_PARAM_DEFAULT, RADIOLIB_LR11X0_CAD_PARAM_DEFAULT, RADIOLIB_LR11X0_CAD_PARAM_DEFAULT));
+  ChannelScanConfig_t config = {
+    .cad = {
+      .symNum = RADIOLIB_LR11X0_CAD_PARAM_DEFAULT,
+      .detPeak = RADIOLIB_LR11X0_CAD_PARAM_DEFAULT,
+      .detMin = RADIOLIB_LR11X0_CAD_PARAM_DEFAULT,
+      .exitMode = RADIOLIB_LR11X0_CAD_PARAM_DEFAULT,
+      .timeout = 0,
+    },
+  };
+  return(this->scanChannel(config));
 }
 
-int16_t LR11x0::scanChannel(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin) {
+int16_t LR11x0::scanChannel(ChannelScanConfig_t config) {
   // set mode to CAD
-  int state = startChannelScan(symbolNum, detPeak, detMin);
+  int state = startChannelScan(config);
   RADIOLIB_ASSERT(state);
 
   // wait for channel activity detected or timeout
@@ -541,10 +550,19 @@ int16_t LR11x0::readData(uint8_t* data, size_t len) {
 }
 
 int16_t LR11x0::startChannelScan() {
-  return(this->startChannelScan(RADIOLIB_LR11X0_CAD_PARAM_DEFAULT, RADIOLIB_LR11X0_CAD_PARAM_DEFAULT, RADIOLIB_LR11X0_CAD_PARAM_DEFAULT));
+  ChannelScanConfig_t config = {
+    .cad = {
+      .symNum = RADIOLIB_LR11X0_CAD_PARAM_DEFAULT,
+      .detPeak = RADIOLIB_LR11X0_CAD_PARAM_DEFAULT,
+      .detMin = RADIOLIB_LR11X0_CAD_PARAM_DEFAULT,
+      .exitMode = RADIOLIB_LR11X0_CAD_PARAM_DEFAULT,
+      .timeout = 0,
+    },
+  };
+  return(this->startChannelScan(config));
 }
 
-int16_t LR11x0::startChannelScan(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin) {
+int16_t LR11x0::startChannelScan(ChannelScanConfig_t config) {
   // check active modem
   int16_t state = RADIOLIB_ERR_NONE;
   uint8_t modem = RADIOLIB_LR11X0_PACKET_TYPE_NONE;
@@ -570,7 +588,7 @@ int16_t LR11x0::startChannelScan(uint8_t symbolNum, uint8_t detPeak, uint8_t det
   RADIOLIB_ASSERT(state);
 
   // set mode to CAD
-  return(startCad(symbolNum, detPeak, detMin));
+  return(startCad(config.cad.symNum, config.cad.detPeak, config.cad.detMin, config.cad.exitMode, config.cad.timeout));
 }
 
 int16_t LR11x0::getChannelScanResult() {
@@ -2007,7 +2025,7 @@ int16_t LR11x0::setPacketMode(uint8_t mode, uint8_t len) {
   return(state);
 }
 
-int16_t LR11x0::startCad(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin) {
+int16_t LR11x0::startCad(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin, uint8_t exitMode, RadioLibTime_t timeout) {
   // check active modem
   uint8_t type = RADIOLIB_LR11X0_PACKET_TYPE_NONE;
   int16_t state = getPacketType(&type);
@@ -2034,9 +2052,16 @@ int16_t LR11x0::startCad(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin) {
     min = 10;
   }
 
+  uint8_t mode = exitMode; 
+  if(mode == RADIOLIB_LR11X0_CAD_PARAM_DEFAULT) {
+    mode = RADIOLIB_LR11X0_CAD_EXIT_MODE_STBY_RC;
+  }
+
+  uint32_t timeout_raw = (float)timeout*1000 / 30.52f;
+
   // set CAD parameters
   // TODO add configurable exit mode and timeout
-  state = setCadParams(num, peak, min, RADIOLIB_LR11X0_CAD_EXIT_MODE_STBY_RC, 0);
+  state = setCadParams(num, peak, min, mode, timeout_raw);
   RADIOLIB_ASSERT(state);
 
   // start CAD

src/modules/LR11x0/LR11x0.h

@@ -844,12 +844,10 @@ class LR11x0: public PhysicalLayer {
 
     /*!
       \brief Performs scan for LoRa transmission in the current channel. Detects both preamble and payload.
-      \param symbolNum Number of symbols for CAD detection.
-      \param detPeak Peak value for CAD detection.
-      \param detMin Minimum value for CAD detection.
+      \param config CAD configuration structure.
       \returns \ref status_codes
     */
-    int16_t scanChannel(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin);
+    int16_t scanChannel(ChannelScanConfig_t config) override;
 
     /*!
       \brief Sets the module to standby mode (overload for PhysicalLayer compatibility, uses 13 MHz RC oscillator).
@@ -979,14 +977,12 @@ class LR11x0: public PhysicalLayer {
     int16_t startChannelScan() override;
 
     /*!
-      \brief Interrupt-driven channel activity detection method. IRQ1 will be activated
+      \brief Interrupt-driven channel activity detection method. DIO1 will be activated
       when LoRa preamble is detected, or upon timeout.
-      \param symbolNum Number of symbols for CAD detection. 
-      \param detPeak Peak value for CAD detection.
-      \param detMin Minimum value for CAD detection.
+      \param config CAD configuration structure.
       \returns \ref status_codes
     */
-    int16_t startChannelScan(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin);
+    int16_t startChannelScan(ChannelScanConfig_t config) override;
 
     /*!
       \brief Read the channel scan result
@@ -1618,7 +1614,7 @@ class LR11x0: public PhysicalLayer {
     bool findChip(uint8_t ver);
     int16_t config(uint8_t modem);
     int16_t setPacketMode(uint8_t mode, uint8_t len);
-    int16_t startCad(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin);
+    int16_t startCad(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin, uint8_t exitMode, RadioLibTime_t timeout);
     int16_t setHeaderType(uint8_t hdrType, size_t len = 0xFF);
 
     // common methods to avoid some copy-paste

src/modules/SX126x/SX126x.cpp

@@ -425,12 +425,21 @@ int16_t SX126x::packetMode() {
 }
 
 int16_t SX126x::scanChannel() {
-  return(this->scanChannel(RADIOLIB_SX126X_CAD_PARAM_DEFAULT, RADIOLIB_SX126X_CAD_PARAM_DEFAULT, RADIOLIB_SX126X_CAD_PARAM_DEFAULT));
-}
-
-int16_t SX126x::scanChannel(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin) {
+  ChannelScanConfig_t config = {
+    .cad = {
+      .symNum = RADIOLIB_SX126X_CAD_PARAM_DEFAULT,
+      .detPeak = RADIOLIB_SX126X_CAD_PARAM_DEFAULT,
+      .detMin = RADIOLIB_SX126X_CAD_PARAM_DEFAULT,
+      .exitMode = RADIOLIB_SX126X_CAD_PARAM_DEFAULT,
+      .timeout = 0,
+    },
+  };
+  return(this->scanChannel(config));
+}
+
+int16_t SX126x::scanChannel(ChannelScanConfig_t config) {
   // set mode to CAD
-  int state = startChannelScan(symbolNum, detPeak, detMin);
+  int state = startChannelScan(config);
   RADIOLIB_ASSERT(state);
 
   // wait for channel activity detected or timeout
@@ -732,10 +741,19 @@ int16_t SX126x::readData(uint8_t* data, size_t len) {
 }
 
 int16_t SX126x::startChannelScan() {
-  return(this->startChannelScan(RADIOLIB_SX126X_CAD_PARAM_DEFAULT, RADIOLIB_SX126X_CAD_PARAM_DEFAULT, RADIOLIB_SX126X_CAD_PARAM_DEFAULT));
-}
-
-int16_t SX126x::startChannelScan(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin) {
+  ChannelScanConfig_t config = {
+    .cad = {
+      .symNum = RADIOLIB_SX126X_CAD_PARAM_DEFAULT,
+      .detPeak = RADIOLIB_SX126X_CAD_PARAM_DEFAULT,
+      .detMin = RADIOLIB_SX126X_CAD_PARAM_DEFAULT,
+      .exitMode = RADIOLIB_SX126X_CAD_PARAM_DEFAULT,
+      .timeout = 0,
+    },
+  };
+  return(this->startChannelScan(config));
+}
+
+int16_t SX126x::startChannelScan(ChannelScanConfig_t config) {
   // check active modem
   if(getPacketType() != RADIOLIB_SX126X_PACKET_TYPE_LORA) {
     return(RADIOLIB_ERR_WRONG_MODEM);
@@ -757,7 +775,7 @@ int16_t SX126x::startChannelScan(uint8_t symbolNum, uint8_t detPeak, uint8_t det
   RADIOLIB_ASSERT(state);
 
   // set mode to CAD
-  state = setCad(symbolNum, detPeak, detMin);
+  state = setCad(config.cad.symNum, config.cad.detPeak, config.cad.detMin, config.cad.exitMode, config.cad.timeout);
   return(state);
 }
 
@@ -1761,8 +1779,7 @@ int16_t SX126x::setRx(uint32_t timeout) {
   return(this->mod->SPIwriteStream(RADIOLIB_SX126X_CMD_SET_RX, data, 3, true, false));
 }
 
-
-int16_t SX126x::setCad(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin) {
+int16_t SX126x::setCad(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin, uint8_t exitMode, RadioLibTime_t timeout) {
   // default CAD parameters are shown in Semtech AN1200.48, page 41.
   const uint8_t detPeakValues[6] = { 22, 22, 24, 25, 26, 30};
 
@@ -1773,29 +1790,17 @@ int16_t SX126x::setCad(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin) {
     this->spreadingFactor = 12;
   }
 
-  // build the packet
+  // build the packet with default configuration
   uint8_t data[7];
   data[0] = RADIOLIB_SX126X_CAD_ON_2_SYMB;
   data[1] = detPeakValues[this->spreadingFactor - 7];
   data[2] = RADIOLIB_SX126X_CAD_PARAM_DET_MIN;
   data[3] = RADIOLIB_SX126X_CAD_GOTO_STDBY;
-  data[4] = 0x00;
-  data[5] = 0x00;
-  data[6] = 0x00;
-
+  uint32_t timeout_raw = (float)timeout*1000 / 15.625f;
+  data[4] = (uint8_t)((timeout_raw >> 16) & 0xFF);
+  data[5] = (uint8_t)((timeout_raw >> 8) & 0xFF);
+  data[6] = (uint8_t)(timeout_raw & 0xFF);
 
- /*
-  CAD Configuration Note:
-  The default CAD configuration applied by `scanChannel` overrides the optimal SF-specific configurations, leading to suboptimal detection.
-  I.e., anything that is not RADIOLIB_SX126X_CAD_PARAM_DEFAULT is overridden. But CAD settings are SF specific.
-  To address this, the user override has been commented out, ensuring consistent application of the optimal CAD settings as 
-    per Semtech's Application Note AN1200.48 (page 41) for the 125KHz setting. This approach significantly reduces false CAD occurrences.
-    Testing has shown that there is no reason for a user to change CAD settings for anything other than most optimal ones described in AN1200.48 .
-  However, this change does not respect CAD configs from the LoRaWAN layer. Future considerations or use cases might require revisiting this decision.
-  Hence this note.
-*/
-
-/*
   // set user-provided values
   if(symbolNum != RADIOLIB_SX126X_CAD_PARAM_DEFAULT) {
     data[0] = symbolNum;
@@ -1809,10 +1814,9 @@ int16_t SX126x::setCad(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin) {
     data[2] = detMin;
   }
 
-*/
-  (void)symbolNum;
-  (void)detPeak;
-  (void)detMin;
+  if(exitMode != RADIOLIB_SX126X_CAD_PARAM_DEFAULT) {
+    data[3] = exitMode;
+  }
 
   // configure parameters
   int16_t state = this->mod->SPIwriteStream(RADIOLIB_SX126X_CMD_SET_CAD_PARAMS, data, 7);

src/modules/SX126x/SX126x.h

@@ -533,18 +533,17 @@ class SX126x: public PhysicalLayer {
 
     /*!
       \brief Performs scan for LoRa transmission in the current channel. Detects both preamble and payload.
+      Configuration defaults to the values recommended by AN1200.48.
       \returns \ref status_codes
     */
     int16_t scanChannel() override;
 
     /*!
       \brief Performs scan for LoRa transmission in the current channel. Detects both preamble and payload.
-      \param symbolNum Number of symbols for CAD detection. Defaults to the value recommended by AN1200.48.
-      \param detPeak Peak value for CAD detection. Defaults to the value recommended by AN1200.48.
-      \param detMin Minimum value for CAD detection. Defaults to the value recommended by AN1200.48.
+      \param config CAD configuration structure.
       \returns \ref status_codes
     */
-    int16_t scanChannel(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin);
+    int16_t scanChannel(ChannelScanConfig_t config) override;
 
     /*!
       \brief Sets the module to sleep mode. To wake the device up, call standby().
@@ -717,12 +716,10 @@ class SX126x: public PhysicalLayer {
     /*!
       \brief Interrupt-driven channel activity detection method. DIO1 will be activated
       when LoRa preamble is detected, or upon timeout.
-      \param symbolNum Number of symbols for CAD detection. 
-      \param detPeak Peak value for CAD detection.
-      \param detMin Minimum value for CAD detection.
+      \param config CAD configuration structure.
       \returns \ref status_codes
     */
-    int16_t startChannelScan(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin);
+    int16_t startChannelScan(ChannelScanConfig_t config) override;
 
     /*!
       \brief Read the channel scan result
@@ -1160,7 +1157,7 @@ class SX126x: public PhysicalLayer {
     int16_t setFs();
     int16_t setTx(uint32_t timeout = 0);
     int16_t setRx(uint32_t timeout);
-    int16_t setCad(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin);
+    int16_t setCad(uint8_t symbolNum, uint8_t detPeak, uint8_t detMin, uint8_t exitMode, RadioLibTime_t timeout);
     int16_t writeRegister(uint16_t addr, uint8_t* data, uint8_t numBytes);
     int16_t readRegister(uint16_t addr, uint8_t* data, uint8_t numBytes);
     int16_t writeBuffer(uint8_t* data, uint8_t numBytes, uint8_t offset = 0x00);

src/modules/SX128x/SX128x.cpp

@@ -411,8 +411,17 @@ int16_t SX128x::receiveDirect() {
 }
 
 int16_t SX128x::scanChannel() {
+  ChannelScanConfig_t config = {
+    .cad = {
+      .symNum = RADIOLIB_SX128X_CAD_PARAM_DEFAULT,
+    },
+  };
+  return(this->scanChannel(config));
+}
+
+int16_t SX128x::scanChannel(ChannelScanConfig_t config) {
   // set mode to CAD
-  int16_t state = startChannelScan();
+  int16_t state = startChannelScan(config);
   RADIOLIB_ASSERT(state);
 
   // wait for channel activity detected or timeout
@@ -668,6 +677,15 @@ int16_t SX128x::checkIrq(uint8_t irq) {
 }
 
 int16_t SX128x::startChannelScan() {
+  ChannelScanConfig_t config = {
+    .cad = {
+      .symNum = RADIOLIB_SX128X_CAD_PARAM_DEFAULT,
+    },
+  };
+  return(this->startChannelScan(config));
+}
+
+int16_t SX128x::startChannelScan(ChannelScanConfig_t config) {
   // check active modem
   if(getPacketType() != RADIOLIB_SX128X_PACKET_TYPE_LORA) {
     return(RADIOLIB_ERR_WRONG_MODEM);
@@ -689,7 +707,7 @@ int16_t SX128x::startChannelScan() {
   this->mod->setRfSwitchState(Module::MODE_RX);
 
   // set mode to CAD
-  return(setCad());
+  return(setCad(config.cad.symNum));
 }
 
 int16_t SX128x::getChannelScanResult() {
@@ -1464,7 +1482,12 @@ int16_t SX128x::setRx(uint16_t periodBaseCount, uint8_t periodBase) {
   return(this->mod->SPIwriteStream(RADIOLIB_SX128X_CMD_SET_RX, data, 3));
 }
 
-int16_t SX128x::setCad() {
+int16_t SX128x::setCad(uint8_t symbolNum) {
+  // configure parameters
+  int16_t state = this->mod->SPIwriteStream(RADIOLIB_SX128X_CMD_SET_CAD_PARAMS, &symbolNum, 1);
+  RADIOLIB_ASSERT(state);
+
+  // start CAD
   return(this->mod->SPIwriteStream(RADIOLIB_SX128X_CMD_SET_CAD, NULL, 0));
 }
 

src/modules/SX128x/SX128x.h

@@ -186,6 +186,7 @@
 #define RADIOLIB_SX128X_CAD_ON_4_SYMB                           0x40        //  7     0                                   4
 #define RADIOLIB_SX128X_CAD_ON_8_SYMB                           0x60        //  7     0                                   8
 #define RADIOLIB_SX128X_CAD_ON_16_SYMB                          0x80        //  7     0                                   16
+#define RADIOLIB_SX128X_CAD_PARAM_DEFAULT                       RADIOLIB_SX128X_CAD_ON_8_SYMB
 
 //RADIOLIB_SX128X_CMD_SET_MODULATION_PARAMS
 #define RADIOLIB_SX128X_BLE_GFSK_BR_2_000_BW_2_4                0x04        //  7     0   GFSK/BLE bit rate and bandwidth setting: 2.0 Mbps   2.4 MHz
@@ -457,6 +458,13 @@ class SX128x: public PhysicalLayer {
     */
     int16_t scanChannel() override;
 
+    /*!
+      \brief Performs scan for LoRa transmission in the current channel. Detects both preamble and payload.
+      \param config CAD configuration structure.
+      \returns \ref status_codes
+    */
+    int16_t scanChannel(ChannelScanConfig_t config) override;
+
     /*!
       \brief Sets the module to sleep mode. To wake the device up, call standby().
       Overload for PhysicalLayer compatibility.
@@ -584,11 +592,19 @@ class SX128x: public PhysicalLayer {
 
     /*!
       \brief Interrupt-driven channel activity detection method. DIO1 will be activated
-      when LoRa preamble is detected, or upon timeout. Defaults to CAD parameter values recommended by AN1200.48.
+      when LoRa preamble is detected, or upon timeout.
       \returns \ref status_codes
     */
     int16_t startChannelScan() override;
 
+    /*!
+      \brief Interrupt-driven channel activity detection method. DIO1 will be activated
+      when LoRa preamble is detected, or upon timeout.
+      \param config CAD configuration structure.
+      \returns \ref status_codes
+    */
+    int16_t startChannelScan(ChannelScanConfig_t config) override;
+
     /*!
       \brief Read the channel scan result
       \returns \ref status_codes
@@ -837,7 +853,7 @@ class SX128x: public PhysicalLayer {
     int16_t readBuffer(uint8_t* data, uint8_t numBytes, uint8_t offset = 0x00);
     int16_t setTx(uint16_t periodBaseCount = RADIOLIB_SX128X_TX_TIMEOUT_NONE, uint8_t periodBase = RADIOLIB_SX128X_PERIOD_BASE_15_625_US);
     int16_t setRx(uint16_t periodBaseCount, uint8_t periodBase = RADIOLIB_SX128X_PERIOD_BASE_15_625_US);
-    int16_t setCad();
+    int16_t setCad(uint8_t symbolNum);
     uint8_t getPacketType();
     int16_t setRfFrequency(uint32_t frf);
     int16_t setTxParams(uint8_t pwr, uint8_t rampTime = RADIOLIB_SX128X_PA_RAMP_10_US);