# ASCII Aquarium on the Cheap Yellow Display: a live ESP32 fish tank > ASCII Aquarium renders an animated ASCII fish tank on the ESP32-2432S028R Cheap Yellow Display, flashed from a browser. Here is what the firmware does, how to install it, and where it stops being the right tool. **POWER-PILL/ASCII-Aquarium** — ASCII Aquarium turns your Cheap Yellow Display into an tiny animated ASCII fish tank. It renders a live aquarium scene with animated fish, bubbles, swaying seaweed, tap-to-feed food flakes, occasional octopus & seahorse visitors, selectable backgrounds, preferences, optional Wi-Fi clock sync, & More! - Repository: https://github.com/POWER-PILL/ASCII-Aquarium - Website: https://power-pill.github.io/ASCII-Aquarium/ - Stars: 437 · Forks: 47 - Language: C++ - License: not declared - Published: 2026-09-20 · Updated: 2026-09-20 · Language: en - Canonical page: https://hysenlabs.com/projects/power-pill-ascii-aquarium ## What ASCII Aquarium actually is, and who it is for ASCII Aquarium is firmware for the ESP32-2432S028R, the board widely sold as the Cheap Yellow Display. It turns the 320x240 ILI9341 panel into a small animated fish tank drawn with punctuation characters. The README is explicit that this is not a video loop: the aquarium is rendered live on the ESP32, with fish that wander, school, turn around, change brightness, avoid each other, and chase food when you tap the glass. The audience is narrow and specific. You need the physical board, a USB data cable, and a desktop or laptop running Chrome, Edge, or the latest Firefox. This is not a terminal program you install on Linux, macOS, or Windows, and it is not a screensaver. Several of the phrases people search for around this name point at desktop aquarium software; the project itself is embedded firmware for one family of ESP32 touchscreen boards. If you do not own that hardware, there is nothing here to run. What you get for the board is a scene with configurable fish population from 6 to 36, bubble count from 0 to 50, animated seaweed with adjustable sway, length, and randomness, and occasional octopus and seahorse visitors with selectable spawn rates. A touch settings menu covers Tank, Seaweed, Clock, and Background tabs. Settings persist through ESP32 Preferences, so the tank comes back the way you left it. ## The rendering and behaviour model behind the tank The README describes the fish as having multiple glyph species, varied colours, depth shading, smooth wraparound, schooling, wandering, and separation behaviour. Visitors are steered around, and fish steer around visitors and each other. That set of behaviours is the substance of the project: the interesting engineering is not drawing characters on a TFT, it is keeping a handful of autonomous agents from piling into one corner of a 320x240 grid. Feeding is the one interaction that changes the simulation rather than the display. Tapping the glass drops flakes, and nearby fish chase them down. The v2.20 release notes add a Timed events setting with auto feeding, which the notes say is useful with a beam splitter because you cannot tap the screen in that setup. That is a sensible admission: the primary input is a resistive touchscreen, and the moment you put glass or optics in front of it, the interaction model breaks. Rendering is layered. Backgrounds are separate from fish, which are separate from bubbles and seaweed, which are separate from the optional clock. The v2.39 notes add Auto Sky, a clock-driven background mode that slowly blends the gradient through sunrise, day, sunset, and night colours, with editable colour slots for each. Because the background is clock-driven, the Wi-Fi time sync and the background system are coupled: no time, no Auto Sky transitions. The README does not describe what Auto Sky falls back to when the clock is unset or Wi-Fi never connects, so treat that combination as unverified. ## Installing ASCII Aquarium with the web flasher The project ships a browser-based installer at the homepage, and the README calls it the easiest way to install. Before you start, the README lists three requirements: a supported CYD board connected by a USB data cable, Chrome, Edge, or latest Firefox on a desktop or laptop, and the Arduino IDE Serial Monitor closed if it was open. That last point matters, because an open serial monitor holds the port and the flasher will not see the board. Open the flasher page, click Flash ASCII Aquarium, choose the CYD serial port, and let the installer finish. The README gives no command-line equivalent, so there is no esptool invocation to copy here. The repository does contain User_Setup.h and User_Setup_Select_CYD.h at the top level, which are TFT_eSPI configuration headers for anyone building from source, but the README does not walk through a source build. For the two additional targets, the README says support has been added for the CYD2USB variant and that there is preliminary support for the JC3248w535 board, and it points at the same flasher page to flash either firmware. Preliminary is the operative word for the JC3248w535: expect less certainty there than on the original board. Once the tank is running, the hidden HUD controls cover setup, capture, Wi-Fi, settings, quick creature tests, respawn, and randomize. The README does not document the gesture that opens the HUD, so you will be looking at the on-screen behaviour rather than a written procedure to find it. If you want a clock, the Wi-Fi panel provides network scan, saved credentials, an on-screen keyboard, reconnect handling, and NTP time sync, with 12-hour and 24-hour formats and timezone selection. ## Screenshots, SD cards, and the reset caveat The board's optional SD card slot is used for BMP screenshots and frame sequence capture. This is the feature most likely to disappoint, because the README carries a note that in build 2.18 the CYD will need to be reset after taking screenshots or sequences. That is a documented rough edge, not a hidden one, and it tells you the capture path is not fully integrated with the render loop. Capture also depends on hardware the original board may or may not have populated. The README lists optional SD card support, so a board without a working card slot cannot use this feature at all. If your reason for flashing this firmware is to capture frames rather than to watch fish, the SD card is the first thing to confirm before you buy anything. The same caution applies to the display and touch controller. The firmware targets the ILI9341 panel and the XPT2046 resistive touchscreen. The README warns that other CYD-style boards may look similar but use different display, touch, or SD hardware. Because the project does not document a hardware detection or fallback path, a clone board with a different controller is a plausible source of a blank screen or a dead touch layer, and there is no troubleshooting section in the README to walk you out of it. ## Where ASCII Aquarium is the wrong choice The clearest limitation is the platform lock. ASCII Aquarium is firmware for the ESP32-2432S028R and two named variants. It is not a library you can call from your own sketch, and the README does not present it as one. If you want animated ASCII in a terminal on Linux, macOS, or Windows, or on a Raspberry Pi, this project does not address that at all, and the searches that mix this name with those platforms are looking for something else. The second limitation is the licence. The repository metadata does not state one, and the README does not discuss licensing. For a personal desk toy that is usually a non-issue. If you plan to ship a product around this firmware, or to redistribute a modified binary, you have no stated terms to rely on, and the absence of a licence file is itself the finding. The third is scope creep in the feature list. Between v2.20 and v2.39 the project added background gradients, ambient RGB lighting, light schedules, tap-to-wake, auto feeding, twenty ASCII clock fonts, rainbow colour cycling, and a rare Cthulhu octopus variant. That is a lot of surface area for one firmware image on a small board, and each addition is another path that a future change can break. The README documents the 2.18 screenshot reset bug but does not carry a general known-issues list, so regressions in the newer subsystems would not necessarily be visible before you flash. ## A real alternative: cava or a terminal ASCII renderer The honest alternative for someone who wants animated ASCII on a screen they already own is a terminal-based renderer such as cava, which draws audio spectrum bars as ASCII characters inside a terminal emulator. The difference in approach is fundamental. cava is a host program: it reads an audio source and writes characters to a terminal, and it runs on a general-purpose operating system with a real process scheduler and no memory ceiling worth worrying about. ASCII Aquarium is the opposite end of that trade. It has no host, no operating system, and no audio input; it owns the metal, drives a specific ILI9341 panel through TFT_eSPI, and reads a resistive touchscreen directly. That difference determines what each is good for. A terminal renderer gives you portability and zero hardware cost, but it stops when you close the terminal and it cannot live on a shelf. ASCII Aquarium gives you a self-contained object that keeps swimming with no computer attached, at the cost of requiring one exact board and a browser-based flash to change anything. If your interest is the simulation rather than the hardware, the terminal route gets you there faster. If your interest is a device that sits on a desk and reacts to a tap, the terminal route cannot do it. A second alternative worth naming is writing your own sketch. The repository ships User_Setup.h and User_Setup_Select_CYD.h, so the TFT_eSPI configuration for this board is visible and reusable. If you want a different scene on the same hardware, starting from those headers and the TFT_eSPI library is a legitimate path, and it avoids inheriting a feature set you did not ask for. ## Maintenance, releases, and what upgrading costs you The repository is not archived, and the last push was on 2026-07-19. Releases are frequent and version numbers do not follow a tidy scheme: v1.67 in May, v2.20 in June, v2.39 later in June. The README links detailed release notes for 2.20 and 2.39 as separate markdown files in the repository root. That is better documentation practice than a changelog buried in commit messages, and it means you can read what changed before reflashing. The upgrade cost is the settings model. Preferences persist on the ESP32, and the v2.20 notes describe a background system overhaul with new dithered gradients, new colours, and a smooth background option. When a subsystem is overhauled, persisted values from the previous version may not map onto the new one. The README does not document a migration path or a settings reset procedure, so if the tank looks wrong after an upgrade, the documented option is not there to help you. The same applies to rollback: the README does not document how to return to a previous firmware version, though the release notes files and the browser flasher are the two places to look. On licensing, there is nothing to reason about because nothing is stated. The repository metadata does not carry a licence identifier and the README does not mention one. If you need clear terms before redistributing or building on this code, that is a gap you have to resolve with the author, not something the repository answers. ## Conclusion Adopt ASCII Aquarium if you already own an ESP32-2432S028R, CYD2USB, or JC3248w535 board and want a desk toy that is rendered live rather than looped from video. Do not adopt it if you need a general-purpose graphics framework, if your board is a CYD-style clone with different display, touch, or SD hardware, or if you cannot accept that the licence is not stated in the repository. Verify two things first: that the web flasher page recognises your serial port with the Arduino IDE Serial Monitor closed, and that your board is the exact model named in the supported hardware list, because the README states other CYD-style boards may look similar but use different parts. ## FAQ ### Which boards does ASCII Aquarium support? The README names the ESP32-2432S028R Cheap Yellow Display as the primary target, with support added for the CYD2USB variant and preliminary support for the JC3248w535 board. It warns that other CYD-style boards may look similar but use different display, touch, or SD hardware. ### How do I install ASCII Aquarium on a CYD? The README recommends the browser flasher on the project homepage: connect the board with a USB data cable, use Chrome, Edge, or latest Firefox on a desktop or laptop, and make sure the Arduino IDE Serial Monitor is closed. Then open the flasher page, click Flash ASCII Aquarium, choose the serial port, and let the installer finish. ### Does ASCII Aquarium run on Linux, macOS, Windows, or a Raspberry Pi? No. The project is ESP32 firmware for the named CYD boards, and the README does not describe a desktop or Raspberry Pi build. The browser flasher runs on a desktop or laptop, but the aquarium itself runs on the board. ### How many fish and bubbles can the tank show? The README lists a configurable fish population from 6 to 36 and a configurable bubble count from 0 to 50, with animated seaweed that has adjustable sway, length, and randomness. ### Can ASCII Aquarium save screenshots? It can write BMP screenshots and frame sequence capture to an SD card, which the README lists as optional hardware support. The README also notes that in build 2.18 the CYD needs to be reset after taking screenshots or sequences. ## Sources - [Issues](https://github.com/POWER-PILL/ASCII-Aquarium/issues) - [POWER-PILL/ASCII-Aquarium on GitHub](https://github.com/POWER-PILL/ASCII-Aquarium) - [Project website](https://power-pill.github.io/ASCII-Aquarium/) - [README](https://github.com/POWER-PILL/ASCII-Aquarium/blob/main/README.md) - [Releases](https://github.com/POWER-PILL/ASCII-Aquarium/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/power-pill-ascii-aquarium