MMP NÜ

_images/mmp_ru_front.webp

This specifies the configuration for Mobile Manipulation Platform (MMP) NÜ version. It has the following components Custom Lift System ,Stepper Motor, Rope Encoder, Ouster lidar, Nvidia Orin, Intel realsense D455 & D405 depth camera’s, Universal Robot UR5e and Robotiq 2F-140 gripper.

Getting Started

To start-up the Ridgeback, the instructional video playlist can be used which details the opening and use of the Ridgeback.

Data Sheets

Documentations

Repository

Auxiliary Sensor Startup

On ridgeback startup the following drivers are started:

  1. Ridgeback base driver

  2. Hokuyo

The Custom Lift System, Stepper Motor, Rope Encoder, Ouster lidar, Realsense D455 & D405 , UR5e and Robotiq 2F-140 are powered on when the Ridgeback robot starts. However, only the software drivers for Hokuyo and ridgeback are activated on start-up.

For UR5e, the arm has to be manually turned on by pressing the power button located on the top of the mounted screen. More on this in the UR5e section.

Network-Setup

The Ridgeback has multiple networks and vary slightly, the following table shows the networks.

Ridgeback- network devices

Device

Network Address

Users

Password

Ridgeback

192.168.131.1

administrator

clearpath

Nvidia

192.168.131.2

administrator

clearpath

UR5e

192.168.131.3

N/A

N/A

Hokuyo Front

192.168.131.21

N/A

N/A

Hokuyo Rear

192.168.131.22

N/A

N/A

Ouster

192.168.131.23

N/A

N/A

Wiring Schematic

_images/mmp_wiring_schematic.webp

Note

The PS4 controller is connected via bluetooth.

Operation

To use the connect and use the MMP Ridgeback, the following steps must be followed:

  1. Connect to the Ridgeback LAN (Password is clearpath).

  2. ssh into the ridgeback via:

$ ssh -X administrator@192.168.131.1
$ clearpath

The following message will show up with quick instructions for startup.

-------------------------------------------------------------------------------
__  ____     ______   ____ _______ _____ _    _  ____  _____           _____
|  \/  \ \   / /  _ \ / __ \__   __/ ____| |  | |/ __ \|  __ \         / ____|
| \  / |\ \_/ /| |_) | |  | | | | | (___ | |__| | |  | | |__) |  _   _| |  __
| |\/| | \   / |  _ <| |  | | | |  \___ \|  __  | |  | |  ___/  | | | | | |_ |
| |  | |  | |  | |_) | |__| | | |  ____) | |  | | |__| | |      | |_| | |__| |
|_|  |_|  |_|  |____/ \____/  |_| |_____/|_|  |_|\____/|_|       \__,_|\_____|

Current PC: Ridgeback
-------------------------------------------------------------------------------

Ridgeback IP: 192.168.131.1
Pswd:         clearpath
SSH:          ssh -X administrator@192.168.131.1

Nvidia IP:    192.168.131.2
Pswd:         clearpath
SSH:          ssh -X administrator@192.168.131.2

UR5e IP:      192.168.131.3  (INFO: Default off)

Hokuyo F IP:  192.168.131.21 (INFO: Default on)

Hokuyo R IP:  192.168.131.22 (INFO: Default on)

Ouster IP:    192.168.131.23 (INFO: Default on)
--------------------------------------------------------------------------
MMP-RU Startup
--------------------------------------------------------------------------

MMP status:      sudo service mmp_ru status
MMP start:       sudo service mmp_ru start
MMP stop:        sudo service mmp_ru stop
MMP restart:     sudo service mmp_ru restart

Update startup:  rosrun mmp_ru startup_installer.py
--------------------------------------------------------------------------
MMP-RU Driver
--------------------------------------------------------------------------
UR5e Driver:     roslaunch mmp_arm arm_base.launch
UR5e MOveit:     roslaunch mmp_ur_moveit_config mmp_moveit.launch

Visualization:   roslaunch mmp_viz view_robot.launch
--------------------------------------------------------------------------
MMP-RU Services
--------------------------------------------------------------------------
Lift Movement: rostopic pub /cmd_lift std_msgs/Float32 "data: 0.0"
            (INFO: +ve for up, -ve down | -20,000 - +20,000 µsteps)

Lift Softlock: rosservice call /get_lift_manual_control "{}"
            (INFO: provides external control)

