This guide will help you set up your programming environment to successfully command and control Boston Dynamics' Spot robot using the Spot Python SDK.
Windows users: Please find notes like this to help you.
The Boston Dynamics Spot Python SDK works with most operating systems including:
- Linux Ubuntu 18.04 LTS
- Windows 10
- MacOS 10.14 (Mojave)
Windows WSL use is discouraged due to so many examples having graphics.
Spot Python SDK works with Python 3.6 or Python 3.7 only. Python 3.8 is not supported.
Downloads and instructions for installing Python can be found at https://www.python.org/.
IMPORTANT: If you have multiple versions of Python installed then running python might reference an incorrect version (e.g. version 2.7). For example, to run python 3 on Ubuntu 18.04 you would run python3 and on Windows you could use the Python launcher and run py -3. Our documentation uses python assuming that the command launches a compatible version of Python.
Verify your python install is the correct version. Open a command prompt or start your python IDE:
$ python --version
Python 3.6.8
Windows users: There are two common methods for starting the Python interpreter on the command line. First, launch a terminal: Start > Command Prompt. At the command prompt, enter either:
python.exe
or
py.exe
The former will directly call the python.exe that is highest priority in the PATH environment variable. (Note you could also supply a full pathname c:\path\to\install\python.exe to directly call the executable).
The latter uses the Python launcher, which by default starts the most recent version of Python installed. You can also optionally pass arguments to the launcher to control what version of python to launch:
py.exe -2 (launches Python 2)
py.exe -3 (launches Python 3)
py.exe -3.6 (launches Python 3.6)
Pip is the package installer for Python. The Spot SDK and the third-party packages used by many of its programming examples use pip to install.
Check if pip is installed by requesting its version:
$ python -m pip --version
pip 19.2.1 from <path on your computer>
Windows users:
> py.exe -m pip --version.If pip is not found, you'll need to install it. There are a few options:
- pip comes preinstalled with all Python 3 versions >= 3.4 downloaded from python.org
- Use the
get-pip.pyinstallation script. - Use an OS-specific package manager (such as the python3-pip package on Ubuntu)
Permission Denied: If you do not use virtualenv (described below), when you install packages using pip, you may receive Permission Denied errors, if so, add the --user option to your pip command.
This section is optional, but recommended.
Users with multiple python versions, anaconda, etc., are responsible for maintaining separation between those installs. Common failures include using the wrong version of python, installing python packages to the wrong python, or using pip associated with the wrong python. One way to improve the stability of your Spot code and your pre-existing python code is to keep them separate using virtual environments. Here are some tips to working with virtualenv.
- Install virtualenv.
- Create a virtualenv, being careful to point at the proper python executable.
- Activate the virtualenv.
- Install packages as needed, including Spot SDK.
- When finished with a session, deactivate.
$ python -m pip install virtualenv
$ python -m virtualenv my_spot_v2_0_env
$ source my_spot_v2_0_env/bin/activate
$ (install packages including Spot SDK, code, edit, execute, etc.)
$ deactivate
Note: Please ensure the virtualenv was created using the expected version of python. If you see:
$ python -m virtualenv my_spot_v2_0_env
Running virtualenv with interpreter /usr/bin/python2
...Then the wrong interpreter is being used. You can pass the interpreter as an additional argument, for example:
$ python -m virtualenv -p /usr/bin/python3 my_spot_v2_0_envWindows users:
> py.exe -m pip install virtualenv
> py.exe -m virtualenv my_spot_v2_0_env
> .\my_spot_v2_0_env\Scripts\activate.bat
Install packages including Spot SDK, code, edit, execute, etc.
> .\my_spot_v2_0_env\Scripts\deactivate.bat
The Spot SDK is open source and available in multiple ways. The three main components of the SDK are:
- Python wheels
- Documentation
- Example applications
The Spot SDK Git repository contains everything listed above. The Python wheels are also available through PyPI, and the full documentation is also available at https://dev.bostondynamics.com. For the same version, the wheels are identical between those two options. For example, SDK version 2.0.0 contains the same wheels as the ones with version 2.0.0 installed from PyPI. The documentation hosted at https://dev.bostondynamics.com is identical to the documentation in an SDK, accessed through the docs/html/README.html file. We recommend installing the Python wheels from PyPI, as described in the setion below Install Spot Python Wheels from PyPI, and accessing the documentation through https://dev.bostondynamics.com. For installations from the cloned Spot SDK repository and to get the Python example applications, please follow the instructions in the section Install Spot SDK from Git Repository.
With python and pip properly installed and configured, the Python wheels are easily installed
from PyPI with the following command.
$ python -m pip install bosdyn-client bosdyn-mission
Installing the bosdyn-client and bosdyn-mission wheels will also install bosdyn-api and
bosdyn-core wheels with the same version. The command above installs the latest version of the
wheels. To install a different version of the wheels from PyPI, for example 2.0.0, use the
following command.
$ python -m pip install bosdyn-client==2.0.0 bosdyn-mission==2.0.0
This section descibes how to get and install the complete Spot SDK from the Git repository.
The Spot Python SDK is available at https://github.com/boston-dynamics/spot-sdk.
Users can either:
- git clone https://github.com/boston-dynamics/spot-sdk.git (recommended)
- Download a zipfile distribution:
- Select green box "Clone or download" from the webpage.
- Select "Download ZIP".
- Unzip the file to your home directory.
- Rename the top-level directory
spot-sdk-mastertospot-sdk.
Now that your python and pip are properly configured and you have Spot SDK downloaded or cloned, it is time to install the Spot SDK Python Packages.
The following commands require a pathname to the SDK which we will call ~/spot-sdk in the following examples. But your pathname may be different depending on where you cloned/downloaded the files. For example, Windows users may have downloaded these files to c:\Downloads\spot-sdk.
$ cd ~/spot-sdk/prebuilt
$ python -m pip install *.whl
Windows users:
Instead of *.whl, please list all .whl files in the directory explicitly in the following order (api, core, client, mission), for example:
$ cd ~/spot-sdk/prebuilt
$ python -m pip install bosdyn_api-2.0.0-py2.py3-none-any.whl
$ python -m pip install bosdyn_core-2.0.0-py2.py3-none-any.whl
$ python -m pip install bosdyn_client-2.0.0-py2.py3-none-any.whl
$ python -m pip install bosdyn_mission-2.0.0-py2.py3-none-any.whlVersion incompatibility:
If you see a version incompatiblity error during pip install such as:
ERROR: bosdyn-core \<a version string> has requirement bosdyn-api==\<a version string>, but you'll
have bosdyn-api 2.0.0 which is incompatible.
Try uninstalling the bosdyn package and then reinstalling:
$ python -m pip uninstall bosdyn-api
$ python -m pip install bosdyn_api-2.0.0-py2.py3-none-any.whlMake sure that the packages have been installed.
$ python -m pip list --format=columns | grep bosdyn
bosdyn-api 2.0.0
bosdyn-client 2.0.0
bosdyn-core 2.0.0
bosdyn-mission 2.0.0
If you don't see these 4 packages with your target version, something went wrong during installation. Contact [email protected] for help.
Windows users: Omit grep if not recognized.
Next, start your python interpreter:
$ python
Python 3.6.8 (default, Jan 14 2019, 11:02:34)
[GCC 8.0.1 20180414 (experimental) [trunk revision 259383]] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import bosdyn.client
>>> help(bosdyn.client)
Help on package bosdyn.client in bosdyn:
NAME
bosdyn.client
DESCRIPTION
The client library package.
Sets up some convenience imports for commonly used classes.
PACKAGE CONTENTS
__main__
...
If the libraries are not installed correctly, you may see an error like this one:
>>> import bosdyn.client
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'bosdyn.client'If that's the case, run python -m pip list again to make sure that the Boston Dynamics Python libraries are installed.
If you can't import bosdyn.client without an error, you may have multiple instances of Python on your computer, have installed bosdyn to one, and are now running the other. Check the pathnames of your python executables. Are they where you'd expect them to be? If not, this is a potential sign that you may have multiple python installs. Consider using virtual environments (see above). If all else fails, contact [email protected] for help.
To use the SDK, you need:
- A Spot Robot on the same version as your SDK,
- An Application Token ("app_token"),
- A user account on the robot
Contact [email protected] to get a Spot robot.
To get an application token, email [email protected] with subject "Application Token Request." You should receive an email with an attached application token within one business day.
While you can technically put your token anywhere, Boston Dynamics recommends you create a .bosdyn directory in your home directory and then copy your token to that directory, renaming it to ~/.bosdyn/dev.app_token. The Spot SDK will always look for your token at this location. If you do not put the token there, you will need to explicitly tell the SDK where your token is, often as an argument to your python executable.
If you just unboxed your Spot robot, you will find a sticker inside the battery cavity with wifi, admin, and username "user" credentials. Please note however that Boston Dynamics recommends that you first have your designated robot administrator log onto the robot with admin credentials and change passwords to increase security.
NOTE: The following examples will assume username "user" and password "password."
- Power on Spot. Wait for the fans to turn off (and maybe 10-20 seconds after that)
- Connect to Spot via wifi.
- Ping spot at 192.168.80.3
$ ping 192.168.80.3
Issue the following command to get your Spot robot's ID:
$ python -m bosdyn.client 192.168.80.3 id
beta-BD-90490007 02-19904-9903 beta29 spot (V3)
Software: 2.0.0 (b11205d698e 2020-03-11 11:53:12)
Installed: 2020-03-11 15:06:57
If this worked for you, SUCCESS! You are now successfully communicating with Spot using the SDK! Note that the output returned shows your Spot robot's unique serial number, its nickname and robot type (Boston Dynamics has multiple robots), the software version, and install date.
If you see the following:
$ python -m bosdyn.client 192.168.80.3 id
Could not contact robot with hostname "192.168.80.3"The robot is not powered on or is unreachable. Go back and try to get your ping to work. You can also try the -v or --verbose to get more information to debug the issue.
If you see the following:
$ python -m bosdyn.client 192.168.80.3 id
Cannot retrieve app token from "None".
The SDK failed to find a valid app_token. Follow the earlier quickstart instructions to get an app_token. If you do have an app token but it is not stored at the default location, you need to specify its location using the --app-token command line option.
OK, we now have our SDK installed properly and we are successfully able to command the robot to give us its id. Let's now see the robot do something!
Change your working directory to the hello_spot example. Do a pip install with requirements.txt as an argument so that any dependent packages are installed. Then run hello_spot:
HELPFUL HINT: When working with any Spot SDK programming example, always use the associated requirements.txt to install dependent third party packages.
$ cd ~/spot-sdk/python/examples/hello_spot # or wherever you installed Spot SDK
$ python -m pip install -r requirements.txt # will install dependent packages
$ python hello_spot.py --username user --password password 192.168.80.3
Hello_spot will fail because there is not an E-Stop endpoint.
2020-03-30 15:26:36,283 - ERROR - Robot is E-Stopped. Please use an external E-Stop client, such as
the E-Stop SDK example, to configure E-Stop.
If you see the following error:
$ python hello_spot.py --username usehername --password pazwierd 192.168.80.3
2020-04-03 15:10:28,189 - ERROR - Hello, Spot! threw an exception: bosdyn.api.GetAuthTokenResponse:
Provided username/password is invalid.
Your username or password is incorrect. Check your spelling and verify your credentials with your robot administrator.
Change your working directory to the E-Stop example and run the nogui version:
$ cd ~/spot-sdk/python/examples/estop # or wherever you installed Spot SDK
$ python -m pip install -r requirements.txt # will install dependent packages
$ python estop_nogui.py --username user --password password 192.168.80.3
Now try to run the estop_gui version:
$ python estop_gui.py --username user --password password 192.168.80.3
You should now have a big red STOP button displayed on your screen. You're now ready to go! (or stop in an emergency!!)
OK, now we have an E-Stop. Leave it running, and open a second python window, and again run hello_spot:
$ cd ~/spot-sdk/python/examples/hello_spot # or wherever you installed Spot SDK
$ python hello_spot.py --username user --password password 192.168.80.3
Your Spot robot should have powered up its motors, stood up, made a few poses, taken a picture, and sat down. If it didn't, be sure to check that the Motor power enable button on the back of Spot was properly turned on.
Try it again, and this time, push the E-Stop button and watch the robot do a "glide-stop." Remember, E-Stop is your friend.
Congratulations, you are now a full-fledged Spot Programming Example Operator!
But, if you also want to be a full-fledged Spot Programmer, you need to understand more about how Spot works. Here are the next steps we recommend:
-
Read our next section, Spot Programming Highly recommended!
-
Take time to explore the programming examples which all launch in essentially the same manner as hello_spot.
- Try making simple modifications to the code. NOTE: If you installed the SDK using a zipfile, be careful to understand what changes you've made, as users sometimes inject errors into the SDK code unintentionally. Git users can simply use
git diffto understand all changes they have made. - Try out the wasd programming example. This is a more detailed example built on top of the Python API which lets you interactively control Spot using the keyboard on your development machine. It covers issuing commands in far more detail than this quick start. And it is fun!
- Try making simple modifications to the code. NOTE: If you installed the SDK using a zipfile, be careful to understand what changes you've made, as users sometimes inject errors into the SDK code unintentionally. Git users can simply use
-
Read through the protocol buffer definitions and the Spot Python SDK source code documentation to understand even more.
If you have any questions, please email [email protected].