Open Duck Mini Runtime

This repository contains the runtime software for the Open Duck Mini, a small, open-source robotic duck. This guide will walk you through setting up the hardware and software to get your duck waddling.

Table of Contents

• Open Duck Mini Runtime
  • Table of Contents
  • Raspberry Pi Setup
    • Install Raspberry Pi OS
    • Setup SSH (If not setup during the installation)
    • System Updates and Dependencies
    • Enable I2C
    • Set the USB Serial Latency Timer
    • Motor Control Board udev Rules
  • Install the Runtime
    • Make a Virtual Environment and Activate it
    • Install the Repository
    • Xbox One Controller Setup
  • Hardware Configuration
    • Speaker Wiring and Configuration
  • Testing and Calibration
    • Test the IMU
    • Make your duck_config.json
    • Find the Joints Offsets
  • Run the walk !
  • Controls

Raspberry Pi Setup

These instructions are for setting up a Raspberry Pi Zero 2W.

Install Raspberry Pi OS

1. Download Raspberry Pi OS Lite (64-bit).

2. Follow the official instructions to install the OS on an SD card: Getting Started Guide.

3. Using the Raspberry Pi Imager, you can pre-configure your user, Wi-Fi, and SSH settings.

   

   Tip: Configure the Raspberry Pi to connect to your phone's hotspot for easy access anywhere.

Setup SSH (If not setup during the installation)

If you didn't enable SSH during the OS installation, you'll need a screen and keyboard for the initial boot.

1. Connect to a Wi-Fi network.
2. Enable SSH using this guide: Raspberry Pi Configuration.

Once SSH is enabled, you can connect to your Raspberry Pi remotely.

System Updates and Dependencies

Update your system and install the required packages:

sudo apt update
sudo apt upgrade
sudo apt install git python3-pip python3-virtualenvwrapper
# Optional for camera support
sudo apt install python3-picamzero

Add the following lines to the end of your .bashrc file to configure the virtual environment wrapper:

export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/Devel
source /usr/share/virtualenvwrapper/virtualenvwrapper.sh

Enable I2C

Use the Raspberry Pi configuration tool to enable I2C: sudo raspi-config -> Interface Options -> I2C

(TODO: Set to 400KHz?)

Set the USB Serial Latency Timer

Create a udev rule to set the latency timer for the USB-to-serial adapter:

sudo nano /etc/udev/rules.d/99-usb-serial.rules

Add the following line to the file:

SUBSYSTEM=="usb-serial", DRIVER=="ftdi_sio", ATTR{latency_timer}="1"

Motor Control Board udev Rules

(TODO)

Install the Runtime

Make a Virtual Environment and Activate it

mkvirtualenv -p python3 open-duck-mini-runtime
workon open-duck-mini-runtime

Install the Repository

Clone the repository and install it in editable mode:

git clone https://github.com/apirrone/Open_Duck_Mini_Runtime
cd Open_Duck_Mini_Runtime
pip install -e .

For Raspberry Pi 5: You may need to replace the GPIO library.

pip uninstall -y RPi.GPIO
pip install lgpio

Xbox One Controller Setup

1. Turn on your Xbox One controller and put it in pairing mode by long-pressing the sync button.

2. On your Raspberry Pi, run the following commands:

   bluetoothctl
   scan on
   

3. Wait for the controller to appear, then pair, trust, and connect to it:

   pair <controller_mac_address>
   trust <controller_mac_address>
   connect <controller_mac_address>
   

   The controller's LED should stop blinking.

4. Test the connection:

   python3 src/open_duck_mini_runtime/xbox_controller.py
   

Hardware Configuration

Speaker Wiring and Configuration

Follow this Adafruit tutorial for wiring the speaker: Adafruit MAX98357 I2S Class-D Mono Amp.

Note: For now, do not activate /dev/zero when prompted in the tutorial.

Testing and Calibration

Test the IMU

Run a basic test to ensure the IMU is working:

python3 src/open_duck_mini_runtime/raw_imu.py

To visualize the IMU data, run the server on the robot and the client on your computer:

# On the robot
python3 dev/hardware/imu_server.py

# On your computer
python3 dev/hardware/imu_client.py --ip <robot_ip>

Use ifconfig on the robot to find its IP address.

Make your duck_config.json

Copy the example configuration file to your home directory and rename it:

cp example_config.json ~/duck_config.json

This file allows you to configure features like expressions, IMU orientation, and joint offsets.

Find the Joints Offsets

This script helps you find the correct joint offsets for your robot. The offsets should be added to your duck_config.json file.

python3 tools/find_soft_offsets.py

Note: This step will be replaced in the future by flashing offsets directly to each motor's EEPROM.

Run the walk !

1. Download the latest policy checkpoint.
2. Copy the checkpoint file to your duck's home directory.
3. Run the walk by just runnning walk. (run walk -h to see the possible command line arguments):

Controls

• A: Pause/Unpause
• X: Turn on/off the projector
• B: Play a random sound
• Y: Turn on/off head control (experimental, use with caution)
• Left/Right Triggers: Control the left and right antennas
• LB (Hold): Increase walking frequency (sprint mode)