Video Alarm Clock

De Video Alarm Clock beschikt over een touchscreen van 720×720, een ingebouwde luidspreker, alarms die bestand zijn tegen stroomuitval en Wi-Fi updates. Het apparaat draait op een Waveshare ESP32-P4 touch display en speelt video's af vanaf een microSD-kaart. Eenmaal geflasht en verbonden met Wi-Fi, kun je media toevoegen en alarms beheren direct vanaf het apparaat.

Deze repository bevat de installatiebestanden en de procedure. De inhoud is verdeeld over de volgende mappen:

  • firmware/: De firmware-binaries en een installer die met één commando werkt.
  • video/: Een container die videobestanden converteert en uploadt.
  • enclosure/: De printbare houder voor op het nachtkastje.

Zodra de firmware is geïnstalleerd, kan de klok zichzelf via Wi-Fi bijwerken via: tandwiel-icoon → About → Check for updates. In principe is de kabel slechts één keer nodig.

Vereisten

Hardware

  • Waveshare ESP32-P4-WIFI6-Touch-LCD-4B: 720×720 MIPI-DSI paneel, GT911 touch, ES8311 audio codec, 32 MB flash, 32 MB PSRAM. Zie: [https://www.waveshare.com/esp32-p4-wifi6-touch-lcd-4b.htm]
  • Let op: De firmware is getest op ESP32-P4 revisie v1.3. De firmware is gebouwd voor revisies v1.00 tot en met v1.99, dus andere v1.x onderdelen zouden moeten werken, maar v1.3 is de enige versie waarop het daadwerkelijk is gedraaid. Indien een revisie niet wordt ondersteund, geeft de flasher dit duidelijk aan: "requires chip revision in range ... this chip is revision ...".
  • USB-C kabel: Voor verbinding met de UART-poort van de printplaat.
  • microSD-kaart: Geformatteerd als FAT32. Video's worden hier opgeslagen en niet in het flashgeheugen. 32 GB is voldoende, 128 GB is ruim.

Computer

  • Linux of macOS: Voor de onderstaande firmware-installatie. Het converteren van video's werkt op Windows via Docker Desktop (zie stap-voor-stap instructies in video/README.md).
  • esptool: Alleen nodig als je de firmware via een terminal installeert: pip install --user esptool. De browser-installer in stap 1 vereist geen extra software.
  • Docker: Voor het gebruik van de video-container. Alternatief kan ffmpeg direct worden gebruikt, plus yt-dlp als je de YouTube-snelkoppeling wilt gebruiken (zie video/README.md).

Installatie

1. De firmware installeren

Sluit de printplaat aan op je computer via de UART-poort (niet de OTG-poort). Je hebt nu twee opties:

Via de browser: Gebruik de web-installer. Dit werkt via Chrome, Edge of Firefox 151+ op desktop. Safari en iOS ondersteunen geen Web Serial en kunnen dit dus niet.

Via de terminal (werkt overal):

cd firmware
./flash.sh

Op Linux verschijnt de printplaat doorgaans als /dev/ttyACM0. Dit commando downloadt de nieuwste release, controleert de checksum en schrijft de firmware. Dit duurt ongeveer een halve minuut, waarna het apparaat herstart en het klokbeeld verschijnt.

Indien nodig kun je een specifieke versie of poort kiezen:

./flash.sh --version v0.2.0
./flash.sh --port /dev/ttyACM0

Problemen met de poort op Linux:

  • Als flash.sh melding maakt dat de poort niet geopend kan worden, voeg dan je gebruiker toe aan de dialout groep:

sudo usermod -aG dialout "$USER" Log daarna uit en opnieuw in om de wijziging door te voeren.

  • Als de poort bezet is door een ander proces, kun je dit vinden met:

fuser -v /dev/ttyACM0

2. Wi-Fi instellen

Ga op het apparaat naar: tandwiel-icoon → Wi-Fi. Scan naar netwerken, kies een netwerk en voer het wachtwoord in.

De klok werkt ook zonder Wi-Fi, maar maakt dan gebruik van de eigen RTC (Real Time Clock), waardoor je de tijd handmatig moet instellen via tandwiel → Time. Met een netwerkverbinding synchroniseert de klok zichzelf binnen enkele seconden via NTP en zijn over-the-air updates mogelijk.

Beveiliging: Het wachtwoord wordt in platte tekst in het flashgeheugen opgeslagen. Iedereen met fysieke toegang en een seriële kabel kan dit uitlezen. Dit is hetzelfde risico als bij elk ESP32-project dat Wi-Fi-gegevens opslaat.

3. Video's toevoegen

Plaats de microSD-kaart in het apparaat. Video's moeten in de hoofdmap (root) staan, zonder subdirectories.

Elk videobestand kan worden gebruikt, maar de klok speelt slechts één specifiek formaat af. Bestanden moeten daarom eerst worden geconverteerd. De videoclock tool doet dit en uploadt het resultaat direct:

cd video
./videoclock vakantie.mov wekker.avi 192.168.0.201

Voor het downloaden van YouTube-video's (als demo) vervang je de bestandsnaam door een URL:

./videoclock "https://youtu.be/VIDEO_ID" wekker.avi 192.168.0.201

Lange bronbestanden kunnen tijdens het converteren worden getrimd (de bestanden verbruiken ongeveer 50 MB per minuut):

START=00:01:30 DURATION=00:00:45 ./videoclock vakantie.mov wekker.avi

Het IP-adres van de klok is te vinden op het scherm tandwiel → Media (bovenaan in het blauw). Dit scherm moet openstaan tijdens het uploaden. Zonder adres wordt het bestand wekker.avi simpelweg in de huidige map op je computer opgeslagen, waarna je het handmatig naar de kaart kunt kopiëren.

Op Windows werkt de videoclock wrapper niet; installeer in dat geval Docker Desktop en roep de container direct aan (zie video/README.md).

Belangrijke regels voor video's:

  • Naamgeving (8.3): Bestandsnamen mogen maximaal 8 tekens bevatten (A-Z, a-z, 0-9, _, -), gevolgd door .avi. De firmware ondersteunt geen lange bestandsnamen. Een te lange naam zal resulteren in een mislukte upload of een vervormde naam die niet meer matcht met het ingestelde alarm.
  • Formaat: Het formaat is strikt: 720×720 MJPEG video, PCM stereo audio op 44.1 kHz, in een AVI-container. Andere formaten worden geweigerd door de player.

Uploads werken alleen als het Media-scherm open is: De klok draait de FTP-server alleen wanneer het scherm tandwiel → Media actief is. Als je dit scherm verlaat, stopt de server en wordt de transfer afgebroken. Er is geen gebruikersnaam of wachtwoord; de beveiliging berust op het feit dat het openen van dit scherm een bewuste handeling op het apparaat is.

4. Alarm instellen

Ga naar: Klokbeeld → alarm-icoon. Voor elk alarm kun je de tijd, de herhaaldagen en de te spelen video instellen. Alarms blijven bewaard na een stroomuitval.

5. De houder printen

In de map enclosure/ vind je de STL-bestanden en de OpenSCAD-broncode. De houder plaatst de printplaat in een hoek van 15°, ideaal voor op een nachtkastje.

Updates

Ga naar: tandwiel-icoon → About → Check for updates. Als er een nieuwere versie beschikbaar is, verandert de knop in "Install". Na een voortgangsbalk van ongeveer tien seconden kun je op "Restart now" klikken.

Het apparaat voert geen automatische updates uit op de achtergrond; dit gebeurt alleen via een handmatige druk op de knop. Dit voorkomt dat de klok herstart terwijl de eigenaar slaapt.

Als een update niet correct opstart, wordt deze automatisch teruggedraaid. De vorige versie blijft bewaard in het andere deel van het flashgeheugen, en de bootloader keert hiernaar terug als de nieuwe versie niet succesvol start.

Mocht je ooit opnieuw de USB-kabel nodig hebben (bijvoorbeeld als het apparaat helemaal niet meer boot), dan werkt firmware/flash.sh nog steeds. Gebruik --erase om alles, inclusief alarms en Wi-Fi-instellingen, te wissen.

Probleemoplossing

SymptoomOorzaakOplossing
flash.sh: no serial port foundBoard niet aangesloten of verkeerde poortGebruik de UART-poort, niet de OTG-poort. Controleer met ls /dev/ttyACM /dev/ttyUSB
flash.sh: cannot open the portGeen rechten voor dialoutVoer uit: sudo usermod -aG dialout "$USER", log daarna uit en opnieuw in
flash.sh: esptool is not installedesptool ontbreektVoer uit: pip install --user esptool
Scherm blijft zwart na flashenOnvoldoende stroom of losse paneelribbonProbeer een andere USB-poort of een powered hub
Tijd is onjuist en synchroniseert nietGeen netwerkverbinding (geen NTP)Ga naar tandwiel → Wi-Fi of stel de tijd handmatig in via tandwiel → Time
Upload geweigerd / connection timeoutMedia-scherm is niet openOpen op het apparaat: tandwiel → Media en laat dit openstaan
De klok weigert een videoNiet in 720×720 MJPEG + PCM in AVIConverteer het bestand met video/videoclock; de foutmelding geeft aan welke codec is gedetecteerd
Geen media zichtbaar, kaart is okéBestanden staan niet in de /clock mapZorg dat bestanden direct in die map staan (geen submappen)
About: "Could not reach the update server"Geen netwerkverbindingGa naar tandwiel → Wi-Fi
About: "The update server answered with nonsense"Geen release gepubliceerdControleer de releases-pagina op GitHub
Update installeert, maar oude versie keert terugNieuwe firmware startte niet correct en is teruggedraaidMeld dit als een bug

Licentie en Auteursrecht

© 2026 Bruno Keymolen. Deze repository valt onder twee licenties:

  1. De houder (enclosure/): De STL-bestanden en OpenSCAD-broncode zijn publiek domein onder CC0 1.0. Je mag ze printen, wijzigen en verkopen zonder toestemming of naamsvermelding.
  2. Overig: De firmware, scripts en documentatie zijn gratis voor niet-commercieel gebruik onder de specifieke voorwaarden in het LICENSE bestand. Installatie, experimenteren, thuisgebruik en aanpassingen zijn toegestaan. Voor commerciële doeleinden (zoals het verkopen van klokken met deze software) is een schriftelijke overeenkomst vereist.

Er is geen garantie op de klok of de content die erop wordt afgespeeld. Dit is een hobbyproject; vertrouw er niet op als je enige wekker voor cruciale afspraken. De verantwoordelijkheid voor het converteren en afspelen van content ligt bij de gebruiker. Zie DISCLAIMER.md voor volledige details.