Remote Debugging

2025-11-28

Remote debugging refers to the technology of connecting to a remote device (Quectel Pi H1) from a local development machine through a network for code debugging, problem troubleshooting, and performance analysis. Compared to debugging directly on the device, remote debugging has the following advantages:

  • Improved Development Efficiency: No need to frequently plug and unplug devices, can debug remote code directly in local IDE
  • Convenient File Transfer: Can quickly upload/download code and files
  • Flexible Debugging Methods: Supports command-line debugging, GUI debugging, and other methods
  • Save Physical Resources: No need to connect monitors, keyboards, and other peripherals

Prerequisites

Before performing remote debugging, you need to ensure:

  1. Network Connection: Quectel Pi H1 is connected to the network (wired or WiFi)

    • Wired network: Plug in the network cable, the device will automatically obtain IP (DHCP protocol)
    • WiFi: Enter the WiFi password to connect, the device will automatically obtain IP (DHCP protocol)

  2. Get Device IP Address: Enter the following command in the debug serial terminal to view the IP address

    ip address
# or
ifconfig

  3. Ensure the local computer and device are on the same LAN

Remote Access Methods

According to different debugging needs, you can choose the following remote access methods:

1. SSH Remote Terminal

Application Scenario: Command-line debugging, code compilation, system management

SSH (Secure Shell) is the most commonly used remote terminal access method, providing encrypted command-line connections.

Detailed Documentation: Please refer to SSH Remote Terminal

Quick Start:

# Linux system (ssh-server is built-in by default)
ssh pi@192.168.2.xxx

# If you need to install ssh-server
sudo apt install openssh-server
sudo systemctl enable ssh
sudo systemctl start ssh

Debugging Advantages:

  • Lightweight, low resource consumption
  • Supports SSH tunneling, can perform port forwarding
  • Can be integrated with IDEs like VS Code, PyCharm for remote debugging

2. VNC Remote Desktop

Application Scenario: GUI debugging, visual tool debugging

VNC (Virtual Network Computing) provides remote graphical desktop access, allowing you to see the complete desktop environment of the remote device locally.

Detailed Documentation: Please refer to VNC Remote Desktop

Port Description:

  • Default port 5900 or 5901

Debugging Advantages:

  • Complete graphical interface support
  • Suitable for debugging graphical applications
  • Can run GUI debugging tools

3. TeamViewer Remote Desktop

Application Scenario: Cross-platform remote control, temporary remote assistance

TeamViewer is a commercial remote desktop software that supports multiple platforms including Windows, Mac, Linux, etc.

Detailed Documentation: Please refer to TeamViewer Remote Desktop

Debugging Advantages:

  • Good cross-platform support
  • Stable connection, suitable for long-term debugging
  • Supports file transfer and remote printing

4. SCP File Transfer

Application Scenario: Code file upload/download, log file retrieval

SCP (Secure Copy Protocol) is based on SSH protocol, used for secure file transfer between local and remote devices.

Detailed Documentation: Please refer to SCP File Copy

Common Commands:

# Upload file to device
scp ~/my_program pi@192.168.2.xxx:/home/pi/

# Download device file to local
scp pi@192.168.2.xxx:/var/log/app.log ./

# Recursively copy directory
scp -r ~/my_project pi@192.168.2.xxx:/home/pi/

5. Samba File Sharing

Application Scenario: Large project file transfer, frequent file exchange

Samba provides Windows-style network file sharing, allowing direct access to device files in Windows Explorer.

Detailed Documentation: Please refer to Samba File Sharing

Access Method:

  • Windows: Enter \\192.168.2.xxx in Explorer
  • Enter username and password to access shared folders

6. Apache Web Server

Application Scenario: Web application debugging, remote access to web interface

Apache Web server can be used to deploy web applications and access remotely through a browser.

Detailed Documentation: Please refer to Apache Web Server

Common Issue Troubleshooting

1. Cannot SSH Connect

  • Check network connection: ping 192.168.2.xxx
  • Check SSH service status: sudo systemctl status ssh
  • Check firewall settings: sudo ufw status

2. VNC Connection Failed

  • Check if VNC service is running: ps aux | grep vnc
  • Check if port is listening: netstat -tln | grep 59
  • Confirm firewall allows VNC port

3. Missing Debug Symbols

  • Ensure -g option is added during compilation
  • Check debug information: file my_program or readelf -w my_program

4. Permission Issues

  • Use sudo to elevate privileges
  • Check file permissions: ls -l
  • Modify file permissions: chmod +x my_program

Summary

Remote debugging is an important skill in embedded development. Choose the appropriate tool according to different debugging needs:

  • Command-line Access: SSH Remote Terminal
  • Graphical Interface Access: VNC or TeamViewer
  • File Transfer: SCP or Samba
  • Web Service: Apache Web Server

Reasonably combining these tools can greatly improve development efficiency and debugging experience.