Shivam Kumar

Category · Hardware

CatEye

An ESP32-C3 desk companion that turns touch, motion, light, battery state, cloud commands, and browser music into animated OLED eyes and vibration feedback.

Live companion portal · Source repository · Architecture

Status: The portal is live, but the complete experience needs the custom ESP32 hardware on the same local network. Repository access may be required.

C++ Arduino ESP32 U8g2 Chrome JavaScript Vercel

System architecture

flowchart LR
    U[User] --> P[Chrome extension]
    T[Browser-tab audio] --> A[Web Audio analyser]
    P --> B[Extension service worker]
    B --> A
    B --> H[ESP32 web server]
    A -->|Beat data| H
    S[Touch, motion, light, battery] --> F[Firmware state engine]
    H --> F
    F --> E[OLED eyes]
    F --> M[Vibration motor]
    F <-->|Status and commands| V[Live portal API]

The portal appears only as an API here because its source is not included in the reviewed repository.

Data flow

  1. The extension captures audio from the current browser tab after a user click.
  2. It finds and verifies CatEye on the local network, then starts an offscreen audio analyser.
  3. The analyser sends energy, beat, and tempo data to the device every 100 ms.
  4. Firmware combines music data with sensors and cloud commands to animate the eyes and vibration motor.

Engineering highlights and trade-offs

  • Expressive state engine: Twenty-four eye states respond to blinks, tilt, music, light, touch, charging, sleep, and time of day.
  • Simple firmware loop: Sensors, networking, animation, and haptics share one timed loop. This avoids thread complexity, but slow network calls can delay other work.
  • Controlled music traffic: Audio is measured frequently but network updates are limited to about ten per second for the small ESP32 server.
  • Local discovery: The extension tries saved addresses, the portal, mDNS, and a local-network scan. This improves setup but requires broad network access.
  • Hardware-aware power use: Sensor smoothing reduces false changes, while soft sleep turns off Wi-Fi, display, and vibration but keeps touch-based wake available.

Runtime cadence

The firmware targets 16 ms animation frames; the extension analyses audio every 25 ms, sends beat data every 100 ms, and polls the portal every 20 seconds.