OpenCat-Quadruped-Robot Documentation

An open source quadruped robot pet framework for developing Boston Dynamics-style four-legged robots that are perfect for STEM, coding & robotics education,...

4,796 stars C++ C++ 1 file · ~7,249 tokens #ai#arduino#block-coding#education#iot#legged-robot#quadruped#quadruped-robot-gaits
RAW Doc

File: README.md

OpenCat — Open-Source Quadruped Robot Framework

On current-gen hardware (Bittle X, Nybble Q) or starting fresh? This repo covers the legacy NyBoard platform. Head to OpenCatESP32 for current hardware and active development, or buy Bittle X on Amazon.

🚀 Quaddle — Petoi's newest OpenCat-lineage quadruped — launches on Kickstarter August 2026. Reserve your spot → (details below)

OpenCat is an open-source Arduino and Raspberry Pi-based framework for building and programming quadruped robots. Developed by Petoi, the maker of futuristic programmable robotic pets, it's the framework behind two mini robot kits: the Bittle robot dog and the Nybble robot cat.

The framework handles the hard parts — gait coordination, servo control, IMU integration — so you can focus on what you're actually building on top of it.

Coming Soon: Quaddle mini robot dog

Quaddle is Petoi's newest quadruped, launching on Kickstarter August 2026 — a mini desk robot built on the same OpenCat lineage as Bittle and Nybble. What makes it worth a look: it's a full quadruped running on just 4 servos instead of the usual 8–12, which forces genuinely different gait-design and leg-coordination solutions to still get all four legs walking, running, and balancing. Its servos are also position-feedback — readable, not just drivable — which is what makes Puppet Mode possible: hand-guide the legs and record a motion directly, no code required to capture a new behavior. We'll also share 3D-printable shells and mounts for customization. Same open platform this repo already supports for gait research, RL, and sim2real work — a hands-on physical AI platform, not a toy version of the idea.

Source code is not yet public. It's an upgraded version of the OpenCat project. The ESP32-S3 code structure is similar to this repo and closer to OpenCatESP32, which already powers thousands of Bittle X and Nybble Q robots in the field. We plan to open source it before Quaddle delivery. Watch this repo and r/petoi for the announcement, or reserve a spot to get notified at launch.

About the Project

Inspired by Boston Dynamics' Spot, Dr. Rongzhong Li started OpenCat in his dorm at Wake Forest University in 2016. The goal was straightforward: make agile quadruped robots affordable and hackable enough for researchers, educators, and makers — not just well-funded labs.

Since then:

  • 30,000+ robots shipped, cumulative across all channels
  • 60+ countries
  • $1M+ raised across two prior Kickstarter and Indiegogo campaigns
  • 20+ academic papers cite the platform — see Research Spotlight
  • One of the most-starred open-source quadruped robot projects on GitHub

OpenCat is now deployed across two robot platforms and used in K-12 schools, university research labs, maker spaces, and independent projects worldwide.

Current Hardware

The original Bittle and Nybble mini robots (NyBoard/ATmega328P) are discontinued but still fully supported by this codebase. This repo is the right place for NyBoard users; for ESP32/BiBoard see OpenCatESP32.

What the Framework Gives You

  • Multi-language: C/C++, Python, block-based coding
  • Open hardware + software: fork, modify, extend — no vendor lock-in
  • Arduino + Raspberry Pi native: works with the tools you already use
  • Sensor integration: cameras, touch, IMUs, ultrasonic, etc. — clip and go
  • Sim-to-real: experiment reinforcement learning models on an affordable robot
  • ROS compatible: SLAM, navigation, and perception pipelines documented by the community

Whether you're teaching robotics programming for the first time, building a weekend hackathon project, or running a graduate-level embodied robotics experiment, the platform scales.

What the Community Has Built

Users have shipped real robotics projects across AI, Raspberry Pi, and research — a few highlights:

Academic and research use cases: Research Spotlight

Hardware

