The Control tab shows a live map with your robot’s position, waypoints,
and obstacles. Use it to monitor navigation in real time.
Go to your machine’s CONTROL tab.
Find the navigation service card.
The map shows:
Robot position with a directional marker showing heading.
Waypoints as markers you can add or remove.
Obstacles (both static and vision-detected).
Current mode (Manual or Waypoint).
Enable debug logging
Set log_file_path in your navigation service configuration to write
detailed logs to a file:
{
"log_file_path": "/tmp/navigation.log"
}
The log includes mode transitions, waypoint navigation attempts and
completions, obstacle detections, frame transformations, and motion
service calls. This is the most useful tool for understanding why the
robot behaves unexpectedly.
You can also check the LOGS tab in the Viam app for errors from the
navigation and motion services.
Common problems
Robot doesn't move after setting Waypoint mode
Check that waypoints exist: call GetWaypoints or check the Control tab
map. The service needs at least one unvisited waypoint to navigate.
Check the LOGS tab for motion service errors. Common causes:
The base isn’t responding (hardware or wiring issue).
The movement sensor isn’t returning position data (GPS not locked).
The motion service can’t plan a path (obstacles blocking all routes).
Verify the base works independently by testing it from its TEST section
in the configure tab.
Robot replans constantly and makes slow progress
Your plan_deviation_m is likely lower than your GPS error. The robot
replans because normal GPS jitter (2-5 meters with standard GPS) exceeds
the deviation threshold (default 2.6 meters).
Fix: increase plan_deviation_m to 5-10 meters for standard GPS. See
Tune navigation behavior for
guidance on setting this relative to your GPS accuracy.
Robot moves in circles or turns the wrong way
This usually indicates a compass heading problem:
Compass interference from motors: Mount the GPS/IMU module farther
from motors and power wiring.
Compass not calibrated: Run magnetometer calibration per your
module’s documentation.
Heading offset: The compass reports a consistent offset (for
example, 90 degrees off). Check the module’s orientation configuration.
Verify by watching the compass heading in the movement sensor’s TEST
section while rotating the robot by hand. The heading should change
smoothly and correspond to the actual direction.
Robot gets stuck at a waypoint and retries indefinitely
When the navigation service can’t reach a waypoint (obstacle it can’t
navigate around, GPS position it can’t get close enough to), it retries
the same waypoint indefinitely. It does not skip to the next waypoint.
To unblock:
Remove the stuck waypoint with RemoveWaypoint (from code or the Control
tab).
Check whether a static obstacle or bounding region prevents the robot
from reaching that location.
Check whether vision-based obstacle detection is producing false
positives that block the path.
Robot navigates but stops short of the waypoint
The motion service considers a waypoint reached when the robot is within
the planning tolerance of the target. With standard GPS accuracy, the
robot may stop 2-5 meters from the intended coordinates because the GPS
position satisfies the arrival condition even though the robot isn’t
exactly at the target.
For tighter arrival accuracy, use RTK GPS.
Obstacles aren't detected
Verify the vision service detects obstacles independently. Go to the
vision service’s TEST section and check that it returns 3D object
point clouds from the camera.
Check obstacle_polling_frequency_hz. At 0 Hz, no obstacle polling
occurs.
Check that the camera and vision service names in obstacle_detectors
match the exact names in your configuration.
Check the LOGS tab for frame transformation errors. The navigation
service needs to transform obstacle positions from the camera frame
to geographic coordinates through the movement sensor.
GPS position jumps or is inaccurate
Verify you have clear sky visibility. Trees, buildings, and overhead
structures degrade GPS accuracy.
Check the number of satellites your GPS module is tracking (if your
module exposes this data).
Consider upgrading to an RTK GPS module for sub-meter accuracy.
If the position jumps between two locations, you may have multipath
interference from nearby reflective surfaces.