Skip to main content

FAQ

Q: I cannot connect to the serial port while downloading, or flashing fails. What should I do?
  • Confirm that the USB cable supports data transfer, and close any other monitors that are occupying the serial port.
  • Hold down BOOT, press and release RST (RESET), then release BOOT. After entering download mode, try again.
  • The serial port number in download mode may differ from that during normal operation. Please select the actual port on your machine again. If necessary, press RST after flashing to start the program.
Q: The VS Code ESP-IDF environment setup or first compilation fails?
  • First check the first error message. If downloading dependencies fails, check the network; if the version is incompatible, verify the selected ESP-IDF environment.
  • The current project configuration uses ESP-IDF v5.5.5 / v6.1, with a component version range of >=5.5.5,<6.3.
  • If it reports that bmgr cannot be found or that the board definition has not yet been generated, install the extension, resolve dependencies, and select the board definition according to ESP-IDF Environment Setup.
  • Keep the complete example package directory; do not copy only a single example project, and do not mix build artifacts and dependency lock files from different ESP-IDF environments.
Q: The Arduino program fails to compile?
  • According to Arduino Parameter Settings, select ESP32S3 Dev Module, 16MB Flash, OPI PSRAM, 3 MB application partition, and the hardware USB CDC/JTAG configuration.
  • Use the matching Arduino-ESP32 3.3.12 and library files; dependencies include RadioLib, esp32_codec2, GFX_Library_for_Arduino, LVGL, ESP32-audioI2S, OneButton, and SensorLib.
  • SensorPCF85063.hpp or GaugeBQ27220.hpp is missing, check SensorLib; for lv_conf.h or font-related errors, check whether the matching LVGL 9.5.0 and configuration file are installed in the correct location.
  • When the IDE reports multiple libraries with the same name, check the actual path being used and rule out conflicts with old versions.
Q: I cannot see output in the serial monitor?
  • In the Arduino environment, check USB CDC On Boot: Enabled and USB Mode: Hardware CDC and JTAG, and set the serial monitor baud rate to 115200.
  • Reconfirm the port, open the monitor, and press RST to check the startup output.
  • ESP-IDF's 01_i2c_scan is an interactive tool. You need to enter i2cdetect at the prompt before scanning starts.
Q: The LoRa communication distance is very short, or communication is not possible?
  • Confirm that the board's RF version, antenna, and frequency band match. The example default of 868 MHz does not mean it applies to all versions.
  • Check whether the frequency, modulation method, bandwidth, spreading factor, coding rate, and sync word of the two devices are consistent.
  • Confirm that the antenna is properly installed and that SPI is configured as SCK=40, MISO=46, MOSI=45, CS=42.
  • In the Ping-Pong example, one device keeps the INITIATING_NODE macro, and the other comments it out.
  • The LoRaWAN example also requires a gateway, network server registration, and matching region and credentials, and it cannot directly interoperate with the regular LoRa Ping-Pong example.
Q: The OLED screen does not display?
  • Confirm that the I2C pins are SDA=13 and SCL=14, with a 7-bit address of 0x3C.
  • Run the 01_i2c_scan example to check whether the OLED is detected; for the ESP-IDF version, enter the i2cdetect command.
  • For the Arduino 08_oled_ssd1309 example, also confirm the LVGL 9.5.0 and matching lv_conf.h configuration.
Q: The walkie_talkie example cannot record or play?
  • Use two devices, confirm that the wireless parameters are consistent, hold PTT to transmit, and release it to receive.
  • First run 04_microphone and 05_speaker separately to distinguish between audio capture, playback, and wireless link issues.
  • Check the I2S pins of the ES7210 and ES8311 and the amplifier enable GPIO8; the standalone speaker example requires placing an MP3 file in the music/ folder in the TF card root directory in advance.
Q: The first compilation of the program is very slow?

The first ESP-IDF compilation downloads dependency components; the first Arduino installation of the core and libraries also needs to download files, so the first full compilation is usually slow. If it stays on the same download error for a long time, check the log and network, then try again.

Q: How do I check which COM port I am using?

Windows system:

  1. Press Windows + R and type devmgmt.msc to open Device Manager.
  2. Expand "Ports (COM & LPT)" and check for the COM port that appears when the development board is connected and disappears when it is unplugged.