# Debugging Welcome to the Debugging section! Whether you're a seasoned maker or just dipping your toes into the world of IoT and blockchain hardware, it's completely normal for things to not go perfectly on the first try. Wires get crossed, code throws errors, and connections can be finicky – that's all part of the adventure. This guide is your trusty companion, packed with helpful hints and tips to troubleshoot common issues when programming with the Arduino IDE (often referred to as Arduino Studio). We'll start with some quick universal tips, then dive into device-specific support to get you back on track quickly and confidently. ### Quick Tips These are general troubleshooting steps that apply across all Little Ledger devices. They're the first things to check when something's not working as expected in the Arduino IDE. #### USB Connection * **Check the cable and connection**: Use a high-quality USB cable that supports data transfer (not just charging). Plug it directly into your computer's USB port – avoid hubs or extensions if possible, as they can cause intermittent connections. * **Install drivers if needed**: ESP32 boards like the DevKit or Xiao S3 often require USB-to-serial drivers. For Windows/Mac, download and install the CP210x (for Silicon Labs chips) or CH340/CH341 drivers from the manufacturer's site. On Linux, these are usually built-in, but you can check with lsusb in the terminal. * **Test the connection**: Open the Arduino IDE, go to **Tools > Port**, and see if your board appears (e.g., as COM3 on Windows or /dev/cu.usbserial on Mac). If not, try a different cable or port. Unplug and replug the device while watching the IDE's port list. #### Port Selection * **Select the right port in IDE**: In the Arduino IDE, navigate to **Tools > Port** and choose the one corresponding to your ESP32 board. If multiple ports show up, unplug the board, note which one disappears, then plug it back in and select that one. * **Common issues**: If the port doesn't appear, ensure the board is in bootloader mode (some ESP32s require pressing the BOOT button while resetting). On Windows, check Device Manager for unrecognized devices and update drivers. Restart the IDE or your computer if ports are grayed out. * **Verification**: After selecting, try uploading a simple Blink sketch (File > Examples > Basics > Blink) to test. If it fails with "No device found," double-check drivers and cable. #### Board Selection * **Choose the correct board**: In the Arduino IDE, go to **Tools > Board > ESP32 Arduino** and select the appropriate variant: * For Developer\_Kit (ESP32 DevKit): "ESP32 Dev Module" or "DOIT ESP32 DEVKIT V1". * For Micro\_Ledger or Desktop\_Ledger (Seeed Xiao ESP32 S3): "Seeed Xiao ESP32S3" (you may need to install the Seeed board package via Boards Manager). * **Install board packages**: If the ESP32 options aren't available, open **File > Preferences**, add to Additional Boards Manager URLs, then go to **Tools > Board > Boards Manager** and search for "esp32" by Espressif. Install the latest version. * **Upload settings**: Set **Tools > Upload Speed** to 921600 (or lower if unstable), **Partition Scheme** to "Default 4MB with spiffs," and ensure **Tools > Programmer** is "esptool" for ESP32. #### Libraries * **Install required libraries**: Our projects use libraries for OLED displays, WebSockets, and more. In the Arduino IDE, go to T**ools > Manage Libraries** and search/install: * "Adafruit SSD1306" and "Adafruit GFX Library" for the OLED screen. * "ESP32" or "WiFi" (built-in, but ensure updates). * "WebSockets" by Markus Sattler for real-time XRPL/Xahau monitoring. * "ArduinoJson" for parsing ledger data. * Any others mentioned in our tutorials (e.g., for speakers: "Tone" library). * **Update and conflicts**: Always update libraries via Manage Libraries. If you get compile errors like "No such file or directory," check that the library is included at the top of your sketch (e.g., #include \). Avoid version conflicts by using the versions specified in our GitHub repos. * **Troubleshooting**: If a library fails to install, check your internet connection or restart the IDE. For custom libraries, download from our GitHub and add via **Sketch > Include Library > Add .ZIP Library**. *** ### Common Coding Errors When writing code for your ESP32-based Little Ledger devices, certain errors are common, especially for beginners. Here are some to watch out for, along with references to built-in Arduino IDE examples to help you learn and troubleshoot: * **Syntax Errors**: * **Issue**: Missing semicolons, mismatched brackets, or typos (e.g., if instead of if). * **Example**: In the **File > Examples > 01.Basics > Blink** sketch, ensure every line ends with a semicolon (e.g., pinMode(LED\_BUILTIN, OUTPUT);). The error message will highlight the line—check for missing ; or {}. * **Fix**: Review the code line by line and compare with the example. * **Pin Definition Mistakes**: * **Issue**: Using an incorrect or unavailable GPIO pin (e.g., assigning an input-only pin as output). * **Example**: The **Blink** example uses LED\_BUILTIN (GPIO 2 on most ESP32s). If it doesn’t blink, verify the pin in **Tools > Board** matches your hardware (e.g., GPIO 2 might be onboard LED). * **Fix**: Consult your board’s pinout diagram and adjust in code (e.g., change to GPIO 26 if needed). * **Missing Library Includes**: * **Issue**: Compiler errors like "undefined reference" due to uninstalled or unlinked libraries. * **Example**: In **File > Examples > 02.Digital > Button**, adding an OLED requires #include \. If missing, install via **Tools > Manage Libraries**. * **Fix**: Add the correct #include statement and install the library. * **Infinite Loops or Delays**: * **Issue**: Code hangs due to excessive delay() or unterminated loops, especially in loop(). * **Example**: The **BlinkWithoutDelay** example shows non-blocking timing using millis(). Avoid long delay(10000) in loop() without conditions. * **Fix**: Use millis() for timing or add break conditions. * **Serial Monitor Issues**: * **Issue**: No output in Serial Monitor due to wrong baud rate or uninitialized Serial. * **Example**: In **File > Examples > 03.Analog > AnalogReadSerial**, Serial.begin(9600) must match the monitor’s baud rate. If blank, check the rate in the bottom right corner. * **Fix**: Ensure Serial.begin(baud) matches and open the monitor after setup(). For more hands-on practice, explore the Arduino IDE’s built-in examples under **File > Examples** to see these concepts in action. If you encounter device-specific issues, check the dedicated subpages for the Developer\_Kit and Micro\_Ledger for tailored support. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://xspence.gitbook.io/little_ledger/helpers/debugging.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.