Kelpie Quadruped

Overview

This repository hosts the code for the Kelpie Quadruped, a robot designed to be low-cost yet capable of both education and research usages and being extensively modified with additional actuators and sensors. CAD for the Kelpie can be found here. A full Bill of materials for purchasable components can be found within this repo.

This code is based on the Dingo Quadruped codebases, with extensive modifications, including integration into ROS 1 Noetic.

The repository includes a driver node, dingo_driver.py, which should be used anytime the code is run. This file enables joystick control of the Dingo, and allows joint and/or task space commands generated by any other code to be passed through the driver via the appropriate ROS command topics. The joystick can also be toggled on and off to override commands received via ROS command topics

The repo also includes a gazebo simulation of the Dingo, based on URDF file and meshes which are also provide.

How Kelpie ROS Network Works

The following flow diagram shows a simplified overview of how a joystick command is handled by the driver to affect joint movements:

Installation of Code

Natively

Install Ubuntu 20.04 onto the Pi's SD card via the Raspberry Pi Imager, and setup username, password and network information.
Install ros-noetic
Install necessary packages via sudo apt-get install python3-catkin-tools git python3-rosdep python3-rosinstall python3-rosinstall-generator python3-wstool python3-pip build-essential wireless-tools libraspberrypi-bin ros-noetic-joy ros-noetic-catkin python3-catkin-tools i2c-tools libi2c-dev python3-smbus
Install necessary python packages via pip install spidev transforms3d pillow rpi.gpio pyserial simple-pid
Change directory to the home folder: cd ~
Get a list of available time zones: timedatectl list-timezones
Set local time zone from list e.g: sudo timedatectl set-timezone Australia/Melbourne
Clone this (the Kelpie Quadruped) repository using git: git clone ...
Update all submodules: git submodule update --init
Move into the kelpie_ws folder: cd /DingoQuadruped/kelpie_ws
Initialise rosdep: sudo rosdep init
Fetch dependencies with rosdep: rosdep update
Build the workspace: catkin build
Source the workspace: source devel/setup.bash
Set ROS_MASTER_URI: echo "export ROS_MASTER_URI=http://dingo:11311" >> ~/.bashrc
Source ROS in bashrc .bashrc:echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc, source ~/.bashrc
(Optional) Add a line to .bashrc to automatically source the workspace: echo "source ~/DingoQuadruped/kelpie_ws/devel/setup.bash" >> ~/.bashrc, source ~/.bashrc

Additional Installation Steps

Bluetooth Setup

For getting bluetooth controller working (for instance PS4 controller)

More info here: https://www.makeuseof.com/manage-bluetooth-linux-with-bluetoothctl/
Install bluetooth:
- sudo apt-get install bluetooth bluez bluez-tools
- sudo apt-get install pi-bluetooth
To pair and connect a controller:
- bluetoothctl
- scan on
- trust AA:BB:CC:11:22:33 (example device)
- pair AA:BB:CC:11:22:33
- connect AA:BB:CC:11:22:33
To test the controller:
- jstest /dev/input/js0
To list connected devices:
- bluetoothctl paired-devices
To later forget the controller:
- bluetoothctl remove AA:BB:CC:11:22:33

At this stage, the controller will only connect if you run bluetoothctl in the terminal, and then press the pair button on the controller. To bypass the step of running bluetoothctl, do the following:

Create a shell script called connect_controller.sh (Make a note of where you create it) with the following contents:

#!/bin/bash

# Replace 'XX:XX:XX:XX:XX:XX' with your controller's MAC address
controller_mac="XX:XX:XX:XX:XX:XX"