This repo targets the NyBoard — a customized Arduino board based on ATmega328P. It coordinates up to 12 high-performance servos for walking, running, jumping, and backflipping.

Extend with:

For ESP32/BiBoard (current-gen hardware), see OpenCatESP32.

Setup

Full documentation: Petoi Doc Center
The following steps give you a brief walk-through, but may miss detailed tips and illustrative pictures.

1. Clone the repo

Remove the -main (or branch name) suffix from the folder after downloading.

2. Open OpenCat.ino — select your robot and board

cpp
#define BITTLE    // Petoi 9 DOF robot dog: 1x on head + 8x on leg
//#define NYBBLE  // Petoi 11 DOF robot cat: 2x on head + 1x on tail + 8x on leg

//#define NyBoard_V0_1
//#define NyBoard_V0_2
#define NyBoard_V1_0
//#define NyBoard_V1_1

3. Enter configuration mode

Comment out #define MAIN_SKETCH, upload, follow serial prompts.

cpp
// #define MAIN_SKETCH

4. (Optional) Auto-init

#define AUTO_INIT skips prompts and auto-calibrates IMU — handy for repeated flashing.

5. Upload

Plug USB uploader into NyBoard, install driver if needed, hit upload (→) in Arduino IDE.

6. Serial Monitor

Set to no line ending and 115200 baud rate.

7. Reset joint offsets

text
Reset joint offsets? (Y/n)
Y

8. IMU calibration

text
Calibrate the IMU? (Y/n):
Y

Place the robot flat on a table. 6 long beeps → reads sensor data → saves offsets → beeps when done. Close Serial Monitor when Ready! appears.

9. Switch to main sketch

cpp
#define MAIN_SKETCH

Uncomment and re-upload.

10. Joint calibration

Boot with one side up to enter calibration mode, or calibrate directly via Serial Monitor.

11. Optional: Petoi app

Plug in Bluetooth dongle for a friendlier calibration UI:

See the calibration guide and app guide.

12. Start building

Infrared remote, Petoi app, Python, or Serial Monitor. Full play guide →

Education

OpenCat shows up in AI robotics education across K-12 programs, community colleges, university labs, and maker spaces — hands-on physical AI teaching that goes beyond screen-based coding exercises:

Community & Discussion

  • r/OpenCat — firmware code, framework hacking, extending and porting OpenCat
  • r/Petoi — hardware Q&A, builds, quadruped coding, curriculum, 3D-printed parts, general discussion

Resources

Follow the project: YouTube · Twitter · Instagram · Facebook · LinkedIn

The legacy OpenCat repository is archived and no longer maintained.

File: OpenCatPythonAPI/demos/Readme.md

Test the functions of the API Interface:

  • allSkills.py
  • testSkills.py
  • ardSerialExample.py
  • petoiRobotExample.py

The API application examples :

  • hlw.py
  • climbCeiling.py
  • moveBySteps.py
  • BittleHitKeyboard.py

File: pyUI/README.md

Petoi Desktop App

The source codes are written with Tinker in Python3

The major function modules are the Firmware Uploader, Joint Calibrator, and Skill Composer.

UI.py is the general entry for all the modules:

  • UI.py

-> FirmwareUploader.py

-> Calibrator.py

-> SkillComposer.py

translate.py provides multi-language support for the UI. You may help to translate the UI into your language.

Before running the app, you need to use the included USB adapter or the Bluetooth dongle to connect to a Petoi robot.

Pre-compiled binaries

You can download the pre-compiled binaries.

Windows users:
Double-click the exe file to run the app. Keep all the files in the Win folder when moving the app.

Mac users:
Double-click the dmg file and drag the app to the Application folder. Go to the Application folder and right-click the Petoi icon. Hold the shift key, then click Open.

Run the app from the Terminal

In the case of compatibility issues, or if you want to modify the source and test, you can also run the code from the Terminal.

The Terminal is a built-in interface on Mac or Linux machines. The equivalent environment on Windows machines is called the Command-Line Tool (CMD).
It's recommended that you install Anaconda to manage your Python environment. It can also provide the Powershell as a Terminal for older Windows machines.

