p3a — Pixel Art Player

p3a is a Wi-Fi pixel art player built on the ESP32-P4. It's a 4-inch smart art frame that plays animated artworks ("gifs") from Makapix Club (a pixel art social network), from Giphy, and your own files—all from one tiny device you can control via touchscreen, web browser, REST API, or securely from anywhere through Makapix Club's MQTTS backend.

Join the community: Connect with other p3a users and discuss pixel art on the Makapix Club Discord.

Photos

Quick start

Get the hardware:
- Waveshare ESP32-P4-WIFI6-Touch-LCD-4B
- microSD card
- USB-C cable
- a small screwdriver
Insert the microSD card: This requires unscrewing the back plate
Flash the firmware: Visit the p3a Web Flasher — just connect your device and click to flash. No software installation needed. See the flashing guide for alternative methods.
Connect to Wi-Fi: On first boot, connect to the p3a-setup network and visit http://p3a.local/ to configure your Wi-Fi
Register it at Makapix Club: Visit the settings page at http://p3a.local/ and follow the instructions
Play art on it: Add a Giphy API key to get trending GIFs, browse https://makapix.club/ to send artworks, or copy your own files via USB

Note: The initial flash requires USB and a laptop or desktop (does not work on a smartphone). After that, all updates are wireless via the web UI.

For detailed usage instructions, see HOW-TO-USE.md.

Features

Makapix Club Integration

Play artworks and channels: Play individual artworks or entire channels (e.g., "Promoted Artworks", "Recent Artworks") directly from Makapix Club to your p3a
4 ways to control: Touchscreen, local web UI at http://p3a.local/, REST API, or remotely via Makapix Club's secure MQTTS (MQTT over TLS) backend
Cloud connectivity: Register your device at makapix.club to unlock remote control from anywhere
Join the community: Connect with other p3a users and discuss pixel art players on the Makapix Club Discord
Coming soon: Send a "like" to the artwork by touching the screen, swipe up to view artwork comments from the Makapix community

Giphy Integration

Trending GIFs on your desk: p3a fetches trending GIFs directly from the Giphy API and plays them in a continuous loop — animated memes, reactions, and pop culture moments cycling on your display all day long
Configurable content: Choose your preferred rendition size, file format (WebP or GIF), and content rating (G through R) from the built-in Giphy settings page
Automatic refresh: p3a periodically checks Giphy for fresh trending content so the feed stays current without any manual intervention
Mix and match: Combine Giphy channels with Makapix artwork channels in the same playset for a varied, ever-changing display

Seamless Playback

Freeze-free, gapless playback: Robust multi-buffer rendering handles animations smoothly, even with corrupt or problematic files
Full format support: Animated WebP and GIF, and still PNG all with transparency and alpha channel support, plus hardware-accelerated JPEG support
Smart upscaling: Giphy content is upscaled with hardware-accelerated bilinear interpolation (PPA) for smooth results, while pixel art from Makapix and local files uses nearest-neighbor scaling to preserve crisp pixel edges
Aspect ratio preservation: Non-square artworks display without distortion, properly centered with configurable background color

Control & Customization

Touch controls: Tap to change artwork, swipe to adjust brightness, rotate with two fingers
Screen rotation: Rotate the display 0°, 90°, 180°, or 270° via touch gesture or web API
Web interface: Full device control from any browser at http://p3a.local/ (only accessible in LAN, not Internet)
Over-the-Air updates: After initial USB flash, update firmware wirelessly via the web UI with automatic rollback protection

Hardware & Connectivity

USB access: Connect via USB-C to access the microSD card as a storage device. Copy you own private, offline files to p3a
Auto co-processor updates: p3a automatically flashes the ESP32-C6 Wi-Fi 6 co-processor firmware when needed
PICO-8 Monitor: Stream PICO-8 games to the display via Wi-Fi

Over-the-Air Updates

After the initial firmware flash via USB-C cable, all subsequent updates can be installed wirelessly. p3a automatically checks for firmware updates from GitHub Releases, and you can install them directly from the web interface.

Update features:

Wireless updates — no need to reconnect USB after the first flash
Automatic checks every 2 hours (or check manually via web UI)
One-click install from the web interface at http://p3a.local/ota
Progress display on both the device screen and web interface
Automatic rollback if the new firmware fails to boot 3 times
Manual rollback to previous version via web UI
SHA256 verification ensures firmware integrity
ESP32-C6 auto-update — the Wi-Fi co-processor firmware is updated automatically when needed
Web UI updates — starting with v0.7.5, the web interface can also be updated over-the-air

Note: Version 0.7.5 requires a full flash (use the web flasher or see alternative methods). This version adds OTA updates for the web UI, so future updates should rarely require a full flash.

OTA update page (click image to watch video)

Hardware specs

Component	Details
Board	Waveshare ESP32-P4-WIFI6-Touch-LCD-4B
MCU	Dual-core ESP32-P4 + ESP32-C6 for Wi-Fi 6/BLE
Display	4" square 720×720 IPS, 24-bit color, dimmable backlight
Touch	5-point capacitive touchscreen
Memory	32MB PSRAM, 32MB flash
Storage	microSD card slot
Power	USB-C (no battery)

Documentation

Document	Description
HOW-TO-USE.md	Detailed usage instructions
flash-p3a.md	How to flash the firmware
INFRASTRUCTURE.md	Technical architecture for developers

Repository layout

main/ — Application entry point, display/touch drivers, animation player, format decoders
components/ — Custom components: state machine, config store, HTTP API, Makapix integration, OTA manager, decoders
managed_components/ — ESP-IDF Component Registry dependencies
webui/ — Web interface files (compiled into SPIFFS)
docs/ — Documentation

Makapix Club integration

Makapix Club is a pixel-art social network where artists share their creations. Register your p3a at makapix.club to:

Play artworks and channels: Stream individual artworks or entire channels (like "Promoted Artworks" or "Recent Artworks") directly to your p3a
Remote control: Control your device from anywhere via secure MQTTS (MQTT over TLS) connection
Real-time updates: Receive artwork notifications instantly
Coming soon: Send "likes" to artworks with a long-press, swipe up to view community comments

Join the discussion: Visit the Makapix Club Discord to connect with other p3a users, share tips, and discuss pixel art players integrated with Makapix Club.

License

p3a is licensed under the Apache License 2.0. See LICENSE for the full license text.

For detailed information about all dependencies and their licenses, see LICENSING.md.

Contributing

Contributions are welcome! By contributing to p3a, you agree that your contributions will be licensed under the Apache License 2.0.

See the INFRASTRUCTURE.md for technical details about the codebase.

Acknowledgements

Thanks to ByteWelder from the Espressif MCUs Discord channel for advice very early in the p3a project.

fabkury/p3a