docs(sx127x): enhance documentation and update default configurations

arjav1528 · arjav1528 · commit 0c49eac37f46 · 2026-03-05T21:02:57.000+05:30
Updated the SX127X demo documentation to include an overview, default configuration settings, short-range FSK testing recommendations, and troubleshooting tips. The default TX power has been changed from 14 dBm to 17 dBm, and CRC is now enabled by default. These changes aim to improve user experience and ensure robust communication for the SX127X radio driver

Signed-off-by: Arjav Patel &lt;arjav1528@gmail.com&gt;
diff --git a/Documentation/applications/examples/sx127x_demo/index.rst b/Documentation/applications/examples/sx127x_demo/index.rst
@@ -3,3 +3,68 @@
 ============================
 
 This example demonstrates the use of the ``SX127X`` radio.
+
+Overview
+========
+
+The ``sx127x_demo`` application exercises the `SX127X` low-power wide-area
+network (LPWAN) radio driver in both transmit and receive modes.  It is
+typically enabled via a board defconfig together with
+``CONFIG_LPWAN_SX127X`` and the appropriate SPI and GPIO wiring for the
+target module.
+
+Default configuration
+=====================
+
+Unless explicitly overridden in the board or application configuration,
+the SX127X driver uses the following relevant defaults:
+
+* RF frequency: ``CONFIG_LPWAN_SX127X_RFFREQ_DEFAULT`` (board-specific,
+  for example 433 MHz, 868 MHz or 915 MHz).
+* TX power: ``CONFIG_LPWAN_SX127X_TXPOWER_DEFAULT``.
+  The global default is **17 dBm**, which provides a stronger and more
+  reliable link than the previous 14 dBm default.
+* CRC: ``CONFIG_LPWAN_SX127X_CRCON``.
+  The global default is **1** (CRC enabled), so payloads are protected
+  by a checksum and corrupted frames are rejected.
+
+Individual boards may override these values in their ``defconfig`` files.
+For example, some boards tested with integrated SX1276 modules may set
+``CONFIG_LPWAN_SX127X_TXPOWER_DEFAULT=20`` and adjust
+``CONFIG_LPWAN_SX127X_RFFREQ_DEFAULT`` to match the module’s band.
+
+Short-range FSK testing
+=======================
+
+When running short-range FSK tests (for example, two modules placed
+around one meter apart on a lab bench), the following settings are
+recommended:
+
+* Keep ``CONFIG_LPWAN_SX127X_TXPOWER_DEFAULT`` at **17 dBm** or higher
+  (some modules work well at 20 dBm) to avoid marginal RSSI values that
+  can lead to intermittent reception.
+* Ensure ``CONFIG_LPWAN_SX127X_CRCON=1`` on both transmitter and
+  receiver so corrupted frames are discarded instead of being printed
+  with incorrect data.
+
+These defaults are based on empirical testing reported by users and are
+intended to provide robust communication without requiring additional
+per-board tuning.
+
+Troubleshooting
+===============
+
+If the receiver occasionally shows no data, truncated data, or payloads
+that do not match what was transmitted, check the following:
+
+* Verify that the RF frequency and modulation settings are identical on
+  both sides.
+* Inspect the reported RSSI and SNR values; very low RSSI at short
+  distance can indicate insufficient TX power or antenna issues.
+* Confirm that CRC is enabled and that both peers are configured
+  consistently (either both with CRC enabled or both with it disabled,
+  though enabling CRC is recommended).
+
+Adjusting TX power or antenna placement and ensuring consistent CRC
+settings on the link typically resolves data integrity problems seen in
+simple FSK tests.
diff --git a/boards/xtensa/esp32/esp32-devkitc/configs/bmp280/defconfig b/boards/xtensa/esp32/esp32-devkitc/configs/bmp280/defconfig
@@ -16,7 +16,6 @@ CONFIG_ARCH_BUTTONS=y
 CONFIG_ARCH_CHIP="esp32"
 CONFIG_ARCH_CHIP_ESP32=y
 CONFIG_ARCH_CHIP_ESP32WROVER=y
-CONFIG_ARCH_IRQBUTTONS=y
 CONFIG_ARCH_STACKDUMP=y
 CONFIG_ARCH_XTENSA=y
 CONFIG_BOARD_LOOPSPERMSEC=16717
diff --git a/boards/xtensa/esp32/esp32-devkitc/configs/buttons/defconfig b/boards/xtensa/esp32/esp32-devkitc/configs/buttons/defconfig
@@ -16,7 +16,6 @@ CONFIG_ARCH_BUTTONS=y
 CONFIG_ARCH_CHIP="esp32"
 CONFIG_ARCH_CHIP_ESP32=y
 CONFIG_ARCH_CHIP_ESP32WROVER=y
-CONFIG_ARCH_IRQBUTTONS=y
 CONFIG_ARCH_STACKDUMP=y
 CONFIG_ARCH_XTENSA=y
 CONFIG_BOARD_LOOPSPERMSEC=16717
@@ -32,7 +31,6 @@ CONFIG_INIT_ENTRYPOINT="nsh_main"
 CONFIG_INIT_STACKSIZE=3072
 CONFIG_INPUT=y
 CONFIG_INPUT_BUTTONS=y
-CONFIG_INPUT_BUTTONS_LOWER=y
 CONFIG_INTELHEX_BINARY=y
 CONFIG_LINE_MAX=64
 CONFIG_MM_REGIONS=3
