-
Notifications
You must be signed in to change notification settings - Fork 0
Installation
This section details the project installation and initialisation; please ensure the project requirements are met before proceeding. Known errors and their solutions are outlined in the issues section below. We have also provided an installation script which performs the entire installation process outlined below; we strongly recommend performing installation manually to begin with. Once installation is complete, you are ready for execution.
These steps outline every command required for a full installation, including navigating into relevant directories; we recommend executing them contiguously, inside a single terminal session. We assume you are using the bash shell, since this is the default in Ubuntu. First, clone the spotters repository into your home directory.
$ cd ~
$ git clone https://github.com/kinda-raffy/spottersNext, create a virtual environment to house all of the project's dependencies. This virtual environment is required because Ubuntu uses the base Python installation internally, and overwriting its dependencies will corrupt the system.
$ cd spotters
$ python3 -m virtualenv --python=/usr/bin/python3 spot_venvThe following commands ensure the project's custom setup script is sourced automatically by every new terminal session. Once the first command has been executed successfully, either run the second or restart your terminal session. If you would prefer to skip this step entirely, you can source the script manually as required with the $ source ~/spotters/.setup.bash command.
$ echo "source ~/spotters/.setup.bash" >> ~/.bashrc
$ source ~/.bashrcNext, activate the Python virtual environment you created. This is not technically required yet, only later once we start installing dependencies, but it's generally good practice to work from the active virtual environment in this context, so consider this step mandatory. If this command does not work for any reason, try the alternative provided in the relevant issues subsection below.
$ spot_envHere we populate the submodules of the base spotters repository. We have used submodules to allow for continuously integrating updated versions of these repositories, so this project remains compatible with the most recent Boston Dynamics Spot SDK. For more information, see the appropriate context section. The wspt command is defined in our custom .setup.bash script: it navigates to the spotters/workspace directory. The spot_ros submodule houses the nested spot_wrapper submodule, which is populated by the final three commands.
$ git submodule init
$ git submodule update
$ wspt
$ cd src/spot_ros
$ git submodule init
$ git submodule updateNext, install the populated submodules as ROS dependencies. This makes them available as packages when developing, building, and running the project.
$ rosdep install --from-paths spot_driver spot_msgs spot_viz spot_description spot_cam --ignore-src -yNow we install the spot_wrapper so it can be used as as an external Python library. The -e argument installs the wrapper from the local repository instead of a remote Python package index.
$ pip install -e spot_wrapperNow we need to install the project requirements into the new virtual environment and onto our system. In the event of errors referencing problematic packages, refer to the relevant error section. These are minor problems in our experience, but they are quite common.
$ wspt
$ cd ..
$ pip install -r requirements.txtThe following dependency is a template library written in C++ that provides access to functions for linear algebra. These are utilised heavily in drawing the robot's location on the generated map using series of points.
$ sudo apt install libeigen3-devPangolin allows us to visualise point cloud data alongside the tracked location of the robot. This functionality has since been more comprehensively integrated with RViz, the ROS visualisation and debugging software. Pangolin is still heavily intertwined within the source code of spot_slam, however, so for now consider this step mandatory, even though Pangolin will be removed as a dependency in the future. The following commands download, build and install Pangolin.
$ cd ~
$ mkdir -p dev/tools
$ cd dev/tools
$ git clone https://github.com/stevenlovegrove/Pangolin.git pangolin
$ cd pangolin
$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make installEnsure OpenCV version 4.2.0 is installed. If a different version is installed, run $ pip uninstall opencv-python and install the correct version with the $ pip install opencv-python==4.2.0.34 command. Multiple versions of OpenCV is heavily discouraged.
$ python3 -c "import cv2; print(cv2.__version__)"Now we install some ROS packages required by the spotters project. The first provides critical octree functionality and the second loads a USB camera device into Linux as a ROS image stream. If the Spot SensorRelay is used, this is required. If Spot Cam is used instead, this step can be ignored. Note that the current repository will require minor changes in the launch configurations to enable Spot Cam functionality.
$ sudo apt install ros-noetic-octomap-server ros-noetic-usb-camThe following dependencies enable video streaming from the SensorRelay app to the primary compute server running ROS. SensorRelay encodes data from capture devices using a hardware accelerated encoding pipeline and pushes the data onto a local web server. Given that the primary compute server is on the same network, the compute server uses gstreamer to listen to the video broadcast, decode and convert the stream for processing, and transfer the data into a dummy webcam device in Linux. This dummy device is then used by the ros-noetic-usb-cam package to load it into ROS for processing.
$ sudo apt install v4l-utils v4l2loopback-dkms gstreamer1.0-toolsFinally, clean build the spotters library using the cbuildspt command, defined in our custom .setup.bash script and outlined in the utilities section. Building requires a significant computational resources and the build will fail if your machine does not have enough memory. In the event of a build failure, refer to the errors and known issues below.
$ cbuildsptThis concludes the project installation; for a guide running the project, please see the execution section.
NOTE: This script is not currently functional, so please install manually for now.
Using the installation script we've provided will attempt to install and initialise the entire project in one pass. We recommend against its use for your first installation. However, for repeated installs on different machines, for example, this method is much more expedient. The following command executes the script; be prepared to input your password when prompted, and possibly again if more than fifteen minutes elapse. If the script terminates in error for any reason, refer to the corresponding explanation or to the error section.
wget -O - https://gist.githubusercontent.com/kinda-raffy/54b0d8390402c6f64b9bc95e3ddc0712/raw/e49d776ed360487a070ff18b8c298cb424f394b4/spotters_install.bash | bashAny errors or warnings encountered during the installation process are documented here, with their corresponding solutions. This list is not exhaustive; we've likely only encountered a subset of possible issues during our own installations and builds. If you encounter a problem not documented here, please contact the owner of this repository. We will look into it and address the issue here.
If any errors like this occur during pip install they mean required Python packages are not supported by pip or are defective. Currently known packages include PyKDL and sip but you may encounter others. In our experience, the apt versions of these packages work perfectly. To resolve these errors, install the precompiled Python packages using apt instead of pip and copy the packages from your base interpreter into your spotters virtual environment. The required package name should be included in the error message.
$ sudo apt install python3-<python_package>
$ cp /usr/lib/python3/dist-packages/<python_package>* ~/spotters/spot_env/lib/<python_version>/site-packages/It's important to note that this solution is not ideal, since the packages will not be tracked by any package manager. Thus, it's important to note down any packages installed this way for reference later, in case they need to be manually upgraded. Alternatively, a better solution would be to create a symlink between the files instead of performing a hard copy. This would leave the base installation's package manager in charge of the dependency. We do not recommend this method by default as we haven't tested it. We will update this command once it has been tested.
$ ln -s /usr/lib/python3/dist-packages/<python_package> ~/spotters/spot_env/lib/<python_version>/site-packages/<python_package> # Untested, don't use this for now.Building SLAM requires the dependencies installed in the spot_venv virtual environment. Before building workspace packages, always ensure this environment is active; if not, activate it as per the below.
$ cd ~/spotters
$ spot_envIf, for some reason, the latter command does not work, try this one, which specifies the activation script explicitly. If you are using a shell other than bash you may need to specify the corresponding script using this method. For example, users of the fish shell will need to source the activate.fish file; the standard activate script will not work.
$ source ~/spotters/spot_env/bin/activateIf this error occurs for any dependencies, manually install the relevant package using pip and ensure spot_env is activated. The only package known to raise this error is transforms3d and we have verified the solution in this case.
$ spot_env
$ pip install <python_package>The build process is resource intensive, and you may encounter errors such as c++: fatal error: Killed signal terminated program cc1plus or similar. The process may also hang or cause your operating system to freeze. This error may be resolved by allocating more resources to the virtual machine. Our recommended build configuration uses 7 cores and 11 gigabytes of memory. If this is not possible, configure catkin tools in the buildspt and cbuildspt commands defined by .setup.bash to use less resources by using the -j or the --mem-limit flags. The former should be used to configure core count, and the latter for memory.
Some dependencies use deprecated modules which could raise warnings during the build process. These are not critical in our experience; we believe it safe to ignore these warnings for the moment, and we will address them when we have a chance.
2023 Spotters 🐶