====== Spot ROS ====== The Spot robot comes with its own Spot SDK from Boston Dynamics, available in Python3 and C++. However, there is a ROS package that allows you to trigger most functionality of the robot using ROS messages, services and actions. ===== Installation ===== Installing the ROS package follows the same process as any other ROS package; git clone the repository, install dependencies, then build the package. Instructions from the Github Pages is [[https://heuristicus.github.io/spot_ros/html/index.html|here]]. It is recommended to use ROS Noetic for Python3 compatibility. Use a Docker container to get the correct ROS distro setup with all the distro-specific packages. First, setup your catkin workspace, if you haven't already. Then, download the source code. mkdir -p ~/catkin_ws/src source /opt/ros/noetic/setup.bash git clone https://github.com/heuristicus/spot_ros.git ~/catkin/src/spot_ros Next, install the required dependencies with `rosdep`. sudo apt install -y python3-rosdep rosdep install --from-paths ~/catkin_ws/src --ignore-src -y Build the package with `catkin build`. cd ~/catkin_ws catkin build Source the built package. source ~/catkin_ws/devel/setup.bash ===== Docker Usage ===== Alternatively, you can make use of pre-built Docker images generated by the CI pipeline. - Download the image from Docker Hub with `sudo docker pull jeremysee/spot_ros:master` - Save the image into a .tar archive with `sudo docker save -o spotros.tar jeremysee/spot_ros:master` - Upload the .tar archive to Spot CORE using [[https://dev.bostondynamics.com/docs/payload/spot_core_portainer|this guide]] {{:documentation:robots:spot:portainer.png?800|}} ===== Configuration ===== The ROS package has certain parameters that can be configured in `spot_driver/config/spot_ros.yaml`. ^ Parameter ^ Description ^ | rates/robot_state | The robot's state (include joint angles) | | rates/metrics | The robot's metrics | | rates/lease | The robot's lease state | | rates/front_image | The image and depth image from the front camera | | rates/side_image | The image and depth image from the side cameras | | rates/loop_frequency | The image and depth image from the rear camera | | rates/point_cloud | The point cloud from the EAP lidar | | rates/hand_image | The image and depth image from the arm's hand camera | | rates/feedback | A feedback message with various information | | rates/mobility_params | Parameters indicating the robot's mobility state | | rates/check_subscribers | Check for subscribers on camera topics. Data is not published without subscribers| There are also some flags that can be set to enable certain startup behaviour. ^ Parameter ^ Description ^ | 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 connects | Lastly, some environmental variables you can set if you want to configure other nodes (Velodyne driver or teleop). ^ Variable ^ Default Value ^ Description ^ | SPOT_VELODYNE_HOST | 192.168.131.20 | IP address of the VLP-16 sensor | | SPOT_JOY_DEVICE | /dev/input/js0 | The Linux joypad input device used by the joy_teleop node | | SPOT_JOY_CONFIG | spot_control/config/teleop.yaml | Joypad button/axis configuration file for joy_teleop | | SPOT_VELODYNE_AUTOLAUNCH| 1 | If 1 and SPOT_VELODYNE is also 1, the VLP16 ROS node will start automatically | ===== Running the spot_ros Driver ===== Before running the driver, you need to set the following parameters to authenticate with the robot. ^ Argument ^ Default ^ Description ^ | username | dummyusername | Use this username to authenticate with spot | | password | dummypassword | Use this password to authenticate with spot | | hostname | 192.168.50.3 | The IP address at which spot can be found | | estop_timeout | 9.0 | Time allowed before rpc commands will time out. Comms between the | | | | robot and driver are checked at a rate of 1/3 of this time. If | | | | comms are down, a gentle estop will trigger | | autonomy_enabled | True | If false, some autonomy commands will be disabled for this run of | | | | the driver. This can only be changed on driver restart | | max_linear_velocity_x | 0 | Limit on linear velocity for moving forwards. 0 is whatever is | | | | specified by BD. | | max_linear_velocity_y | 0 | Limit on linear velocity for moving sideways. 0 is whatever is | | | | specified by BD. | | max_linear_velocity_z | 0 | Limit on angular velocity for rotation. 0 is whatever is specified | | | | by BD. | | allow_motion | True | If false, the robot starts with all motion disallowed and must have| | | | it enabled by calling a service or pressing a button in rviz | To view the robot in RViz, use: roslaunch spot_viz view_robot.launch You should see something like this. The colour points represent the depth cloud produced by the 5 stereo cameras on the robot. The white dots will only be available after adding the PointCloud2 LIDAR data (/spot/lidar/points) to the RViz viewport. {{:documentation:robots:spot:spot_rviz_view_robot.jpg?800|}} Basic control of the robot can be done using the control panel on the right. This allows you to claim the lease, power on the robot and make it stand up. You can also command it to move to a specific location using the `2D Nav Goal` tool in RViz, or set a specific body pose to go to. When issuing any movement commands to the robot, you will need to claim the lease -> power on -> stand, before the commands will execute. ===== ROS Usage ===== The documentation of available ROS services, topics and actions are listed below, explaining the capabilities of the spot_ros driver. ===== ROS Services ===== The available ROS services and thier descriptions are in this section. ^ Topic ^ Type ^ Description ^ | /spot/claim | Trigger | Claim the lease | | /spot/release | Trigger | Release the lease | | /spot/self_right | Trigger | Flip onto the legs | | /spot/sit | Trigger | Sit the robot | | /spot/stand | Trigger | Stand the robot | | /spot/power_on | Trigger | Enable motor power | | /spot/power_off | Trigger | Disable motor power | | /spot/estop/hard | Trigger | Trigger the estop immediately | | /spot/estop/gentle | Trigger | Trigger the estop gracefully | | /spot/estop/release | Trigger | Release the estop | | /spot/allow_motion | SetBool | Enable or disable motion | | /spot/stair_mode | SetBool | Enable or disable stair climbing mode | | /spot/locomotion_mode | SetLocomotion | Set locomotion_mode | | /spot/swing_height | SetSwingHeight | Set swing_height mode | | /spot/velocity_limit | SetVelocity | Set velocity_limit as Twist message | | /spot/clear_behavior_fault | ClearBehaviorFault | Clear faults by id | | /spot/terrain_params | SetTerrainParams | Set ground_mu_hint and grated surfaces mode | | /spot/obstacle_params | SetObstacleParams | Set obstacle avoidance parameters | | /spot/posed_stand | PosedStand | Set body height and pose | | /spot/list_graph | ListGraph | Get the list of waypoints in the active graph | | /spot/download_graph | DownloadGraph | Download the list of waypoints in the active graph | | /spot/navigate_init | NavigateInit | Localization with a fiducial in the provided map | | /spot/graph_close_loops | GraphCloseLoops | Request loop closure in the active graph | | /spot/optimize_graph_anchoring | Trigger | Request anchor optimization in the active graph | | /spot/roll_over_right | Trigger | Roll body over to the right | | /spot/roll_over_left | Trigger | Roll body over to the left | | /spot/dock | Dock | Dock at dock_id | | /spot/undock | Trigger | Undock the robot | | /spot/docking_state | GetDockState | Get the dock_state of the robot | | /spot/spot_check | SpotCheck | Run Spot Check self-calibration | | /spot/arm_stow | Trigger | Arm stow position | | /spot/arm_unstow | Trigger | Arm unstow position | | /spot/gripper_open | Trigger | Gripper open position | | /spot/gripper_close | Trigger | Gripper close position | | /spot/arm_carry | Trigger | Arm carry position | | /spot/gripper_angle_open | GripperAngleMove | Gripper open to specific angle | | /spot/arm_joint_move | ArmJointMovement | Arm move to specific angle for each joint | | /spot/force_trajectory | ArmForceTrajectory | Arm move as a wrench | | /spot/gripper_pose | HandPose | Gripper move to Pose in a specific frame | | /spot/grasp_3d | Grasp3d | Execute a pick at a Position in a specific frame | | /spot/arm_gaze | Trigger | Arm gaze towards the front, for demonstration | | /spot/stop | Trigger | Stop the robot | | /spot/locked_stop | Trigger | Stop the robot and disallow motion | | /spot/spot_ros/tf2_frames | Trigger | Get tf2 transformation frames as a FrameGraph | ===== ROS Topics ===== ^ Topic ^ Type ^ Description ^ | /clock | rosgraph_msgs/Clock | ROS simulation time | | /diagnostics | diagnostic_msgs/DiagnosticArray | ROS diagnostics | | /joint_states | sensor_msgs/JointState | Spot joint pose states | | /rosout | rosgraph_msgs/Log | Logging messages | | /rosout_agg | rosgraph_msgs/Log | Logging messages | | /spot/body_pose/status | actionlib_msgs/GoalStatusArray | Body pose from standing action server | | /spot/camera/back/camera_info | sensor_msgs/CameraInfo | Spot monochrome fisheye camera info | | /spot/camera/back/image | sensor_msgs/Image | Spot monochrome fisheye camera data | | /spot/camera/frontleft/camera_info | sensor_msgs/CameraInfo | Spot monochrome fisheye camera info | | /spot/camera/frontleft/image | sensor_msgs/Image | Spot monochrome fisheye camera data | | /spot/camera/frontright/camera_info | sensor_msgs/CameraInfo | Spot monochrome fisheye camera info | | /spot/camera/frontright/image | sensor_msgs/Image | Spot monochrome fisheye camera data | | /spot/camera/hand_color/camera_info | sensor_msgs/CameraInfo | Spot colour hand camera info | | /spot/camera/hand_color/image | sensor_msgs/Image | Spot colour hand camera data | | /spot/camera/hand_mono/camera_info | sensor_msgs/CameraInfo | Spot monochrome hand camera info | | /spot/camera/hand_mono/image | sensor_msgs/Image | Spot monochrome hand camera data | | /spot/camera/hand/depth_in_color/camera_info | sensor_msgs/CameraInfo | Spot colour and depth hand camera data | | /spot/camera/left/camera_info | sensor_msgs/CameraInfo | Spot monochrome fisheye camera info | | /spot/camera/left/image | sensor_msgs/Image | Spot monochrome fisheye camera data | | /spot/camera/right/camera_info | sensor_msgs/CameraInfo | Spot monochrome fisheye camera info | | /spot/camera/right/image | sensor_msgs/Image | Spot monochrome fisheye camera data | | /spot/depth/back/camera_info | sensor_msgs/CameraInfo | Spot depth camera info | | /spot/depth/back/image | sensor_msgs/Image | Spot depth camera data | | /spot/depth/frontleft/camera_info | sensor_msgs/CameraInfo | Spot depth camera info | | /spot/depth/frontleft/image | sensor_msgs/Image | Spot depth camera data | | /spot/depth/frontright/camera_info | sensor_msgs/CameraInfo | Spot depth camera info | | /spot/depth/frontright/image | sensor_msgs/Image | Spot depth camera data | | /spot/depth/hand/camera_info | sensor_msgs/CameraInfo | Spot depth hand camera info | | /spot/depth/hand/depth_in_color | sensor_msgs/Image | Spot depth colour hand camera data | | /spot/depth/hand/image | sensor_msgs/Image | Spot depth hand camera data | | /spot/depth/left/camera_info | sensor_msgs/CameraInfo | Spot depth in visual camera info | | /spot/depth/left/image | sensor_msgs/Image | Spot depth in visual camera data | | /spot/depth/right/camera_info | sensor_msgs/CameraInfo | Spot depth in visual camera info | | /spot/depth/right/image | sensor_msgs/Image | Spot depth in visual camera data | | /spot/depth/back/depth_in_visual/camera_info | sensor_msgs/CameraInfo | Spot depth in visual camera info | | /spot/depth/back/depth_in_visual | sensor_msgs/Image | Spot depth in visual camera data | | /spot/depth/frontleft/depth_in_visual/camera_info | sensor_msgs/CameraInfo | Spot depth in visual camera info | | /spot/depth/frontleft/depth_in_visual | sensor_msgs/Image | Spot depth in visual camera data | | /spot/depth/frontright/depth_in_visual/camera_info | sensor_msgs/CameraInfo | Spot depth in visual camera info | | /spot/depth/frontright/depth_in_visual/camera_info | sensor_msgs/Image | Spot depth in visual camera data | | /spot/depth/left/depth_in_visual/camera_info | sensor_msgs/CameraInfo | Spot depth in visual camera info | | /spot/depth/left/depth_in_visual | sensor_msgs/Image | Spot depth in visual camera data | | /spot/depth/right/depth_in_visual/camera_info | sensor_msgs/CameraInfo | Spot depth in visual camera info | | /spot/depth/right/depth_in_visual | sensor_msgs/Image | Spot depth in visual camera data | | /spot/dock/status | actionlib_msgs/GoalStatusArray | Spot docking status | | /spot/lidar/points | sensor_msgs/PointCloud2 | Spot EAP Velodye VLP-16 LIDAR data | | /spot/motion_or_idle_body_pose/status | actionlib_msgs/GoalStatusArray | Body pose with movement action server | | /spot/navigate_to/status | actionlib_msgs/GoalStatusArray | GraphNav navigation action server | | /spot/odometry | nav_msgs/Odometry | Spot odometry, "vision" or "odom" | | /spot/odometry/twist | geometry_msgs/TwistWithCovarianceStamped | Legacy compatibility with /spot/cmd_vel | | /spot/status/battery_states | spot_msgs/BatteryStateArray | Spot status: battery state | | /spot/status/behavior_faults | spot_msgs/BehaviorFaultState | Spot status: behavior fault | | /spot/status/estop | spot_msgs/EStopStateArray | Spot status: emergency stop (estop) | | /spot/status/feedback | spot_msgs/Feedback | Spot status: standing, sitting, moving, version | | /spot/status/feet | spot_msgs/FootStateArray | Spot status: feet state | | /spot/status/leases | spot_msgs/LeaseArray | Spot status: active lease holder | | /spot/status/metrics | spot_msgs/Metrics | Spot status: distance and power usage metrics | | /spot/status/mobility_params | spot_msgs/MobilityParams | Spot status: velocity limit, other parameters | | /spot/status/motion_allowed | std_msgs/Bool | Spot status: motion enabled status | | /spot/status/power_state | spot_msgs/PowerState | Spot status: charging, shore power, battery power | | /spot/status/system_faults | spot_msgs/SystemFaultState | Spot status: system fault | | /spot/status/wifi | spot_msgs/WiFiState | Spot status: wifi ESSID, current mode | | /spot/trajectory/status | actionlib_msgs/GoalStatusArray | Trajectory pose movement action server | | /spot/world_objects | spot_msgs/WorldObjectArray | Spot world object detections | | /tf | tf2_msgs/TFMessage | Transformation frames from TF2 API | | /tf_static | tf2_msgs/TFMessage | Transformation frames from TF2 API | | /twist_marker_server/update | visualization_msgs/InteractiveMarkerUpdate | Legacy compatibility with /spot/cmd_vel | | /twist_marker_server/update_full | visualization_msgs/InteractiveMarkerInit | Legacy compatibility with /spot/cmd_vel | ===== ROS Actions ===== ^ Topic ^ Type ^ Description ^ | /spot/navigate_to | NavigateToAction | Go to a GraphNav waypoint | | /spot/navigate_route | NavigateRouteAction | Go to a series of GraphNav waypoints | | /spot/trajectory | TrajectoryAction | Move robot to a Pose | | /spot/motion_or_idle_body_pose | PoseBodyAction | Rotate body to a pose | | /spot/body_pose | PoseBodyAction | Stand and move robot to a Pose | | /spot/dock | DockAction | Dock or undock at a specific dock_id | ===== Frequently Asked Questions (FAQ) ===== Question 1: How do I upload a Docker container to Spot? Answer: Follow [[https://dev.bostondynamics.com/docs/payload/spot_core_portainer|this guide]] on how to use Portainer on the Spot CORE. Question 2: Does Spot have access to the Internet? Answer: No, not unless you [[https://support.bostondynamics.com/s/article/Spot-CORE-Accessing-the-Internet-Through-Spot#:~:text=On%20your%20computer%2C%20navigate%20to%20the%20robot's%20IP%20address%20using,selecting%20OPEN%20COCKPIT%20%2D%20SYSTEM%20MANAGEMENT.|specifically set it up]]. ===== Further Reading and Resources ===== This section includes links to additional documentation, tutorials, and other resources. [[https://github.com/heuristicus/spot_ros|spot_ros Github]] [[https://github.com/bdaiinstitute/spot_wrapper|spot_wrapper Github]] [[https://github.com/bdaiinstitute/spot_ros2|spot_ros2 Github]] A snapshot of these repos are also available on the internal gitlab: https://git.cs.lth.se/robotlab/spot