Remote debugging

2026-02-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 through Wi-Fi)

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

  2. Get device IP address: Enter the following command in the debug UART 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.