Troubleshooting

A symptom-first index for a PICO9918 that is not behaving. Find the symptom as you would describe it, then follow the link to the page that owns the detail.

Start here

Three checks account for most reports.

1. Orientation and seating. The PICO9918 goes into the socket the same way round as the VDP it replaces, pin 1 aligned, fully home. A board one row out, or with a pin folded underneath it, looks exactly like a dead board.
2. The logo. At power-on the firmware slides its own logo into the lower border and leaves it there until the host enables the display. If you can see the logo, the board is running and the video path to your display works, which rules out most of the next section.
3. Device mode. If the VDP you removed was not a TMS9918 or TMS9918A, the PICO9918 needs a matching device mode, applied over USB before it goes in. Chip Variants says which part needs which mode.

Tip

If the host has not enabled the display about 15 seconds after power-on, the firmware switches all four Diagnostic Overlays on by itself. Overlays over an otherwise empty screen are good news: the board is alive and rendering, and it is the host that has never written the display-enable bit, so the fault is on the host side of the socket. They disappear the moment the host enables the display.

Symptom	Where to look
Nothing on the display at all	No video at all
Picture is fine, but the machine is dead or silent	Video, but the host is dead or silent
Machine does not start at all	The machine will not boot at all
Colours wrong, monochrome, or a channel missing	Wrong or missing colour
Lines dropping out, flicker, tearing	Flicker, missing lines, tearing
Screen went black right after an output setting changed	The display went black after I changed an output setting
Configurator ROM will not run	The configurator will not load
Firmware update stopped or reported errors	A firmware update failed

No video at all

No logo, no overlays, nothing.

Warning

The FFC cable goes in contacts facing down. Inserted the other way up the dongle simply does not work, and the connector is a reflowed 0.5 mm-pitch part that is not field-replaceable if it is damaged getting the cable back out. See Hardware Setup for the five-step sequence, including closing the latch.

• Cable not seated, or the latch left open. Push the cable fully home and press the locking tab down until it clicks.
• Wrong output selected. The display driver setting is Auto, VGA/HDMI or SCART, under Output in the Configurator. Forced to SCART with a VGA monitor attached, or the reverse, there is no picture. Auto selects SCART only when a SCART dongle is detected.
• Dongle swapped while powered. SCART detection runs once, at power-on, by testing continuity between HSYNC and VSYNC. Power off to change dongles. See Auto detection.
• A hand-made SCART cable with no RGB select. The 180 Ω resistor to SCART pin 16 lives in the cable, not the dongle. Without it the display stays on the composite signal on pin 20 instead of switching to RGB. See SCART AV Dongle and RGB Mode Enable (Pin 16).
• The display cannot lock to the mode. VGA and HDMI output is 640x480 @ 60 Hz progressive; SCART is interlaced 576i @ 50 Hz or 480i @ 60 Hz. See Video Output Modes.
• An output setting that was changed and then reverted. See the section below.
• A v0.3 board built with a genuine Raspberry Pi Pico. GROMCLK and CPUCLK need GPIO23 and GPIO29, which a genuine Pico does not expose: v0.3 is designed for the DWEII RP2040 USB-C module. See v0.3 (DIY Piggybacked Pi Pico).

Video, but the host is dead or silent

The PICO9918 is clearly working; the machine around it is not. Almost always the GROMCLK / CPUCLK pins.

• A TI-99 that will not boot. GROMCLK is essential on this machine: without it the GROMs cannot be read and the TI-99 does not start. The default device mode drives it on pin 37. A cut GRM jumper, or TMS9118 device mode (which holds pin 37 low), leaves the machine dead. See GROMCLK and CPUCLK.
• A TI-99 with no sound. CPUCLK clocks the TMS9919 sound chip. TMS992xA device mode holds pin 38 low, and a cut CPU jumper disconnects it entirely. See CPUCLK and GROMCLK.
• ColecoVision with Expansion Module 1. The TMS9928A never had CPUCLK, and the module may need the PICO9918 to stop driving it. Select TMS992xA device mode first; cutting the CPU jumper is the destructive fallback. See Expansion Module 1 Compatibility.
• Something else on the host board drives the same net. Device mode only stops the PICO9918 driving the pin. If the signal has to be physically disconnected, use the CPU and GRM jumpers.

The machine will not boot at all

