iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
A tiny DOOM port can fail at four different layers: the computer may not compile the source, the board may reject the UF2, the firmware may boot without its separate game data, or the display build may not match the screen revision. Identify which layer is failing before changing files. The instructions below fit the Smallest-Doom RP2040 builds and the Thumby-oriented port most closely, but the title alone does not identify a particular console or release.
First identify what is actually failing
Write down the device label, board revision, port or release name, and the exact point at which the process stops. A Thumby, an RP2040 Zero with an SSD1306 OLED, and another small RP2040 console can use different binaries, display drivers, and data-loading addresses. A fix for one is not automatically safe for another.
| Symptom | Most likely layer | First check |
|---|---|---|
| The compiler or CMake stops on the computer | Build environment or board configuration | ARM compiler, Pico SDK paths, pico-extras checkout, and the selected board |
| The build completes, but the board does not accept the file | Flashing procedure or wrong UF2 | BOOTSEL mode and the UF2 intended for that exact hardware and release |
| Flashing completes, but there is no game or only a black screen | Missing or mismatched game data, firmware variant, or display driver | WHX/WHD pairing, target address, and display-specific UF2 |
| An image appears but is torn, shifted, or out of sync | Display timing or driver | Screen revision, SPI variant, and a separate display test |
The phrase “won’t run” is therefore not a diagnosis. Keep the first compiler error, the board name, the firmware filename, and whether a converted data file was installed. Those details prevent instructions for a native desktop build from being mixed with an RP2040 build.
Confirm the port and hardware before rebuilding
The closest documented match is GorGylka’s Smallest-Doom repository, which targets RP2040 hardware, including an RP2040 Zero configuration. A separate TinyCircuits forum thread describes a DOOM port adapted for the Thumby screen. Neither source establishes that every device sold under a similar description uses the same release.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
- Read the label printed on the board or inside the console and record the exact model and revision.
- Record the release page or archive name, not just the game title. Display-specific filenames are meaningful.
- Decide whether you are compiling from source, flashing a supplied UF2, or installing a converted WAD. These are separate operations.
- If the device is a DIY RP2040 build, note its flash capacity and display controller or wiring. The 2 MB and 8 MB firmware families have different data requirements.
If you cannot identify those four items, stop before copying a UF2. The safest next step is to obtain the error text, console revision, release name, and failure stage from the person who assembled the device.
Fix a source-build failure on the computer
Smallest-Doom’s RP2040 target is a cross-compilation project. Its documented prerequisites include CMake, the Raspberry Pi Pico SDK, current pico-extras, and an ARM bare-metal compiler such as arm-none-eabi-gcc. The repository’s example invocation passes PICO_BOARD, PICO_SDK_PATH, and PICO_EXTRAS_PATH; use those variables with the values for your own checkout rather than copying a command intended for another board.
Make a clean, reproducible check
- Save the complete first error, operating system, compiler version, SDK branch or commit, and intended board. Later errors are often consequences of the first one.
- Verify the tools are on the path. Running
cmake --versionandarm-none-eabi-gcc --versionshould return versions instead of a command-not-found error. - Check that
PICO_SDK_PATHpoints to the Pico SDK checkout used by the project and thatPICO_EXTRAS_PATHpoints to the matching pico-extras checkout. A path to an empty directory or to a different SDK family can produce misleading CMake failures. - Configure a new build directory with the repository’s documented CMake command, supplying the board value and both SDK paths explicitly. Do not reuse a cache created for another board.
- Inspect the first meaningful CMake or compiler diagnostic. Fix that item, delete the build directory, and configure again before interpreting later messages.
The project says it was built against the Pico SDK develop branch and warns that compiler versions other than arm-none-eabi-gcc 9.2.1 can create binary-size problems. That is maintainer guidance for this project, not a general rule that current ARM toolchains are invalid. If a newer compiler builds an image that is too large, reproduce the project’s stated toolchain in an isolated environment rather than randomly changing optimization flags.
Initialize the USB-keyboard dependency only when needed
The USB-keyboard target uses the TinyUSB submodule included by the repository. From the repository root, initialize submodules with:
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
git submodule update --initRun this when the selected target actually includes USB keyboard support. It will not repair a bad board selection, a missing WAD, or a display timing mismatch. If the submodule command itself fails, record the Git error and confirm that you are in the correct checkout.
Do not install SDL2 for the wrong target
The repository also documents ordinary native Chocolate Doom builds, which use SDL2 dependencies. That path is distinct from the RP2040 cross-build. Installing SDL2 cannot fix an RP2040 CMake error unless you intentionally selected the native desktop target. First inspect the target name and CMake configuration; only then install dependencies required by that target.
Pair the executable, data format, and flash address
A successful UF2 copy does not prove that DOOM’s game data was installed. The RP2040 documentation describes UF2 files as containing executable code and data but not the converted WAD payload. The payload is a separate WHX or WHD artifact that must be placed at the address expected by the selected firmware. Mixing a filename, format, or address from another variant can produce a silent boot or black screen.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →| Documented target | Data format | Data address | Typical flash requirement | USB keyboard |
|---|---|---|---|---|
doom_tiny |
WHX | 0x10040000 |
2 MB configuration | No |
doom_tiny_usb |
WHX | 0x10042000 |
2 MB configuration | Yes; the project reports about 2 KB of additional binary growth |
doom_tiny_nost |
WHD | 0x10048000 |
8 MB configuration for larger WADs | No |
doom_tiny_nost_usb |
WHD | 0x10048000 |
8 MB configuration for larger WADs | Yes |
These addresses belong to the variants documented by the project repository. Treat them as target-specific constants, not as a general RP2040 rule. Follow the exact installation instructions for the binary you selected; do not load WHX at the WHD address or assume that a USB build uses the non-USB address.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Understand WHX versus WHD
WHX is the highly compressed, “super-tiny” format intended to run shareware DOOM1 data on a 2 MB Pico configuration. Larger Ultimate Doom and Doom II WADs need the less-compressed WHD format and more flash. The maintainer states that those larger WADs are too complex for WHX and will not fit in 2 MB. The whd_gen documentation also says support for non-id WADs is not guaranteed.
Use game data that you are legally entitled to use. The technical port and its conversion tools do not imply that commercial WAD files are included. If conversion succeeds but the game still does not start, verify that the output format matches the firmware and that the converted file was written to the documented address.
Flash the Thumby-oriented release in the documented order
An older Smallest-Doom release describes a specific sequence for an RP2040 Zero and Thumby-oriented display files. It is release-specific, so do not apply it blindly to another revision.
Free tools Windows power users keep installed
One-click scans. No signup required.
- Put the RP2040 board into BOOTSEL mode.
- Copy the release’s
thumby-doom.uf2file to the mounted board. - Allow the board to reboot, then enter BOOTSEL mode again.
- Try the release’s four
doom_tiny_spi.....uf2display variants according to the internal display specifications. - The release author reported
doom_tiny_spi62000000_fp6100_pl2.uf2working on the author’s setup. This is not proof that it suits every Thumby revision. - If the display remains blank, the release instruction is to start the whole process again, including the BOOTSEL steps, rather than merely copying another display file over the previous one.
The release notes are available from the project’s GitHub releases page. The page is an older release source; verify that the filenames belong to the release you actually downloaded.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
When flashing succeeds but the screen stays blank
“Nothing on the display” can mean missing data, an incompatible display build, or a failure before the renderer starts. The Thumby maintainer notes that doing nothing at boot can indicate a missing data file, among many other possible problems, and that this build provides no debug output. Use the following order so a display experiment does not hide a data-installation error.
1. Recheck the executable and data as a pair
- Confirm the exact UF2 filename and target variant.
- Confirm whether that variant requires WHX or WHD.
- Confirm that the data was loaded at that variant’s documented address.
- Confirm the flash capacity is sufficient for the selected WAD and firmware family.
A firmware copy that completed normally can still leave the game unable to start if the payload is absent or at the wrong address.
2. Use the release’s display-specific build
Thumby-oriented releases provide multiple SPI, timing, or panel variants because the same nominal screen can require different initialization values. Choose from the files listed by that release, not from a similarly named file in another archive. If you do not know the panel revision, identify the hardware before trying to tune timing.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errors3. Test the screen independently
The forum troubleshooting advice recommends restoring Thumby firmware and running the uGrey greyscale test, greytest.py, to check display compatibility. This separates a screen-driver problem from DOOM’s data-loading path. Restore the normal firmware first, run the test exactly as documented for your device, and record whether the display is stable.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
4. Treat timing reports as experiments, not guarantees
One forum user reported visible desynchronization at one timing and a better result around 6100. That is a single-device observation, not a universal setting. Change timing only after data pairing and the independent display test are correct, and change one parameter at a time. Keep the original UF2 so you can return to a known state.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Diagnose a distorted or desynchronized image
If the game image appears but is shifted, torn, or unstable, the boot path and data may already be working. Concentrate on the display driver, SPI frequency, panel initialization, and timing variant. Compare the symptoms with the release’s display filenames and internal display specification rather than changing the WAD address.
- A completely black screen after a known-good display test points first to firmware/data pairing or an incompatible UF2.
- A stable but incorrectly oriented or offset image points to panel configuration.
- Intermittent tearing or desynchronization points to timing or SPI settings.
- A screen that works in the greyscale test but not in DOOM still requires checking the DOOM release’s display-specific build; the independent test does not prove that every game driver is compatible.
Because the Thumby build has no debug output, a serial log cannot be assumed. Record the exact filename, timing value, and hardware revision whenever you report the issue so another person can reproduce the same combination.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Common compile and configuration mistakes
| Message or behavior | Cause to check | Correction |
|---|---|---|
| CMake cannot find the Pico SDK | PICO_SDK_PATH is unset or points to the wrong checkout |
Set the path to the intended SDK, remove the cached build directory, and reconfigure |
| Headers or extras are missing | PICO_EXTRAS_PATH is absent or mismatched |
Point it to the matching pico-extras checkout used by the project |
| No ARM compiler is found | arm-none-eabi-gcc is not installed or is not on the path |
Install the ARM cross-compiler required by your operating system and verify it with --version |
| The wrong board is configured | The PICO_BOARD value or cached CMake configuration targets different hardware |
Use the board value documented for the release and configure a fresh build directory |
| USB target files are missing | TinyUSB submodule was not initialized | Run git submodule update --init in the repository root |
| The image builds but is too large | Compiler version or target selection differs from the project’s documented setup | Compare the toolchain with the maintainer’s 9.2.1 guidance and confirm that you did not select a larger target accidentally |
| An SDL2 error appears while targeting RP2040 | The native Chocolate Doom path was selected | Return to the RP2040 target configuration instead of adding desktop SDL2 packages |
What the project claims about size and speed
The Smallest-Doom documentation reports approximately 30–35 or more frames per second, but this is a project claim rather than an independent benchmark. It describes a 2 MB flash configuration for the super-tiny WHX build and an 8 MB configuration for larger WHD data. USB support is described as adding roughly 2 KB to the binary. These figures depend on the selected target, compiler, display, and game data, so they are useful capacity checks, not a promise for every assembled console.
A practical recovery checklist
- Identify the console, board revision, release, and failure stage.
- For a source error, verify CMake,
arm-none-eabi-gcc, Pico SDK, pico-extras, and the intendedPICO_BOARD. - Initialize TinyUSB only for the USB-keyboard target.
- For a flash error, return to BOOTSEL and use the UF2 made for that hardware.
- For a blank boot, pair the exact firmware with its WHX or WHD file and documented address.
- Check flash capacity before attempting a larger WAD.
- For Thumby, try the release’s display-specific UF2 sequence, then run the independent uGrey test on restored firmware.
- Change timing only after the data and display paths have been verified, and treat any value reported by another user as hardware-specific.
This sequence keeps the four failure layers separate. It also explains why repeatedly copying a different UF2, without checking the data format or address, often produces the same “black screen of doom.”
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
