03 · Troubleshooting: Network / Topic / Logs / Software & Hardware

1 Problem Reporting Guidelines

1.1 How do I submit a feedback report for secondary development issues?

To improve troubleshooting efficiency, please provide as complete environmental information, reproduction steps, symptom descriptions, and relevant logs as possible when submitting a problem.

For complex / in-depth secondary development issues, it is recommended to provide at least the following:

• Robot model
• Involved firmware/SDK versions
• Reproduction steps
• Actual behavior
• Expected behavior
• Complete or key logs
• Related configuration files
• Modified code or parameters

Note: for content developed by the developers themselves or business logic implemented on their own, as long as robot software/hardware failures and performance insufficiency are ruled out, functionality that does not meet expectations generally falls outside our support scope and needs to be resolved by the developers.

What kind of problem reports are easier to locate quickly? Good example:

PM01, system version XX, ROS2 Humble. After launching xxx.launch.py, the topic /camera/depth/image_raw is visible, but ros2 topic echo returns no data.

Ran:

Bash ros2 topic info /camera/depth/image_raw -v

It shows the Publisher QoS is BEST_EFFORT while the Subscriber uses RELIABLE.

After changing the Subscriber QoS, everything returned to normal.

This kind of report already includes:

Environment → Operation → Symptom → Debugging process → Logs/commands → Result

What kind of reports are hard to locate? Bad examples:

The camera doesn't work, please take a look.

Or:

No ROS2 data.

Or sending only a photo of the robot on site, without logs, versions, or reproduction steps.

Suggestion:

Avoid describing only conclusions such as "doesn't work", "no response", or "laggy". Try to state when it happens, how to reproduce it, the specific behavior, and what you have already tried.

2 Software vs. Hardware Issues

2.1 How do I determine whether it is a hardware failure? (Hardware issues require after-sales support)

Key observations:

• Whether only a single device is abnormal
• Whether it remains abnormal after restart
• Whether it remains abnormal after restoring the default software configuration/version

For example:

A joint is stuck or has limit abnormalities

The application unit cannot ping the motion control board, the LiDAR IP, etc.

The two types of phenomena above should be handled separately:

Joint sticking or limit abnormalities: first stop the motion, record the joint, error code, conditions, and versions, then contact after-sales for further inspection; the symptom alone cannot determine a motor or cable fault. Network ping failure: first check the target address, NIC, routes, device power, and physical connections; the target may also have ICMP disabled, so it cannot be directly attributed to the motor. Do not disassemble the robot yourself or hot-plug cables.

2.2 What if actual test results differ from the official documentation, e.g., some topics are missing? / What if software or drivers need updating?

First verify the robot model and firmware/SDK/driver versions against the applicable version of the documentation you are reading, and check launch parameters, namespaces, node status, and communication configuration. Missing topics do not necessarily mean the version is outdated. When an upgrade is truly needed, confirm the compatible version, upgrade method, and rollback plan with official support staff; do not blindly update just for troubleshooting.

3 SSH & Network Connectivity

3.1 What should I do if I cannot SSH into the robot?

Check in the following order:

1. On the development computer, check connectivity to the target robot IP (replace the placeholder IP in the command with the actual address)

ping <robot-ip>

2. On the robot itself, check the SSH service (this requires a local console or another authorized access method; running this command on the development computer cannot check the robot)

systemctl status ssh

3. On the development computer, check port 22 on the robot (the nc command below works on Linux/macOS with netcat installed; on Windows PowerShell use Test-NetConnection -ComputerName <actual robot IP> -Port 22)

nc -zv <robot-ip> 22

4. On a Linux development computer, check the IP, NIC, and routes; on a Windows development computer use ipconfig and route print

ip addr
ip route

5. On a Linux development computer, check the neighbor table (on Windows use arp -a); if the target is behind a router, the neighbor table may not contain the target device

ip neigh

Then:

• ping fails → check the network/IP/cable/switch first (if the development machine is also connected to the external network, avoid external router IPs in 192.168.0.X/24 to prevent confusion and conflicts)
• ping succeeds but SSH fails → check the SSH service, firewall, and port
• SSH connects but drops frequently → check network stability, CPU, system load, etc.

3.2 Why can't ROS2 see topics?

Things to check:

• Physical/IP-layer connectivity
• Whether the environment variables are sourced
• DDS/RMW configuration
• ROS_DOMAIN_ID
• NIC
• Firewall
• UDP communication
• Multicast
• Network topology

The most common causes — check these first:

