TV-Top Kiosk Firmware

Technische specificaties

De firmware produceert een output van 1920x1080 bij 30 Hz in volledige 8-bit-per-kanaal kleur, zonder framebuffer en zonder externe videohardware. Aangezien een 1080p-frame bij 24-bit bijna 6 MB groot is en de RP2350 slechts 520 KB geheugen heeft, wordt er geen volledig frame in het geheugen bewaard. Elke scanlijn wordt vlak voordat de straal deze bereikt (zes lijnen van tevoren) opgebouwd als een run-length HSTX command stream, gebaseerd op vectorgeometrie die in het flashgeheugen is gecachet.

De HSTX-serialisator van de RP2350 is gespecificeerd voor 300 Mbit/s per pin. Voor 1080p30 is 744 Mbit/s nodig, waardoor het systeem draait op 372 MHz met de kernregelaar op 1,30 V. Raadpleeg docs/HARDWARE.md voor de kloktabellen, de overclocking en de bijbehorende problemen met wifi-interferentie.

Zelf bouwen

Er is geen aangepaste hardware vereist. Je hebt enkel een Raspberry Pi Pico 2 W nodig, een manier om acht GPIO's op een HDMI-connector aan te sluiten en een televisie.

Er zijn twee configuraties mogelijk, passend bij de twee revisies van de aangepaste printplaat:

Configuratie	Radio	Extra onderdelen
Optie 1	De on-board cyw43 van de Pico 2 W	Geen
Optie 2	Een ESP32 via een UART	Een ESP32-C3 DevKitM-1

Optie 1 is de eenvoudigste build. Optie 2 verplaatst wifi, de IP-stack en TLS naar de ESP32; dit is de configuratie die wordt gebruikt op de v3-board en waarop het 1080p-werk is ontwikkeld. De bedrading en de ESP-IDF build staan beschreven in docs/MODEM.md.

Opmerking: Een Pico W (RP2040) kan deze firmware ook draaien door DVI aan te sturen via PIO in plaats van HSTX, maar deze haalt een resolutie die ruim onder de 1080p ligt.

HDMI-uitgang realiseren

