Miyoo Mini Onion Guide

Last updated: 19FEB2022 (see Changelog for details)

NOTE: There is a new Miyoo Mini v2 guide now available, with updated Onion instructions as well as a guide for installing MiniUI. I recommend using that guide instead.

When it first released last month, I was torn on the Miyoo Mini. It has a cute size, nice display resolution, and can fit in a playing card holster (a VERY important feature). But its software navigation and contrast/sharpness issues with its display left me unsatisfied. Today, we’re going to look at a new community-created OS solution called Onion, which improves the software experience, adds new systems and emulators, and incorporates recent fixes for the screen, too.

Credit for Onion goes to Jim Gray and a wonderful ragtag team of community contributors. They do not have a direct donation set up for the project, but if you are feeling generous, they requested you make a donation with the Mutual Aid Disaster Relief fund in their honor.

Onion is an active work in progress, so expect new features in the future.

To buy the Miyoo Mini, you can grab it via AliExpress or KeepRetro.com. Stock is low right now so expect shipping delays. Additionally, while the device retails for $50, some stores have marked up the price to $60 or higher; it’s going to be up to you whether you are willing to pay that premium or wait until supply better matches demand.

Table of Contents:

Onion features list
Recommended tools
Update to the most recent Miyoo Mini base firmware
Install Onion
Add BIOS files
Add game files and images
Download new themes
Trim and modify the emulators list
Move a save file to the Miyoo Mini
Miscellaneous notes

Changelog

Onion features list

Here is a list of reasons why Onion has improved the stock user experience:

  • 48 pre-configured emulation systems
  • Easily toggle-able “Expert Mode” with another 68 apps
  • Updated emulation cores, pre-configured and optimized for performance
  • Auto save/load enabled for most systems for improved pick-up-and-play
  • Standardized hotkey bindings (see the built-in Onion manual for specifics)
  • Streamlined folder structure, UI, and RetroArch menus
  • Real-time clock emulation
  • Cartridge function. This allows you to set a single game as your “cartridge” and every time you turn on the device it’ll automatically load that game, and when you close the game it will turn the device off. Perfect for when you want to focus on playing through just one game at a time.
  • Upgraded DinguxCommander file explorer app
  • Rumble motor enabled
  • One-click installation app. Simply drag the new app onto a blank SD card, and run it from the Miyoo Mini menu.
  • One-click theme installation, with over a dozen themes already available

Recommended tools

128GB SanDisk Ultra and Samsung EVO Select microSD cards

To install Onion, I recommend starting from scratch with a new microSD card. You could use a 16GB card to save on costs and keep your game library trim (which will also result in faster navigation), or you could fill it up with the works. Personally, I use a 32GB card in mine, with only a few PS1 and Sega CD games taking up the majority of the space. Here are the cards I recommend:

16GB cards: 
SanDisk Ultra  
SanDisk Industrial

32GB cards:
Samsung Pro Endurance
SanDisk Extreme

64GB cards:
Samsung Pro Endurance
SanDisk Extreme

128GB cards:
SanDisk Extreme
Samsung EVO Select
Samsung Pro Endurance
SanDisk Ultra

256GB cards:
Samsung EVO Select
SanDisk Ultra

If you don’t have one already, I also recommend a nice microSD USB card reader. This one from Anker has never done me wrong.

You can also pick up spare batteries for the Miyoo Mini for extended play sessions. The battery you are looking for is called the EB645247LU and you can find it easily on eBay or AliExpress.

Additionally, playing card cases work perfectly with this device. The one I recommend is made with imitation sheepskin and has a nice felt interior. You can find it for about $15 on Amazon.

Update to the most recent Miyoo Mini base firmware