# Use bluetoothctl to connect the controller
bluetoothctl <<EOF
connect $controller_mac
exit
EOF`

Make it executable by running chmod +x connect_controller.sh
Create a UDEV rule to run this script every time the controller attempts to pair: SUBSYSTEM=="bluetooth", KERNEL=="hci0", ACTION=="add", ENV{DEVTYPE}=="adapter", TAG+="systemd", SYMLINK+="bluetooth", RUN+="/bin/sleep 10", RUN+="/path/to/connect_controller.sh"
reload the UDEV rules: sudo udevadm control --reload The controller should now autopair every time the pair button is pressed, without needing to do anything on the Pi

Wifi Setup

To get WiFi working

Edit the file /etc/netplan/50-cloud-init.yaml
Add the following to the bottom of the file

    wifis:
        wlan0:
            optional: true
            dhcp4: true
            access-points:
                "<wifi SSID>":
                    password: "<wifi password>"

LCD Node Additional Setup

The LCD node has been created following the waveshare tutorial here: https://www.waveshare.com/wiki/1.47inch_LCD_Module. Apart from installing the libraries listed there, the fonts also need to be moved into the ubuntu fonts folder to be used by executing the following lines:

cd ~
sudo apt-get install unzip -y
sudo wget https://files.waveshare.com/upload/8/8d/LCD_Module_RPI_code.zip
sudo unzip ./LCD_Module_RPI_code.zip
cd ~/LCD_Module_RPI_code/RaspberryPi/python/Font
sudo mv Font00.ttf /usr/share/fonts/truetype/Font00.ttf
sudo mv Font01.ttf /usr/share/fonts/truetype/Font01.ttf
sudo mv Font02.ttf /usr/share/fonts/truetype/Font02.ttf

If getting an error with "rounded_rectangle", need to install later version of Pillow.

Upgrade pillow with pip3 install --upgrade Pillow

Setting necessary permissions for ROS

To run ROS as non-root, must set permissions correctly via udev for several /dev files.

Add the following to /etc/udev/rules.d/99-ROS.rules

       KERNEL=="ttyS0", OWNER="root", GROUP="ros", MODE="0660"
       KERNEL=="spi", OWNER="root", GROUP="ros", MODE="0660"
       KERNEL=="i2c", OWNER="root", GROUP="ros", MODE="0660"
       KERNEL=="gpiomem", OWNER="root", GROUP="ros", MODE="0660"
       KERNEL=="mem", OWNER="root", GROUP="ros", MODE="0660"

Add new group to user account: sudo groupadd ros && sudo adduser <username> ros
Reload udev rules: sudo udevadm control --reload-rules && sudo udevadm trigger

Setting up I2C

First, run this command to check whether i2c is working for root: sudo i2cdetect -y 1. If this doesnt work, try replacing the 1 with a 0. If this works, replace the 1 with a 0 in all subsequent steps.
Now try for your user: i2cdetect -y 1. If the same matrix appears, all is good. Otherwise, run the following:

    sudo groupadd i2c
    sudo chown :i2c /dev/i2c-1
    sudo chmod g+rw /dev/i2c-1
    sudo usermod -aG i2c [INSERT YOUR USERNAME]

Reboot or logout and back in and then check if i2c is working by running i2cdetect -y 1. The matrix should now appear for your user.

Setting up SPI

Please run the code first before following these steps. If you do not receive an SPI permission error, there is no need to do the following SPI setup steps. Proceed if you receive an error

Run ls -la /dev/spidev* to list SPI devices
Then, run the following to give your user SPI permissions, repeating the last two lines for all SPI devices listed from previous command:

    sudo groupadd spi
    sudo usermod -aG spi <yourusername>
    sudo chown :spi <put the spi device name here>
    sudo chmod g+rw <put the spi device name here>

Try running the code again. If it works, reboot the device and run the code again immediately after logging in. If it still works after reboot, no need to continue, but it if does not, keep going below:
Run sudo nano /etc/systemd/system/spi-permissions.service and put the following into the file, saving and exiting afterwards:

    [Unit]
    Description=Set SPI Permissions
     
    [Service]
    ExecStart=/path/to/your/script.sh
    User=root
    Group=root
    Restart=on-failure
    RestartSec=5s
     
    [Install]
    WantedBy=multi-user.target

Now, run nano ~/startspi.sh and put the following into the file, saving and exiting afterwards. Note: If your SPI device names are different, please update them accordingly:

    #!/bin/bash
    sudo usermod -aG spi <yourusername>
    sudo chown :spi /dev/spidev0.0
    sudo chmod g+rw /dev/spidev0.0
    sudo chown :spi /dev/spidev0.1
    sudo chmod g+rw /dev/spidev0.1

Run the following in the terminal:
- sudo chmod +x /path/to/your/script.sh
- sudo systemctl daemon-reload
- sudo systemctl enable spi-permissions.service
- sudo systemctl start spi-permissions.service

SPI should now work across restarts

Setting up Voltage Monitoring

The voltage monitoring on this robot was done using the TLA2024IRUGT chip. Please install the required library to run it with pip3 install adafruit-circuitpython-tla202x

Setting up camera

Install required packages: sudo apt-get install ros-noetic-video-stream-opencv

Configuring web server

Install apache sudo apt-get install apache2
Start apache sudo /etc/init.d/apache2 start
Edit the apache conf to point to the Kelpie HTML files and allow access sudo nano /etc/apache2/sites-enabled/000-default.conf
- Change /var/www to home/{username}/DingoQuadruped/web_gui/
- Add in the directory directives to allow access
```
<Directory home/{username}/DingoQuadruped/web_gui>
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>
```
Restart apache sudo /etc/init.d/apache2 restart
Install ROS bridge sudo apt-get install ros-noetic-rosbridge-suite
Finally, the web server should be accessible on the local network at http://dingo:80/index.html

SD Card Backup

It's a good idea to backup the sdcard every so often. Here is how to do that on linux.

Take out the sdcard from the Raspberry Pi and mount it into another linux system.
Run these commands to backup/restore. Replace source/destination appropriately.
- Backup to file: sudo dd if=/dev/sdb of=~/kelpie_backup.img bs=4M status=progress
- Restore back to sdcard: sudo dd if=kelpie_backup of=/dev/sdb bs=4M status=progress

Servo Calibration

Help with getting the servos calibrated

Run the calibrate_servo.py file in the following path: kelpie_ws\src\kelpie_hardware_interface\scripts\calibrate_servo.py
For auto calibration, type auto, this will calibrate all the legs automatically, excluding the roll servos
For manual calibration, type the servo name (e.g. fr r for front right, roll), then follow the instructions to fine tune the servos
Type q to save the quit the calibration script

Running the code

Kelpie_Driver

The Kelpie_Driver should be started before any other code is launched on the Kelpie. It starts joystick control of the robot and allows joint and task space commands to be received from other code or controllers via command ROS topics, as long as joystick control is disabled. If enabled, joystick control will override any commands sent through the command topics. To launch it, run the following line: roslaunch kelpie kelpie.launch

Arguments are:

mode (0/1)
- 0: physical (default)
- 1: simulation
input_type (0/1):
- 0: PS4 controller (default)
- 1: keyboard
use_cam (0/1):
- 0: camera off (default)
- 1: camera on (Note that this is induces lag on a Pi4, recommend Pi 5)

With no arguments specified, it will assume a joystick controller is used for control and it will launch the hardware interface with IMU feedback disabled. No joint data will be published for WeBots to use to simulate the robot.

As an example of how the arguments can be used, if the code is to be run with keyboard control and the camera enabled, you would launch the driver with the following arguments: roslaunch kelpie kelpie.launch input_type:=1 use_cam:=1

When the code is running, the device that is ssh'd into the Kelpie quadruped, you can go to http://dingo:80/index.html to access the gui.

Kelpie Joystick Controls

The diagram above shows the mapping of joystick commands for the Kelpie. These instructions are based on a PS4 type controller. An alternative, more general description of joystick commands is below:

The Kelpie has two main states: Rest and Trot.

While in the TROT state: Left stick controls the robot's movement. Right stick controls the robot's tilt and turning. PID control only applies to the yaw.
While in the REST state: Left stick is disabled. Right stick controls the robot's gaze while staying in place. PID control can be toggled.

Buttons:

Joystick Control Toggle (L1 Button): Pause/Resume control from the joystick.
Gait Toggle (R1 Button): Toggles between trotting and resting modes.
PID Control Toggle (Square): Toggles PID control on/off

Movement: (Speed proportional to how far stick is moved)

Left Stick (Horizontal): Pushing left or right strafes the robot in that direction.
Left Stick (Vertical): Push up to move forward, down to move backward.

Gaze:

Right Stick (Horizontal): Pushing left or right turns the robot in that direction.
Right Stick (Vertical): Push up to raise front of robot, down to raise back of robot.

Orientation:

D-pad (Vertical): Pressing up or down adjusts the height of the robot.
D-pad (Horizontal): Pressing left or right tilts the robot in that direction.

Running the Simulation on WeBots

For Windows users (Native Linux users can skip this)

Install Windows Subsystem for Linux (WSL) for Ubuntu 20.04 by running wsl --install -d Ubuntu-20.04 in your preferred terminal
From Powershell, type in wsl (wsl -d Ubuntu-20.04 if you have multiple ubuntu versions), this will launch WSL and Ubuntu 20.04

Install Required Packages

Execute the following in the bash terminal:

sudo apt-get update
sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
sudo apt install curl
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
sudo apt-get update
sudo mkdir -p /etc/apt/keyrings
cd /etc/apt/keyrings
sudo wget -q https://cyberbotics.com/Cyberbotics.asc
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/Cyberbotics.asc] https://cyberbotics.com/debian binary-amd64/" | sudo tee /etc/apt/sources.list.d/Cyberbotics.list
sudo apt update
sudo apt install webots
sudo apt-get install ros-noetic-desktop-full ros-noetic-moveit
sudo apt-get install python3-rosdep
sudo rosdep init
rosdep update
sudo apt-get install ros-noetic-webots-ros ros-noetic-joy python3-pip
pip3 install transforms3d adafruit-circuitpython-servokit adafruit-circuitpython-bno055
sudo apt install python-is-python3

Setting Up the Simulation Environment

Source the ros files on the shell launch and other environment variables, don't forget to change the file path (make sure the path is WSL and not windows)

echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
echo "export KELPIE_WS=/mnt/windows/path/to/kelpie_ws" >> ~/.bashrc
echo "export WEBOTS_HOME=/usr/local/webots" >> ~/.bashrc
source ~/.bashrc

Set up the workspace

cd /path/to/kelpie_ws
catkin_make

Running the Simulation Environment

Run the kelpie launch file on a local ubuntu 20.04 environment.

cd /path/to/kelpie_ws
catkin_make
source devel/setup.bash
roslaunch src/kelpie/launch/kelpie.launch mode:=1

Open another terminal and run the webots launch file

source devel/setup.bash
roslaunch src/kelpie_webots/launch/webots_ros_python.launch

Running the Simulation as a Digital Twin

Connect to the kelpie and run it as described in Kelpie_Driver, in physical mode

roslaunch src/kelpie/launch/kelpie.launch mode:=0

Run the webots launch file on your local (Ubuntu!) computer

cd /path/to/kelpie_ws
catkin_make
source devel/setup.bash
export ROS_MASTER_URI=http://dingo.local:11311/
roslaunch src/kelpie_webots/launch/webots_ros_python.launch

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Kelpie Quadruped

Overview

How Kelpie ROS Network Works

Installation of Code

Natively

Additional Installation Steps

Bluetooth Setup

Wifi Setup

LCD Node Additional Setup

Setting necessary permissions for ROS

Setting up I2C

Setting up SPI

Setting up Voltage Monitoring

Setting up camera

Configuring web server

SD Card Backup

Servo Calibration

Running the code

Kelpie_Driver

Kelpie Joystick Controls

Running the Simulation on WeBots

For Windows users (Native Linux users can skip this)

Install Required Packages

Setting Up the Simulation Environment

Running the Simulation Environment

Running the Simulation as a Digital Twin

Files

README.md

Latest commit

History

README.md

File metadata and controls

Kelpie Quadruped

Overview

How Kelpie ROS Network Works

Installation of Code

Natively

Additional Installation Steps

Bluetooth Setup

Wifi Setup

LCD Node Additional Setup

Setting necessary permissions for ROS

Setting up I2C

Setting up SPI

Setting up Voltage Monitoring

Setting up camera

Configuring web server

SD Card Backup

Servo Calibration

Running the code

Kelpie_Driver

Kelpie Joystick Controls

Running the Simulation on WeBots

For Windows users (Native Linux users can skip this)

Install Required Packages

Setting Up the Simulation Environment

Running the Simulation Environment

Running the Simulation as a Digital Twin