No picture, no host activity, and the board seemed fine on the bench. This is the classic wrong-device-mode signature.

• A TMS9128 or TMS9129 machine left on the default mode. These parts carry CPUCLK on pin 37, not pin 38. On the default mode that pin is driven as GROMCLK instead, and the machine will not boot. Set TMS912x. The Spectravideo SVI-728 is one of these.
• A TMS9118 machine. No GROMCLK, CPUCLK on pin 38: set TMS9118. The Casio MX-10 is one of these.
• You cannot fix it from inside the machine. Device mode is deliberately exposed only in the web configurator, because a machine that will not boot cannot run the ROM configurator. Apply it over USB, then refit the board.

Important

"Reset defaults" in the native configurator clears the device mode back to TMS9918A. The reset writes zero to all 160 configuration bytes and then re-seeds only the 16 palette entries (configtool/src/config.bas:19-27). Device mode is byte 12, and zero is TMS9918A. On a machine that needs TMS992xA, TMS9118 or TMS912x, saving after a reset will stop it booting on the next power cycle. Recover by re-applying the device mode over USB with the web configurator.

Wrong or missing colour

• Everything grey, sepia or otherwise off. A saved palette. The Greyscale, Sepia, EGA and V9938 presets, and any custom palette, live in flash and survive a firmware update. Check the palette in the Configurator: see Palette Presets.
• Colour 0 will not change. Palette entry 0 is forced to black, and entries 1 to 15 have their alpha nibble forced opaque, every time the configuration is written. That is by design.
• A whole channel missing: no red, or no green, or no blue. RGB leaves the board as a 4-bit resistor ladder per channel through the FFC connector, so a dead channel points at the cable, the dongle or the connector rather than at the firmware. Reseat the FFC cable; see Hardware Setup.
• A program changed the palette and left it changed. F18A palette RAM is writable by the host. The stored palette is re-seeded at boot, so a power cycle puts it back. See F18A Compatibility.
• Everything back to defaults for no obvious reason. The firmware resets the whole configuration, palette included, if any stored value is out of range, or if the flash is moved to a different Pico model. See Configuration Storage.

Flicker, missing lines, tearing

• Lines dropping out under busy content. A scanline that overruns its budget is not drawn late; the next one is skipped instead. Overload therefore shows up as missing or stale lines rather than as a slow display.
• Diagnostic overlays are on. They draw on every scanline and cost real render time: on RP2040 the overlay alone is enough to start dropping lines. Turn them off before judging performance. See Diagnostic Overlays.
• Raise the clock preset. 252 MHz is the default; 302.4 MHz and 352 MHz buy headroom. The change takes effect on the next power cycle and goes through the confirmation flow below. See Clock Presets.
• Lower the scanline sprite limit. 4, 8, 16 or 32 sprites per scanline. Four is what the original TMS9918A managed, and sprite work is part of the per-scanline budget.
• Every second line dark. That is the CRT scanlines option doing its job. Turn it off in the Configurator.
• Interlace flicker on SCART. The 576i and 480i modes are interlaced with no line doubling, so fine horizontal detail flickers by design. See SCART Output Reference.
• The dropped-frame term behind the FPS row is not a renderer problem. There is no dropped-frame row on the overlay; the count only scales FPS, and a "dropped frame" there is a frame the host never acknowledged. See Performance Overlay.

The display went black after I changed an output setting

Nothing here can strand you, and this is worth reading before you change one of these settings rather than after.

Four settings are held back when you save them: Driver (Auto / VGA / SCART), VGA/HDMI mode, SCART mode and Clock frequency. Saving any of them writes the new values into a separate flash block and leaves the main configuration holding its last confirmed values.

1. You save the change. The screen shows POWER CYCLE TO TEST NEW CONFIGURATION. The setting is not live yet.
2. First power cycle. The pending values are applied and the block is marked armed. The screen shows OPEN CONFIGURATOR TO CONFIRM NEW SETTINGS.
3. Open the configurator. After its firmware-version check it asks Display change OK? before any menu appears. Confirm writes the values into the main configuration and erases the pending block. Cancel erases it immediately: the session you are in keeps running, and the old values come back on the next boot.
4. Do nothing. The second power cycle erases the pending block by itself, and the last confirmed settings return.

Tip