Er worden vier differentiële paren (acht GPIO's) gebruikt. De positieve lijn van elk paar is de lagere GPIO, waardoor er niets geïnverteerd hoeft te worden:

Signaal	+	−
D0, blauw	GPIO12	GPIO13
Clock	GPIO14	GPIO15
D2, rood	GPIO16	GPIO17
D1, groen	GPIO18	GPIO19

Dit is dezelfde pinout als picosockcfg van libdvi, die door de meeste Pico DVI-breakouts wordt gevolgd. Geschikte hardware is onder andere een HSTX-naar-DVI-adapter, een Pico DVI Sock, een eenvoudige HDMI-breakout-board of direct gesoldeerde draden.

Optioneel kan DDC worden aangesloten op GPIO4 (SDA) en GPIO5 (SCL). Hiermee kan het edid console-commando uitlezen welke modi het display daadwerkelijk ondersteunt, wat de snelste manier is om te achterhalen waarom een TV een bepaalde modus weigert. Video werkt ook zonder DDC.

Waarschuwing over bedradingskwaliteit: Bij 1080p transporteert elke lane 744 Mbit/s vanuit 3,3 V CMOS-pinnen. Jumper-draden op een breadboard volstaan voor een beeld bij 480p60 en kunnen waarschijnlijk 720p60 aan, maar 1080p vereist korte, strak gepaarde verbindingen en een korte HDMI-kabel. Begin bij 480p60 om te bevestigen dat er beeld is, en werk vanaf daar omhoog.

Snelstart

Installeer de Pico SDK (2.2.0 of later), de Arm GNU toolchain, cmake, ninja en picotool.

Build voor Optie 1

cmake -S . -B build -G Ninja -DPICO_BOARD=pico2_w -DKIOSK_TLS=ON -DKIOSK_VIDEO_MODE=1080p30
cmake --build build
picotool load -f build/tvtop_kiosk.uf2 && picotool reboot

Build voor Optie 2

Bij deze optie beëindigt de ESP32 de TLS, waardoor deze firmware geen mbedTLS nodig heeft:

cmake -S . -B build -G Ninja -DPICO_BOARD=pico2_w -DKIOSK_MODEM=ON -DKIOSK_VIDEO_MODE=1080p30
cmake --build build
picotool load -f build/tvtop_kiosk.uf2 && picotool reboot

Geheugenbeperkingen: Optie 1 bij 1080p met TLS is de meest krappe configuratie; er blijft ongeveer 48 KB van de 520 KB van de RP2350 over voor de heap, terwijl een mbedTLS-handshake 30 tot 40 KB vereist. Als de server niet bereikt kan worden, schakel dan over naar -DKIOSKVIDEOMODE=720p60 (wat ongeveer 140 KB aan line pool vrijmaakt) of gebruik Optie 2, waarbij TLS op de ESP32 draait en er ongeveer 79 KB overblijft.

Eerste boot en configuratie

Bij de eerste boot heeft de kiosk geen wifi-gegevens. Hij start daarom een open access point genaamd TVTOP-xxxx en toont deze naam op de TV. Maak verbinding met je telefoon, open de setup-pagina, kies je netwerk en druk op Save. Volledige details staan in docs/PROVISIONING.md. Daarna registreert de kiosk zich bij de server en toont een koppelingscode op de TV die in de app moet worden ingevoerd.

Videomodi

De videomodus kan worden ingesteld met -DKIOSKVIDEOMODE= tijdens het build-proces, of via het USB-seriële console-commando mode <naam> gevolgd door een reboot. Deze instelling wordt in het flashgeheugen bewaard.

Modi voor de Pico 2 W (RP2350, HSTX):

Mode	Output	clk_sys	Notities
720p60	1280x720, CEA VIC 4	372 MHz	De veilige standaardwaarde
1080p30	1920x1080, CEA VIC 34	372 MHz	Vereist een sink die 33,8 kHz lijnrate accepteert
1080p25	1920x1080, CEA VIC 33	372 MHz	Voor TV's die niet boven de 30 kHz gaan
1080p24	1920x1080, CEA VIC 32	372 MHz	Idem
960x540p60	960x540	351-372 MHz	Terugvaloptie bij slechte kabel of chip
480p60	640x480	252 MHz	Mildste overclock, breedste compatibiliteit

Omdat de kiosk alleen opnieuw tekent wanneer de speltoestand verandert, is er in het gebruik geen zichtbaar verschil tussen 30 Hz en 60 Hz. Indien er geen beeld is, raadpleeg dan de checklist in docs/HARDWARE.md. De meest voorkomende oorzaken zijn een TV die de timing weigert of een te lange HDMI-kabel.

Serverconfiguratie

Standaard communiceert de kiosk met https://kiosk.tvtop.games. Dit kan worden overschreven tijdens het bouwen met -DKIOSKSERVERBASE=, via de setup-pagina, of met het commando server <url> in de seriële console. De tekenoperaties die de kiosk implementeert zijn gedocumenteerd in docs/RENDERING.md. De protocolspecificatie en de server zelf zijn niet open source.

Documentatie

• ARCHITECTURE.md: Hoe de onderdelen samenwerken en de achterliggende beperkingen.
• BUILD.md: Build-opties en flashen.
• HARDWARE.md: Bedrading, videomodi, overclocking en wifi-interferentie.
• RENDERING.md: Tekenoperaties en rasterisatie van frames.
• NETWORK.md: Long poll, backoff en TLS.
• PROVISIONING.md: Eerste boot, setup-portaal en seriële console.
• MODEM.md: De ESP32 wifi-modem gebruikt door de aangepaste board.
• FONTS.md: Tekstrendering.

Gebruikte libraries en componenten

• PicoDVI (Luke Wren): Gebruikt via vendor/libdvi voor video op het RP2040-pad.
• pico-examples: Voor de DHCP-server gebruikt door het setup-portaal.
• stb: Voor font-rasterisatie.

Licenties

Het project valt onder de MIT-licentie, met uitzondering van de volgende onderdelen die hun eigen (permissieve) voorwaarden behouden:

• vendor/libdvi: BSD 3-Clause (Luke Wren)
• vendor/pico-examples: BSD 3-Clause (Raspberry Pi Trading Ltd)
• vendor/stb: MIT of public domain (Sean Barrett)
• tools/fonts/*.ttf: Apache 2.0 (Google). De bestanden src/common/font_blob.c en assets/fonts.bin zijn hieruit gegenereerd.