Debugging and Testing

Debugging and Testing

Relevant source files

• boards/pibot_pendant_v1_0/components/bsp/board_init.h
• boards/pibot_pendant_v1_0/components/bsp/control_event.h
• cmake/dev_tools.cmake
• components/esp3d_log/CMakeLists.txt
• components/esp3d_log/esp3d_log.c
• components/esp3d_log/esp3d_log.h
• components/esp3d_log/esp3d_log_backend.h
• components/esp3d_log/library.json
• docs/architecture/authentication_lifecycle.md
• docs/features/features.md
• docs/guides/esp3d_log_guide.md
• docs/roadmap/ws_client_and_auth_roadmap.md
• main/display/components/panel_component.cpp
• main/display/components/panel_component.h
• main/modules/log/sd/esp3d_log_sd_backend.cpp
• main/modules/log/uart2/esp3d_log_uart2_backend.cpp
• main/modules/log/websocket/esp3d_log_websocket_backend.cpp
• sdkconfig
• tools/bt_client/fluidnc_ble.py
• tools/bt_client/fluidnc_bt.py
• tools/fonts/Conversions.txt
• tools/fw_simulator/fluidnc.py
• tools/fw_simulator/fw_simulator.py
• tools/fw_simulator/grbl.py

Purpose and Scope

This page provides practical guidance for debugging and testing the PiBot CNC Pendant firmware. It covers the centralized logging system, message queue inspection, value subscription validation, screen transition debugging, and communication protocol troubleshooting. These tools are essential for maintaining the stability of the LVGL-based UI and the real-time communication with FluidNC/grblHAL controllers.

---

Logging System

The firmware uses a specialized logging component, esp3d_log, which supports multiline output, timestamps, and pluggable backends.

Log Level Configuration

Log levels are defined in esp3d_log.h and configured globally via cmake/dev_tools.cmake.

Level	Macro	Description
0	N/A	Logging disabled
1	esp3d_log_e	Error messages only
2	esp3d_log_w	Warnings and errors
3	esp3d_log_d	Debug, warnings, and errors
4	esp3d_log	All messages (Verbose)

Sources:components/esp3d_log/esp3d_log.h#28-32cmake/dev_tools.cmake#37-44

Logging Implementation

The core output function esp3d_log_output handles multiline splitting and assembly into a final buffer. It prepends a header containing the filename, line number, and function name components/esp3d_log/esp3d_log.c#200-201 Access to internal static formatting buffers is protected by s_log_mutex to ensure thread-safety across UI and communication tasks components/esp3d_log/esp3d_log.c#49-50

// Example usage in code
esp3d_log_d("Initializing %s at baud %d", client_name, baud);
esp3d_log_e("Failed to allocate message buffer");

The system includes a utility esp3d_log_u64_to_str (aliased as U64_STR(x)) because some standard library printf implementations on ESP32 lack %llu support components/esp3d_log/esp3d_log.h#108-111 It uses 4 rotating buffers to allow multiple calls within a single log line components/esp3d_log/esp3d_log.c#100-102

Sources:components/esp3d_log/esp3d_log.c#49-129components/esp3d_log/esp3d_log.h#108-118

Advanced Configuration and Backends

Developers can tune the logging behavior in cmake/dev_tools.cmake:

• ESP3D_LOG_TIMESTAMP: Prepends [+SSSSs.MMM] (seconds/ms since boot) to every line cmake/dev_tools.cmake#56-57
• DISABLE_COLOR_LOG: Toggles ANSI color codes for serial terminals cmake/dev_tools.cmake#50-51
• ESP3D_LOG_BUFFER_SIZE: Sets the maximum size of a formatted log line (default 512 bytes) cmake/dev_tools.cmake#68-69
• ESP3D_LOG_PREFIX: Defaults to ; so that log output sent over a shared CNC serial line is treated as a comment by the target firmware components/esp3d_log/esp3d_log.h#50-52

The firmware supports five backends selected at compile-time via ESP3D_LOG_BACKENDcomponents/esp3d_log/esp3d_log.h#37-41:

1. Serial (0): Standard UART output via esp_log_writecomponents/esp3d_log/CMakeLists.txt#25-26
2. SD Card (1): Writes logs to the SD card main/modules/log/sd/esp3d_log_sd_backend.cpp#1-10
3. UART2 (2): Output to a secondary UART port main/modules/log/uart2/esp3d_log_uart2_backend.cpp#1-10
4. Telnet (3): Streams logs over a Telnet connection main/modules/log/telnet/esp3d_log_telnet_backend.cpp#1-10
5. WebSocket (4): Broadcasts logs to connected WebSocket clients main/modules/log/websocket/esp3d_log_websocket_backend.cpp#1-10