diff --git a/boards/xtensa/esp32/esp32-ethernet-kit/configs/buttons/defconfig b/boards/xtensa/esp32/esp32-ethernet-kit/configs/buttons/defconfig
@@ -15,7 +15,6 @@ CONFIG_ARCH_BUTTONS=y
 CONFIG_ARCH_CHIP="esp32"
 CONFIG_ARCH_CHIP_ESP32=y
 CONFIG_ARCH_CHIP_ESP32WROVER=y
-CONFIG_ARCH_IRQBUTTONS=y
 CONFIG_ARCH_STACKDUMP=y
 CONFIG_ARCH_XTENSA=y
 CONFIG_BOARD_LOOPSPERMSEC=16717
@@ -31,7 +30,6 @@ CONFIG_INIT_ENTRYPOINT="nsh_main"
 CONFIG_INIT_STACKSIZE=3072
 CONFIG_INPUT=y
 CONFIG_INPUT_BUTTONS=y
-CONFIG_INPUT_BUTTONS_LOWER=y
 CONFIG_INTELHEX_BINARY=y
 CONFIG_LINE_MAX=64
 CONFIG_MM_REGIONS=3
diff --git a/boards/xtensa/esp32/esp32-lyrat/configs/buttons/defconfig b/boards/xtensa/esp32/esp32-lyrat/configs/buttons/defconfig
@@ -16,15 +16,13 @@ CONFIG_ARCH_BUTTONS=y
 CONFIG_ARCH_CHIP="esp32"
 CONFIG_ARCH_CHIP_ESP32=y
 CONFIG_ARCH_CHIP_ESP32WROVER=y
-CONFIG_ARCH_IRQBUTTONS=y
 CONFIG_ARCH_STACKDUMP=y
 CONFIG_ARCH_XTENSA=y
 CONFIG_BOARD_LOOPSPERMSEC=16717
 CONFIG_BUILTIN=y
 CONFIG_ESP32_GPIO_IRQ=y
 CONFIG_ESP32_TOUCH=y
 CONFIG_ESP32_TOUCH_FILTER=y
-CONFIG_ESP32_TOUCH_IRQ=y
 CONFIG_ESP32_UART0=y
 CONFIG_EXAMPLES_BUTTONS=y
 CONFIG_FS_PROCFS=y
@@ -35,7 +33,6 @@ CONFIG_INIT_ENTRYPOINT="nsh_main"
 CONFIG_INIT_STACKSIZE=3072
 CONFIG_INPUT=y
 CONFIG_INPUT_BUTTONS=y
-CONFIG_INPUT_BUTTONS_LOWER=y
 CONFIG_INTELHEX_BINARY=y
 CONFIG_LINE_MAX=64
 CONFIG_MM_REGIONS=3
diff --git a/boards/xtensa/esp32/esp32-wrover-kit/configs/buttons/defconfig b/boards/xtensa/esp32/esp32-wrover-kit/configs/buttons/defconfig
@@ -16,7 +16,6 @@ CONFIG_ARCH_BUTTONS=y
 CONFIG_ARCH_CHIP="esp32"
 CONFIG_ARCH_CHIP_ESP32=y
 CONFIG_ARCH_CHIP_ESP32WROVER=y
-CONFIG_ARCH_IRQBUTTONS=y
 CONFIG_ARCH_STACKDUMP=y
 CONFIG_ARCH_XTENSA=y
 CONFIG_BOARD_LOOPSPERMSEC=16717
@@ -32,7 +31,6 @@ CONFIG_INIT_ENTRYPOINT="nsh_main"
 CONFIG_INIT_STACKSIZE=3072
 CONFIG_INPUT=y
 CONFIG_INPUT_BUTTONS=y
-CONFIG_INPUT_BUTTONS_LOWER=y
 CONFIG_INTELHEX_BINARY=y
 CONFIG_LINE_MAX=64
 CONFIG_MM_REGIONS=3
diff --git a/boards/xtensa/esp32/esp32-wrover-kit/configs/lua/defconfig b/boards/xtensa/esp32/esp32-wrover-kit/configs/lua/defconfig
@@ -21,7 +21,6 @@ CONFIG_ARCH_BUTTONS=y
 CONFIG_ARCH_CHIP="esp32"
 CONFIG_ARCH_CHIP_ESP32=y
 CONFIG_ARCH_CHIP_ESP32WROVER=y
-CONFIG_ARCH_IRQBUTTONS=y
 CONFIG_ARCH_STACKDUMP=y
 CONFIG_ARCH_XTENSA=y
 CONFIG_BOARD_LOOPSPERMSEC=16717
@@ -50,7 +49,6 @@ CONFIG_INIT_ENTRYPOINT="nsh_main"
 CONFIG_INIT_STACKSIZE=3072
 CONFIG_INPUT=y
 CONFIG_INPUT_BUTTONS=y
-CONFIG_INPUT_BUTTONS_LOWER=y
 CONFIG_INTELHEX_BINARY=y
 CONFIG_INTERPRETERS_LUA=y
 CONFIG_LINE_MAX=64
diff --git a/drivers/wireless/lpwan/sx127x/Kconfig b/drivers/wireless/lpwan/sx127x/Kconfig
@@ -17,7 +17,7 @@ config LPWAN_SX127X_SPIFREQ
 
 config LPWAN_SX127X_TXPOWER_DEFAULT
 	int "SX127X default TX power"
-	default 14
+	default 17
 
 config LPWAN_SX127X_PREAMBLE_DEFAULT
 	int "SX127X default preamble length"
@@ -34,7 +34,7 @@ config LPWAN_SX127X_MODULATION_DEFAULT
 config LPWAN_SX127X_CRCON
 	int "SX127X CRC ON"
 	range 0 1
-	default 0
+	default 1
 
 config LPWAN_SX127X_RXSUPPORT
 	bool "SX127X RX support"
