MMP Nܶ
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:
Ridgeback base driver
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.
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¶
Note
The PS4 controller is connected via bluetooth.
Operation¶
To use the connect and use the MMP Ridgeback, the following steps must be followed:
Connect to the Ridgeback LAN (Password is
clearpath).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¶
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¶
Navigate and open
mmp_startup/launch/mmp_ru_system.launch.
Add your custom node or launch file.
Run the following script:
rosrun mmp_startup startup_installer.sh
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¶
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¶
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¶
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.
Robotiq 2F-140¶
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
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