Pan and Tilt:  rostopic pub /cmd_pan_and_tilt mmp_msgs/PanTilt "pan: 0.0
            tilt: 0.0"
            (INFO: -1.5708 to +1.5708 in radian)
-------------------------------------------------------------------------------

Software Architecture

_images/mmp_software_architecture.webp

Important

The diagram illustrates the ROS package structure and interaction. Please note that the mmp_startup interacts will all others ros packages depending on the set environment variables.

This section will explain all the custom packages that we have written which are being used in this particular robot.

mmp_arm

This package is responsible for universal_robot UR5e & robotiq gripper control. The interface variables that are used to active UR5e & gripper software are RIDGEBACK_UR_ARM & RIDGEBACK_UR_HAND. These variables can be changed (activated/deactivated) according to your requirement by opening the setup.bash file located at mmp_startup/config changing the value to 0 or 1. The provided code is package is used for controlling the Universal Robots UR5e robotic arm and Robotiq gripper. The launch file contains various arguments, which can be passed to it during execution to customize the behavior of the system. The launch file takes arguments for configuring the connection to the UR5e robot, such as the IP address of the robot and the ports used for communication. It also includes arguments for setting the tool communication parameters, such as the tool voltage, baud rate, parity configuration, and stop bits, among others. These parameters are only used when tool communication is enabled.

The launch file also includes arguments for setting the controller configurations, which determine the behavior of the robot arm. There are default controllers that are activated, such as the joint state controller, scaled position joint trajectory controller, and force-torque sensor controller. There are also controllers that are initially loaded but not started, such as the position joint trajectory controller and joint group vel controller.The launch file contains an argument for the robot description launch file, which is currently not used from UR as it is separately handled from Ridgeback. It also includes an argument for the kinematics configuration file used for calibration correction, which verifies that the robot’s calibration matches the robot description.

Additionally, there are arguments for enabling the headless mode, which automatically sends URScript to the robot to execute, and for requiring the UR hardware interface node, which shuts down the ROS environment if the UR hardware interface node dies. Finally, the launch file includes an XML group that loads the UR common launch file and starts the UR remote control and relay arm joint states nodes. The UR common launch file sets up the connection to the robot and includes the ROS control controllers for the UR5e robot. The UR remote control node sends commands to the robot and listens for responses, while the relay arm joint states node relays the joint states between the UR5e robot and other nodes in the ROS environment.

mmp_lidars

This package is responsible for two Hokuyo Lidars (located at front and back of robot) & an Ouster lidar Sensor. The interface variables that are used to active the two Hokuyo & Ouster software are the RIDGEBACK_FRONT_HOKUYO_LASER, RIDGEBACK_REAR_HOKUYO_LASER & RIDGEBACK_OUSTER_LASER.These variables can be changed (activated/deactivated) by opening the setup.bash file located at mmp_startup/config changing the value to 0 or 1.

The lidars.launch contains a launch file for the robot’s lidar sensors. It includes three launch files for different types of lidars - hokuyo front lidar, hokuyo back lidar, and ouster. The ouster file contains launch file for the ouster lidar. It defines several arguments that can be customized when launching the node. These arguments include the IP address of the lidar, the UDP destination for the lidar data, the lidar and IMU ports, the lidar mode, the timestamp mode, and the visualization parameters. Additionally, the launch file conditionally launches the ouster sensor node based on whether the “RIDGEBACK_OUSTER_LASER” environment variable is set.

Lastly, the hokuyo lidar file contains a launch file for the front hokuyo lidar as well as back. It launches the “urg_node” node from the “urg_node” package, which communicates with the hokuyo lidars. The node’s parameters include the IP address of the lidar, the baud rate, the frame ID, and the minimum and maximum angles for the sensor’s range. The launch file conditionally launches the node based on whether the “RIDGEBACK_FRONT_HOKUYO_LASER” environment variable is set.

mmp_msgs

This package consists of custom messages for PanTilt and SoftSwitchesStatus which are used wile controlling different components of the robot.

mmp_startup

The mmp_ru package manages the robot startup files. Ridgeback needs ROS to be running at startup. Ridgeback driver needs to run at startup which communicates between the robot and its MCU which is on network address 192.168.131.1.

Warning

Make sure none of your devices are having 192.168.131.1 as well as 192.168.131.2 ip address this will crash the node and the robot will not function properly.