Depending on your existing Python configuration, you may need to upgrade to Python3 and install the following libraries:

  • pyserial
  • pillow

You can install them by entering pip3 install pyserial pillow in the Terminal or use the package manager in Anaconda.

To run the code:

  1. In the Terminal, use the cd command to navigate to the OpenCat/pyUI/ folder. You can use the Tab key to auto-complete the path name.
  2. After entering the pyUI/ folder, enter ls and ensure you can see the UI.py and other python source codes listed.
  3. Enter python3 UI.py.

File: Resources/NyBoard/boardManager/README.md

Arduino IDE Board Manager

Adds the NyBoard board definition through the Arduino 1.6.4 (and later) board manager rather then editing boards.txt directly as described at https://github.com/PetoiCamp/OpenCat/wiki/Software-setup.

Usage

  1. Open the Arduino IDE application

  2. Open the Preferences... panel

  3. In the Additional Boards Manager URLs field, add https://raw.githubusercontent.com/PetoiCamp/OpenCat/master/Resources/NyBoard/boardManager/package_petoi_nyboard_index.json. If there are already URLs listed in this field, separate them with commas or click on the icon next to the field to open up an editor and add this URL to a new line.

  4. Click on the OK button to close the Preferences... panel (you may need to do this for the Additional Boards Manager URLs editor first, if you opened it up in the previous step)

  5. Open the Boards Manager... window with the Tools -> Board: XXXX -> Boards Manager... menu item.

  6. In the Filter your search... field, type NyBoard

  7. Select the entry and click on Install

  8. Click on the Close button

  9. Select ATmega328P (5V, 20 MHz) NyBoard from the Tools -> Board: XXXX menu and enjoy!

Updating the Board Definition

This section should not be necessary for most users and is included only for reference. As this is my first foray into using the Boards Manager, these steps may change slightly as necessary and I will try to keep this updated for reference.

  1. Any additions to the NyBoard-0.1 directory or changes to NyBoard-0.1/boards.txt require the following additional steps (update version numbers as appropriate):

A. The archive file NyBoard-0.1.x.tar.bz2 needs to be rebuilt

text
i. Mac or Linux, use: `tar -cjf NyBoard-0.1.x.tar.bz2 NyBoard-0.1`

ii. *TBD* need Windows equivalent

B. Update pacakge_petoi_nyboard_index.json as follows:

text
i. Update the `"version"` field to match the new version number (e.g. "0.1.x")

ii. Update the `"url"` and `"archiveFileName"` fields to match the new archive name.

iii. Update the `"size"` field to match the new archive file size

iv. Update the `"checksum"` field to match the new archive file

  a. Mac or Linux use: `openssl dgst -sha256 NyBoard-0.1.x.tar.bz2` to get this value

  b. *TBD* need Windows equivalent

C. Alternatively, if you wish to keep multiple versions of the board definition around, you can copy the entire entry in "platforms" (lines 12 - 31), add a comma after the closing brace of the last entry in "platforms", paste the copy to the next line (before the closing bracket) and make the changes in B to the new entry.

  1. Changes to the other informational fields of pacakge_petoi_nyboard_index.json should not require rebuilding the archive or modifying the file size or checksum values.

Reference

File: serialMaster/README.md

serialMaster User Guide

Preparation

  1. Install python (version≥ 3.6, such as Anaconda3-5.2.0-Windows-x86_64.exe)

  2. Install pyserial library (version 3.5)

Run script

The script program will automatically identify the serial port number at the very beginning of the run, and complete the connection.

Generally, when using a USB adapter to connect to Nybble (or Bittle), there is only one serial port number:

When using the Bluetooth module, there are two serial port numbers:

Open Terminal (such as Anaconda Prompt), enter the path where the script is located (***\serialMaster), you can use the following command to run the script:

Method 1: Run the ardSerial.py

***\serialMaster>python3 ardSerial.py kbalance

