🌍 您也可以阅读本文件的其他语言版本 简体中文 Simplified Chinese
Holocubic was originally an open-source project by 稚晖君, and this project is a third-party independent firmware running on HoloCubic hardware.
AIO stands for All in One, aiming to integrate as many features as possible into the Holocubic firmware while keeping it open-source. The firmware currently contains 20,000+ lines of code, with the host software at 4,000 lines (excluding font libraries and images). We invite everyone to join in developing the AIO firmware, host software, and peripherals to meet more users' needs.
This firmware is fully open-source for learning and experimentation. If you use this project for secondary development or partial reference, please provide appropriate attribution.
- Original project: https://github.com/peng-zhihui/HoloCubic
- Original AIO project: https://github.com/ClimbSnail/HoloCubic_AIO
- This project (Latest): https://github.com/asdfghj1237890/HoloCubic_AIO
- AIO Framework & Core Apps: ClimbSnail, asdfghj1237890
- 2048 Game: AndyXFuture
- New Weather Clock: PuYuuu, asdfghj1237890
- BiliBili Fans App: cnzxo
- Anniversary & Heartbeat Apps: WoodwindHu, asdfghj1237890
- PC Resource Monitor: Jumping99
- Multi-function Animation: LHYHHD
- Stock App: redwolf, asdfghj1237890
- More developers joining...
- Rich APP Ecosystem: Built-in weather, clock, photo album, special effects, video player, PC screen sharing, web settings, and more
- Flexible Hardware: Boot normally regardless of TF card insertion, MPU6050 soldering status, or WiFi connection (requires 2.4G WiFi)
- Modular Design: Low-coupling architecture for easy extensibility
- Web Configuration: Configure network and settings via web interface (see APP Introduction for details)
- Multiple Access Methods: Access via IP address or domain name (http://holocubic) - some browsers may have limited support
- Remote File Management: Upload/delete files on SD card via web interface without physical access
- Complete PC Tools: Full host software suite with open-source code: https://github.com/asdfghj1237890/HoloCubic_AIO/tree/v2.0.2/AIO_Tool
Video Tutorial: https://www.bilibili.com/video/BV1wS4y1R7YF/
Download the PC tool from the release page to flash the firmware.
bootloader_dio_40m.bin- Bootloaderpartitions.bin- Partition fileboot_app0.bin- Boot appHoloCubic_AIO_XXX.bin- Latest firmware (updated with each version)
Note: Files 1-3 remain stable across updates. Only the firmware file (
HoloCubic_AIO_XXX.bin) changes with each version.
- Place files 1-3 and
CubicAIO_Tool.exein the same directory - Run
CubicAIO_Tool.exe - Select the latest firmware
HoloCubic_AIO_XXX.bin - Flash the firmware
Video Tutorial: https://b23.tv/5e6uDh
Having issues with hardware assembly or soldering? Check out our comprehensive troubleshooting guide:
🔧 HoloCubic Troubleshooting Guide v2.4
This guide covers:
- Hardware versions and compatibility
- PCB fabrication and soldering
- Common issues and solutions
- Component selection and vendors
- Multimeter usage and testing procedures
The device uses an MPU6050 gyroscope/accelerometer. For proper initialization:
- Keep the device stationary for the first 3 seconds after power-on (don't hold it)
- Wait for sensor initialization to complete - the RGB LED will fully light up
- After initialization, normal operation can begin
Troubleshooting: If the MPU6050 soldering is faulty, the orientation reading will be erratic (symptom: apps constantly switching). TF card insertion does not affect boot.
- File System: FAT32
- Required for: Photo album, video playback
- Setup: Copy all files and folders from the
放置到内存卡directory to the TF card root before first use - Note: Device boots normally with or without TF card, but some APP functions require it
| Gesture | Duration | Action |
|---|---|---|
| Shake left/right | 0.5s | Switch between APPs |
| Tilt forward | 1s | Enter current APP |
| Tilt backward | 1s | Exit current APP |
🌐 Web Server (网页配置服务)
- Requirements: None (WiFi info stored in flash, independent of TF card)
- Access:
- Device creates AP
HoloCubic_AIO(no password) at192.168.4.2 - Or use domain: http://holocubic
- Recommended: Use IP address for better compatibility
- Device creates AP
- Features:
- System parameter configuration
- Weather APP settings
- Photo album parameters
- Player settings
- Auto-start APP configuration
- Developer: ClimbSnail, asdfghj1237890
First-time setup: Connect PC to HoloCubic's WiFi hotspot, then configure via web interface.
📁 File Manager (文件管理器)
Purpose: Manage TF card files wirelessly
- Requirements:
- WiFi configured
- TF card inserted
- Sufficient USB power supply
- Usage: Enter via Windows File Explorer:
ftp://holocubic:aio@[YOUR_IP]- Replace
[YOUR_IP]with the IP shown on device screen
- Replace
⚠️ Note: Some features still under development
🖼️ Picture Album (相册)
- Requirements:
- TF card with
image/directory - Image files in
.jpgor.binformat
- TF card with
- Setup:
- Convert images using PC tool (any resolution, auto-compressed)
- Save to
image/directory - Filename must be alphanumeric (cannot start with number)
- Image Formats:
- Weather icons: C array (Indexed 16 colors)
- Other images: Binary RGB565
.binor.jpg
- Settings: Additional features configurable via WebServer
🎬 Video Player (Media)
- Requirements: TF card with
movie/directory - Setup:
- Convert videos (1:1 aspect ratio recommended) using conversion tool
- Save as
.mjpegor.rgbformat inmovie/directory - Filename must be alphanumeric (cannot start with number)
- Power Saving:
- Low-power mode after 90s idle
- Secondary low-power mode after 120s (reduced frame rate)
- Settings: Additional features configurable via WebServer
🖥️ Screen Sharing (屏幕分享)
- Requirements:
- WiFi configured via Web Server
- Sufficient USB power supply
- PC Tool: Uses 大大怪's tool
- Tip: Reduce quality to improve frame rate if laggy
🌤️ Weather & Clock (天气、时钟)
- API: AccuWeather API
- Requirements: Internet connection
- Setup:
- Configure city name (English): e.g., Beijing, Taipei, Tokyo
- Get API key: AccuWeather API
- Leave city name empty for automatic IP-based location detection
- UI: Inspired by
misakaclock interface - Notes:
- Free tier limited to 50 requests/day, adjust update frequency accordingly
- Location Key is automatically cached, no manual configuration needed
- Migration details:
AIO_Firmware_PIO/src/app/weather/ACCUWEATHER_MIGRATION_EN.md
- Developer: PuYuu, asdfghj1237890
- API: Seniverse Weather API (v3)
- Requirements: Internet connection, TF card optional
- Setup:
- Copy
weather/folder to TF card root (some icons stored on card) - Configure city name and API key at https://seniverse.com
- Copy
- UI: Inspired by CWEIB
Note: Clock continues running even when offline. Best to connect WiFi on boot for time sync.
✨ Special Effects (Idea)
- Requirements: None
- Features: Built-in animation effects
- Credits: Ported from community member "小飞侠"
🎮 2048 Game
- Requirements: None (just working screen)
- Controls:
- Up/Down: Quick tilt
- Enter/Exit: Hold tilt for 1 second
- Developer: AndyXFuture
📺 BiliBili Fans APP
- Requirements:
- TF card with
bilibili/folder - WiFi configured
- Avatar image:
bilibili/avatar.bin(100×100 pixels)
- TF card with
- Setup:
- Get UID: Visit https://space.bilibili.com/ (number in URL)
- Configure UID in WebServer
- Add avatar image (convert using AIO tool)
- Developer: cnzxo
🎂 Anniversary (纪念日)
- Requirements: Internet connection
- Setup: Configure via WebServer
- Name and date (format:
2022.5.8) - Year = 0 for recurring anniversaries (e.g., birthdays)
- Supports up to 2 anniversaries
- Name and date (format:
- Supported Characters:
生日还有毕业养小恐龙种土豆老婆女朋友爸妈爷奶弟妹兄姐结婚纪念 - Credits: Based on LizCubic, developed by WoodwindHu
💓 Heartbeat (心跳)
- Requirements:
- Internet connection (performance mode)
- MQTT server (port 1883)
- Two HoloCubic devices
- Setup: Configure via WebServer
- Role: 0 or 1 (for two devices)
- Client ID: Same QQ number for both devices
- MQTT server, port, credentials
- Usage: Auto-enters when receiving message from paired device
- Credits: Based on LizCubic, developed by WoodwindHu
Free MQTT service info available in QQ groups
📈 Stock Market (股票行情)
- Requirements: WiFi configured, sufficient USB power
- Supported Markets:
- Chinese Market (CN) - Shanghai & Shenzhen Stock Exchanges
- US Market (US) - NASDAQ, NYSE, etc.
- Hong Kong Market (HK) - HKEX
- Data Sources:
- Chinese Market: Sina Finance API
- International Markets: Yahoo Finance API
- Setup: Configure via WebServer
- Enter Stock Symbol:
- US stocks:
AAPL,TSLA,GOOGL, etc. - Chinese stocks:
601126,sh601126,sz000001, etc. - Hong Kong stocks:
0700,9988, etc.
- US stocks:
- Select Market Type: US/CN/HK
- Set Update Interval (default: 10 seconds)
- Enter Stock Symbol:
- Display Info: Real-time price, change percentage, trading volume, etc.
- Developer: redwolf, asdfghj1237890
See
AIO_Firmware_PIO\src\app\stockmarket\INTERNATIONAL_STOCK_SUPPORT.mdfor detailed configuration
💻 PC Resource Monitor
- Requirements:
- WiFi configured
- PC and HoloCubic on same network
- AIDA64 installed on PC
- Setup:
- Import config file
aida64_setting.rslcd(inAIO_Firmware_PIO\src\app\pc_resource\) - Set PC service IP in WebServer
- Import config file
- Developer: Jumping99
See group documentation for detailed setup steps
🎨 Multi-function Animation (LH&LXW)
Controls:
- Tilt backward: Enter APP / Enter selected function
- Tilt forward: Exit
- Tilt left/right: Switch functions
1. Matrix Rain (代码雨)
- Left/Right: Switch size
- Forward: Exit
2. Cyber Album (赛博相册)
- TF Card Setup:
./LH&LXW/cyber/imgx.cyber (x=0~99) ./LH&LXW/cyber/cyber_num.txt (image count, e.g., "07") - Image Conversion (48×40 pixels):
import cv2
img_path = './123.jpg'
out_path = './123.cyber'
img = cv2.imread(img_path)
img = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
with open(out_path, 'wb') as f:
for a in img:
for b in a:
f.write(b)- Controls:
- Left: Stop auto-switch
- Right: Resume auto-switch
- Backward: Toggle static/dynamic
- Forward: Exit
3. QQ Emoji (QQ超级表情)
- TF Card Setup:
./LH&LXW/emoji/videos/videox.mjpeg (240×240, x=0~99) ./LH&LXW/emoji/images/imagex.bin (60×60, x=0~99) ./LH&LXW/emoji/emoji_num.txt (video count) - Controls:
- Left/Right: Select emoji
- Backward: Play current emoji
- Forward: Exit (during selection) or stop playback
- Auto-plays each emoji for 33.3s
4. Eye Animation (眼珠子)
- Left/Right: Switch eye style
- Forward: Exit
5. Dynamic Heart (动态心)
- Shake device: Particles scatter
- Hold still: Particles form heart shape
- Forward: Exit
Demo Video: https://www.bilibili.com/video/BV1wK421173C
This project is developed using PlatformIO on VSCode with the ESP32-Pico Arduino platform.
Tutorial: https://b23.tv/kibhGD
-
Install VS Code: Download and install from Visual Studio Code official website
-
Install PlatformIO Extension:
- Open VS Code
- Click the Extensions icon on the left sidebar (or press
Ctrl+Shift+X) - Search for "PlatformIO IDE"
- Click Install to install the extension
- Restart VS Code after installation completes
-
Open Project:
- In VS Code, select File > Open Folder
- Select the
AIO_Firmware_PIOfolder - PlatformIO will automatically recognize the project and install required dependencies
-
Configure Upload Port: Modify
upload_portinplatformio.inito match your COM port -
Disable Apps (Optional): To exclude built-in apps, set the corresponding
APP macroto0inAIO_Firmware_PIO\src\app\app_conf.h -
SPI Library: ✅ No modification needed! The project includes a pre-configured SPI library in the
lib/directory with correct pin settings
📜 Legacy SPI Configuration (for reference only - can be ignored)
Previous versions required manual SPI library modification to prevent SD card read failures:
Both PlatformIO and Arduino IDE users needed to modify the MISO default pin to 26 in the SPI library. For example, in Arduino IDE's package path esp32\hardware\esp32\1.0.4\libraries\SPI\src\SPI.cpp:
if(sck == -1 && miso == -1 && mosi == -1 && ss == -1) {
_sck = (_spi_num == VSPI) ? SCK : 14;
_miso = (_spi_num == VSPI) ? MISO : 12; // Change to 26
_mosi = (_spi_num == VSPI) ? MOSI : 13;
_ss = (_spi_num == VSPI) ? SS : 15;This was necessary because the hardware uses two hardware SPI connections for screen and SD card. HSPI's default MISO pin 12 is used for flash voltage setting during ESP32 boot, and pulling it up before power-on prevents chip startup. We replaced it with pin 26.
After configuration, you can use PlatformIO to build and upload firmware to your device:
In the PlatformIO toolbar at the bottom of VS Code:
- ✓ Build: Click to build the firmware and check for code errors
- → Upload: Click to build and upload firmware to the connected device
- 🔌 Serial Monitor: View debug output from the device
- Click the PlatformIO icon on the left sidebar (alien head icon)
- Under PROJECT TASKS, select your environment (e.g.,
esp32dev) - Choose an operation:
- Build: Build firmware only
- Upload: Build and upload firmware
- Upload and Monitor: Upload firmware and open serial monitor
- Clean: Clear build cache
- Press
Ctrl+Shift+Pto open the command palette - Type "PlatformIO"
- Select:
- PlatformIO: Build: Build the project
- PlatformIO: Upload: Upload to device
Important Notes:
- Ensure the device is properly connected via USB before uploading
- Verify that
upload_portinplatformio.iniis configured correctly - First-time builds will download required toolchains and libraries, which may take some time
Framework Explanation Video: https://www.bilibili.com/video/BV1jh411a7pV?p=4
- Edgeline
- GUI Guider
- Learning: http://lvgl.100ask.org | http://lvgl.100ask.net
- Simulator: https://github.com/lvgl/lv_platformio
- Font Tool:
LvglFontTool V0.4(located inDoc/directory)
- App Icons (128×128): Download from Alibaba IconFont
Debug Error Location:
xtensa-esp32-elf-addr2line -pfiaC -e firmware_name.elf [Backtrace_address]Extract Chinese Characters from C Files:
python Script/get_font.py path/to/font_file.cCurrent Version: v2.5.0
v2.5.x - Latest
- Icons: Updated app icons for screen share, media player, picture album, weather, etc.
- Documentation: README improvements and corrections
v2.3.x
- Stock: Refactored data processing & UI, added international market support, fixed memory leaks
- Weather: Integrated AccuWeather API, improved stability, multi-language & Traditional Chinese font optimization
- Web Settings: Enhanced multi-language support and UI
- Anniversary: Fixed time API
- Other: Streamlined unnecessary features, fixed font inclusion issues, optimized Pomodoro interface
v2.2.x
- Updated LVGL to v8.3.3, modified all LVGL-related APPs
- Fixed all functions with return values but missing return statements
v2.1.x
- Added weather font library
- Added Stock APP
- Added brightness adjustment threshold to prevent crashes
v2.0.x
- Fixed 7-day weather only reading Beijing, modified API, added humidity
- Support MPU6050 operation direction mapping adjustment
- Support LittleFS (migrated existing KV storage)
- SD card SPI support, SD dual mode (pending)
- Added parameter settings
- Coordinated screen sharing PC tool adjustment (pending)
- Fixed 2048 (pending)
- Support hiding APPs (pending)
- Fixed BiliBili API and memory leaks
- Fixed memory leaks caused by missing
lv_style_resetin all APPs using LVGL - New weather supports 3-character city names
- Added performance mode support
- Added Heartbeat and Anniversary APPs
v1.9.x
- Major screen sharing APP overhaul, fixed lag issues (thermal protection, medium performance)
- Added FTP file transfer support (PC tool not updated)
- Added thermal control in video playback to prevent ESP32 overheating damage
v1.8.x
- Added 2048 game, new weather clock, BiliBili fans APP
- Modified MPU6050 operations, added two key values
- Modified image loop playback, fixed clock interface lag
- Added event queue
v1.7.x
- Added screen sharing and Settings APP
- Added APP names
- Added screen brightness and orientation adjustment in WebServer
- Enhanced video and photo album orientation switching support
- Fixed Idea APP graphics not clearing causing overlapping
- Fixed memory release issues in some APPs
- Changed weather icons to QWeather icons
v1.6.x
- Adjusted screen brightness and WiFi scheduling to reduce power consumption
- Modified TFT_eSPI library to eliminate boot screen artifacts
- Added MJPEG video playback while maintaining RGB playback, increased video frame rate to 20fps
v1.5.x
- Added video playback (continuous improvement)
- Added MPU6050 calibration for tilted base compatibility
- Photo album supports both JPG and BIN formats
- Added Idea animation APP
- Accelerated boot display
v1.4
- Major framework modifications
- Added screen brightness control
- Fixed photo album "white screen" phenomenon during switching
v1.3
- Moved WiFi configuration from SD card to flash (non-album APPs no longer require SD card)
- Adjusted RGB ambient lighting
- Added
movie/directory to SD card structure
HoloCubic_AIO_Tool v1.6.2 - Latest
- Fixed BGR color channel issue in photo conversion tool
- Improved UX in photo transform tool
HoloCubic_AIO_Tool v1.6.0
- Added multi-language support (Traditional Chinese, English, etc.)
- Added tool settings page
- Fixed MJPEG tool issues, added video conversion log and thread support
- Improved ffmpeg command real-time output capture
- Enhanced input file error handling and validation
- ESP32 Memory Distribution: https://blog.csdn.net/espressif/article/details/112956403
- Video Playback: https://github.com/moononournation/RGB565_video
- FTP Implementation: https://blog.csdn.net/zhubao124/article/details/81662775
- ESP32 Arduino Dual-Core: https://www.yiboard.com/thread-1344-1-1.html
- Captive Portal Authentication: https://blog.csdn.net/xh870189248/article/details/102892766
Special thanks to all authors of open-source libraries used in the lib/ directory.
This project is open-source. If you use this project for secondary development or partial reference, please provide appropriate attribution.
Made with ❤️ by the HoloCubic AIO Community









