Skip to content

Commit

Permalink
Merge remote-tracking branch 'upstream/master'
Browse files Browse the repository at this point in the history
  • Loading branch information
maubrunn committed Oct 17, 2022
2 parents 59a515e + d872d5a commit 2235158
Showing 122 changed files with 21,853 additions and 521 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -10,7 +10,7 @@ pip3 install bosdyn-client bosdyn-mission bosdyn-api bosdyn-core

## Documentation

Check-out the usage and user documentation [HERE](http://www.clearpathrobotics.com/assets/guides/melodic/spot-ros/)
Check-out the usage and user documentation [HERE](https://heuristicus.github.io/spot_ros)


## Environment Variables
Empty file added docs/.nojekyll
Empty file.
5 changes: 5 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
To generate docs, run

```
sphinx-build -b html . html
```
71 changes: 71 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# -*- coding: utf-8 -*-

import os
import sys
import xml.etree.ElementTree as etree

sys.path.insert(0, os.path.abspath(os.path.dirname(__file__)))

extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.viewcode',
]

source_suffix = '.rst'
master_doc = 'index'

project = u'Spot ROS User Documentation'
copyright = u'2020, Clearpath Robotics'

# Get version number from package.xml.
tree = etree.parse('../spot_driver/package.xml')
version = tree.find("version").text
release = version

#.. html_theme = 'nature'
#.. html_theme_path = ["."]
html_theme = "sphinx_rtd_theme"
html_theme_path = ["."]


html_sidebars = {
'**': ['sidebartoc.html', 'sourcelink.html', 'searchbox.html']
}

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = False

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.

# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.

# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',

# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',

# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'SpotROSUserDocumentation.tex', 'Spot ROS User Documentation',
'Dave Niewinski', 'manual'),
]
32 changes: 32 additions & 0 deletions docs/driver_configuration.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
Configuring the ROS Driver
==========================

There are some basic settings that can be configured to control how the driver runs and at what rate it obtains data. Data that is more important for your applicaiton can be obtained at a higher rate.

The default configuration file is located at ``spot_driver/config/spot_ros.yaml``

+------------------------+---------------------------------------------------------------------------------+
| Parameter | Description |
+========================+=================================================================================+
| rates/robot_state | The rate in Hz to obtain the robot's state (include joint angles) |
+------------------------+---------------------------------------------------------------------------------+
| rates/metrics | The rate in Hz to obtain the robot's metrics |
+------------------------+---------------------------------------------------------------------------------+
| rates/lease | The rate in Hz to obtain the robot's lease state |
+------------------------+---------------------------------------------------------------------------------+
| rates/front_image | The rate in Hz to obtain the image and depth image from the front camera |
+------------------------+---------------------------------------------------------------------------------+
| rates/side_image | The rate in Hz to obtain the image and depth image from the side cameras |
+------------------------+---------------------------------------------------------------------------------+
| rates/rear_image | The rate in Hz to obtain the image and depth image from the rear camera |
+------------------------+---------------------------------------------------------------------------------+
| auto_claim | A boolean to automatically claim the body and e stop when the driver connects |
+------------------------+---------------------------------------------------------------------------------+
| auto_power_on | A boolean to automatically power on the robot's motors when the driver connects |
+------------------------+---------------------------------------------------------------------------------+
| auto_stand | A boolean to automatically stand the robot after the driver conneccts |
+------------------------+---------------------------------------------------------------------------------+

.. warning::

Having the robot power its motors and stand after the driver connects is a physical action and has inherent danger. Make sure to use these settings with cuation and ensure the area is clear before starting the driver
4 changes: 4 additions & 0 deletions docs/html/.buildinfo
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 8c9c186176eb636c4dfb46136aa915f2
tags: 645f666f9bcd5a90fca523b33c5a78b7
Binary file added docs/html/.doctrees/driver_configuration.doctree
Binary file not shown.
Binary file added docs/html/.doctrees/environment.pickle
Binary file not shown.
Binary file added docs/html/.doctrees/index.doctree
Binary file not shown.
Binary file added docs/html/.doctrees/robot_setup.doctree
Binary file not shown.
Binary file added docs/html/.doctrees/ros_setup.doctree
Binary file not shown.
Binary file added docs/html/.doctrees/ros_usage.doctree
Binary file not shown.
Binary file added docs/html/_images/add_user_1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/add_user_2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/front-left-depth.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/front-right-depth.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/network_1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/network_2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/network_3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/network_4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/network_5.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/network_6.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/rviz_panel.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/software_version.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/view_model.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/view_robot.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/wifi_1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/wifi_2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/html/_images/wifi_3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
32 changes: 32 additions & 0 deletions docs/html/_sources/driver_configuration.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
Configuring the ROS Driver
==========================