Parameters: kbalance is a serial port command representing Nybble (or Bittle) skills.

Of course, you can also run this script without any parameters:

***\serialMaster>python3 ardSerial.py

When the system recognizes that there are multiple serial port numbers, the script will print out the following prompt message at the very beginning of the run:

If there is no response after you input the serial command in the terminal, you should close the terminal first, then change the value of "bluetoothPortIndex" in the ardSerial.py (line:128)to connect to another blue tooth serial port, then reopen the terminal and rerun the script.

When the script formally starts running, the following prompt information is printed out:
You can type 'quit' or 'q' to exit.

Next, you can enter serial port commands in Terminal to control Nybble (or Bittle) to do various interesting actions e.g.

kbalance # Command to control Nybble(or Bittle) to stand normally

m 0 -30 0 30 # Command to control Nybble(or Bittle) head to swing left and right

Method 2: Run a custom script, e.g. example.py

***\serialMaster>python3 example.py

The list testSchedule in example.py is used to test various serial port commands. Run the following script code to see the execution effect of each serial port command in the list:

for task in testSchedule:
wrapper(task)

You can also refer to the content of the stepUpSchedule list (in***\serialMaster\demos\stepup.py), write a list of behaviors according to your actual needs, and realize your creativity.

Note: When running the scripts under the path "*\serialMaster\demos"**, you must first use the "cd demos" command to enter the path where the scripts are located (\serialMaster\demos), and then use the python3 command to run the script. e.g.
***\serialMaster\demos>python3 stepup.py

Explanation of the serial port commands in the listtestSchedule:

['kbalance', 2]

  • 'kbalance' indicates the command to control Bittle to stand normally
  • 2 indicates the postponed time after finishing the command, in seconds

['m', [0, -20], 1.5]

  • m indicates the command to control the rotation of the joint servo
  • 0 indicates the index number of joint servo
  • -20 indicates the rotation angle (this angle refers to the origin, rather than additive) the unit is degree
  • 1.5 indicates the postponed time after finishing the command, in seconds. It can be a float number

['m', ['m', '0', '45', '0', '-45', '0', '45', '0', '-45'], 2]

Using this format, multiple joint servo rotation commands can be issued at one time, and these joint servo rotation commands are executed SEQUENTIALLY, not at the same time.
The meaning of this example is: the joint servo with index number 0 is first rotated to the 45 degree position, and then rotated to the -45 degree position, and so on. After these motion commands are completed, the next command will be executed after a 2-second delay.

['M', ['M', '8', '-15', '9', '-20'], 2]

Using this format, multiple joint servo rotation commands can be issued at one time, and these joint servo rotation commands are executed AT THE SAME TIME.
The meaning of this example is the joint servos with index numbers 8, 9 are rotated to the -15, -20 degree positions at the same time. After these motion commands are completed, the next command will be executed after a 2-second delay.

['d', 2]

  • d indicates the command to put the robot down and shut down the servos
  • 2 indicates the postponed time after finishing the command, in seconds

['c', 2]

  • c indicates the command to enter calibration mode
  • 2 indicates the postponed time after finishing the command, in seconds. After these motion commands are completed, the next command will be executed after a 2-second delay.

['c', [0, -9], 2]

  • c indicates the command to enter calibration mode
  • 0 indicates the index number of joint servo
  • -9 indicates the rotation angle, the unit is degree
  • 2 indicates the postponed time after finishing the command, in seconds

Using this format, you can enter the calibration mode to calibrate the angle of a certain joint servo.
Note: If you want the correction value in this command to take effect, you need to enter the "**s"**command after executing this command.
The meaning of this example: the joint servo with serial number 0 rotates -9 degrees. After these motion commands are completed, the next command will be executed after a 2-second delay.

['i', [8, 50, 9, 50, 10, 50, 11, 50, 0, 0], 3]

  • i indicates the command to rotate multiple joint servos at the same time
  • 8, 9, 10, 11, 0 indicate the index numbers of joint servos
  • 50, 50, 50, 50, 0 indicate the rotation angle (this angle refers to the origin, rather than additive ), the unit is degree
  • 3 indicates the postponed time after finishing the command, in seconds

