Skip to content

ESPurr hardware

Custom RGB cat ears with fabric/fur over contoured LED flex PCBs, headband control electronics, microphones and experimental sensing. This repository contains the KiCad projects, local libraries and build/review tooling.

Hardware is still in development. See the plan for current status and next steps, and the design reference for hardware details.

Setup

Run commands from the repository root. Install KiCad 10, just, uv and KiKit 1.8.1 with a KiCad-compatible Python environment.

On macOS, install KiCad, then:

brew install just uv ruff librsvg
/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 -m pip install 'kikit==1.8.1'

Follow KiKit's platform instructions for its other dependencies. On Linux, use a Python with KiCad 10's pcbnew and wxPython available. Ensure kicad-cli and kikit are on PATH; the standard macOS KiCad app's CLI and Python are also discovered automatically.

Recipes use uv run --script scripts/hw.py with one driver dependency declaration. KiCad operations run in a separate compatible interpreter with pcbnew, wxPython and KiKit; an ordinary uv-managed interpreter does not provide those bindings.

Override tool paths with KICAD_CLI, KICAD_PYTHON and KIKIT when needed; each accepts one executable path without extra arguments. UV_PYTHON selects the driver interpreter independently. The public CLI requires Python 3.12+. The environment check records actual versions in build/reports/check.json.

just --list     # available commands
just check      # tools, project loading, libraries and inventory
just test       # all fast unit/safety tests; artifact checks stay explicit
just reports    # ERC/DRC on disposable copies; incomplete designs can fail

Generated projects, logs and reports stay under gitignored build/; workflows check that source files are preserved. Passing a check is not a fabrication release. Ear builds and board previews have their own setup/usage guides linked below.

For Python editing, use the recommended VS Code extensions and Ruff. Required scoped lint/format checks are in the working rules.

Artwork attribution

ESPurr's physical ear shape is adapted from MiniStudioo's DIY kitten/cat ears pattern. Some curves and shapes are reused in the PCB design files with the creator's permission. See artwork provenance for redistribution boundaries.