1. Check whether you can ping it
2. Source the environment variables, e.g., source install/setup.bash
3. Confirm that ROS_DOMAIN_ID is the same on both ends, and check the NIC selection and discovery settings for RMW and DDS per the robot's communication configuration. For the ROS2 Humble multi-machine communication scenario in this document, set ROS_LOCALHOST_ONLY=0; a value of 1 restricts communication to the local machine and cannot be used in this scenario.

4 Common ROS2 Topic Issues

4.1 A topic exists but has no data — how do I run basic checks?

Start with:

ros2 topic info /xxx

to view the Publisher / Subscriber.

Then:

ros2 topic info /xxx -v

Focus on:

• Reliability
• Durability
• History
• Depth

Then:

ros2 topic echo /xxx

4.2 How do I identify and handle QoS incompatibility?

Focus on QoS mismatch.

For example, Publisher:

BEST_EFFORT

while Subscriber:

RELIABLE

In terms of the Reliability policy, a BEST_EFFORT publisher cannot satisfy a RELIABLE subscriber's requirements; the reverse combination should not be judged incompatible outright. Also check policies such as Durability — you cannot simply require all QoS values to be identical.

You can use:

ros2 topic info /xxx -v

Confirm the publisher's actual QoS before choosing the subscription settings. For example, when the publisher uses BEST_EFFORT, try this in a terminal with the environment configured:

# Replace the topic name with the actual one
ros2 topic echo /actual_topic_name --qos-reliability best_effort

If there is still no data, continue to confirm whether the publisher is producing messages, whether Durability is compatible, and network communication. Do not change the QoS of all publisher nodes just for troubleshooting.

For sensor data, usually focus on:

BEST_EFFORT
VOLATILE
KEEP_LAST

4.3 How do I check a topic's publish frequency / bandwidth usage?

ros2 topic hz /xxx

For example:

ros2 topic hz /camera/color/image_raw

You can also:

ros2 topic bw /xxx

to check the bandwidth.

This is very useful for troubleshooting high network bandwidth, high CPU usage, and message loss caused by camera data.

5 Camera / LiDAR Parameters

5.1 How do I get the camera and LiDAR intrinsics/extrinsics?

Camera intrinsics can usually be obtained from the topic: /camera/cam_head/color/camera_info

TF can be used to query transforms between coordinate frames, but not every TF should be called a calibrated extrinsic. The transform from odom to imu often involves a pose that changes over time; sensor calibration extrinsics require checking fixed sensor coordinate frame pairs, orientations, units, and calibration files. The example below first views the actual frames, then queries the selected frames:

ros2 run tf2_tools view_frames
# Replace the two frames below with the actual, connected sensor frames
ros2 run tf2_ros tf2_echo <actual_source_frame> <actual_target_frame>

You can also check the calibration YAML files under the ROS driver directory of the LiDAR camera device. For the T800 LiDAR camera, for example:

A11/A22/A12/u0/v0  **Camera intrinsics**
Tcl_0              **LiDAR-Camera0 extrinsics**
Tcl_1              **LiDAR-Camera1 extrinsics**
T_cl_cr            **Left-right camera extrinsics**

The image below is a schematic of the matrix representation from the original material and should not be used directly as a generic K-matrix format for all cameras. When reading camera_info, distinguish between K (3×3 intrinsic matrix), D (distortion parameters), and P (3×4 projection matrix); the meaning and layout of specific calibration YAML fields follow the device driver documentation.

6 Logs & System Troubleshooting

6.1 How do I view system logs?

View in real time:

journalctl -f

View a specific service:

journalctl -u robotics.service

View recent logs:

journalctl --since "10 minutes ago"

6.2 How do I view Linux kernel logs?

dmesg

View in real time:

dmesg -w

View recent errors:

dmesg | grep -i error

USB issues:

dmesg | grep -i usb

Network issues:

dmesg | grep -i eth

CAN:

dmesg | grep -i can

7 Service & Process Issues

7.1 How do I check whether the robot services are normal?

For example:

# Main motion control program
systemctl status robotics.service 

View all related services:

systemctl --type=service

View processes:

ps aux | grep <process>

View resources:

top

Or:

htop

7.2 Why are CPU / memory / network usage high after the program starts?

Check these together:

top
free -h
df -h

Network:

ip -s link

ROS2:

ros2 topic hz /xxx
ros2 topic bw /xxx

For high-frequency sensors such as cameras and point clouds, focus on:

Resolution × FPS × Data type × Number of topics × DDS forwarding scope