There are some basic settings that can be configured to control how the driver runs and at what rate it obtains data. Data that is more important for your applicaiton can be obtained at a higher rate.

The default configuration file is located at ``spot_driver/config/spot_ros.yaml``

+------------------------+---------------------------------------------------------------------------------+
| Parameter | Description |
+========================+=================================================================================+
| rates/robot_state | The rate in Hz to obtain the robot's state (include joint angles) |
+------------------------+---------------------------------------------------------------------------------+
| rates/metrics | The rate in Hz to obtain the robot's metrics |
+------------------------+---------------------------------------------------------------------------------+
| rates/lease | The rate in Hz to obtain the robot's lease state |
+------------------------+---------------------------------------------------------------------------------+
| rates/front_image | The rate in Hz to obtain the image and depth image from the front camera |
+------------------------+---------------------------------------------------------------------------------+
| rates/side_image | The rate in Hz to obtain the image and depth image from the side cameras |
+------------------------+---------------------------------------------------------------------------------+
| rates/rear_image | The rate in Hz to obtain the image and depth image from the rear camera |
+------------------------+---------------------------------------------------------------------------------+
| auto_claim | A boolean to automatically claim the body and e stop when the driver connects |
+------------------------+---------------------------------------------------------------------------------+
| auto_power_on | A boolean to automatically power on the robot's motors when the driver connects |
+------------------------+---------------------------------------------------------------------------------+
| auto_stand | A boolean to automatically stand the robot after the driver conneccts |
+------------------------+---------------------------------------------------------------------------------+

.. warning::

Having the robot power its motors and stand after the driver connects is a physical action and has inherent danger. Make sure to use these settings with cuation and ensure the area is clear before starting the driver
11 changes: 11 additions & 0 deletions docs/html/_sources/index.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
Spot ROS User Documentation
===========================

.. toctree::
:maxdepth: 0
:caption: Contents

ros_setup
robot_setup
driver_configuration
ros_usage
80 changes: 80 additions & 0 deletions docs/html/_sources/robot_setup.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
Spot Platform Configuration
===========================

.. note::
This driver has only been fully tested up to version 2.0.1. Any version after this may have unexpected behviour

.. _Spot Login:

Login to Spot as an Administrator
---------------------------------

Connect to the wireless access point created by the robot. The data for this is inside the battery bay of the robot. Once connected, login as the admin user by going to the robot's IP address (https://192.168.80.3) in your web browser and entering the admin login that is also available in the battery bay.

Check the Software Version
--------------------------

Currently, the Spot driver only supports API v1 data, but it is recommended to upgrade the robot to version 2.0 or later to get a number of improvements.

To check the current version of your robot, :ref:`Spot Login`, then press Software Update to see the current version.

.. image:: images/software_version.png

If your software is outdated, it is highly recommended to update using the process recommended by Boston Dynamics.

Create a New User (Optional)
----------------------------

For connecting to the robot with ROS, it is recommended to create a new, non-administrator user. This allows for more security and user-management in the future.

To setup a new user, :ref:`Spot Login`, then navigate to the User Management page and press ADD USER.

Ender a valid username and password. The user does not have to be an administrator to use the ROS driver.

.. image:: images/add_user_1.png

Once your new user is setup, you will see it appear under the USER MANAGEMENT page.

.. image:: images/add_user_2.png

Setup Networking
----------------

There is a large amount of data that will be streaming to the robot over the network. It is *highly recommended* to connect the Spot to the ROS PC through a gigabit ethernet interface.

Change your PC's IP address
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are able to, you can set your computer’s IPaddress is in the range of 10.0.0.*, 10.0.0.100 for example. The robot will be available on 10.0.0.3.

Setup Wi-Fi (Optional)
----------------------

