# Muse Cube V1.2

**Fully open-source, multi-function handheld terminal.**
Hardware and software are open, hackable, and designed to fit in your pocket.

[!\[Hardware](https://img.shields.io/badge/Hardware-OSHWHub-green)](https://oshwhub.com/dydcyy/mp3-based-on-stm32)
[!\[Software](https://img.shields.io/badge/Software-GitHub-black)](https://github.com/dydcyy-gh/MuseCube)

## Overview

Muse Cube is a tiny (8 × 5 × 2.2 cm) handheld device built around an STM32F405. It combines a music player, video player, retro game emulator, USB gadget, desktop assistant, and many creative tools into one pocket‑friendly gadget. Everything – PCB, 3D‑printed shell, firmware – is open source.

### Hardware highlights

* **MCU:** STM32F405 @ 168 MHz, 128 KB SRAM + 64 KB CCM, 1 MB Flash
* **Display:** 1.54″ IPS, 240×240, vibrant colors
* **Audio:** ES9018K2M DAC + dedicated headphone amplifier; dual speakers driven by MAX98357A
* **Storage:** 16 MB on‑board SPI Flash (W25Q128), TF card slot (up to 32 GB, SDIO 24 MHz DMA)
* **Input:** two Switch‑style joysticks
* **Connectivity:** USB‑C (charge / data / host), 3.5 mm headphone jack
* **Battery:** 2000 mAh Li‑Po, all‑day music or desktop use
* **Form factor:** 8 × 5 × 2.2 cm, pocketable, held together with M1.6/M2 screws and heat‑set inserts

## Key features (firmware V1.1)

* **Home screen** — lock screen with desktop widgets, left/right swipe to flip pages for more app icons
* **Music player** — WAV, MP3, FLAC, AAC, APE; DAC advanced settings
* **Video player** — MJPEG (240×240 @ 30 fps), RAW RGB565
* **Image viewer** — JPG, PNG, BMP, GIF (including animated); photo album for BMP browsing
* **NES emulator** — play classic ROMs from TF card
* **USB gadget** — CDC serial, MSC, UAC1/UAC2 audio, HID mouse/keyboard/gamepad, Display (screen mirroring)
* **USB host** — read USB drives, connect serial devices, HID keyboard/mouse
* **File manager** — refined drive letter display, SD card hot-plug auto mount/unmount
* **System log**, task manager
* **Notebook**, TXT reader, pixel‑art drawing
* **Tools** — calculator, serial assistant, clock/timer/stopwatch/alarm, countdown, date \& time settings
* **CMD terminal** — Letter Shell embedded command-line interface
* **Calendar** — day view and month view
* **Study helpers** — vocabulary memorizer (TXT word‑list parsing, word/phonetic/definition display), timetable, lottery drawing
* **Pinyin IME** for text input
* **Control centre**, notification centre, about device page
* Boot animation and splash screen

> Many more features are planned and will land in monthly firmware updates (starting May 2026).

## Code architecture

The firmware is split into two parts:

1. **Bootloader** (first 64 KB of Flash)

   * Based on CherryUSB UF2 protocol – drag‑and‑drop firmware update over USB
   * Minimal RTOS + memory allocator (FreeRTOS, TLSF)
2. **Main application**

   * **RTOS:** FreeRTOS
   * **GUI:** LVGL (v8.2)
   * **Memory:** TLSF allocator managing 128 KB RAM + 64 KB CCM
   * **File systems:** FatFS (TF card), FlashDB (on‑chip flash key‑value \& time‑series database)
   * **USB stack:** CherryUSB (device \& host)
   * **Audio:** libhelix‑aac, libhelix‑mp3, libfoxenflac, libdemac
   * **Image/video:** PNGdec, Tjpgd, AnimatedGIF
   * **Shell:** Letter Shell (embedded command-line interactive shell)
   * **Vocabulary:** english-wordlists (TXT‑format word books)
   * **Fonts:** WenQuanYi bitmap, ChillBitmap, fusion‑pixel
   * **Watchdog:** Independent watchdog (IWDG) for crash recovery
   * **Random numbers \& RTC:** hardware RNG, lunar calendar conversion

Peripherals are driven with DMA wherever possible (SPI display @ 42 MHz, SDIO, I2S audio, ADC for joysticks). The system uses STM32 Standard Peripheral Library and compiles with Arm Compiler 5 in Keil MDK.

## Project structure

```text
MuseCube/                          Handheld multimedia player firmware project based on STM32F405RGT6 (Keil MDK + AC5 + STM32 Standard Library)
│
├── 1-library/                         STM32F4xx Standard Peripheral Library (StdPeriph\_Driver V1.8.1), HAL drivers for all on-chip peripherals (.c/.h pairs)
│
├── 2-start/                            CMSIS startup layer: startup assembly, system clock init (168 MHz), Cortex-M4 core access headers, CMSIS-DSP library
│
├── 3-main/                             Application entry layer: main() function, FreeRTOS scheduler startup, global variables, task config macros, interrupt handlers
│
├── 4-ware/                             Firmware core code (21 subdirectories covering hardware drivers → middleware → application → GUI → FreeRTOS tasks)
│   ├── BSP/                            Board support package: ADC, ES9018K2M DAC, I2S audio interface, SDIO SD card, W25Q128 SPI flash, LCD/backlight, keypad drivers
│   ├── Lib\_FreeRTOS/                   FreeRTOS real-time OS kernel (ARM Cortex-M4F port)
│   ├── Lib\_LVGL/                       LVGL v8.x embedded graphics library (DMA2D GPU acceleration, TLSF memory allocator, rich widgets and fonts)
│   ├── Lib\_Cherry\_USB/                 CherryUSB protocol stack: supports USB Device/Host (CDC/MSC/UAC1/UAC2/HID/Display/Video/ADB and more)
│   ├── Lib\_Fatfs/                      FatFs FAT file system (mounts SD card and USB storage)
│   ├── Lib\_FlashDB/                    FlashDB embedded database: key-value database (KVDB) + time-series database (TSDB), built on FAL flash abstraction layer
│   ├── Lib\_TLSF/                       TLSF O(1) dynamic memory allocator, replaces standard malloc/free
│   ├── Lib\_Music\_lib/                  Audio decode library: Helix MP3/AAC decoder, foxen-flac FLAC decoder, DEMAC APE decoder (all with ARM assembly optimizations)
│   ├── Lib\_Tjpgd/                      Tiny JPEG Decompressor — ultra-lightweight JPEG decode library
│   ├── Lib\_PNGdec/                     PNG decode library (includes zlib inflate decompression)
│   ├── Lib\_AnimatedGIF/                Animated GIF decode library
│   ├── Lib\_Letter\_Shell/              Letter Shell — embedded command-line interactive shell
│   ├── Apps\_Music/                     Music player application layer: playback state machine, I2S DMA double-buffering, MP3/AAC/FLAC/APE/WAV format decode wrappers
│   ├── Apps\_Media/                     Media decode application layer: BMP/PNG/GIF/JPG/MJPEG video decode wrappers
│   ├── Apps\_NES/                       NES emulator: 6502 CPU (assembly), PPU graphics rendering, APU audio, 90+ mapper support
│   ├── Apps\_Text/                      Text application layer: TXT reader, LRC lyrics parser, vocabulary manager
│   ├── GUI\_Page/                       Full-screen GUI pages (29+): desktop, music, file manager, settings, DAC, calendar, clock, calculator, sketchpad, NES games, CMD terminal, photo album, etc.
│   ├── GUI\_Unit/                       Reusable GUI components (22 groups): status bar, navigation bar, control center, keyboard, page-specific widgets
│   ├── GUI\_Icons/                      GUI icon resources: app icons, MuseCube logo, background images as LVGL-compatible bitmap data
│   ├── Tasks/                          FreeRTOS task implementations: TaskManager + 7 tasks (Basic/LVGL/Music/Video/Game/USB)
│   └── Utils/                          Utility functions: CPU usage, FFT spectrum analysis, battery level, Pinyin input method, lunar calendar conversion, debug logging
│
├── bootloader/                        USB UF2 bootloader (standalone Keil project, occupies first 64 KB of flash, drag-and-drop firmware update)
│   ├── 1-library/                     STM32F4 Standard Peripheral Library subset (DMA/Flash/GPIO/RCC/SPI/TIM/NVIC), only the peripheral drivers needed by the bootloader
│   ├── 2-start/                       CMSIS startup layer: startup assembly, system clock init (168 MHz), Cortex-M4 core access headers
│   ├── 3-main/                        Bootloader main entry: main() key detection → enter UF2 firmware update mode or jump to main app (0x08010000); ISRs and peripheral config header
│   ├── 4-ware/                        Bootloader BSP: UF2 protocol engine (emulated FAT16), flash programming driver (protects bootloader sectors), LCD progress bar, key detection, TLSF memory allocator (CCM), pin control, SysTick delay
│   ├── 5-freertos/                    FreeRTOS kernel (Cortex-M4F port), provides multitasking for LCD UI polling task and CherryUSB EP0/MSC threads
│   └── 6-cherryusb/                   CherryUSB Device stack: DWC2 OTG HS controller driver + MSC mass storage class, enumerates as a USB drive for drag-and-drop UF2 firmware files
│
├── bin2uf2/                           Firmware format conversion tool: Python script to convert Keil .bin/.hex output to UF2 format
│
└── TFcard\_files/                      System resource files to be placed on the TF card (music, pictures, fonts, game ROMs, lyrics, text files, word lists, etc.)
```

### Building

* IDE: Keil MDK 5
* Compiler: Arm Compiler 5 (armcc)
* Dependencies: all third‑party libraries are included in the repository under their respective licenses. Open the project file and build the `Bootloader` and `App` targets.

### Flashing

1. Flash the **bootloader** with an ST‑Link (or any SWD programmer).
2. Power on while holding the top button – the device enters UF2 mode.
3. Copy the generated `.uf2` firmware file to the virtual USB drive that appears.

## License

* **Hardware** (PCB, case, panel): [CC BY‑NC‑SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)
* **My software code**: MIT
* **Firmware as a whole** (includes third‑party libraries): [GPL v3](https://www.gnu.org/licenses/gpl-3.0.html)

|Library|License|
|-|-|
|FreeRTOS|MIT|
|LVGL|MIT|
|TLSF|3‑Clause BSD|
|FatFS|1‑Clause BSD|
|CherryUSB|Apache‑2.0|
|FlashDB|Apache‑2.0|
|libhelix‑mp3 / aac|RPSL 1.0|
|libfoxenflac|LGPL‑2.1|
|libdemac|GPLv2+|
|PNGdec / AnimatedGIF|Apache‑2.0|
|Tjpgd|Custom (see source)|
|Letter Shell|MIT|
|english‑wordlists|—|
|Fonts|GPL‑2.0 / OFL‑1.1 / MIT|

Wallpapers are used with permission from the artist [银锘](https://space.bilibili.com/1704688254) (non‑commercial only).

## Acknowledgements

* Thanks to all friends and supporters
* Tutorials and references from 江协科技, 正点原子, and the countless open‑source contributors
* AI tools (GitHub Copilot) that sped up development

\---

**Enjoy building and hacking your Muse Cube!**  
For questions, contact the author via QQ: 3793000877, or open an issue on GitHub.