Sources:cmake/dev_tools.cmake#59-69components/esp3d_log/CMakeLists.txt#3-10docs/guides/esp3d_log_guide.md#101-110

---

Debugging Message Queues

Queue Architecture Overview

The communication system relies on a dual-queue architecture (RX and TX) implemented in the ESP3DClient base class.

Title: Message Queue Code Entities

Sources:main/core/esp3d_client.cpp#34-247docs/architecture/connection_management.md#52-58

Inspecting Queue State

To debug communication lag or “stuck” commands, developers can inspect the queue sizes and memory usage using getRxMsgsCount() and getTxMsgsCount()main/core/esp3d_client.cpp#114-147

---

Debugging Value Subscriptions

The esp3dTftValues service is a pub/sub system for real-time CNC data (positions, overrides, status).

Title: Value Subscription Data Flow

Common Debugging Patterns

1. Trace Subscriptions: Log every time a callback is triggered to ensure the parser is extracting data correctly.
2. Verify Unsubscription: Ensure unsubscribe() is called in prepareForDestruction(). Failure to do so causes crashes when the pub/sub system attempts to call a method on a deleted screen object main/display/cnc/screens/jog_screen.cpp#1123-1161

Sources:main/display/cnc/screens/jog_screen.cpp#1123-1161docs/architecture/connection_management.md#52-58

---

UI Component Debugging: PanelComponent

The PanelComponent manages interactive elements with rotary encoder navigation. A common issue is “phantom navigation” where encoder pulses from a previous screen affect the new one. The constructor explicitly calls VirtualButtonsComponent::resetEncoderSteps() to prevent this main/display/components/panel_component.cpp#41-45

Encoder Mode Debugging

PanelComponent operates in two modes: PANEL_NAVIGATION_MODE and PANEL_EDITING_MODEmain/display/components/panel_component.h#34-35 If an item is not responding to the encoder, check if enableEncoderFor() was called with the correct mode main/display/components/panel_component.cpp#333-356

Sources:main/display/components/panel_component.cpp#29-62main/display/components/panel_component.h#34-53

---

Testing Tools

Firmware Simulator

The tools/fw_simulator/ directory contains Python scripts to simulate CNC controllers (Marlin, Grbl, FluidNC). This allows testing the pendant without physical CNC hardware tools/fw_simulator/fw_simulator.py#1-11

• fw_simulator.py: The main entry point. It detects serial ports and routes G-code to specific firmware logic tools/fw_simulator/fw_simulator.py#12-32
• fluidnc.py: Simulates FluidNC status reports and Jog commands.

Sources:tools/fw_simulator/fw_simulator.py#1-75

Build System & Dev Tools

The cmake/dev_tools.cmake file provides several flags to aid development:

• NO_CONNECTION_LOCK: Set to 1 in dev builds to keep the UI interactive even when no CNC is connected cmake/dev_tools.cmake#83-88
• ESP3D_SNAPSHOT_FEATURE: Enables the LVGL snapshot API to dump screens to the SD card cmake/dev_tools.cmake#74-75
• -Werror=unused-variable: Enforced at compile-time to ensure code cleanliness cmake/dev_tools.cmake#11

Sources:cmake/dev_tools.cmake#1-90

---

Troubleshooting Checklist

Symptom	Potential Cause	Debug Step
UI Freeze	Mutex Deadlock	Check s_log_mutex usage in esp3d_log output components/esp3d_log/esp3d_log.c#49-50
Crash on Screen Change	Missing Unsubscribe	Verify esp3dTftValues.unsubscribe is called in prepareForDestruction.
Stale Position Data	Parser Failure	Use fw_simulator.py to send known status strings and check log output.
No Serial Comm	Baud Mismatch	Verify ESP3D_LOG for “Serial initialized” and check NVS settings.
Phantom Encoder Clicks	Buffer Not Cleared	Ensure PanelComponent constructor clears the encoder buffer main/display/components/panel_component.cpp#41-45

Sources:main/core/esp3d_client.cpp#42-80main/display/components/panel_component.cpp#41-45cmake/dev_tools.cmake#83-88components/esp3d_log/esp3d_log.c#49-50