ROS 2
Navel uses ROS 2 Jazzy. You can read robot data, control the base, or use the supplied Nav2 and RTAB-Map SLAM stack. Use ROS tools locally over SSH or connect a development PC as described below.
To send navigation goals from Python without using ROS 2 directly, go to Use navigation from the Navel SDK. You still need the navigation stack running, but you can skip the ROS terminal and network configuration below.
For ROS concepts and command-line basics, see the official ROS 2 Jazzy beginner tutorials.
Interfaces provided by Navel
The navel-bodyd service exposes the ROS node /bodyd independently of
the navigation stack:
Topic |
Message type |
Purpose |
|---|---|---|
|
|
Position, orientation, and velocity estimates from the wheels |
|
|
Person bounding boxes and tracking IDs |
|
|
Base velocity commands |
/cmd_vel accepts unstamped Twist messages, without a timestamp.
Use linear.x for forward/backward velocity in meters per second and
angular.z for turning velocity in radians per second.
The optional navel-ros2 service runs Nav2 and RTAB-Map and provides the
/navigate_to_pose action, described under Use Navel’s navigation
stack.
Use ROS 2 locally on Navel
For local use with default settings, no service configuration changes are needed. Connect over SSH and prepare each new terminal:
source /opt/ros/jazzy/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST
export ROS_DOMAIN_ID=0
export CYCLONEDDS_URI=file:///opt/navel/bodyd/etc/navel-bodyd-cyclonedds-localhost.xml
ros2 daemon stop
ros2 daemon start
Sourcing may display not found: "/opt/ros/jazzy/share/libg2o/local_setup.bash".
This is a known message and does not affect the functionality described here.
Sourcing makes ROS tools and installed packages available. The exports match
/bodyd’s middleware, domain, and discovery settings.
Warning
The shared Cyclone DDS XML selects the loopback interface so local nodes can discover each other without depending on Wi-Fi or Ethernet. By default, ROS discovery is restricted to the robot itself. If the robot uses custom ROS settings, match those instead.
Inspect the available interfaces and read odometry:
ros2 node info /bodyd
ros2 topic list -t
ros2 topic info -v /odom
ros2 topic echo /odom --once --qos-reliability best_effort
ros2 topic info -v /odom shows the publishers, subscribers, and their
Quality of Service (QoS) settings. Replace /odom with any topic you want
to use and configure your subscriber with compatible QoS. If a topic is
visible but no messages arrive, check these settings first. See the
ROS 2 QoS reference.
Warning
Navel cannot move while it is charging or connected to Ethernet.
To test /cmd_vel, publish a rotation command:
ros2 topic pub --rate 10 /cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.5}}"
Navel should start rotating. Press Ctrl+C to stop publishing. Publish at 10 Hz for smooth movement; at lower rates, Navel may decelerate between commands.
Change Navel’s ROS settings
To access Navel’s ROS interfaces from another PC, prepare the override files described here first. Then follow Connect Navel to a PC. For local use with default settings, skip these two sections.
The navel account can create and edit configuration files in
/etc/navel/bodyd_override/ without sudo. The following files override the default ROS settings:
/etc/navel/bodyd_override/ros.env: ROS environment overrides./etc/navel/bodyd_override/cyclonedds.xml: a custom Cyclone DDS configuration.
If you do not already have a custom configuration, copy the default file:
cp -n /opt/navel/bodyd/etc/navel-bodyd-cyclonedds-localhost.xml /etc/navel/bodyd_override/cyclonedds.xml
Then edit the configuration:
nano /etc/navel/bodyd_override/cyclonedds.xml
To allow network access, edit /etc/navel/bodyd_override/cyclonedds.xml to select an interface.
For example, let Cyclone DDS choose a suitable interface automatically:
<?xml version="1.0" encoding="UTF-8"?>
<CycloneDDS>
<Domain Id="any">
<General>
<Interfaces>
<NetworkInterface autodetermine="true" />
</Interfaces>
</General>
</Domain>
</CycloneDDS>
Alternatively, specify an interface:
<?xml version="1.0" encoding="UTF-8"?>
<CycloneDDS>
<Domain Id="any">
<General>
<Interfaces>
<NetworkInterface name="wlP3p1s0"
multicast="true"
presence_required="true" />
</Interfaces>
<AllowMulticast>true</AllowMulticast>
<MulticastRecvNetworkInterfaceAddresses>all</MulticastRecvNetworkInterfaceAddresses>
</General>
</Domain>
</CycloneDDS>
Replace wlP3p1s0 with the interface connected to the PC’s network. You
can list Navel’s network interfaces with:
ip a
Both examples can select a network interface instead of lo. The robot’s
local ROS peers must also use compatible interface and discovery settings.
Peers confined to loopback may no longer communicate with it. See the Cyclone DDS configuration guide.
At power-on, navel-bodyd may start before Wi-Fi is connected. With
automatic interface selection, DDS can fall back to loopback. If you suspect
this is preventing discovery, first restart the service on Navel once Wi-Fi
is connected:
systemctl restart navel-bodyd.service
The default configuration explicitly selects loopback so local ROS processes can use the same interface whether or not Wi-Fi is connected.
ROS environment
Edit the ROS environment overrides:
nano /etc/navel/bodyd_override/ros.env
For example, select the custom cyclonedds.xml and enable subnet discovery:
# Supported: SUBNET, LOCALHOST, OFF, SYSTEM_DEFAULT.
ROS_AUTOMATIC_DISCOVERY_RANGE=SUBNET
# Supported: the packaged URI or this exact custom URI.
CYCLONEDDS_URI=file:///etc/navel/bodyd_override/cyclonedds.xml
# Supported: integers 0 through 101, without leading zeros.
ROS_DOMAIN_ID=0
# Supported: rmw_cyclonedds_cpp
RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
See ROS 2 discovery configuration. The domain range follows the ROS 2 domain-ID recommendation.
Use one KEY=value assignment per line, without export or a systemd
Environment= wrapper. Blank lines and full-line # comments are ignored.
Leading/trailing spaces on a line and matching quotes around a value are
accepted. The last assignment wins when a key appears more than once.
Only supported keys and values are accepted. Inline comments, tabs, Windows carriage returns, shell expansion, and additional environment keys are not supported. Use Unix line endings.
A missing, empty, or comments-only file retains the service defaults. An omitted key also retains its default. Invalid input makes the restart fail, and no partial set of overrides is applied. An unreadable file is an error.
After choosing your final settings, apply the configuration:
systemctl restart navel-bodyd.service
systemctl status navel-bodyd.service
The navel account can run these commands without sudo. Applying the changes
briefly interrupts robot services.
In each new terminal on Navel, set matching environment variables:
source /opt/ros/jazzy/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export ROS_AUTOMATIC_DISCOVERY_RANGE=SUBNET
export ROS_DOMAIN_ID=0
export CYCLONEDDS_URI=file:///etc/navel/bodyd_override/cyclonedds.xml
ros2 daemon stop
ros2 daemon start
Check that the node is visible:
ros2 node info /bodyd
Connect Navel to a PC
First prepare the override files in Change Navel’s ROS settings to enable subnet communication. The default loopback settings do not allow access from another PC.
Both machines must be on the same local network, which must permit multicast and DDS UDP traffic. Wi-Fi client isolation, VPNs, or firewalls can prevent discovery.
Configure the development PC
The example below assumes Ubuntu 24.04 LTS (Noble) with ROS 2 Jazzy installed. If your Linux PC runs another distribution or Ubuntu version, you can instead use a VS Code dev container. Run the PC commands below inside the container when using this option.
Install Cyclone DDS and the required message packages:
sudo apt update
sudo apt install ros-jazzy-rmw-cyclonedds-cpp ros-jazzy-nav-msgs \
ros-jazzy-vision-msgs ros-jazzy-nav2-msgs
Prepare each new terminal on the development PC:
source /opt/ros/jazzy/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export ROS_AUTOMATIC_DISCOVERY_RANGE=SUBNET
export ROS_DOMAIN_ID=0
ros2 daemon stop
ros2 daemon start
If CYCLONEDDS_URI is unset, Cyclone DDS selects an interface automatically.
You can also set it to a custom XML configuration.
Use the same domain ID on the PC and robot.
Verify the connection
On the PC:
ros2 node info /bodyd
If discovery fails, inspect the environment in the ROS terminal on each machine:
echo "$ROS_DOMAIN_ID"
echo "$ROS_AUTOMATIC_DISCOVERY_RANGE"
echo "$RMW_IMPLEMENTATION"
echo "$CYCLONEDDS_URI"
Check that the domain ID, discovery range, and middleware match.
To test UDP multicast independently of ROS discovery, start a receiver on one machine:
ros2 multicast receive
Then send from the other machine:
ros2 multicast send
The receiver should print Hello World!. Repeat with the machines’ roles
swapped. This checks multicast connectivity only; DDS discovery still depends
on the ROS and Cyclone DDS settings above.
Use Navel’s navigation stack
In Control Studio for research robots, open Drive and turn on the ROS2
switch below the manual drive controls. This starts and enables
navel-ros2.service, which runs Nav2 and
RTAB-Map SLAM. Turning the switch off stops and disables the service. The map
is not retained when the service restarts.
You can also start, stop, and check the service on Navel:
systemctl start navel-ros2
systemctl stop navel-ros2
systemctl status navel-ros2
To enable or disable the service like the Control Studio switch:
systemctl start navel-ros2-enable
systemctl start navel-ros2-disable
Wait for the navigation stack to start before sending a goal. The goal command
waits for the result; add --feedback to display progress.
Movement circle
The supplied behavior trees constrain Nav2 navigation to the circle configured with the Driving radius slider in the ROS2 section of Drive in Control Studio. Set the radius from 1 to 10 meters in 1-meter steps. Its center is Navel’s position when navigation starts. Whenever Navel is lifted from the ground, the center resets to the position where it is placed back on the ground.
This restriction applies to Nav2 goals through these behavior trees.
Direct /cmd_vel commands are not constrained by this circle.
Send a goal
The examples use base_link, Navel’s reference frame.
To request a random goal within the movement circle:
ros2 action send_goal /navigate_to_pose nav2_msgs/action/NavigateToPose "{
pose: {
header: {frame_id: base_link},
pose: {}
},
behavior_tree: '/opt/ros/jazzy/share/navel_interface/behavior_trees/navigate_to_random_w_replanning_and_recovery.xml'
}"
To request a specific point, which must be inside the movement circle (goals outside it fail):
ros2 action send_goal /navigate_to_pose nav2_msgs/action/NavigateToPose "{
pose: {
header: {frame_id: base_link},
pose: {
position: {x: 1.0, y: 0.0, z: 0.0},
orientation: {w: 1.0}
}
},
behavior_tree: '/opt/ros/jazzy/share/navel_interface/behavior_trees/navigate_to_pose_w_replanning_and_recovery.xml'
}"
Positions are in meters. In the send_goal terminal, press Ctrl+C to
request cancellation of an accepted goal. See the ROS 2 action tutorial
for the action command-line tools.
Use navigation from the Navel SDK
If your application already uses the Navel SDK, you can request navigation
without using ROS 2 directly. Start navel-ros2 as described in Use Navel’s
navigation stack, then run this script on Navel:
import asyncio
import navel
async def navigate():
async with navel.Robot() as robot:
action = await robot.navigate_to_pose_relative(1.0, 0.0, 0.0)
result = await action.result()
if result.state != navel.ActionState.SUCCEEDED:
raise RuntimeError(result.error_message or str(result.state))
if __name__ == "__main__":
asyncio.run(navigate())
The relative goal arguments are x, y in meters and heading in radians,
in Navel’s reference frame. The SDK also provides:
navigate_to_pose_absolute(x, y, heading)for a goal in theodomframe.navigate_to_pose_random()for a random goal.
The relative, absolute, and random goals use the supplied behavior trees and
the restrictions described under Movement circle. A relative or absolute
goal outside the circle fails. Each method accepts a
timeout in seconds, defaulting to 60, and returns an action handle. Use
async for update in action.feedback()
for progress and await action.result() for the final state. To request
cancellation, use await action.cancel(); the synchronous
robot.navigate_to_pose_cancel() sends the same cancel command.
The SDK reports canceled, rejected, and aborted goals as FAILED. A timeout
reports TIMED_OUT and requests cancellation without waiting for confirmation.
Wait for a result before starting another navigation request from any SDK
client, and avoid calling next_locomotion() while navigation is active:
these operations share the motion socket. See Communication Classes for the SDK methods.