OpenCat Quadruped Robot

OpenCat‑Quadruped‑Robot – Technical Briefing

Clone (verbatim) git clone https://github.com/moses-y/OpenCat-Quadruped-Robot

The Problem

This repository is a portfolio of five semi‑independent projects (ModuleTests, src, serialMaster, pyUI, OpenCatPythonAPI) that together form an open‑source quadruped‑robot framework. There is no single entry point, no shared build pipeline, and no lockfile for the Python dependencies. A contributor who clones the repo and tries to run a demo faces an ad‑hoc set of install steps, missing test coverage, and large binaries that inflate clone size.

What This Does

OpenCat supplies low‑level control for four‑legged robots: servo timing, IMU integration, and gait coordination. The code base is split into distinct domains:

The React tag detected by the scanner appears only in the pyUI front‑end fragments; the bulk of the functionality is C/C++ firmware and Python glue code.

Key files and their responsibilities (derived from the internal call graph):

• OpenCatPythonAPI/requirements.txt – declares pyserial, numpy etc.; no lockfile → non‑reproducible builds.
• serialMaster/SerialCommunication.py – opens the serial port without a context manager (resource‑safety finding).
• pyUI/Debugger.py – open(...) not wrapped in with (resource‑safety finding).
• pyUI/commonVar.py – same pattern (resource‑safety finding).

The import graph resolves 27 internal modules with zero import edges and no circular dependencies, indicating each project can be built/understood in isolation.

How It Is Wired

Execution flow depends on which sub‑project you target:

The most connected module according to the measured graph is OpenCatPythonAPI/demos/BittleHitKeyboard (Ca 0, Ce 0), i.e., a leaf demo with no importers or importers. No hubs or cycles exist, so changing one component does not automatically ripple through the others—each project must be wired independently.

How To Use It

Setup

# 1️⃣ Clone
git clone https://github.com/moses-y/OpenCat-Quadruped-Robot
cd OpenCat-Quadruped-Robot

# 2️⃣ Python API dependencies (OpenCatPythonAPI)
python -m venv .venv && source .venv/bin/activate
pip install -r OpenCatPythonAPI/requirements.txt   # pyserial, numpy

No lockfile is present; pin versions manually if reproducibility is required.

Configuration

• No environment variables or secret keys are required for the basic demos.
• For serial communication, ensure the correct port is selected (e.g., /dev/ttyUSB0 on Linux, COM3 on Windows).

Running a demo

# Example: keyboard‑controlled Bittle demo
python OpenCatPythonAPI/demos/BittleHitKeyboard.py

The script opens the serial port, sends posture commands, and displays real‑time joint angles in the console.

Building firmware (Arduino)

# Install Arduino IDE, then open any *.ino under ModuleTests/ or src/
# Use “Upload” to target the NyBoard (ATmega328P) or an ESP32 board.

Real‑World Use

A graduate‑level RL lab can use the OpenCatPythonAPI to script gait experiments on a Bittle X robot. The researcher writes a Python controller that calls serialMaster/SerialCommunication.send() to transmit way‑points; the robot’s firmware (C++ in src/) converts those way‑points into servo pulses. The loop runs at ~100 Hz, allowing reinforcement‑learning policies to be evaluated on hardware without custom driver code.

Code Health & Issues

Measured findings (static analysis, 77 total)

SDLC observations (structure‑driven)

• Tests present: yes (78 test files) but no CI to run them.
• CI: GitHub Actions configured? No explicit workflow found.
• Dockerfile: absent – no containerised build.
• Licence: present (LICENSE file).
• Lockfile: absent (Python dependencies).
• Committed secrets: none detected.

The Bottom Line

OpenCat‑Quadruped‑Robot is a collection of five focused projects that together deliver a capable quadruped‑control framework. The C++ firmware and Python API are functional and well‑structured for their individual scopes, but the repo lacks a unified build/test pipeline, a dependency lockfile, and basic CI. It is well‑suited for educators, hobbyists, and researchers who are comfortable wiring their own serial/Arduino workflows, but teams requiring reproducible CI/CD or robust test coverage will need to add those layers themselves.

If you need a ready‑to‑run robot platform with out‑of‑the‑box CI, consider the upstream PetoiCamp/OpenCat-Quadruped-Robot (5200 ⭐) which provides a more mature monorepo structure.