Skip to content

Instantly share code, notes, and snippets.

@rleroi

rleroi/Portmaster-TrimUI-Brick-StockOS-Guide.md

Last active July 19, 2026 11:18
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save rleroi/803ee658cd4926fc8a8a0a747950ea53 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save rleroi/803ee658cd4926fc8a8a0a747950ea53 to your computer and use it in GitHub Desktop.
Download ZIP
PortMaster on the TrimUI Brick (Stock OS) — Step-by-Step
Raw
Portmaster-TrimUI-Brick-StockOS-Guide.md

PortMaster on the TrimUI Brick (Stock OS) — Step-by-Step

Get PC game ports (TMNT: Shredder's Revenge, Stardew Valley, Celeste, …) running on a TrimUI Brick with stock firmware. No custom firmware, no soldering, no Linux knowledge needed.

What you need:

  • TrimUI Brick + a microSD card (blank, or one you're willing to wipe)
  • A computer with an SD card reader (Windows/Mac/Linux all fine)
  • WiFi for the Brick
  • Your own copies of the games (Steam/GOG/Epic)

Stock firmware does not include PortMaster. These steps install TRIMUI_EX — a community add-on by kloptops (PortMaster team) that runs from the SD card.

Part 1 — Prepare the SD card

  1. Format the SD card as FAT32. Start blank.
    • Windows: for cards up to 32GB, right-click the drive → Format → FAT32. For larger cards Windows won't offer FAT32 — use Rufus: select the card, Boot selection: "Non bootable", File system: "Large FAT32", Start.
    • Mac: Disk Utility → select the card (the device, not the volume) → Erase → Format: "MS-DOS (FAT)", Scheme: "Master Boot Record".
    • Linux: mkfs.vfat -F 32 /dev/sdX1 (check the device name with lsblk first).
  2. Download the latest Brick firmware from github.com/trimui/firmware_brick — the asset named like firmware_BRICK_tg3040_..._vX.X.X.zip (not the sd_recovery_... one). Extract trimui_tg3040.awimg from it and put that file on the card root.
    • This is a normal file copy — drag and drop like any file. No dd, no balenaEtcher, no disk-imaging tools. The Brick's bootloader finds the file on the card and does the flashing itself in Part 2.
  3. Go to TRIMUI_EX releases and download both files:
    • trimui.portmaster.zip → copy to the card root as-is, do not unzip
    • TRIMUI_EX.zip → unzip its contents to the card root
    • ⚠️ Unzip gotcha: extracting often creates a TRIMUI_EX subfolder. The card root itself must end up containing System/, Emus/, etc. — if you see a TRIMUI_EX folder on the card, move its contents up to the root and delete the empty folder.
  4. (Optional, for retro emulators too) Download TrimUI's SD base package from github.com/trimui/assets_brick and unzip it onto the card as well — same gotcha: its folders (RetroArch/, Emus/, …) must sit at the card root, merging with what's already there.
  5. Mac users: before ejecting, clean the junk files Finder creates: 
    dot_clean -m /Volumes/YOURCARD

Your card root should now contain at least: System/, Emus/, Roms/, Imgs/, trimui_tg3040.awimg, trimui.portmaster.zip.

Part 2 — Flash and first boot

  1. Put the card in the Brick (device off).
  2. Hold POWER + VOL DOWN. When the logo appears, release POWER. When the green progress bar appears, release VOL DOWN.
  3. Wait — firmware flashes, the device reboots, and "Installing TRIMUI_EX …" splash screens run. Takes a couple of minutes. Don't power off.
  4. When the main menu appears: Settings → connect WiFi.
  5. While you're in Settings: set the auto screen-off timer to a long value (some game installs take 15+ minutes and sleep can interrupt them).

Part 3 — Set up PortMaster

  1. Open Apps → PortMaster. First launch downloads the port catalog.
  2. Go to Options → Runtime Manager → download all. This prevents the most common install crash on the Brick.
  3. That's it. Browse the catalog on the device, or at portmaster.games/games.html from your computer.

Ports marked "Ready to Run" need nothing else — install and play. Commercial games need your game files (next part).

Part 4 — Install a commercial game (example: TMNT Shredder's Revenge)

  1. On the Brick: PortMaster → find the game → install. This creates the launcher plus a data folder at Data/ports/<portname>/ on the card.
  2. Read the port's page on portmaster.games — it says exactly which store version works and what to copy.
  3. Get the game files from Steam on any computer (works even on a Mac for Windows-only games). You need the Steam desktop app installed and logged in to an account that owns the game:
    • Open steam://open/console in your browser (allow the "open Steam?" prompt) — Steam opens with an extra Console tab.
    • Type app_info_print <appid> (the appid is the number in the game's store page URL). In the output, find the "depots" section and pick the depot whose "oslist" matches what the port asks for (windows/linux). Depots are usually numbered appid+1, +2, +3.
    • Type download_depot <appid> <depotid>. Wait (no progress bar) — when done, the console prints "Depot download complete" with a folder path.
  4. Put the SD card in your computer and copy the contents of that depot_... folder (not the folder itself) into Data/ports/<portname>/gamedata/.
  5. Mac users: run dot_clean -m /Volumes/YOURCARD again before ejecting.
  6. Card back in the Brick → Games → PORTS → launch the game.

First launch of some ports (TMNT included) converts files for 15+ minutes on a mostly-black screen. Looks frozen — it isn't. Let it finish. Prefer to see the ports in the homepage Ports tab instead of the Games list? PortMaster → Options → Ports Location toggles it.

Part 5 — Bring your PC save games (optional)

  1. Find the save on your PC. Steam cloud saves usually live in Steam/userdata/<your-ID>/<appid>/remote/.
  2. On the card, the port's save folder is Data/ports/<portname>/savedata/.
  3. Rename the existing save there (backup), then copy your PC save files in. Same game + same engine = saves usually just work.

Troubleshooting

Symptom Fix
PortMaster won't start / python errors Reboot with the card in — the "Installing TRIMUI_EX" bootstrap must complete once. Don't delete Apps/PortMaster.
Deleted Apps/PortMaster by accident Re-download both files from TRIMUI_EX releases and redo the update: unzip TRIMUI_EX.zip over the card, trimui.portmaster.zip at root.
Runtime Manager crashes WiFi on → restart PortMaster → let it sit on the main screen a minute → retry.
Port crashes during install/validation Runtime Manager → download all.
Game "frozen" on first launch It's converting files. Wait 15+ min. Disable auto screen-off.
"Encoder not found" / "libtheora" during conversion Harmless — intro video skipped, game unaffected.
Screen off-center / weird resolution Fix inside the game's own display settings, then relaunch.
A/B buttons feel swapped That's Xbox-style mapping (SDL standard). Rebind in-game if it bothers you.
._* junk files everywhere (Mac) dot_clean -m /Volumes/YOURCARD before every eject.

Extras

Hide empty systems in the Games menu: every folder in Emus/ on the card = one system in the menu. The menu ignores folders whose name starts with an underscore. So with the card in your computer, make a folder Emus/_hidden and drag unused systems into it (any file manager works). Drag back to restore. Reboot the Brick to refresh.

SSH / web file manager: stock firmware v1.1.1+ has SSH built in (enable it in Settings; login root/tina). TRIMUI_EX additionally runs a web file manager at http://<device-ip>:8080/ (user trimui, password trimui) and SFTP on port 2022. Either way: no more card shuffling.

Control the RGB button LEDs: download LedController.zip from pierceTee/TrimuiLEDController, unzip, and put the LedController.pak folder into Apps/ on the card. Launch it from the Apps menu to set colors/brightness/effects. Built for stock OS. ⚠️ Remove it only via its built-in uninstall option — deleting the folder leaves its LED service behind, and the LEDs (including the stock Settings LED toggle) stop responding entirely.

Which games can even be ported? Check the engine on PCGamingWiki:

  • FNA/MonoGame/XNA, GameMaker, LÖVE, Godot, AGS, HashLink → good candidates (run natively on ARM)
  • Unity, Unreal, custom 3D engines → not portable, skip
  • No analog stick on the Brick → skip games needing free/twin-stick aim, regardless of engine
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment