Display troubleshooting

Blank screen or “no signal”#

Most blank-screen reports come down to one of three causes:

Wrong orientation#

Rotation is applied in two places — the software rendering layer (wlr-randr, instant) and the Pi firmware (/boot/config.txt, applied on boot). The admin UI updates both for you.

1. 1
   Open the Players page

   Navigate to Admin → Players. Each Player card has a rotation button.

2. 2
   Pick the new orientation

   Landscape (0°), portrait (90°), inverted landscape (180°), or portrait-reversed (270°). The change applies live via wlr-randr — you’ll see the TV flip within a second.

3. 3
   (Optional) Verify the config persists through a reboot

   Reboot the Player from the same page to confirm the new orientation sticks. The orchestrator writes /boot/config.txt on its way down so firmware-level rotation matches.

Black bars or wrong aspect ratio#

If the menu has pillarboxed black bars on the sides, the issue is usually the template, not the display. Templates target a specific aspect ratio per layout.

• Go to Admin → Screens and check the screen’s aspect mode. Options are fit, fill, and stretch.
• Fit preserves aspect ratio and may pillarbox.
• Fill crops instead of pillarboxing.
• Stretch ignores aspect ratio (rarely what you want).

If the whole desktop is the wrong resolution (admin UI looks squashed too), the TV is likely reporting a weird EDID. Reboot the Pi with the TV already on, and it will re-negotiate the resolution at boot.

Flicker, tearing, or choppy video#

• Flicker: almost always the HDMI cable. Swap it for a known-good cable — long or cheap micro-HDMI cables are especially prone.
• Tearing on video playback: check the video is H.264/AAC (see video formats below). Non-H.264 video is decoded in software and stutters on a Pi.
• Choppy transitions: the dwell/cross-fade timings are configured per screen. Try raising dwell on Admin → Screens — very short dwells (under ~2 s) give the Pi no time to preload the next page and cause jitter.

TV won’t turn on or off (HDMI-CEC)#

Blazeboard can power your TV on/off over the HDMI cable (HDMI-CEC), and it can do so on a schedule. When this works, you don’t need a separate smart plug. When it doesn’t, 95% of the time it’s a TV setting.

1. 1
   Check CEC is enabled on the TV

   Sony	BRAVIA Sync — Settings → Preferences → BRAVIA Sync → HDMI Control → On
   Samsung	Anynet+ — Settings → General → External Device Manager → Anynet+ → On
   LG	SIMPLINK — Settings → Advanced → Connection → HDMI Device Settings → SIMPLINK → On
   Vizio	CEC — Settings → System → CEC → Enable
   TCL / Roku	Settings → System → Control other devices (CEC) → both checkboxes on

2. 2
   Pair the TV in the admin UI

   Go to Admin → TV Control, click Scan for TVs. You should see your TV’s vendor detected. If you see Unknown, CEC is passing through the cable but the TV is reporting a non-standard vendor; manual power controls will still work.

3. 3
   Set a schedule (optional)

   The TV Control page lets you set an on/off schedule — e.g. on at 08:30 and off at 22:00. The orchestrator runs the schedule regardless of whether the admin UI is open.

Player is offline in the dashboard#

Every Pi reports a heartbeat roughly every 60 seconds. The admin UI and the cloud dashboard classify status like this:

When a Player goes red, the most common causes (in order) are: the store Wi-Fi dropped, the HDMI cable is disconnected so the Player is sleeping CPU-idle with no heartbeat, or the Pi’s power was unplugged. From Admin → Players you can reboot the Player, restart its kiosk, or reload its URL without needing physical access.

Kiosk crashes or reloads on its own#

The orchestrator runs a watchdog that catches kiosk failures and escalates — so you’re rarely left with a black screen for long. The escalation ladder is:

• Monitoring — baseline; health check every few seconds.
• Restart kiosk — Chromium died; the watchdog relaunches it.
• Restart container — Chromium keeps dying; the watchdog restarts the app container.
• Reboot — container restart didn’t help; the Pi reboots. This is rare.

If you’re seeing reboots more than once a day, open a ticket. It’s almost always one of three things: insufficient power supply, a malformed video asset that stalls the decoder, or low disk space. Admin → System → Housekeeping lets you reclaim space and rotate logs if disk is the issue.

Unplayable video uploads#

The Pi’s hardware decoder supports H.264 (video) and AAC (audio). Blazeboard converts uploads to these formats at upload time, but a few edge cases trip it up:

• Videos over ~500 MB — upload may time out on slow Wi-Fi. Reduce resolution or bitrate before upload.
• HEVC/H.265 videos — transcoded on upload, but the process is slow. Expect a multi-minute wait.
• 4K source — Pi 4 is bound to 1080p output. 4K sources are downscaled; no 4K output is ever sent to the TV.
• Vertical 9:16 for portrait screens — make sure you rotate the screen (see rotation) rather than uploading rotated video.

Supported output is 1080p @ 60 Hz, with H.264/AAC containers (MP4 or MOV). Anything else is best effort.