You, too, can run this adorable pixel aquarium on your ESP32 CYD

The ESP32 CYD Pixel Aquarium: A Budget-Friendly Marine Adventure

If you've been looking for a fun way to put your ESP32 Color Your Display (CYD) board to work, this pixel aquarium project delivers both visual appeal and technical learning opportunities. What started as a simple experiment has evolved into one of the more charming demonstrations of what's possible on these inexpensive microcontrollers.

What Is the ESP32 CYD?

The ESP32 CYD is a budget development board built around the Espressif ESP32 microcontroller, featuring a 240x240 pixel ILI9341 TFT display. At roughly $5-10 depending on your supplier, it's become a favorite among makers who want color graphics without breaking their parts budget. The board includes 4MB of flash storage and 320KB of RAM, which turns out to be just enough for clever pixel art animations when optimized properly.

The Aquarium Project Breakdown

The pixel aquarium project uses the TFT_eSPI library to handle graphics rendering, with custom sprite-based fish animations created using simple 8x8 and 16x16 pixel art frames. Water effects are simulated through carefully timed pixel manipulation, creating the illusion of gentle current movement across the screen.

Here's what makes this project particularly interesting from a development standpoint:

Memory Management: With only 320KB of available RAM, the project demonstrates efficient sprite handling. Fish animations are stored in program memory (PROGMEM) rather than RAM, and the display buffer is managed through direct pixel writes rather than full-screen buffering.

Frame Rate Optimization: Rather than redrawing the entire screen each frame, the project uses dirty rectangle tracking to update only the portions of the display that change. This approach maintains smooth animation while keeping CPU usage reasonable on the dual-core ESP32.

Color Palette Constraints: The ILI9341 display supports 65,536 colors, but the project limits itself to a carefully chosen 16-color palette that evokes a retro aquarium aesthetic while minimizing memory overhead.

Technical Implementation Details

The core loop handles three main systems:

1. Fish AI: Each fish has a simple state machine tracking position, velocity, and direction. Collision detection with tank walls uses bounding box checks, and random direction changes create natural-looking swimming patterns.

2. Bubble System: Bubbles rise using pre-calculated sine wave paths, with lifetime management to recycle bubble objects efficiently. The particle system uses a fixed-size array to avoid dynamic memory allocation.

3. Water Surface Effects: Animated ripples are triggered by fish movement near the surface, using a height map approach where wave amplitudes decay over time.

Getting Started

To build your own pixel aquarium, you'll need:

• ESP32 CYD board
• Arduino IDE with ESP32 support installed
• TFT_eSPI library (install via Library Manager)
• A USB cable for programming

After installing the libraries, configure your UserSetup.h file in the TFT_eSPI library folder to match the CYD pinout. The project typically uses SPI pins for display communication, with CS pin 5 and DC pin 4 by default.

The code itself is straightforward enough for beginners to modify. Adding new fish types involves creating additional sprite arrays and implementing new animation frames. The color palette can be adjusted in the global variables section to create different aquarium themes.

Why This Matters for Cross-Platform Developers

While the ESP32 CYD might seem like a niche platform, projects like this demonstrate several principles that translate directly to mobile and embedded development:

Resource-Constrained Optimization: The techniques used here mirror those needed for older Android devices or iOS devices with limited memory. Learning to profile and optimize for constrained environments builds skills applicable to mobile development.

Real-Time Graphics Programming: Unlike high-level frameworks that abstract away rendering details, this project works directly with pixel manipulation. Understanding these fundamentals helps when debugging performance issues in Unity, Flutter, or native UI frameworks.

Hardware Integration Patterns: The direct GPIO manipulation and SPI communication provide a foundation for understanding how mobile devices interact with sensors and displays at a lower level.

The Broader Maker Ecosystem

This project joins a growing collection of aquarium and aquarium-like simulations running on small displays. Similar projects include OLED-driven betta fish animations and e-ink aquarium displays that update periodically to conserve power. What distinguishes the CYD version is its balance of visual quality and performance on such a capable yet affordable platform.

The code is typically shared through maker forums like GitHub or specialized communities like the ESP32 forum. Many versions include customization options for different tank sizes, fish counts, or lighting effects, making it a solid starting point for those learning embedded graphics programming.

Moving Forward

For developers already working with cross-platform tools, this project offers a refreshing return to fundamentals. The constraints of the ESP32 CYD force creative problem-solving that often gets abstracted away in higher-level frameworks. Plus, there's an undeniable satisfaction in seeing those tiny pixel fish swim across a screen you built yourself.

The project also serves as an excellent introduction to real-time graphics concepts. Those familiar with game development will recognize elements like sprite batching and dirty rectangle updates, while mobile developers can observe how careful resource management enables smooth performance even on modest hardware.

Whether you're looking to understand embedded systems better or simply want a cute decoration for your desk, the ESP32 CYD pixel aquarium proves that charm and technical merit often go hand in hand. The source code is readily available through maker communities, and the modifications you can make are limited only by your imagination and the 240x240 pixel canvas before you.

For those interested in the technical details, the TFT_eSPI library documentation provides comprehensive information about display optimization, while the ESP32 Arduino core offers insights into the hardware capabilities that make projects like this possible.