In order to take advantage of Onion, you need to be on the most recent Miyoo Mini firmware update. This is a relatively easy process but does have some risk of bricking the device if done improperly. Follow these instructions to a “T” (and watch the video above for a demonstration.

  • Save any important game files or your BIOS folder to your computer just in case.
  • Go to the Miyoo website and download the latest image update, then unzip the file.
  • In the unzipped folder, go to “The firmware” > miyoo283_fw.img and drag that file into the root of your Miyoo Mini SD card
  • Go to “TF card” folder and drag the three subfolders (Emu, miyoo, and RetroArch) into the root of your card, and replace any existing files when prompted.
  • Eject the SD card from your computer and plug it into the Miyoo Mini
  • Remove the battery from the Miyoo Mini, then plug the Mini into a wall charger. Do NOT plug it into a PC, but instead use a low-wattage wall plug. For best results, use a USB-A to USB-C cable, and a “smart” plug that can adjust wattage, or one of those cheap 5V/1A plugs that used to come with cell phones.
  • The Miyoo Mini will automatically power on and run the update. Don’t touch the device at all!
  • The device will restart and will then display a battery image and the charging screen. At this point you are done. Unplug the device from the cable and remove the SD card.
  • Plug the SD card into your computer and delete the miyoo283_fw.img file before doing anything else.
  • Put the SD card back into the device, install the battery, and you should be good to go.

Here is a fancy infographic (credit: PIXELSHIFT and TNGLIKER) that walks you through the process. Their process is a bit different, in that they move the “TF card” files to the SD card after the upgrade; either method works fine.

click image for full-scale resolution

If you are having issues upgrading your device, or it gets caught in a loading screen while flashing the new firmware, follow the instructions provided in this Reddit comment.

Photo credit: StubbornPixel

Install Onion

The easiest part of this whole process is installing Onion!

  • Format your microSD card to FAT32 file system.
    • If using Windows, use the guiformat tool to format the card to FAT32. You can name it whatever you want.
    • If you have a Mac, “Erase” the disk using the Mac’s built-in Disk Utility app, with the format MS-DOS (FAT), name it whatever you want.
  • Head over to the Onion GitHub Releases page and grab the latest release (it will be a zip file).
  • Unzip the file, and you should have a single folder, called “App”. Drag this folder into your freshly-formatted FAT32 microSD card.
  • Eject the SD card and place it in your Miyoo Mini. Go into the Settings section and turn the Hibernate option to “Never”.
  • Plug your Miyoo Mini into a wall charger just to be safe
  • Navigate to Apps > The Onion Installer and run that program. It will take about 10-15 minutes for a new install, or about 5 minutes if you are updating from a previous version of Onion.

Add BIOS files

Once you have run the Onion Installer, you can now shut down the device, eject the microSD card, and add your files to it.

In the BIOS folder, add your BIOS file collection. You can simply copy/paste the files from your stock SD card, or add your own. On the stock SD card, you can find the BIOS files under RetroArch > .retroarch > System

You will need to be able to see hidden folders in Windows or your Mac to see the .retroarch folder. Here is how to do that:

  • Windows 10: Open File Explorer from the taskbar. Select View > Options > Change folder and search options. Select the View tab and, in Advanced settings, select Show hidden files, folders, and drives and OK.
  • MacOS: Press CMD + SHIFT + . (period) to show/hide hidden files.

To see a recommended list of BIOS files to add, head over to the Onion wiki page to see their list of emulators and recommended BIOS files for each system. For most systems, BIOS are not required, but can enhance the playing experience (like adding the original boot logo when starting up a game). For systems like PS1, Sega CD, and TurboGrafx-CD, BIOS are a necessary component. For best results, use the psxonpsp660.bin BIOS file for PS1.

Add game files and images

In the Roms folder, add your game files into the corresponding subfolder. Some of the folders are named after their Japanese counterpart, like “FC” (Famicom) for NES, “MD” (Mega Drive”) for Sega Genesis, or “PCE” (PC-Engine) for TurboGrafx-16. For a full listing of each folder and the accepted file extensions, check out the Onion wiki page.

When adding game files for systems that use the same RetroArch core file, you can create subfolders. For example, You could make Sega CD and Sega 32x subfolders inside of your Sega Genesis to clean up your front menu and streamline the navigation experience.

In the Imgs folder, add your image files to the corresponding subfolder. Images should be in .png format and the file name should match the ROM file perfectly. Additionally, images should be no more than 256px in width. Note that adding many images to your card may slow down your navigation experience. In order to see your images, when in the game list view, press right on the d-pad to show the image.

Download new themes

Adding new themes is a breeze on Onion.

  • Head over to the Onion theme repository
  • Download the themes you like by clicking on their picture
  • Unzip the downloaded file, and then place the unzipped folder in the Apps folder of your microSD card
  • The theme will be added to the Apps section of your Miyoo Mini
  • When switching themes, the device will shut itself off. Simply power the device back on to enjoy your new theme.

Note that you can go in the Settings menu on your Miyoo Mini and reduce (or mute) the background music.

Trim and modify the emulators list

Onion currently ships with a large variety of emulators, some of which you may not actually want on your navigation screen. Here’s how to safely remove extra emulators from your home screen:

  • Create a folder named something memorable (I used the name “NoThanks”) and place it in the root of your microSD card.
  • Go into the Emu folder on your SD card and move any emulator you don’t want into your “NoThanks” folder instead of the Emu folder.
  • To add the emulator back to your home menu, simply move it back into the Emu folder.

If you want to change the display name of the emulator on your home screen, open up the emulators folder (inside the Emu folder), and then open the config.json file. Here, just alter the “label” line to whatever display name you prefer, then save the .json file.

Move a save file to the Miyoo Mini

If you’re like me and are considering moving over some save games from the RG280V (or other system) to the Miyoo Mini, here is how to do it specifically for the Adam firmware image:

  • Using the Adam image, go to App > PyBackup and back up your RetroArch saves.
  • Insert your Adam SD2 card into a computer, then navigate to backups and unzip the RetroArch saves.tgz file using something like 7Zip.
    • Note that if you are using an emulator that is not RetroArch (like ReGBA), use that folder instead to find your save file.
  • Inside the tgz file, navigate to media > data > local > home > .retroarch > saves and find your save file (in .sav format). Save this to your computer.
    • You will need to be able to see hidden folders in Windows or your Mac to see the .retroarch folder. Here is how to do that:
    • Windows 10: Open File Explorer from the taskbar. Select View > Options > Change folder and search options. Select the View tab and, in Advanced settings, select Show hidden files, folders, and drives and OK.
    • MacOS: Press CMD + SHIFT + . (period) to show/hide hidden files.
  • On your Miyoo Mini card, navigate to RetroArch > .retroarch > saves > (name of core) and place the .sav file inside.

Miscellaneous notes

  • Be default, the PSX emulator is set to have the DualShock controller enabled. This will allow for rumble in games (which may need to be turned on in the game’s settings in order to work), but may render some older games unplayable. To fix this, press MENU + SELECT to bring up the RetroArch Quick Menu, then navigate to Controls > Port 1 Controls > Device Type and change it to Standard. These older games don’t support rumble anyway, so you’re not missing out on anything. To save this setting, go to Quick Menu > Controls > Save Game Remap File. This will ensure that this game will use the Standard control type from now on.
  • By default, both NES and SNES will have a Normal2x filter applied, which will allow for very sharp graphics but can result in slowdown in some games. If you experience slowdown in a game, press MENU + SELECT to bring up the RetroArch Quick Menu, then navigate to Settings > Video and select Remove Video Filter. This will make the image a bit blurrier but will improve performance. If you want to keep this setting for that particular game, go to Quick Menu > Overrides > Save Game Overrides.
  • It’s been reported to me that leaving the device to charge overnight can result in the battery icon burning into the screen, so definitely don’t do that. Since this is an LCD screen, the damage shouldn’t be permanent, and will go away over time.

Here is my original review of the Miyoo Mini:


Changelog

22FEB2022
– added link to spare battery

19FEB2022
– added link to Reddit comment with a fix if you have issues flashing upgraded Miyoo firmware

27JAN2022
– published guide
– added Miscellaneous notes section

27 thoughts on “Miyoo Mini Onion Guide

  1. Thank you! Thank you! Thank you!
    Its so reassuring having somebody break everything down so easily and as a newbie to Retro Handhelds I am truly greatful for this and similar Guides as I’d truly be lost without them!!!

    Massive thanks to the Community for supporting this device and I can’t wait to try things out once my Miyoo Mini arrives soon.

    Best wishes for 2022 and can’t wait to see your upcoming videos.

    Like

  2. Excellent guide, thank you very much. I have a little question… If I put some games from the \RRoms\mame2010 and \RRoms\mame2003 (stock folder) in the onion arcade folder \Emu\ARCADE (according to what the wiki indicates) it doesn’t read them. It only reads the ones I move from \Roms\MAME2003 (stock roms). any suggestion ???? thx.

    Like

  3. Hey man love your content, you’re a great help for the retro community, I was wondering if you can show us some instructions to play the Doom classic games on the Miyoo Mini like you did in the Rg280v guide, please.

    Like

  4. Wonderful guide! The only issue I’m experiencing atm is the cheat codes on PSX emulator not working. I’ve set RetroArch menu to show the cheats menu and downloaded what seems to be the correct .csh file but after applying them nothing happens. Am I missing something?

    Like

  5. Hi, i also ran into problems with PSX but mine wont start at all. double checked all BIOS files and also tried a different Set. sadly no success. it just jumps back to loading. any pointers on where to start?

    Also, thank you for the amazing guide!

    Like

  6. Does anyone know how to turn of cartridge mode? I made the mistake of changing my theme with it being activated and now it’s in a continuous loop of shutting down. Also messed up my keybinds to all A. Think I’ll just restart my install.

    Like

  7. This is so nice, but can anyone tell me how to get PS games to work on here? I’ve had zero success with .pbp, .7z, unzipped .7z to a subfolder with BIN/CUE. It’s very frustrating.

    Like

  8. Hi there,
    could anyone please tell me how to turn on expert mode on the latest onion version?
    I’m trying to run Retroarch to change the Arcade settings, but the normal Retroarch menu does not show any emulator cores.
    Thanks!

    Like

  9. I cannot for the life of me get thumbnail box art to display. Files are in PNG and width-wise smaller than 256p. Any ideas?

    Like

  10. I set them all at 300×300 PNG. I believe the CPS1, CPS2 and CPS3 file paths for box art images are not correctly set. I have not checked all the cores but no harm to double check the config file under Emu/CPS1 [or whichever core you are working on]/. Have a look at the file paths for both rom and images. Make sure they are with the correct folder names (case sensitive). After tweaking the file paths I was able to get the CPS1, 2 and 3 box arts shown again. Good luck.

    Like

    1. How does box art work on the miyoo? I havent seen any videos of this on the internet and im wondering if its like a netflix like gallery or you have to press something to show each games art

      Like

  11. I followed this guide and my device bricked. Idk if dragging the TF files BEFORE installing the FW like Russ’s guide says is the culprit but every other guide and official source does not do this in that order. Should’ve paid more attention and just follow the official update process.

    Like

  12. Do you have any guide on how to set the configuration for skraper so i can get the images for my roms or I just need the main image at your mentioned dimension? Now the Miyoo doesnt show the art like lets say the rp2+ does correct? you have to almost manually ask to show the cover art for each game.

    Like

  13. Thank you.

    Can you address how to use fast forward?

    I was able to use the hot keys, but they required me to hold the button. I’m interested in using the toggle function so I don’t have to hold a button down. My B button is pretty shot after holding it down to use as a fast forward hotkey. For some reason it wont let me remap the toggle fast forward… or at least the toggle fu cation isn’t working. I’m playing Pokémon so I’m not sure if it’s the game choice or I need to delete a configuration or what.

    Any advice is appreciated.

    Like

    1. Ok… I figured it out… silly.

      Pressing select and R at the same time will toggle… while just holding R will fast forward as long as you’re holding R. That was simpler than I thought. No need to remap!

      Like

  14. i’m curious if i’ve missed something or someone can tell me what i’m doing wrong. when I download the OnionOS zip file and extract it, i don’t have an App folder. I just have a .tmp_update folder w/ some subfolders within.
    i can’t get Onion installed on my MM.

    Thanks

    Like

  15. Is removing the battery absolutely necessary to upgrade the firmware? I don’t see any mention of this step in the official instructions and I just got the v2 version where the battery is taped and plugged in a pretty tight space and I don’t feel like messing around with it just yet.

    Like

    1. I set it up without upgrading to the latest firmware (mine was delivered with the second to last which is the January one anyway, so fairly recent). Looking forward to the v2 guide that will eventually come out for proper upgrade instructions!

      I played a few minutes with Onion OS menus and decided to give Mini UI a try on a spare SD card and I must say I’m beyond impressed! The way it just gets out of the way and lets you access the games and still allows most common tweaks without being intimidating.

      The Miyoo Mini v2 with Mini UI is the only retro handheld I own (and I have a pretty large collection at this point) that can be used without ever knowing what a hotkey is.

      Like

  16. Hey Russ, I think the install process has changed in the recent past. Instead of copying the “App” folder to the microSD, now you just copy the “.tmp_update” folder to the root of the microSD

    Like

    1. Hi, yes there is a big notice at the top of this page that there is a new process, and I made a whole new guide and video on it! Check it out!

      Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s