SpotProject

This repository contains a ROS 2 description + demo control stack for a Boston Dynamics Spot-like quadruped model (with an optional arm) that you can visualize in RViz2 and drive using a simple keyboard teleop.

At a high level:

• spot_description provides the URDF/Xacro, meshes, RViz configs, and launch files.
• walk.py runs a basic gait / IK-based controller that outputs joint angles as sensor_msgs/JointState on /joint_states.
• teleop.py reads keyboard input from your terminal and publishes velocity commands as geometry_msgs/TwistStamped on /twist.

The default walking demo loop is:

1. teleop.py publishes /twist
2. walk.py subscribes to /twist, computes the next body/foot motion + joint targets
3. walk.py publishes /joint_states
4. robot_state_publisher consumes /joint_states to update TF
5. RViz shows the robot moving

---

What’s in here

Main ROS 2 package: spot_description

Directory (inside SpotProject/spot_description/):

• launch/: ROS 2 launch files for visualization and demos
• urdf/: Spot URDF/Xacro sources (Spot-only, Spot+arm, simplified model, standalone arm)
• meshes/: visual + collision meshes for the base and arm
• rviz/: RViz2 configurations
• walk.py: walking/gait demo node (publishes /joint_states, subscribes /twist)
• teleop.py: keyboard teleop node (publishes /twist)

For the list of URDF variants, see SpotProject/spot_description/urdf/README.md.

For details on inertial properties / how the inertials were extracted, see SpotProject/spot_description/README.md.

---

Requirements

• ROS 2 installed (this is a ROS 2 workspace; the launch files use ros2 launch)
• Python deps used by the demo nodes:
  • numpy
  • ROS 2 Python libraries (rclpy, tf2_ros, message packages such as geometry_msgs, sensor_msgs)
• ROS executables used by launch:
  • robot_state_publisher
  • joint_state_publisher / joint_state_publisher_gui
  • rviz2
  • xacro

The ROS exec dependencies are also listed in SpotProject/spot_description/package.xml.

---

Build (colcon)

From your workspace root (the parent directory of src/):

source /opt/ros/$ROS_DISTRO/setup.bash
cd ~/robotws
colcon build --symlink-install
source install/setup.bash

If your workspace is not ~/robotws, adjust the cd accordingly.

---

Run

1) Visualize Spot in RViz2 (no walking)

This launches robot_state_publisher, joint_state_publisher(_gui), and RViz:

ros2 launch spot_description description.launch.py

To include the arm in the model:

ros2 launch spot_description description.launch.py arm:=true

2) Visualize standalone arm

ros2 launch spot_description standalone_arm.launch.py

3) Walking demo + keyboard teleop (recommended quickstart)

This launches RViz + walk.py + teleop.py:

ros2 launch spot_description walk.launch.py

Keyboard controls (teleop)

teleop.py uses your terminal (reads from /dev/tty) and publishes to /twist:

• w: forward
• s: backward
• a: strafe left
• d: strafe right
• q: yaw left
• e: yaw right
• Space: stop (zero command)

Safety/behavior notes:

• Commands timeout quickly (about 0.1s) if you stop pressing keys, so the robot returns to zero velocity.
• If you run through SSH or a non-interactive terminal, /dev/tty input may not work; run teleop.py locally in a real terminal session.

---

ROS interfaces (topics)

The walking demo is intentionally simple and uses two global topics:

• /twist (geometry_msgs/TwistStamped): teleop velocity command (linear + angular)
• /joint_states (sensor_msgs/JointState): joint positions/velocities produced by walk.py

walk.py also publishes a TF transform from world → body so RViz can display the body moving in the world frame.

---

How the walking demo works (high-level)

walk.py implements a lightweight quadruped gait loop:

• Tracks a desired body pose (position + orientation) by integrating commanded twist (/twist).
• Keeps feet within an elliptical reachability region relative to the body; when a foot drifts out of range, it is switched into a swing phase.
• Swing legs follow a parabolic swing trajectory (lift + land), while stance legs hold position.
• Uses Jacobian-based IK tasks:
  • Primary: match desired foot positions (all four feet)
  • Secondary: keep body height near a nominal (Z) (stability)
  • Tertiary: bias joints toward “natural-looking” centers

The output is a 12-DOF leg joint vector published as JointState.

---

Troubleshooting

• RViz opens but robot doesn’t move:

  • Make sure you launched the walking demo (walk.launch.py), not just description.launch.py.
  • Confirm that /twist is being published (press keys in the teleop terminal).
  • Confirm that /joint_states is being published (ros2 topic echo /joint_states).

• Teleop doesn’t respond to keypresses:

  • teleop.py reads from /dev/tty. Run it in a real interactive terminal (not piped, not redirected).
  • If you’re using SSH, ensure you have a proper TTY (ssh -t) and that your terminal supports raw input.

• Launch can’t find package:

  • Rebuild and re-source:

cd ~/robotws
colcon build --symlink-install
source install/setup.bash