MiyooCFW is custom firmware that turns cheap Linux handhelds into retro consoles

Firmware for a specific family of cheap handhelds

Miyoo custom firmware is the definitive custom firmware for BittBoy, PocketGo and PowKiddy V90, Q90 and Q20 devices, and for third party consoles. It allows you to unlock the potential of the hardware and use software from a wide variety of consoles and computers, thanks to the availability of numerous emulators and native ports of several games.

The framing matters. This is not a game bundle and it is not an emulator distribution. It is a firmware image, in the same sense that a router firmware is a firmware image, and it replaces the operating system that shipped on the device with one that has a menu, a settings application, a launcher for emulated and native software, and an update mechanism.

The project is not affiliated or related with any company or manufacturer, and the readme states that plainly, along with the note that they do not pay or get paid for this work. For a project whose success depends on people buying cheap hardware and flashing it, that disclaimer is doing real work, because the alternative is a support burden that a volunteer project cannot carry.

The licence is GPL-2.0, the last push was on 2026-09-25, and the release list is 2.0.0-beta-2 from 2024-03-08, 2.0.0-beta from 2023-12-31 and 1.3.3 from 2022-04-01, which is marked as the old release. So the 2.0 line has been in beta for a while and the 1.3.3 build is what many devices are still running.

The repository is a firmware project, not a file dump

The top level listing is the clearest description of what the project contains, and it is a complete embedded software stack.

There is a buildroot/ directory, which is the Buildroot based build system that assembles the userspace, a kernel/ directory for the Linux kernel and its configuration, and a uboot/ directory for the bootloader. Then there is the userspace of the firmware itself: a daemon/ directory, a miyooctl/ directory for the command line control tool, and gmenu2x/ with a gmenu2x-skins/ directory, which is the graphical menu system that the handheld boots into.

There is a logo/ directory for the boot splash, and a CHANGELOG.md, a LICENSE.txt, a README.md and a .github/ directory with the workflows, including the build workflow that produces the nightly images.

And there are the two Dockerfiles, Dockerfile-musl and Dockerfile-uclibc, which is the detail that most tells you about the project. Two container images means the build can be reproduced in a fixed environment on a machine that is not the target, which matters for a project whose output is a disk image for ARM hardware that most contributors do not own.

The .gitmodules entry confirms that the subcomponents, the kernel and the bootloader, are tracked as separate upstreams rather than as patches inside the tree.

musl or uclibc, and why both are in the tree

The two Dockerfiles are the interesting structural decision, and they are about the C library rather than about the firmware.

The supported devices run on ARM processors, and a userspace has to be built for them. A full glibc is heavy and assumes a Linux with the system assumptions of a server, while a smaller C library is a better fit for a device with limited memory and storage and a fixed kernel.

Building two variants, one against musl and one against uclibc, covers devices where one works and the other does not, and it keeps the choice explicit rather than accidental. The container image for each is what makes the build reproducible, since the build happens inside a known environment rather than on whatever distribution the contributor happens to run.

The build itself is Buildroot, which is the tool for assembling a complete embedded Linux system from source with a menuconfig style configuration. That is a heavy dependency for a hobby project to carry, and it is also the reason the resulting image is consistent between contributors, which matters when the output is flashed onto somebody else's device.

For an adopter, the practical effect is that there are two images to choose from and the wiki covers the setup for each supported console. The readme points there for the main guides on setup, which is where the device specific instructions live.

The 2.0 line and the beta it has been sitting in

The release history is short and it explains the state of the project.

The most recent tags are 2.0.0 Beta 2, marked as a pre-release, from 2024-03-08, then 2.0.0 Beta from 2023-12-31, and before that 1.3.3, marked as the old release, from 2022-04-01.

So the 2.0 line has been in beta for a long time, and the last stable tag is from 2022. For a firmware project that is unusual, and the usual explanation is that a major version for embedded software means a change to the base system, and the beta period is where the devices that cannot be updated get sorted out.

