These docs are public and open source.Edit on GitHub

TROUBLESHOOTING

This page lists the checks and fixes for the common problems on the car.

FIRST CHECKS

Run these before anything else. They show whether the driver is up and which hardware the car can see.

bash
racecar status            # USB devices, /dev/osrbot_* symlinks, running nodes
racecar service status    # the four core services, active and enabled
ros2 topic list           # /scan /drive /imu/fused /odom /camera/color /joy

Symptom	Cause	Fix
Empty node or topic list	Workspace not sourced in this shell, or the services are down.	racecar source, then racecar service status
A device is missing from racecar status	Unplugged or unpowered hardware.	Reseat the cable and check its power.
The symlink exists but its node is not running	Software problem.	racecar service restart
Port or process already in use	A launch was started twice.	racecar cleanup --force, then relaunch

POWER

Symptom	Cause	Fix
No response at the power switch	The battery is discharged.	Charge it on the included balance charger.
No response with a charged battery	The XT60 plug is not seated.	Push the XT60 plug in firmly until it clicks.
Still no response	Power hardware failure.	Do not disassemble the boards.

TRANSMITTER

Symptom	Cause	Fix
The transmitter does not turn on or drops out	Transmitter batteries are low.	Replace them. Alkaline batteries are recommended.
The car does not respond to the sticks	SWB is not in the manual position.	Flip SWB up.
Still no response in manual	The receiver cable or the OSCORE USB link is loose.	Reseat the receiver cable at the OSCORE board.
The receiver does not respond to the transmitter	The pair is not bound.	Re-pair them following the FlySky manual.

LIDAR

bash
ros2 topic hz /scan          # ~30 Hz when healthy
ping -c 3 192.168.8.2        # the sensor; the host side is 192.168.8.1
ip a | grep 192.168.8        # the usb* interface should hold .1

# count the finite returns in one scan; an indoor scan has hundreds
ros2 topic echo /scan --once --field ranges

# the driver logs blind scans itself
journalctl -u neoracer-teleop -b | grep scan-watchdog

Symptom	Cause	Fix
Ping to 192.168.8.2 fails	The USB-C lidar link is down.	Reseat the USB-C cable, then racecar setup networking to rebuild the link.
Ping works but /scan publishes nothing	The driver stopped receiving data from the sensor.	racecar service restart
Scan publishes but reads all zeros	Something covers the sensor dome.	Check for tape, dirt, or a shell edge in front of the dome, and wipe the window with a soft dry cloth. The rear 90° always reads 0 by design.

CAMERA

bash
ros2 topic list | grep camera                        # /camera/color present?
ros2 topic bw /camera/color                          # ~3-4 MB/s when healthy
ls -l /dev/osrbot_usb_cam                            # the udev symlink
v4l2-ctl --list-formats-ext -d /dev/osrbot_usb_cam   # MJPG must appear

Symptom	Cause	Fix
Frames publish but are black	The shipping film is still on the lens.	Peel it off.
No /camera/color at all	The camera node crashed or the USB cable is loose.	Reseat the USB cable at the front of the car, then racecar service restart.
A subscriber receives nothing	The publisher is best-effort.	Subscribe with sensor-data QoS.
The camera is absent from /dev on the car	Camera hardware failure.	Test the camera on another computer.

IMU

bash
ros2 topic hz /imu/fused             # ~200 Hz when healthy
ros2 topic echo /imu/fused --once    # readings should be steady while the car is still

Symptom	Cause	Fix
No /imu/fused at all	The OSCORE serial link is down.	Check that racecar status lists /dev/osrbot_base, then racecar service restart.

MOTOR AND STEERING

First check whether the cause is software or hardware. Command zero speed. A car that is silent at zero has a software cause. A car that jitters at zero has an electrical or mechanical cause.

python
rc.drive.set_speed_angle(0, 0)   # the car should be silent and still

Symptom	Cause	Fix
Oscillates while your code drives	Control gain too high; the script overcorrects.	Halve the proportional gain and retest.
Jitters at zero command	A pinched motor wire, common after a crash.	Check the rear loom where it passes the chassis edge.
Grinds or skips at top speed	Worn pinion gear.	Inspect the pinion teeth; replace the gear if teeth are missing.
Forward command drives in reverse	Motor wiring reversed.	Swap any two motor leads.
Wheels not symmetric left and right	Steering center is off.	Adjust steering_trim_deg, see ROS 2 params.
Odometry jumps a known distance	Loose encoder cable.	Reseat the encoder cable.
Pulls to one side or fishtails	Worn tires, loose wheel screws, or worn shock absorbers.	Replace worn tires on the same axle together. Tighten the wheel screws.
Steering is weak or does not turn	A mechanical jam or a servo failure.	Power off and turn the front wheels by hand. Remove anything blocking them.
Steering has slack	Loose ball joints on the steering linkage.	Tighten the linkage connectors.

WI-FI

bash
# 1. Join the car's network: neoracer-[Car ID], password neobotics.
# 2. Ping the car's address for that network.
ping 192.168.10.100        # cudy router
ping 10.42.0.1             # access point

# 3. If the ping answers, SSH in and confirm it is the right car.
ssh racecar@192.168.10.100
hostname                   # neoracer
whoami                     # racecar

Symptom	Cause	Fix
The network never appears	The car has not finished booting, or the access point was renamed.	Wait a minute after power-on. racecar setup networking --show prints the saved name.
Joined, but the ping hangs	Wrong Car ID, or your laptop joined a different network.	Check which Wi-Fi your laptop is on and match the car ID on the sticker.
No Wi-Fi at all	Radio or configuration problem.	Connect an Ethernet cable between your computer and the car. Set your computer to an address in 192.168.10.x, SSH to 192.168.10.100, then run racecar setup networking.

◀Previous

Safety

Next▶

Maintenance