This package is dependent upon roswiki robot_upstart which converts roslaunch files to systemd service job in Ubuntu. This job runs at the startup of the robot. The one responsible for Ridgeback is mmp_startup. The status of this service can be checked by:

sudo service mmp_ru status

To change the setup files at startup of the robot include/remove nodes from launch/mbs_rp_system.launch. This is the file which is launched all the time.

To update this launch file at the robot startup, run:

rosrun mmp_startup startup_installer.py

Attention

This command will remove the previous job and install a new one.

Note

Do not edit the files manually to systemd setup files or launch files (it won’t work), always run the above mentioned command to reflect the changes.

This packages also includes UDEV rules for different devices on the robot. They are already set up but for a fresh installation they can be run by:

./setup_udev_rules.sh

The packages have some configuration files for the robot utilities. For example config/description.bash is responsble set up environment variables for URDF in order to include parts on the go. Similarly config/setup.bash is responsible for setting up environment variables for Ridgeback drivers.

mmp_demo

This package runs an example to demonstrate the working of all the robot component attached with the robot simultaneously. A special movement has been programed in this package that will allow you to see all the component workings.

mmp_pan_and_tilt

This package is responsible for two servo motors on which one of the camera is attached. The interface variable that is used to activate the motors is RIDGEBACK_PAN_AND_TILT_UNIT. These variables can be changed (activated/deactivated) according to your requirement by opening the setup.bash file located at mmp_startup/config changing the value to 0 or 1

mmp_ur_moveit_config

This package is responsible for the moveit configuration for all the sensors and components that are attached to the robot.

mmp_description

This is a ros package that contains the 3D models of the Ridgeback. Additionally, the seperate 3D models are stitched together into a single entity via the universal robot description format (URDF). It contains the models for auxiliary components such as lidars as well. Additions to the robot’s 3D model can be made in the xacro/accessories.urdf.xacro. To view the robot with simulated dummy drivers.

roslaunch mmp_viz view_model.launch

If you want to add more accessories to the robot please make sure that you add those accessories to accessories.urdf.xacro file located in mmp_description/xacro/ so that the new accessories can be stitchedwith the old ones.

mmp_lift

This package is responsible for lift control. The interface variable that is used to activate the lift software is RIDGEBACK_LIFT_PLATE. This variables can be changed (activated/deactivated) according to your requirement by opening the setup.bash file located at mmp_startup/config changing the value to 0 or 1. This package uses the rope encoder to provide jointstate of the lift hub for transforms between the different links.The lift itself communicates via an Arduino nano.

mmp_realsense_cameras

This package is responsible for two realsense cameras(D455 & D405) control. The interface variables that are used to active both cameras software are RIDGEBACK_PAN_AND_TILT_CAMERA & RIDGEBACK_WRIST_CAMERA. These variables can be changed (activated/deactivated) according to your requirement by opening the setup.bash file located at mmp_startup/config changing the value to 0 or 1.

Note

The package for Intel Realsense D405 has been ported from ROS2 to ROS1 and is custom, the default package will not work with mmp.

Custom Startup Job

The launch file mmp_ru_system.launch & bash file config/setup.bash``in the catkin package of ``mmp_startup includes everything which is being launched at the startup. The setup.bash file consists of all environment variables which are controlling the different components of the robot individually.By ultering the bash file we can set which individual component software is to be activated on startup.For example

# All the configuration variables
export RIDGEBACK_ACCESSORIES=0
export RIDGEBACK_OUSTER_LASER=0

export RIDGEBACK_FRONT_HOKUYO_LASER=1
export RIDGEBACK_REAR_HOKUYO_LASER=1

export RIDGEBACK_LIFT=1
export RIDGEBACK_PAN_AND_TILT_UNIT=1
export RIDGEBACK_PAN_AND_TILT_CAMERA=1

export RIDGEBACK_UR_ARM=1
export RIDGEBACK_WRIST_CAMERA=1

export RIDGEBACK_LIFT_PLATE=1
export RIDGEBACK_UR_HAND=1

All environment variables are used in a heirarichal manner, for parts in URDF and launch files to run the driver. Most of them are used for both visualization and for running the driver. Note that RIDGEBACK_UR_ARM_URDF is used for URDF to load properly.

Important