['l', [20, 0, 0, 0, 0, 0, 0, 0, 45, 45, 45, 45, 36, 36, 36, 36], 5]

  • l indicates the command to control all joint servos to rotate at the same time (currently the command supports 16 degrees of freedom, that is, 16 servos)
  • 20,0,0,0,0,0,0,0,45,45,45,45,36,36,36,36 indicate the rotation angle of each joint servo corresponding to 0-15 (this angle refers to the origin, rather than additive), the unit is degree
  • 5 indicates the postponed time after finishing the command, in seconds

['b', [10, 255], 2]

  • b indicates the command to control the buzzer to beep
  • 10 indicates the music tone
  • 255 indicates the lengths of duration, the value range is 0~255
  • 2 indicates the postponed time after completing the pronunciation, in seconds

['b', ['b', '14', '90', '14', '90', '21', '90', '21', '90', ‘23', '90', '23', '90', '21', '180'], 5]

  • b indicates the command to control the buzzer to beep
  • '14', '14', '21', '21', ‘23', '23', '21' indicate the music tones
  • '90', '90', '90', '90', '90', '90', '180' indicates the lengths of duration
  • 5 indicates the postponed time after the music melody is played, in seconds

Using this format, multiple tone pronunciation commands can be issued at one time, and a simple melody can be played.
The meaning of this example is: play a simple melody, and delay 5 seconds after the music melody is played.

For the description of other serial port commands, please refer to Chapter 7 of the Petoi Bittle User Manuals:
7 🕹 Play with Bittle

Please help Nybble and Bittle find their sparks. Wish you have fun!

File: SkillLibrary/Readme.md

New skill library for OpenCat robots

This folder is a collection of new skills that can be performed by OpenCat robots, such as Nybble and Bittle.

There are several ways to perform the new skills:

  1. Import a skill file through the Petoi Desktop app -> Skill Composer. It will be saved to the robot's memory and overwrite the last sent skill. Use token 'T' to call the skill. You can send 'T' through the serial command or assign it to one of the infrared remote key.

  2. Insert it in OpenCat/serialMaster/example.py.

  3. Integrate the skill directly into the OpenCat main code. But it requires a deeper understanding of the data structure.

You can check the Video Tutorial and create new skills with the Skill Composer.

You are welcome to share your skills by sending merge requests to this folder.

text
# Name(Model-ShortSkillName)
Note: XXXXXXX
Model: XXXXXX
Creator: XXX
Country: XXX
Date: Sep 9, 2022
# Demo Video link
# Token: X
# Data
{
  skill data array
  .....
}

The data array must be surrounded by {}. The skill composer will use the first pair of {} to parse the array, so you don't need to worry about the commenting information.

File: src/Adafruit-PWM-Servo-Driver-Library/README.md

Adafruit PCA9685 PWM Servo Driver Library

This is a library for our Adafruit 16-channel PWM & Servo driver, shield or FeatherWing

Pick one up today in the adafruit shop!

These drivers use I2C to communicate, 2 pins are required to interface.

Adafruit invests time and resources providing this open source code, please support Adafruit and open-source hardware by purchasing products from Adafruit!

Written by Limor Fried/Ladyada for Adafruit Industries. BSD license, check license.txt for more information.

All text above must be included in any redistribution

File: src/MemoryFree/README.md

This is the excellent MemoryFree library from http://www.arduino.cc/playground/Code/AvailableMemory.

I am hosting it here so there is a quick and easy way to pull it down.

(20 Mar 2015) Repository updated with code from http://playground.arduino.cc/code/AvailableMemory

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#ai Browse ai catalog → #arduino Browse arduino catalog → #block-coding Browse block-coding catalog → #education Browse education catalog → #iot Browse iot catalog → #legged-robot Browse legged-robot catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →