Spot Micro Quadruped Project

Video of robot: https://www.youtube.com/watch?v=S-uzWG9Z-5E

• Overview
• General Instructions
• Description of ROS Nodes
• Additional Project Components
  • URDF
  • TF2 Publishing and Odometry
  • SLAM
• Future Work
• External Links

Overview

This project is the source code for a Spot Micro quadruped, a 4 legged open source robot. This code implements motion control of a 3d printed spot micro robot, including sit, stand, angle and walk control. Supporting libraries provide additional capabilities, such as mapping through SLAM and a body mounted lidar. The software is implemented on a Raspberry Pi 3B running Ubuntu 16.04 with ROS Kinetic installed.

The software is composed of C++ and Python nodes in a ROS framework.

Hardware:

The frame utilized is the Thingverse Spot Micro frame developed by KDY0523. See the thingverse page for additional details for assembly hardware. The files for cls6336hv servos were printed which also fit the hv5523mg servos I used.

Component List:

• Computer: Raspberry Pi 3B
• Servo control board: PCA9685, controlled via i2c
• Servos: 12 x PDI-HV5523MG
• LCD Panel: 16x2 i2c LCD panel (Optional)
• Battery: 2s 4000 mAh Lipo, direct connection to servo board for servo power
• UBEC: HKU5 5V/5A ubec, used as 5v voltage regulator to power raspberry pi, lcd panel, pca9685 control board.
• Lidar: RPLidar A1
• Custom 3d printed parts for mounts and reinforcements

More information about the hardware, including the additional custom 3d printed parts, coordinate system information, and sample hardware installation photos, can be found in the additional hardware description document.

Software:

This repo is structured as a catkin workspace in a ROS Kinetic envivornment on Ubuntu 16.04. The software may not work or compile outside this environment. Raspberry Pi images preloaded with Ubuntu 16.04 and a ROS Kinetic installation can be found via ubiquity robotics. See ubiquity robotics webpage for download, setup, and wifi setup instructions. It is suggested to also install ROS Kinetic on a Ubuntu 16.04 linux installation/dual boot/virtual machine on a PC for development and for running control nodes. Instructions to install ROS kinetic can be found here.

NOTE A SWAP partition of about 1 GB on the RPI's sd card is necessary to increase the virtual memory available beyond the RPI's onboard RAM. In my experience the catkin compilation process uses all the onboard RAM and stalls indefinitely and does not complete without adding a SWAP partition. Example instructions for adding a SWAP partition can be found here.

The provided ROS Catkin make build system can be utilized, but I used catkin tools instead (see catkin tools website). Compilation commands below will be given assuming catkin tools. If not using catkin tools on the raspberry pi, the stock catkin_make can be used to compile the code via command such as catkin_make -DCMAKE_BUILD_TYPE=Release from the home of the catkin workspace.

Software Checkout and Setup:

This repo should be checked out to a catkin workspace on the raspberry pi so the directory structure appears as below. If not already available, a catkin workspace can be created or transitioned from a catkin make workspace using catkin tools (or if using stock ROS tools, see tutorial pages for creating a catkin workspace). If you don't have the pi connected to the internet you could use the catkin commands to create the workspace on another conputer, then copy the files to a RPi over wifi via scp. For example: scp spotMicro/* ubuntu@10.42.0.1:~/catkin_ws/src/.

catkin_ws/
│
├── src/
│   ├── spot_micro_motion_cmd
│   │   └── ...
│   ├── spot_micro_keyboard_cmd
│   │   └── ...  
│   └── ...

Note that this repo utilizes two git submodules, which require additional steps to check out. After checking out the main repo, checkout the submodules via:

git submodule update --init --recursive
git submodule update --recursive

If any git permission errors are encountered, try the following suggestions via this stackoverflow post.

Three additional ROS packages may need to be installed for this project to build succesfully. They can be installed via:

sudo apt-get install ros-kinetic-joy
sudo apt-get install ros-kinetic-rplidar-ros
sudo apt-get install ros-kinetic-hector-slam

Since the same repo is checked out on both a pi and a laptop/PC, you will need to install an i2c library on the laptop/pc for the software to compile correctly. The i2cpwm_board node is not run on the laptop/pc, but compilation will look for dependencies for this node. Install the necessary library via: sudo apt-get install libi2c-dev

