Bongo Cat ESP32 Installer

Bongo Cat

Bongo Cat is a cute digital pet that will type with you. It can show CPU, RAM, and your typing speed in words per minute as well as time. Bongo cat will type faster if you type faster, featuring adorable animations and expressions that bring joy to your desk. Now available as a cross-platform desktop app for both Windows and Mac! The hardware is open source, costs around $10 to build, and flashes in seconds with no soldering required.

Software Installation Instructions

⚠️ Choose the correct board size below - 2.4 inch or 2.8 inch display

2.4 Inch Display Board

  1. Connect your ESP32 board with 2.4 inch TFT display to your computer's USB port.
  2. Click the 'Connect' button below. This will only work in Google Chrome or Microsoft Edge.
  3. When prompted to choose a port, choose "USB Serial".
  4. Click 'Install Bongo Cat'.
Your browser doesn't support Web Serial. Please use Chrome, Edge, or Opera. HTTPS required for Web Serial. Please use a web server.

Most common board type

2.8 Inch Display Board

  1. Connect your ESP32 board with 2.8 inch TFT display to your computer's USB port.
  2. Click the 'Connect' button below. This will only work in Google Chrome or Microsoft Edge.
  3. When prompted to choose a port, choose "USB Serial".
  4. Click 'Install Bongo Cat'.
Your browser doesn't support Web Serial. Please use Chrome, Edge, or Opera. HTTPS required for Web Serial. Please use a web server.

Newer, larger display version

🔄 Inverse Colors Fix

⚠️ If your display shows inverted/wrong colors after flashing the regular firmware, use these fixed versions instead:

2.4 Inch Display (Inverse Colors Fix)

  1. Connect your ESP32 board with 2.4 inch TFT display that has color issues.
  2. Click the 'Connect' button below. This will only work in Google Chrome or Microsoft Edge.
  3. When prompted to choose a port, choose "USB Serial".
  4. Click 'Install Bongo Cat (Inverse Fix)'.
Your browser doesn't support Web Serial. Please use Chrome, Edge, or Opera. HTTPS required for Web Serial. Please use a web server.

⚠️ Use only if regular firmware shows wrong colors

2.8 Inch Display (Inverse Colors Fix)

  1. Connect your ESP32 board with 2.8 inch TFT display that has color issues.
  2. Click the 'Connect' button below. This will only work in Google Chrome or Microsoft Edge.
  3. When prompted to choose a port, choose "USB Serial".
  4. Click 'Install Bongo Cat (Inverse Fix)'.
Your browser doesn't support Web Serial. Please use Chrome, Edge, or Opera. HTTPS required for Web Serial. Please use a web server.

⚠️ Use only if regular firmware shows wrong colors

💡 How to know if you need the inverse fix: Flash the regular firmware first. If the colors look wrong or inverted on your display, then flash the appropriate inverse colors version.

All installations only work in Google Chrome or Microsoft Edge.

💡 Troubleshooting Tip: If the flashing takes more than 15 minutes or gets stuck at "Initializing", press and hold the BOOT button on your ESP32 board while using webflasher.

Desktop Application Download

After flashing your ESP32, you'll need the Bongo Cat desktop application to enable the interactive features. The new cross-platform Electron app communicates with your ESP32 to send typing data, system stats, and control animations. Now available for both Windows and Mac!

🪟 Windows Application

Legacy Windows installer with full functionality

📦 Download Windows Installer ZIP

Compatible with Windows 10/11

🍎 Mac Application (New!)

Cross-platform Electron app with the same great features

📱 Download Mac App

Compatible with macOS 10.14+

Setup Steps After Flashing:

Windows Setup:

  1. Download the BongoCat_Installer.zip file and extract it
  2. Run the BongoCat_Setup.exe installer from the extracted files
  3. The app will automatically find your ESP32 board and connect
  4. The app runs from the system tray - look for the Bongo Cat icon
  5. Start typing and watch your Bongo Cat come to life! 🎉

Mac Setup:

  1. Download the latest Bongo Cat Monitor app from the GitHub releases
  2. Open the downloaded .dmg file and drag the app to your Applications folder
  3. Launch the app from Applications (you may need to allow it in Security & Privacy settings)
  4. Connect your ESP32 to your Mac via USB cable
  5. In the app, select the correct USB port to connect to your ESP32
  6. Once connected, the app will communicate with your ESP32 via USB
  7. Start typing and watch your Bongo Cat come to life! 🎉

How to Use:

🖱️ System Access

Windows: The app runs from your system tray. Click the Bongo Cat icon to access options.
Mac: The app appears in your menu bar. Click the icon to access settings and controls.

System tray screenshot

⚙️ Settings

Right-click (Windows) or click (Mac) the icon to configure what information is shown and set sleep time.

Settings screenshot

🍎 Mac Troubleshooting

If the app won't open, go to System Preferences → Security & Privacy → General and click "Open Anyway" next to the blocked app warning.

🔗 USB Connection

Select the correct USB port in the app to connect to your ESP32. Make sure your ESP32 is connected to your computer via USB cable.

What the App Can Do:

  • 🎹 Typing Detection: Detects your keyboard activity and triggers adorable bongo animations
  • 📊 System Stats: Shows real-time CPU usage, RAM consumption, and Words Per Minute (WPM)
  • ⏰ Time Display: Shows current time on your ESP32 display
  • 🎨 Multiple Animations: Various cat expressions and speed-responsive animations
  • 💤 Sleep Mode: Cat goes to sleep when idle with customizable sleep timer
  • 🌐 Cross-Platform: Works seamlessly on both Windows and Mac with the same features
  • 📡 USB Communication: Connects to your ESP32 via USB for reliable data transfer

Animation Examples:

Normal Typing

Normal typing animation

Fast Typing

Fast typing animation

Sleeping

Sleeping animation