ROS 2
================================================
This tutorial assumes you have either pre-installed `ROS 2 `_
or launched the included VS Code development container. For more details, please see ``.devcontainer/readme.md``.
.. note::
Before proceeding, please install the Reach Robotics SDK. Instructions
for installation can found in the :ref:`Getting Started` section.
.. warning::
BPL Protocol will be deprecated in 2025 and replaced with Reach System protocol.
The ROS 2 packages provided in this SDK are for the convenience of the user and are
not currently supported by the Reach Robotics team. If you need support with your
ROS 2 integration, please speak to your Reach Robotics sales representative for a quote
(all services are subject to availability).
Setup
---------------------
First, source the ROS 2 underlay:
.. code-block:: bash
source /opt/ros/foxy/setup.bash
.. note::
It can be convenient to automatically source this script every time a new shell is launched.
.. code-block:: bash
echo "source /opt/ros/foxy/setup.bash" >> ~/.bashrc
source ~/.bashrc
Keep in mind, if you have more than one ROS distribution installed, ~/.bashrc must only source
the setup.bash for the version you are currently using.
Build the ROS 2 packages:
.. code-block:: bash
cd ~/workspace
colcon build
Source the ROS 2 overlay packages:
.. code-block:: bash
source ~/workspace/install/local_setup.bash
At this point the Reach Robotics nodes have been built and are ready to use.
.. note::
If you are using a ROS 2 distribution other than Foxy, you'll need to modify the source
command accordingly. I.e. ```source /opt/ros/humble/setup.bash```
Packages
---------------------------
The ROS 2 folder is split into several packages. Each package is briefly described below.
bpl_passthrough
^^^^^^^^^^^^^^^^^^^^^^^^
The BPL passthrough is the core package that facilitates communication to Reach
Robotics products. This passthrough converts ROS 2 messages into Serial or UDP
packets that can be read by the connected product. Each node in the passthrough
uses :code:`bpl_msgs/Packet` for messaging. The packet construct is defined as:
.. code-block::
uint8 device_id
uint8 packet_id
uint8[] data
where ``device_id`` is the device identifier, ``packet_id`` is the packet identifier, and
``data`` is a list of 8 bit integers representing the data to be sent. To launch the
passthrough, run:
.. tabs::
.. tab:: Serial
.. code-block:: bash
ros2 run bpl_passthrough serial_passthrough --ros-args -p serial_port:=/dev/ttyUSB0
where,
* :code:`serial_port` (string) - Serial Port to connect to the arm (Defaults to "/dev/ttyUSB0")
* :code:`baudrate` (int) - Baudrate port of the serial connection. (Defaults to 115200)
.. tab:: UDP
.. code-block:: bash
ros2 run bpl_passthrough udp_passthrough --ros-args -p ip_address:=192.168.2.4 -p port:=6789
where,
* :code:`ip_address` (string) - IP Address of the arm. (Defaults to 192.168.2.3)
* :code:`port` (int) - UDP Port of the arm. (Defaults to 6789)
For both passthrough nodes, the published topic and the subscribed topic, respectively, are:
* :code:`/rx` (:code:`bpl_msgs/Packet`) - Received Packets from the manipulator
* :code:`/tx` (:code:`bpl_msgs/Packet`) - Packets that will be sent to the manipulator
Examples
"""""""""
This example demonstrates how to request read joint positions from joints on a manipulator.
To launch this example, run the launch file.
.. tabs::
.. tab:: Serial
.. code-block:: bash
ros2 launch bpl_passthrough serial_passthrough_example.launch.py serial_port:="/dev/ttyUSB0"
.. tab:: UDP
.. code-block:: bash
ros2 launch bpl_passthrough udp_passthrough_example.launch.py ip_address:=192.168.2.4 port:=6789
The script communicates to the passthrough node via the :code:`/tx` and :code:`/rx` topics.
It publishes request packets to the :code:`/tx` topic at a set frequency.
It subscribes the to :code:`/rx` topic and listens for position packets.
.. note::
This script has been tested to work at 400 Hz over a UDP Connection to the Base MCU.
bpl_bravo_description
^^^^^^^^^^^^^^^^^^^^^^^^
BPL Bravo Description package contains the Universal Robot description File (URDF) files for the Bravo range of manipulators.
Supported Products:
- RB-7002 - Reach Bravo 7 (PRO)
- RB-5002 - Reach Bravo 5 (PRO)
Examples
""""""""""
Examples of viewing URDFs in RVIZ.
.. image:: ../images/rviz_bravo_7.png
:width: 600
Viewing a Bravo 7 URDF:
.. code-block:: bash
ros2 launch bpl_bravo_description view_bravo_7.launch.py
Viewing a Bravo 5 URDF:
.. code-block:: bash
ros2 launch bpl_bravo_description view_bravo_5.launch.py
Viewing a Bravo 5 and Bravo 7 URDF:
.. code-block:: bash
ros2 launch bpl_bravo_description view_bravo_double.launch.py
.. bpl_control
.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. BPL Control is a package that provides control and feedback for a manipulator.
.. .. note::
.. The BPL Control Nodes are intended for use with a full duplex connection. (I.e not intended for use over 485 Serial)
.. joint_state_publisher
.. """"""""""""""""""""""""""""""""""""""""
.. The Joint state publisher node will request and publish the corresponding joint states (position/velocity) to ROS. The
.. published topics of ``joint_state_publisher`` are:
.. * :code:`joints_states` (:code:`sensor_msgs/JointState`) - Joint State of the manipulator.
.. * :code:`tx` (:code:`bpl_msgs/Packet`) - Packets to be sent to the manipulator.
.. and the subscribed topics are:
.. * :code:`rx` (:code:`bpl_msgs/Packet`) - Packets to be received from the manipulator
.. with parameters:
.. * :code:`joints` (List) - List of the Joint Device IDs of the manipulator.
.. * :code:`joint_names` (List) - List of the corresponding Joint Names of the manipulator.
.. * :code:`request_frequency` (Float) - Frequency to request the joint positions from the manipulator (default: :code:`10`).
.. * :code:`publish_frequency` (Float) - Frequency to publish the joint state of the manipulator (default: :code:`10`).
.. end_effector_pose_publisher
.. """""""""""""""""""""""""""""""""""""""""""
.. The end effector pose publisher node will request the end effector pose from the manipulator and publish it to ROS. The
.. published topics of ``end_effector_pose_publisher`` are:
.. * :code:`end_effector_pose` (:code:`geometry_msgs/PoseStamped`) - End effector pose of the manipulator.
.. * :code:`tx` (:code:`bpl_msgs/Packet`) - Packets to send the the manipulator.
.. and the subscribed topics are:
.. * :code:`rx` (:code:`bpl_msgs/Packet`) - Packets to receive from the manipulator.
.. with parameters:
.. * :code:`frame_id` (String) - TF Frame ID of the maniulator base (default: :code:`bravo_base_link`).
.. * :code:`frequency` (Float) - Frequency to Request / Publish the end effector pose (default: :code:`20`)
.. control_node
.. """""""""""""""""""""""""""""
.. The BPL Control Node provides control of the manipulator. Control options include:
.. * Joint Velocity Control
.. * Joint Position Control
.. * End Effector Pose Control
.. The published topics of ``end_effector_pose_publisher`` are:
.. * :code:`tx` (:code:`bpl_msgs/Packet`) - Packets to send to the manipulator.
.. and the subscribed topics are:
.. * :code:`control/`
.. Bravo 5 Example
.. """""""""""""""""""""""
.. .. image:: ../images/bravo_5_bringup.png
.. :width: 600
.. The launch file connects to a Bravo 5 over UDP and presents a live view in RVIZ.
.. It also presents a visualisation of the current end effector pose.
.. .. code-block:: bash
.. ros2 launch bpl_bringup bravo_5_udp.launch.py ip_address:=192.168.2.4 port:=6789
.. Bravo 7 Example
.. """""""""""""""""""""""
.. .. image:: ../images/bravo_7_bringup.png
.. :width: 600
.. The launch file connects to a Bravo 7 over UDP and presents a live view in RVIZ.
.. It also presents a visualisation of the current end effector pose.
.. .. code-block:: bash
.. ros2 launch bpl_bringup bravo_7_udp.launch.py ip_address:=192.168.2.4 port:=6789
.. Bravo 7 and Bravo 5 Example
.. """""""""""""""""""""""""""""""""""""""
.. .. image:: ../images/bravo_double_bringup.png
.. :width: 600
.. The launch file connects to a both a Bravo 7 and Bravo 5 over UDP and presents a live view in RVIZ.
.. It also presents a visualisation of the current end effector poses of the manipulators.
.. .. code-block:: bash
.. ros2 launch bpl_bringup bravo_double_udp_launch.py ip_address_a:=192.168.2.4 port_a:=6789 ip_address_b:=192.168.2.8 port_b:=6789