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 :ref:`navigation-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 `_. .. contents:: On this page :local: :depth: 2 Interfaces provided by Navel ---------------------------- The ``navel-bodyd`` service exposes the ROS node ``/bodyd`` independently of the navigation stack: .. list-table:: :header-rows: 1 :widths: 25 40 35 * - 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`_. .. _ros2-local-terminal: 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash cp -n /opt/navel/bodyd/etc/navel-bodyd-cyclonedds-localhost.xml /etc/navel/bodyd_override/cyclonedds.xml Then edit the configuration: .. code-block:: bash 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: .. code-block:: xml Alternatively, specify an interface: .. code-block:: xml true all Replace ``wlP3p1s0`` with the interface connected to the PC's network. You can list Navel's network interfaces with: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash nano /etc/navel/bodyd_override/ros.env For example, select the custom ``cyclonedds.xml`` and enable subnet discovery: .. code-block:: ini # 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash ros2 node info /bodyd If discovery fails, inspect the environment in the ROS terminal on each machine: .. code-block:: bash 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: .. code-block:: bash ros2 multicast receive Then send from the other machine: .. code-block:: bash 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: .. code-block:: bash systemctl start navel-ros2 systemctl stop navel-ros2 systemctl status navel-ros2 To enable or disable the service like the Control Studio switch: .. code-block:: bash 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: .. code-block:: bash 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): .. code-block:: bash 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. .. _navigation-sdk: 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**: .. code-block:: python 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 :doc:`api/communication` for the SDK methods.