So if a new output setting leaves you with no picture: power-cycle once more. Nothing is bricked, nothing needs reflashing, and losing power part-way through the save still reverts cleanly, because the pending block is written before the main configuration.

Applying a configuration over USB with the web configurator writes both blocks: the generated UF2 is four 512-byte blocks, a configuration block and a pending block for each of the RP2040 and RP2350 family IDs.

The configurator will not load

• PICO9918 not found. The ROM probes for a PICO9918 by unlocking F18A mode and running a small TMS9900 program on the on-board GPU. If it finds nothing F18A-compatible at all it adds PICO9918 firmware too old / Firmware v1.0+ required and points you at a USB update. See VDP Detection.
• FIRMWARE OUT OF DATE. The ROM refuses to run against firmware older than the firmware it carries, and shows both versions. A full-tier ROM (TI-99, ColecoVision, MSX) updates the board for you and then asks for a power cycle; a lite ROM (SG-1000, NABU) tells you to update over USB and stops. No CreatiVision ROM ships yet: a lite one is planned for v1.2.1. See Supported Platforms.
• TI-99: the ROM needs the 32KB Memory Expansion. Loading it without one gets you nowhere.
• MSX: wrong mapper. ASCII16 is the more widely compatible build; try the Konami build if your flash cart prefers it. See MSX Configurator.
• Looking for device mode and not finding it. It is web-only on purpose, so it cannot be changed by accident from inside a working system.

A firmware update failed

• New firmware data is invalid, before anything is written. The ROM verifies every UF2 block in its own banks first (bank markers, block start and end magic, block sequence) and reports the bank and block that failed. That is the cartridge image or the cart, not the board. Re-download the ROM from Releases and reseat the cartridge.
• Blocks marked as failed during the write. The firmware returns an error code per block and the ROM marks that cell in the progress grid. The board may be left half-written.
• Recovery is always the same. The update path only ever writes the first 256 KB of flash (the firmware rejects any UF2 block targeting outside it) so holding BOOT and dropping a release UF2 on the USB drive always gets you back to a working board. See Installing Firmware.
• Wrong image for the silicon. A pico9918pro- UF2 is RP2350 only. The combined UF2 covers both, and the combined configurator ROM picks its payload from the processor family it detects.
• Nothing changed after the update. A cartridge update ends with REBOOT REQUIRED: power-cycle the host to load the new firmware.
• On v1.2 and older, take the board out before connecting USB. v1.3 and newer, PRO included, can be updated in place with the host powered off.
• Settings after an update. They are kept, except when the flash moves to a different Pico model or a stored value is out of range. Settings introduced by the newer firmware are written at their defaults.

Still stuck

• Turn on the Diagnostic Overlays. The performance panel reports hardware version, firmware version, system clock and the active output driver: what the board thinks it is, rather than what you think you configured.
• Read the configurator's Device info page. Processor family, hardware version, firmware version, display driver, resolution, F18A version and core temperature, all reported by the board itself.
• Suspect the host bus? Host Bus Timing covers the read and write cycles against the TMS9918A datasheet, including Glitch rejection.

Caution

On a self-built board, run the QC loopback test before spending time on the firmware. It answers the one question no software test can, which is whether this board is wired the way the schematic says. test/qc/ builds pico9918qc, a standalone UF2 that replaces the firmware on the board under test: three jumpers tie CPUCLK to /CSR, GROMCLK to /CSW and /INT to MODE, and it drives one end while reading the other, reporting over USB serial. Flash the real firmware back afterwards. test/host/ builds pico9918test, which answers "does this board talk to a host at all" using a second Pico in place of the host CPU.

Still nothing? Ask on the AtariAge thread or open an issue on GitHub. Include the hardware and firmware versions from the performance overlay or the Device info page, the machine, the original VDP part number, and which output you are using.

Related

• Hardware Setup: FFC cable insertion, the CPU and GRM jumpers, and the MDE1 pin
• Device mode configuration: matching GROMCLK and CPUCLK to the VDP you removed
• Diagnostic Overlays: the four on-screen panels and what every field means
• Configurator: the native ROMs, the web configurator, and which platform gets which tier
• Firmware: installing, updating, output modes and clock presets
• Supported Devices: every tested machine, its VDP variant and its configurator tier
• Host Bus Timing: read and write cycles measured against the TMS9918A datasheet
• Building from Source: build-time problems, which are a different kind of troubleshooting