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

/odom

nav_msgs/msg/Odometry

Position, orientation, and velocity estimates from the wheels

/chest_cam/detections

vision_msgs/msg/Detection2DArray

Person bounding boxes and tracking IDs

/cmd_vel

geometry_msgs/msg/Twist

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 the odom frame.

  • 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.