Configure catkin tools so cmake Release flag is added. This speeds up code execution. Alternatively, if you want to debug through an IDE such as VSCode, use build type Debug so debug symbols are generated: catkin config --cmake-args -DCMAKE_BUILD_TYPE=Release

Compile spot_micro_motion_cmd and i2cpwm_board nodes via catkin tools. The command below will automatically build i2cpwmboard in the process as it is a dependency. E.g.: catkin build spot_micro_motion_cmd

Or just build entire project: catkin build

If you get an error like the below when running on the pi its likely you are missing the libi2c-dev, which may not be installed in the rpi image you download. To fix this, you could install the library on your pi with an apt-get command. If you don't have internet on the pi, you can download the file as a debian .deb package to your main computer with the right version for ubuntu 16.04 (https://ubuntu.pkgs.org/16.04/ubuntu-universe-amd64/libi2c-dev_3.1.1-1_all.deb.html) and then copy the file via scp to the pi (scp libi2c-dev_3.1.1-1_all.deb ubuntu@10.42.0.1:~/) and and install it manually (sudo dpkg -i libi2c-dev_3.1.1-1_all.deb).

ros-i2cpwmboard/CMakeFiles/i2cpwm_board.dir/build.make:62: recipe for target 'ros-i2cpwmboard/CMakeFiles/i2cpwm_board.dir/src/i2cpwm_controller.cpp.o' failed
make[2]: *** [ros-i2cpwmboard/CMakeFiles/i2cpwm_board.dir/src/i2cpwm_controller.cpp.o] Error 1
CMakeFiles/Makefile2:2343: recipe for target 'ros-i2cpwmboard/CMakeFiles/i2cpwm_board.dir/all' failed

Note on Walking Gaits

The default gait implemented is a 8 phase gait that incorporates body movement which helps maintain balance and stability. An alternate trot gait, where the diagonally opposite legs move simultaneously, can achieve faster walking speeds, but is less stable and requires careful positioning of the robot's center of mass. The trot gait is the one depicted in the animation at the top of this document. See the spot_micro_motion_cmd node's config file for information on how to switch to the trot gait. The 8 phase gait can be observed in the linked Youtube video.

General Instructions

This section attemps to be a full set of instructions to get a spot micro robot calibrated and running with this code.

Servo Configuration

Comprehensive instructions for servo installation, calibration, and configuration can be found in servo_calibration document.

Running:

Open at least two terminal windows, with at least one ssh'ed to the raspberry pi. I reccomend using a terminal multiplexer such as tmux for convenience. Start the following launch files in the respective terminals:

• roslaunch spot_micro_motion_cmd motion_cmd.launch: Run on the Raspberry Pi. Launches the i2c_pwmboard node as well as the robot's motion control node. On startup, the motion command node sends a servo configuration message to the i2c_pwmboard node, then starts a state machines and enteres an idle state.
• roslaunch spot_micro_keyboard_command keyboard_command.launch Run on a local machine. Launches the keyboard command node, for issuing keyboard commands to the spot micro robot
• OPTIONAL: The above two launch files can take optional command line arguments to start additional nodes. Some of the command line arguments are listed below.
  • Command line arguments for motion_cmd.launch:
    • run_standalone:=true: Runs the motion command node standalone (without running the i2c_pwmboard node)
    • debug_mode:=true: Overrides the debug_mode parameter to true. Useful in combination with run_standalone for running or debugging the motion command node on a PC instead of the RPi
    • run_lcd:=true: Runs the lcd monitor node to display simple state information on a LCD monitor if installed. Only works running on a RPi
  • Command line arguments for keyboard_command.launch:
    • run_rviz:=true: Starts RVIZ and displays a 3d model of the robot with state update in real time.
    • run_plot:=true: Runs python plotting node to display a stick figure wireframe model of the spot micro robot state in real time. Must be run on a PC. Requires updated matplot lib python library (matplotlib 2.2.5) and updated numpy library (numpy 1.16.6).
• For running SLAM, see the SLAM document for more information, which is also referenced in the Additional Project Components section.

Stopping and exiting