RIDGEBACK_ACCESSORIES is responsible for controlling all the accessories on lift i.e. Pan and Tilt Unit, UR Arm and Gripper, Lift Controller and all Realsense cameras.This does not control the lidars because they can be needed in cases where only Ridgeback operation is desired, so that’s why Ouster is seperately set to 0 by default because it is part of lift. First RIDGEBACK_ACCESSORIES should be 1 and than all other lift accessories will be functional based on their environmet variable value.

Warning

Do not create multiple startup jobs with multiple launch files this will break the system. Only one launch file should be created and everything else should be included in this.

If the systems breaks at startup you can start debugging by:

roslaunch mmp_startup mmp_ru_system.launch

This will show which part of the launch file is having errors or you can start running everything in the launch file one by one in separate terminals.

Adding ROS-Nodes & Launch Files to Robot Startup

  1. Navigate and open mmp_startup/launch/mmp_ru_system.launch.

_images/mbs_ridgeback_launch.webp
  1. Add your custom node or launch file.

  2. Run the following script:

rosrun mmp_startup startup_installer.sh
  1. Verify if it is working correctly via:

sudo service mmp_ru status

Important

Once you add your custom node or launch files in the mmp_ru_system.launch, you will need to run rosrun mmp_startup startup_script.sh so that it updates the start-up job on the Ridgeback’s PC otherwise it will not be updated.

Lidars

_images/ouster_s.webp _images/hokuyo.webp

To manually launch the all three lidar driver, the following command can be used:

roslaunch mmp_lidars lidars.launch

If you want to run all the different lidars seperetly then insted of lidars.launch you can use ouster.launch, hokuyo_front_lidar.launch or hokuyo_back_lidar.launch.

Intel Realsense D455 & D405

_images/D455.webp _images/D405.webp

On the robot start-up the Ridgeback starts, however, the Intel realsense D455 & D405 has to be manually launched.

  • ssh into the Ridgeback via:

ssh -X administrator@192.168.131.1
  • Password

clearpath
  • To launch the Intel realsense D405 run the command

roslaunch mmp_realsense_cameras wrist_camera.launch
  • To launch the Intel realsense D455 run the command

roslaunch mmp_realsense_cameras pan_and_tilt_camera.launch

Customization of the camera position can be done here via the following command

rostopic pub /cmd_pan_and_tilt mmp_msgs/PanTilt "pan: 0.0 tilt: 0.0"

Important

The Intel realsense D455 & D405 requires USB 3.0 port so please make sure to use 3.0 USB port.

UR5e

_images/Ur5e.webp
  • You can manually launch Universal Robot UR5e, please run the each individual commands separately in a new terminal.

roslaunch mmp_arm arm_base.launch
roslaunch mmp_ur_moveit_config mmp_moveit.launch
roslaunch mmp_viz view_robot.launch

An emergency power cut-off for the UR5e is available in the auxiliary frame of the Ridgeback.

Important

make sure that the UR5e is manually powered on by pressing the power button located on “Teach Pendant”(tablet) that is mounted on the robot and make sure that the Emergency Stop button is released.

_images/power_button.webp

Robotiq 2F-140

_images/Gripper.jpg
  • To launch the Robotiq 2f-140 hardware driver, run the above command mentioned above:

roslaunch mmp_arm arm_base.launch
roslaunch mmp_ur_moveit_config mmp_moveit.launch
roslaunch mmp_viz view_robot.launch

On Rviz window you will first select Manipulations from the left display section which in return will open a Display Box from which we can select Planning Group and Goal State to controll the gripper.

Important

The robtiq is controlled via ros action client. You can run the following command to control the action of the gripper

rostopic pub /ur_arm/command_robotiq_action/goal robotiq_2f_gripper_msgs/CommandRobotiqGripperActionGoal "header:
seq: 0
stamp:
    secs: 0
    nsecs: 0
frame_id: ''
goal_id:
stamp:
    secs: 0
    nsecs: 0
id: ''
goal: {emergency_release: false, emergency_release_dir: 0, stop: false, position: 1.0,
speed: 0.0, force: 0.0}"

Visualization

  • To visualize the robot model.

roslaunch mmp_viz view_robot.launch
_images/mmp_ru_viz.gif

Lift Control

  • Movement of the lift is controlled by publishing topic mentioned below:

rostopic pub /cmd_lift std_msgs/Float32 "data: 0.0" -r1

where data: 0.0 value controlls the movement speed of the lift which is between 0 to 20,000 µsteps, where as the signs indicate the direction lift will be moving i.e. +ve for up, -ve down