Quick Start Install
Welcome!
A license key is required to run MoveIt Pro; if you do not already have one please contact us for more information. By downloading the MoveIt Pro software you are agreeing to the Terms and Conditions.
Supported Operating Systems
MoveIt Pro runs on Ubuntu natively, but we also support Windows and macOS through virtual machines. Choose your computer's operating system from below:
- Ubuntu
- macOS
- Windows
Ubuntu Desktop 22.04 is our recommended operating system for best performance.
- Note: Our installation process will not install ROS or MoveIt on your host machine, and will not affect any existing ROS workspaces or configurations you may have.
Mac support requires Parallels for hardware virtualization.
- Follow the instructions to install Parallels on your Mac.
- Follow the instructions to install Ubuntu 22.04 Linux in a Parallels VM
- Once the installation is finished, adjust the VM's allocated Hardware settings:
- Shut down the VM via the "Actions" menu and select "Shut Down"
- From the "Parallels Desktop" application select the "Windows" menu and select "Control Center"
- Open the Settings menu from the gear icon of your Ubuntu virtual machine.
- Select the "Hardware" tab in the configuration window.
- Select "CPU and Memory" and select at least 8 processors and 12 GB of RAM for optimal performance. The simulator needs a lot of computer resources, though less may still work also.
- Optional: Configure Port Forwarding by selecting the "Network" tab
- Click "Advanced.."
- Click "Open Network Preferences..."
- In the "Port forwarding rules:" table click the "+" button. Add 4 total rules:
- Source Port: 80
- Forward to: Choose your virtual machine
- Destination Port: 80
- Repeart adding rules for ports 3200, 3202, 3201
- Close out all the window
- Restart the VM to continue installing MoveIt Pro.
Note for Parallels users: your Docker daemon may occasionally need restarts to fix DNS issues during MoveIt Pro install. There is a known issue where your network configuration can become degraded in long-running virtual machines. You can address this each time by restarting Parallels, or by running this command: sudo systemctl restart docker
. You will need to do this whenever performing upgrades, also.
Windows support requires VMware for hardware virtualization. Note we do not currently support the Windows Subsystem for Linux (WSL) due to its separate networking stack.
- Download VMware Workstation Player.
- Follow the VMware install instructions.
- Download the Ubuntu 22.04 ISO. The download is ~4.6 GB, which can take many minutes depending on your network speed.
- Create a new VM in VMware Workstation Player and install Ubuntu 22.04 using the downloaded ISO.
- Once the installation is complete, shut down the VM and open the VM settings menu using Ctrl+D.
- If VMWare shuts down completely, re-open the application from the start menu, select your VM from the left menu, and then choose 'Edit virtual machine settings' in the right hand window.
- In this menu you will want to increase the amount of memory allocated to the virtual machine. We recommend using at least 8 GB of memory.
- Ensure that "Side Channel Mitigations" are turned off, if the option is available. This option is not available in the free version of Workstation Player.
For the full system requirements see the Tech Specs.
Docker Installation
MoveIt Pro uses a Docker-based install to make ROS dependency management and compatibility easier. Note we do not currently support Docker Desktop due to its separate network stack. Check if you already have Docker by running in a terminal:
docker run hello-world
If Docker is already installed, click here.
Make sure that your Docker version is from Docker's Apt repositories - the versions from Canonical are very old. You can check this by running
apt-cache policy docker-compose-plugin
and making sure that the installed version (marked with ***
) is from https://download.docker.com/linux/ubuntu
, not a domain under ubuntu.com
.
If Docker is not installed, click here.
We recommend two ways to install Docker:
Easiest
Simply copy paste the below commands into your terminal:
sudo apt-get install curl
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo groupadd docker
sudo usermod -aG docker $USER
sg docker "newgrp $(id -gn)"
More Advanced Follow Docker's official documentation:
- Docker's convenience script
- Docker's post-installation steps to ensure you can run without
sudo
privileges.
Finally
To ensure permissions settings take affect for all terminal sessions, log out and back in to your computer.
Finally, verify that you can run Docker commands without sudo.
docker run hello-world
Install MoveIt Pro
Upgrading: If you have previously installed the software, see instead Upgrading MoveIt Pro.
To install, run in a terminal:
curl -LJO https://github.com/PickNikRobotics/moveit_pro_deb/raw/main/picknik/moveit-pro-6.5.0-any.deb
sudo apt install ./moveit-pro-6.5.0-any.deb
If you got some concerning apt warnings or errors, click here.
Known Warning
You might notice a warning
N: Download is performed unsandboxed as root as file '/home/USERNAME/moveit-pro-6.5.0-any.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
at the end of the install. This warning can be ignored and is not an indicator of install failure. You can continue with the steps below to run and launch MoveIt Pro.
Known Prompt
Running kernel seems to be up to date.
Restarting services...
Daemons using outdated libraries
...
Which services should be restarted?
This is likely because you are using Ubuntu Server, perhaps in Parallels, and can be ignored. Just press enter.
Known Issue
If you use pyenv
you may need to run the following command to ensure the correct Python version is used:
pyenv global system
Quick Start MoveIt Pro
Let's get started:
moveit_pro run
When you run MoveIt Pro for the first time, it will prompt you to download an example user workspace and robot configuration. These are our recommend responses:
- Agree to downloading the default user workspace ("moveit_pro_example_ws").
- Remove existing folders, if prompted. Folders that contain user configuration are automatically backed up.
- Remove old, unused Docker files, if prompted.
- Rebuild the user workspace.
MoveIt Pro will download and build the necessary Docker image, which requires a ~2 GB download the first time, and might take a few minutes to update and install the package dependencies. Go get a coffee ☕.
Advanced users: if you have an existing, custom MoveIt Pro workspace, you can use moveit_pro configure
to set your particular user workspace and robot configuration. See Configuring MoveIt Pro to learn more.
To learn more about configure
and other MoveIt Pro CLI options, try moveit_pro --help
.
If you run into problems at this point, check out our Troubleshooting Guide
After building your workspace:
The last step of the quick start should have you choose the robot configuration package. We provide several example packages with varying robot types and morphologies. We recommend you choose "lab_sim" as this will load an example UR5e robot on a linear rail in a physics simulator.
Next, the MoveIt Pro Runtime should load in the background, and the MoveIt Pro Developer Platform user interface should launch in your default browser at http://localhost/. It should look like this:
You can also run the MoveIt Pro Runtime in headless mode, have it communicate with your application, and visualize things through other tools like RViz:
moveit_pro run --headless
Troubleshooting
If you are using a firewall, click here.
The Cryptlex licensing servers we use in the US require whitelisting the following IP addresses and web API URL:
52.223.22.71
35.71.188.31
https://api.cryptlex.com:443
Servers in the EU require whitelisting the following IP addresses and web API URL:
75.2.113.112
99.83.149.57
https://api.eu.cryptlex.com:443
For more information on offline authentication, please contact us_ directly.
Other issues, questions, or feedback:
- Check out our Troubleshooting Guide
- If provided, use your shared Slack channel to contact support directly.
- Email [email protected]
Start An Example Application
To quickly see an example application (an "Objective") click the "Run" button on the "Pick April Tag Labeled Object" Objective that should listed in the "All Objectives" menu. You should now see a UR5e arm on a linear rail executing a pick and place motion:
To get a better understanding of the robot's simulated world, change the view to 4 quadrant view by clicking on the squares icon at the top right of the application:
If you have an Nvidia GPU and experience slower camera performance than pictured here, there is a temporary workaround documented in your checkout of the moveit_pro_example_ws
Dockerfile.
After updating the Dockerfile, you must rebuild your user image (moveit_pro build user_image
).
The degraded performance is a result of Docker X11 forwarding with Nvidia drivers.
A permanent solution is in development will be released as an update to MoveIt Pro.
Advanced: Externally Trigger MoveIt Pro using Python API
Often times MoveIt Pro is integrated into your existing codebase and tech stack - this is possible using our Python API tutorial. It will explain how to use ROS to start and stop Objectives using Python code. Another approach is to communicate using websockets in languages such as JavaScript, Python, Rust, or Java. This is documented in our Websocket Interface tutorial.
Click on the Next button below to continue through the tutorials.