The alternative is the nightly development builds, which the readme links through the build workflow on nightly.link. For a device owner, the nightly build is often the more useful artefact, because it contains the fixes that have landed since the last tag.

The version badge in the readme points at the releases page with pre-releases included, which tells you the project expects people to be running the beta.

The changelog is linked for the version details history, and the readme also points at the wiki for the main setup guides, so the documentation is split between the wiki for the how and the changelog for the what.

Where the community and the software catalogue live

The Information section is a list of six links, and it describes how a community project is organised.

There is the releases page for the latest release and the nightly development builds, the wiki for the main setup guides, the discussion forums for feedback and comments, the changelog for the version history, a Discord chat server for support, and a Matrix server for development chat.

Having both Discord and Matrix is a deliberate choice and a common one among projects that have had a moderation problem on one platform, and the split is sensible, with support in the place where end users are and development in the place where contributors are.

The Resources section is a catalogue of the homebrews and native ports available for the platform, with a download link and the person who developed each one, and the list runs to dozens of entries. Reading it tells you two things about the project. The first is that the software is mostly free homebrew and native ports rather than emulated commercial titles, which is what keeps the project on the right side of the law. The second is that the community is spread across several authors, with a handful of people, szymor among them, responsible for a large share of the catalogue, and others contributing ports of their own.

That catalogue is why the firmware exists at all. A custom firmware for a device with no operating system worth using only makes sense if there is software to run on it, and the two lists grow together.

The menu system and the control tool

Two directories in the tree are worth explaining, because they are the parts a user actually touches.

The gmenu2x/ directory with its gmenu2x-skins/ sibling is the menu system. It is a separate, existing piece of software with a skins directory alongside it, which tells you the firmware does not invent a menu but adopts one and lets the community restyle it. On a device with a small screen and a low resolution, the menu is the product, and making it skinnable is a design decision the community clearly cares about.

The miyooctl/ directory is the command line control tool, and on a device that also boots into something called a daemon, the split between the two is the usual split between the foreground interface and the background service.

The daemon/ directory is the other half of that arrangement, and it is where the parts of a firmware that have to keep running regardless of what the user is doing would sit, such as the controller input handling or the volume control, both of which are the sort of thing that has to work while the menu is open and while an emulator is running.

The logo/ directory is the smallest entry and it is there because a handheld that boots to a black screen looks broken, whatever the firmware underneath is doing.

What the project is asking of you

Pulling the readme together, the project is asking for two things, and they are different in kind.

The first is that you use the official channels. The releases page, the nightly builds, the wiki, the discussions, the Discord and the Matrix server are listed in that order in the Information section, and the wiki is where the setup guides are. The reason is the disclaimer about not being affiliated with any manufacturer. Nobody supports your device, so the documentation is the support, and the readme is careful to point you to it before you flash anything.

The second is that you contribute software rather than asking for it. The Resources section lists homebrews and native ports with the developer credited, and the two questions that the community answers most often, what can it run and who wrote it, are answered by that list.

The project is also explicit that it is not affiliated with or related to any company or manufacturer, and that no money changes hands in either direction. On a project with a Discord, a Matrix server, a wiki, nightly build pipelines and a catalogue of dozens of ports, that sentence covers a lot of work that is being done for free, and it is the kind of thing that a project says when it wants the boundary understood rather than assumed.

Editorial conclusion

Adopt MiyooCFW if you own one of the supported handhelds and want a coherent firmware with a menu, emulators and a working update path rather than a pile of separate binaries. Do not adopt it as a general purpose Linux distribution, since it is built for one SoC family and its userspace choices are constrained. Verify first which of the two C library builds suits your device, since the repository ships separate musl and uclibc images, and that the nightly build you flash matches the hardware revision, because the readme is explicit that the project is not affiliated with or supported by the manufacturers.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. TriForceX/MiyooCFW on GitHub