[SW-764] Consolidate examples into a single ROS package (#279)

## Change Overview This PR puts all spot related examples in `spot_ros2` into a single package called `spot_examples`. Previously, all examples of using the Spot driver were organized into separate ROS packages in the `examples` directory. Each of these ROS 2 packages only held a single node, resulting in a lot of bloat and making it more of a hassle to add new examples. Old structure: ``` examples/ ├── README.md ├── inverse_kinematics_example (ROS2 package) │ ├── inverse_kinematics_example │ │ └── send_inverse_kinematics_requests.py │ ├── package.xml │ ├── README.md │ ├── ... ├── simple_arm_motion (ROS2 package) │ ├── ... ├── simple_walk_forward (ROS2 package) │ ├── ... ├── utilities (ROS2 package) │ ├── ... ``` New file structure implemented in this PR ``` ├── spot_examples (ROS 2 package) │ └── spot_examples │ ├── __init__.py │ ├── arm_simple.py │ ├── send_inverse_kinematics_requests.py │ ├── simple_spot_commander.py │ └── walk_forward.py │ ├── docs │ │ ├── arm_simple.md │ │ ├── send_inverse_kinematics_requests.md │ │ └── walk_forward.md │ ├── package.xml │ ├── setup.py │ ├── README.md │ ├── ... ``` Now, when a new example is added, instead of creating an entirely new package, these steps can be followed. * create `new_example.py` in `spot_examples/spot_examples` and add it to `spot_examples/setup.py` * add documentation `new_example.md` to `spot_examples/docs` and link to it in `spot_examples/README.md` ## Additional consideration In our internal repo, there is a single file that uses `SimpleSpotCommander` which used to be in `examples/utilities` ROS 2 package (can be found by searching for the string `from utilities.simple_spot_commander import SimpleSpotCommander`). This would now need to be updated to `from spot_examples.simple_spot_commander import SimpleSpotCommander` with this implementation. ## Testing Done - [x] Robot tests all successful in one terminal ran `ros2 launch spot_driver spot_driver.launch.py config_file:=spot_ros.yaml spot_name:=Pluto` In another terminal, was successfully able to run ``` ros2 run spot_examples walk_forward --robot Pluto ros2 run spot_examples arm_simple --robot Pluto ros2 run spot_examples send_inverse_kinematics_requests --robot Pluto ```
bdaiinstitute · Mar 12, 2024 · dbf6105 · dbf6105
1 parent 4a27bb4
commit dbf6105
Show file tree

Hide file tree

Showing 34 changed files with 176 additions and 343 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 <p align="center">
   <img src="spot.png" width="350">
-  <h1 align="center">Spot ROS2 Driver</h1>
+  <h1 align="center">Spot ROS 2 Driver</h1>
   <p align="center">
     <a href="https://github.com/MASKOR/spot_ros2/blob/main/LICENSE">
     <img src="https://img.shields.io/badge/License-MIT-yellow.svg" />
@@ -18,14 +18,14 @@
 </p>
 
 # Overview
-This is a ROS2 package for Boston Dynamics' Spot. The package contains all necessary topics, services and actions to teleoperate or navigate Spot.
-This package is derived from this [ROS1 package](https://github.com/heuristicus/spot_ros). This package currently corresponds to version 4.0.0 of the [spot-sdk](https://github.com/boston-dynamics/spot-sdk/releases/tag/v4.0.0).
+This is a ROS 2 package for Boston Dynamics' Spot. The package contains all necessary topics, services and actions to teleoperate or navigate Spot.
+This package is derived from this [ROS 1 package](https://github.com/heuristicus/spot_ros). This package currently corresponds to version 4.0.0 of the [spot-sdk](https://github.com/boston-dynamics/spot-sdk/releases/tag/v4.0.0).
 
 ## Prerequisites
 This package is tested for Ubuntu 22.04 and ROS 2 Humble, which can be installed following [this guide](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html). 
 
 ## Installation
-In your ROS2 workspace `src` directory, clone the repository:
+In your ROS 2 workspace `src` directory, clone the repository:
 ```bash
 git clone https://github.com/bdaiinstitute/spot_ros2.git
 ```
@@ -43,7 +43,7 @@ cd <path to spot_ros2>
 or
 ./install_spot_ros2.sh --arm64
 ```
-From here, build and source the ROS2 workspace:
+From here, build and source the ROS 2 workspace:
 ```
 cd <ros2 ws>
 source /opt/ros/humble/setup.bash
@@ -52,7 +52,7 @@ source install/local_setup.bash
 ```
 
 ## Example Code
-See the [examples](examples/) for some examples of using the ROS2 driver.
+See [`spot_examples`](spot_examples/) for some examples of using the ROS 2 driver to control Spot.
 
 ## Launch
 The spot login data hostname, username and password can either be specified as ROS parameters or as environment variables.  If using ROS parameters, see `spot_driver/config/spot_ros_example.yaml` for an example of what your file could look like.  If using environment variables, define `BOSDYN_CLIENT_USERNAME`, `BOSDYN_CLIENT_PASSWORD`, and `SPOT_IP`.
@@ -105,12 +105,12 @@ rm /tmp/ros-humble-spot-msgs_0.0.0-0jammy_amd64.deb
 ```
 
 ### Install bosdyn_msgs from source
-The `bosdyn_msgs` package is installed as a debian package as part of the `install_spot_ros2` script because it's very large.  It can be checked out from source [here](https://github.com/bdaiinstitute/bosdyn_msgs) and then built as a normal ROS2 package if that is preferred (compilation takes about 15 minutes).
+The `bosdyn_msgs` package is installed as a debian package as part of the `install_spot_ros2` script because it's very large.  It can be checked out from source [here](https://github.com/bdaiinstitute/bosdyn_msgs) and then built as a normal ROS 2 package if that is preferred (compilation takes about 15 minutes).
 
 
 ## License
 
-MIT license - parts of the code developed specifically for ROS2.
+MIT license - parts of the code developed specifically for ROS 2.
 BSD3 license - parts of the code derived from the Clearpath Robotics ROS1 driver.
 
 ## Contributing

diff --git a/examples/README.md b/examples/README.md
diff --git a/examples/inverse_kinematics_example/package.xml b/examples/inverse_kinematics_example/package.xml
diff --git a/examples/inverse_kinematics_example/resource/inverse_kinematics_example b/examples/inverse_kinematics_example/resource/inverse_kinematics_example
diff --git a/examples/inverse_kinematics_example/setup.cfg b/examples/inverse_kinematics_example/setup.cfg
diff --git a/examples/inverse_kinematics_example/setup.py b/examples/inverse_kinematics_example/setup.py
diff --git a/examples/simple_arm_motion/package.xml b/examples/simple_arm_motion/package.xml
diff --git a/examples/simple_arm_motion/resource/simple_arm_motion b/examples/simple_arm_motion/resource/simple_arm_motion
diff --git a/examples/simple_arm_motion/setup.cfg b/examples/simple_arm_motion/setup.cfg
diff --git a/examples/simple_arm_motion/setup.py b/examples/simple_arm_motion/setup.py
diff --git a/examples/simple_arm_motion/simple_arm_motion/__init__.py b/examples/simple_arm_motion/simple_arm_motion/__init__.py
diff --git a/examples/simple_walk_forward/resource/simple_walk_forward b/examples/simple_walk_forward/resource/simple_walk_forward
diff --git a/examples/simple_walk_forward/setup.cfg b/examples/simple_walk_forward/setup.cfg
diff --git a/examples/simple_walk_forward/simple_walk_forward/__init__.py b/examples/simple_walk_forward/simple_walk_forward/__init__.py
diff --git a/examples/utilities/package.xml b/examples/utilities/package.xml
diff --git a/examples/utilities/resource/utilities b/examples/utilities/resource/utilities
diff --git a/examples/utilities/setup.cfg b/examples/utilities/setup.cfg
diff --git a/examples/utilities/setup.py b/examples/utilities/setup.py
diff --git a/examples/utilities/utilities/__init__.py b/examples/utilities/utilities/__init__.py
diff --git a/examples/utilities/utilities/tf_listener_wrapper.py b/examples/utilities/utilities/tf_listener_wrapper.py
diff --git a/pyproject.toml b/pyproject.toml
@@ -57,5 +57,5 @@ strict_equality = true
 warn_unreachable = true
 warn_redundant_casts = true
 no_implicit_optional = true
-files = ['spot_description', 'spot_driver', 'examples']
+files = ['spot_description', 'spot_driver', 'spot_examples']
 exclude = '^(docker|.*external|.*thirdparty|.*install|.*build|.*_experimental|.*conversions.py)/'
diff --git a/spot_examples/README.md b/spot_examples/README.md
@@ -0,0 +1,31 @@
+# spot_examples
+This is a ROS 2 package that demonstrates how to use the Spot driver to control the robot.
+
+Before running any of these nodes, make sure that the robot is in an open space and that you've built and sourced your ROS 2 workspace. 
+```bash
+cd <ros2_workspace>
+colcon build --symlink-install
+source install/setup.bash
+```
+After this, it's time to start the Spot driver. Define the environment variables `BOSDYN_CLIENT_USERNAME`, `BOSDYN_CLIENT_PASSWORD`, and `SPOT_IP` appropriately for your robot, or put the login credentials into a configuration file yaml ([example](../spot_driver/config/spot_ros_example.yaml)). The driver can be started via the following launchfile:
+```bash
+ros2 launch spot_driver spot_driver.launch.py
+```
+* If you are defining your login credentials in a configuration yaml instead of as environment variables, add the launch argument `config_file:=path/to/config.yaml`
+* If you want to launch with a namespace, use the launch argument `spot_name:=<spot_name>`
+
+
+## Nodes
+Once the driver has been started, different examples can be run with the following command:
+```bash
+ros2 run spot_examples <example_node>
+```
+Follow the links on each of the node names for more detailed documentation about how each example works, possible command line arguments, and other safety considerations you may need to take into account. 
+
+* [`walk_forward`](docs/walk_forward.md): A simple example that shows how to use ROS 2 to send `RobotCommand` goals to the Spot driver. If you are new to Spot and ROS 2, we recommend starting here.
+* [`arm_simple`](docs/arm_simple.md): An example of converting the [BD Simple Arm Motion](https://dev.bostondynamics.com/python/examples/arm_simple/readme) example to use ROS 2. 
+* [`send_inverse_kinematic_requests`](docs/send_inverse_kinematics_requests.md): An example that shows how to send inverse kinematics requests to the Spot Arm using ROS 2. 
+
+
+## Adding new examples
+To add examples that demonstrate other features of the Spot driver, create a new node `new_example.py` in [spot_examples](spot_examples) and add it to `setup.py`. Make sure to also write a documentation file (`new_example.md`) in [docs](docs) that explains how to run the example and how the code works, and link to it in this central README.