Using wireless for ROS is not recommended. There are cases where changing the robot's wireless settings an be useful.

.. note::

This section is for referene only as there are some quirks with this wireless configuration.

First, :ref:`Spot Login`, and go to the Networking tab. Choose WIFI

.. image:: images/wifi_1.png

If you want to change the Access Point hosted by the robot, it can be configured here. The following steps assume you are trying to connect the robot to an existing network.

Change the network type to Client and enter a valid IP address. Make sure the IP you choose is:

* Different than your ROS PC's IP
* Different from all network sensor IPs
* Outside of DHCP range for any DHCP server in your network
* Not in the reserved ranges noted above

Set the Route Prefix to match your network. This is commonly called the "netmask". You will also want to set the Stored Default Route address correctly or you will likely have network issues.

.. image:: images/wifi_2.png

Once that is setup, go back to the Ethernet tab and set your DNS nameservers. This is a global setting, not speific to WiFi.

You will also want to disabble "Is Current Default Route" under the Ethernet tab and enable it under the WIFI tab.

.. image:: images/wifi_3.png
104 changes: 104 additions & 0 deletions docs/html/_sources/ros_setup.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
Spot ROS Computer Setup
=======================

.. note::
This driver has been tested using the steps below with Spot SDK version 2.3.5. Any version after this may have unexpected behviour.

The ROS driver was created and tested on Kinetic and Melodic

Setup Spot Core
---------------

If you have a Spot Core, download the latest `Melodic ISO <https://packages.clearpathrobotics.com/stable/images/latest/melodic-bionic/amd64/>`_, set it up with `BalenaEtcher <https://www.balena.io/etcher/>`_, and install it onto the Core

If you are using a Jetson, follow the `Jetson Setup Instructions <https://docs.nvidia.com/sdk-manager/install-with-sdkm-jetson/index.html>`_

Once your backpack PC is setup, all steps below are to be followed on that PC

Installing Dependencies
-----------------------

.. code:: bash
sudo apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654
sudo apt update
sudo apt install ros-melodic-ros-base
.. code:: bash
sudo apt update
sudo apt install -y python3-pip
pip3 install cython
pip3 install bosdyn-client bosdyn-mission bosdyn-api bosdyn-core
pip3 install empy
Setup Networking
----------------

Replace the `/etc/network/interfaces` file with the one below

.. code:: bash
auto lo br0 br0:0 br0:1
iface lo inet loopback
# Bridge together physical ports on machine, assign standard Clearpath Robot IP.
iface br0 inet static
bridge_ports regex (eth.*)|(en.*)
address 192.168.131.1
netmask 255.255.255.0
bridge_maxwait 0
# Dedicated port for spot
iface br0:0 inet static
address 192.168.50.1
netmask 255.255.255.0
# Also seek out DHCP IP on those ports, for the sake of easily getting online,
# maintenance, ethernet radio support, etc.
iface br0:1 inet dhcp
Building the Driver from Source
-------------------------------

As the driver hasn't been released yet, it must be built from source. This requires a source workspace on the ROS PC.

.. code:: bash
mkdir -p ~/catkin_ws/src
Setup the workspace so it knows about your ROS installation

.. code:: bash
cd ~/catkin_ws/src
source /opt/ros/melodic/setup.bash
catkin_init_workspace
Clone the spot_ros repository into the workspace

.. code:: bash
cd ~/catkin_ws/src
git clone https://github.com/clearpathrobotics/spot_ros.git
git clone https://github.com/ros/geometry2 --branch 0.6.5
Use rosdep to install of the necessary dependencies

.. code:: bash
cd ~/catkin_ws/
rosdep install --from-paths src --ignore-src -y
Once all the necessary packages are installed, build the packages in the workspace

.. code:: bash
cd ~/catkin_ws/
catkin_make --cmake-args -DCMAKE_BUILD_TYPE=Release -DPYTHON_EXECUTABLE=/usr/bin/python3 -DPYTHON_INCLUDE_DIR=/usr/include/python3.6m -DPYTHON_LIBRARY=/usr/lib/x86_64-linux-gnu/libpython3.6m.so
Source your newly built workspace and the packages inside

.. code:: bash
source ~/catkin_ws/devel/setup.bash
Loading

0 comments on commit 2235158

Please sign in to comment.