When the picture rolls
The following symptoms occurred on the development machine. Use them to diagnose problems with the picture, connection or emulator.
For picture problems, start with sync, RGB blanking and connector leasing in the first three sections.
The picture rolls vertically
If the image is recognisable but moves continuously up or down, check composite sync. Changing modeline timings will not fix a missing vertical sync signal.
The television expects combined horizontal and vertical sync. The RGB-Pi 2 starts with horizontal sync only. OmaCRT selects composite sync over the HDMI control bus and must repeat this after every converter power cycle.
Try both combining modes on an unfamiliar television. The Bang & Olufsen used here locks to one; broadcast monitors often use the other. Once configured, OmaCRT applies the selected mode during the television’s startup sequence.
The picture is sharp and black and white
Check pin 16, the RGB blanking pin. It needs a volt or two to select RGB input. Without that voltage, the television can remain in composite mode and show only luminance. Check that the converter or adapter drives this pin. See the converter chapter.
Hyprland has kept the connector
If the television stays dark and the connector is unavailable for leasing, check these two causes. The kernel flag can be correct while Hyprland still holds the output.
A Hyprland monitor rule may claim the connector. Search your configuration for both the connector name and the converter’s description string. Rules often match the description. Remove the matching rule, then reboot. Reloading is insufficient because Hyprland retains its decision about the connector.
The non-desktop override must be applied before Hyprland starts. If you applied it manually after login, reboot. The boot-time service applies it early enough for Hyprland to offer the connector. A set flag alone does not prove that leasing is available in the current session.
The picture jumps briefly
The tested RGB-Pi 2 revision has a phase-locked-loop decoupling fault, reported by RetroRGB and acknowledged by the vendor. OmaCRT monitors the lock register and resets the converter when lock drops. The vendor’s system image uses the same workaround. This recovers the output but does not repair the hardware.
The picture turns blue or loses sync
Competing traffic on the converter’s control bus can cause incorrect register reads or writes.
The display data channel that carries the converter's control interface is also the channel a desktop uses to ask a monitor about its brightness. Omarchy's shell probes every such channel for that purpose, including this one, so its traffic interleaves with the launcher's own reads. Registers are therefore read in a single transaction instead of as a page select followed by a read. The launcher also takes a lock on the bus, so its own users cannot interleave with each other.
A converter reset clears the sync-combining setting, so it is used only as a last resort. Writing an invalid value back to that setting can turn the picture blue.
The picture goes black during a game
The display process owns the leased connector. The launcher, emulator and video player connect to it as Wayland clients. If the display process exits, those clients lose their display and the television goes black.
omacrt on starts a watchdog. After a display failure, it restores the display process, timing, converter sync and launcher within a second. It stops after three restarts in two minutes. If the picture remains black, read the watchdog log for the reason before trying again.
Games are killed after seconds or minutes
A game may be killed abruptly while the same game runs normally from a terminal. In the failure seen here, the launcher recorded the kill, but there was no crash dump or system-journal explanation.
The launcher’s audio library loaded a realtime module that set a 200 millisecond limit on uninterrupted realtime execution. This allowed the system’s realtime broker to grant priority to its audio thread. Child processes inherited the limit and could not raise it. When the broker also gave the emulator’s audio thread realtime priority, 200 milliseconds without sleeping caused the kernel to kill the emulator.
OmaCRT sets an environment variable to select a different audio backend for the launcher. That backend leaves the process limits unchanged.
The emulator crashes when a game ends
Several cores crashed while unloading a second run-ahead instance. OmaCRT therefore uses single-instance run-ahead. It also avoids sending a termination signal to an emulator that is already shutting down, which caused another exit-time crash.
A 480i mode gives a narrow strip in the middle
This is the stock-kernel interlace limitation described in The signal. The driver accepts the timing and the converter stays locked, but the output is scanned progressively at half the intended field rate. Working interlace requires kernel patches. OmaCRT uses 240p for these consoles instead.
The launcher says something is playing when nothing is
An emulator may have survived after the launcher stopped. The init system adopts it, and it can keep the audio device open. OmaCRT detects the running emulator and refuses another launch.
Use omacrt doctor to find orphan processes and omacrt doctor --fix to remove them. OmaCRT also checks when the television is switched on or off, and once a minute while it is on. It identifies its emulators by the OmaCRT configuration on their command line. An emulator is considered orphaned only when no launcher is above it in the process tree. Other processes are left alone.
Logs
Check four logs in OmaCRT’s state directory: the launcher log, current game output, display-process log and watchdog log. Each emulator run replaces the game log. The launcher records every game’s exit status, which can reveal a kill even when other logs have no entry.