FAQ

Q: Why can't I find the download port or upload?

Confirm that the cable supports data transfer, and check the USB interface and Device Manager. Try to manually enter download mode and reselect the port. For Arduino, use ESP32S3 Dev Module, and enable USB CDC and Hardware CDC and JTAG according to the tutorial.

Q: Why is my ESP-IDF project missing gen_bmgr_codes?

All 13 ESP-IDF examples (including example 07) require running idf.py bmgr -b esp32_s3_lr1121_epaper_2_9 in the selected example directory to generate the board-level code before compiling. idf.py bmgr -l only downloads the component and lists the board types; it does not generate code.

The board type comes from the waveshare/waveshare_boards component, and the example repository does not include a boards directory. If the downloaded component does not yet include this model, the board type maintainer needs to provide the corresponding definition. Place the board type directory containing board_info.yaml, board_peripherals.yaml, and board_devices.yaml into managed_components/waveshare__waveshare_boards/boards/esp32_s3_lr1121_epaper_2_9/ before generating. This needs to be prepared for each example, and it also needs to be checked after re-downloading the component; if the component already includes this board type, there is no need to add it manually.

For the complete operation, see ESP-IDF Build and Flash.

Q: Why does my screen not display or report a BUSY timeout?

Confirm that the 2.9-inch configuration is used, and check the GPIO38 shared power supply, GPIO8 BUSY, GPIO9 RESET, and the SPI connection. A high BUSY level indicates busy. The e-paper and LR1121 share the bus, so after modifying the program, you also need to check the chip select and access mutex.

The "2.13inch" functional block title in the schematic is inconsistent with this product; do not switch drivers based on it. After updating the bundled library in Arduino, remove or disable the old library copy and check the actual library path used in the compilation output.

Q: Why is my battery current or state-of-charge estimate inaccurate?

First check the battery connection and current direction. The onboard sampling resistor R16 is 10 mΩ, and the example has been converted according to this value; when modifying the program, keep the sampling resistor configuration consistent. SOC and remaining time also depend on the battery model; the example does not write a new model for the connected battery, so the estimate cannot be regarded as a calibration result.

In the ESP-IDF fuel gauge example, when reading some fields fails, the last value may be retained. Check whether consecutive samples are reasonable; do not judge the measurement as valid based solely on successful initialization. The AXP2602 chip temperature is also not the ambient temperature.

In ESP-IDF comprehensive example 09, an invalid temperature displays temp=UNAVAILABLE, while a valid 0°C is still a normal result.

Q: Why does my LR1121 initialize successfully but receive no data?

Check the matching antenna, RF version, peer device, and the frequency, bandwidth, SF, coding rate, and sync word on both sides. The LoRa point-to-point example is not equivalent to LoRaWAN and cannot directly interoperate with gateways using a different protocol.

The current wireless adaptation code uses TCXO 3.0 V initialization parameters; the old documentation still has 1.6 V text. Do not switch the voltage yourself because of the old documentation; verify it against the current source code and the actual module specifications. Successful initialization also does not prove that the antenna matching, transmit power, or communication distance meets the requirements.

Q: Why does my LoRaWAN example show a configuration error or fail to activate?

Replace the credential placeholder values in the corresponding example, and verify the server's region, MAC version, OTAA/ABP method, and key roles. Arduino example 11 uses the four independent session keys of LoRaWAN 1.1; ESP-IDF example 11 uses 1.0.x by default, so the configurations cannot be copied directly.

The single-channel test parameters of ESP-IDF examples 11 and 13 also need to be synced with the gateway. Check according to the LoRaWAN Usage Instructions, and use the server logs to distinguish between not sent, not received by the gateway, activation rejected, or receive window mismatch.

Q: Why do nonce or frame counter errors occur after I reflash?

The examples save the nonce, session, and frame counters to avoid reuse. Do not clear Preferences or NVS on every startup. The ABP session address, keys, and counters need to be consistent with the network server; when a reset is needed, handle both the device and server state.

NVS ERROR or STATE ERROR indicates that state saving failed; resolve the storage problem first. A receive error after wireless transmission also does not necessarily mean the uplink was not sent; judge based on the actual frame counters and server records.

Q: Why does my TF test fail or prompt that a test file already exists?

Confirm that the card is FAT32, and check GPIO10/CMD, GPIO11/D0, GPIO12/CLK, and the GPIO38 power supply. The example does not automatically format; ESP-IDF uses /ws_sd/test.txt, and Arduino uses /waveshare_sd_test/roundtrip.txt. If the corresponding file already exists, the program refuses to overwrite it; after confirming the purpose, rename or delete it, and try again. A reset or power loss during the test may leave this file behind.

The SD PASS / SD FAIL on the screen and the serial port FINAL correspond to the TF test result, and DISPLAY separately reports the display result. If the display fails, continue to check the TF test based on the serial logs.

Q: Why is my sleep current high?

Check the framework, example, power input, voltage, measurement point, and peripheral state. Arduino and ESP-IDF example 08 both include wireless pin isolation and GPIO38 shared power shutdown, but they use different drivers, so the actual current needs to be measured separately. If Arduino shows SLEEP aborted, it has not yet entered sleep; if the fuel gauge is not detected, it also cannot be considered to have entered sleep. Comprehensive example 09 enters the low-power state only after shutdown is complete.

The sleep power consumption is about 36.5 μW. The test conditions are a 3 V power supply, running the deep sleep program with all peripheral power supplies turned off. When comparing, keep the test conditions consistent.