Troubleshooting

Most problems come down to one of three things: the agent is not running, rosbridge cannot be reached, or the topic names do not match the robot. Work down this page in order and you will land on the cause quickly.

Check These First

Three commands on the robot answer most questions. Run them over SSH:

systemctl status ctrlr-agent    # apt install: is the agent running?
docker ps                       # Docker install: is the container up?
ss -lntp | grep 9090            # is rosbridge listening?

Then the agent's own logs, which say why it stopped if it did:

journalctl -u ctrlr-agent -f    # apt install
docker logs -f ctrlr-agent      # Docker install

Robot Will Not Come Online

The Robot Setup page keeps saying offline, or the robot disappears from Command HQ.

• The agent exits on purpose when it cannot reach our signaling server. This is by design, so it gets restarted cleanly rather than sitting in a broken state. It only comes back automatically if it is being supervised, which the standard install handles. If you launched it by hand, it will stay down. Check it is running as a service, or as a container with a restart policy.
• The enrollment token is one-time use and expires. It is consumed the moment the robot registers. If an install failed halfway, or you are reinstalling, the old command will not work twice. Generate a fresh token from the Robot Setup page.
• The robot needs outbound internet. It dials out to us over a secure WebSocket; nothing needs to be opened inbound. If the robot is on a locked-down network, outbound access is the thing to ask for.
• Check the clock. A badly wrong system time on the robot breaks secure connections in ways that look like random failures.

Network and Connectivity

This is the most common source of confusing behaviour, because everything looks healthy in isolation and still does not work together.

• The agent and rosbridge must be on the same machine. The agent connects to rosbridge on the loopback address, port 9090, and that is fixed. It cannot reach a rosbridge running on another computer.
• Docker installs need host networking. Our installer sets this up for you. If you are running the container by hand and left it out, the agent will start fine and never see a single topic.
• The robot's driver has to be visible to rosbridge. If the manufacturer runs their software in its own container or with isolated network settings, rosbridge sees nothing even though the robot is working perfectly. Check with ros2 topic list in the same environment rosbridge runs in.
• Two robots on one network can steal each other's commands. By default ROS 2 shares topics across the whole local network, so a second robot can receive instructions meant for the first. Restrict discovery to the local machine:

export ROS_LOCALHOST_ONLY=1
export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST

No Video or Controls

The session connects, but the screen is black or the robot ignores you.

• Source your ROS environment before starting rosbridge. If you launch rosbridge without sourcing your ROS distribution and any manufacturer SDKs in the same shell, it starts successfully but without the message types your robot uses, and those topics become invisible to the agent. This is the single most common cause of a black screen on a healthy robot.
• The topic names probably do not match. Our defaults are conventions, not guarantees. Compare what the robot actually publishes against what is configured, and see Configuring Your Robot for how to find and fix them.
• Use JPEG, not Raw, unless you have a reason. Raw frames at higher resolutions travel badly and can collapse to roughly one frame per second. If video is technically working but unusably slow, this is usually why.
• Colours look wrong? That is the image encoding. Cameras publishing rgb8 need the encoding set to RGB rather than the default.
• The robot may not accept standard movement commands. If video works but driving does nothing, check whether anything on the robot is actually listening for standard movement messages. Some manufacturers use their own motion API, which needs a small translator on the robot.

Configuring a New Robot

Getting a robot you have never connected before to match our defaults is usually the hardest part of onboarding. It is almost always a naming problem rather than a broken robot. Work through it in this order.

1. See what the robot actually publishes

On the robot, with your ROS environment sourced:

ros2 topic list -t              # every topic, with its message type
ros2 node list                  # what is actually running

rostopic list -v                # ROS 1 equivalent
rosnode list

An empty or very short list means the robot's own software is not running, or is not visible from where you ran the command. Fix that before touching any CTRL+R settings.

2. Inspect the topics that matter

ros2 topic info /cmd_vel        # type, and whether anything is listening
ros2 topic echo /camera/image_raw --once   # is real data flowing?
ros2 topic hz /camera/image_raw            # how fast?

A camera topic with a publisher but no data means the driver is up and the camera is not. A movement topic with no subscriber means nothing on the robot is waiting for commands, so driving will never work no matter what you configure.

3. Check for the manufacturer's ROS packages

Most manufacturers ship their own ROS driver, and many publish it on GitHub. If their topics are missing entirely, their package is usually either not installed or not sourced in the shell where rosbridge was started.

ls /opt/ros/                       # which ROS versions are installed
ros2 pkg list | grep -i <vendor>   # is the vendor package present?
printenv | grep -i ros             # what is sourced in this shell

If the package is installed but its topics are invisible to us, source it in the same shell as rosbridge and restart rosbridge. Sourcing only your ROS distribution is not enough when a vendor SDK provides its own message types.

4. Put the real names into CTRL+R

Once you know the actual topic names, enter them in the live config panel on the Robot Setup or Edit Robot page. Nothing gets installed on the robot and changes apply immediately. Full detail on every setting is in Configuring Your Robot.

Quick fixes

• No topics at all. ROS environment not sourced, or the robot's software is not running.
• Topics exist but ours are empty. Names differ. Copy the real ones in.
• Right name, no data. The publisher is not actually running. Confirm with echo before blaming the configuration.
• Right name, wrong type. The robot uses a different message shape, so renaming will not help. It needs a small translator on the robot.
• Video connects but crawls. Switch the image format to JPEG and point at the compressed camera topic.
• Video works, colours inverted. Set the image encoding to RGB.
• Everything works until reboot. rosbridge is not set up to start on boot. Run it as a service.

Navigation Problems

• Nothing happens when sending a robot to a location. CTRL+R sends a destination; the robot does the navigating. If it has no navigation stack running, the goal arrives and is ignored. Confirm the robot can navigate on its own first.
• The trip never shows as finished. The agent expects exactly three values on the navigation status topic: started, completed and failed. Anything else is ignored, so a robot reporting its own wording will appear to travel forever.
• The robot is not on the map. The live position marker needs pose streaming switched on, which is off by default, and the robot must report its position against the same map. See Locations.
• Goals go to the wrong place. Some navigation stacks listen on their own goal topic rather than ours. Point the nav goal topic at whatever the robot actually uses.

Audio Problems

• Restart the agent after switching audio on. The audio pipeline is set up when the agent starts, so the toggle saves but nothing flows until it restarts.
• Plug hardware in before starting the agent, otherwise it will not be picked up.
• Wrong device selected. List what the robot can see with arecord -L and aplay -L, then set the device names explicitly. See Two-way Audio.
• Nothing from your side? Check the browser has microphone permission for the CTRL+R site.

Dependencies and Sources

CTRL+R sits on top of standard, open tooling rather than anything proprietary, so problems underneath us usually have well documented answers.