Codex in Home Assistant: bouw samen je slimme huis

Home Assistant is een duizendpoot op het gebied van thuisautomatisering. Je kunt eindeloos knutselen en experimenteren. Tegelijkertijd is het, zeker voor beginners, behoorlijk overweldigend. Als je vertrouwd bent met de basis, kan AI gelukkig al snel een waardevolle hulp zijn om samen iets te bouwen. Denk aan een complexe automatisering, een speciale sjabloon-sensor, een onderdeel voor een dashboard of een externe toepassing die werkt met een API of een ingewikkelde configuratie voor ESPHome. Denk aan een gebruikersinterface met LVGL.

In deze masterclass verkennen we deze mogelijkheden stap voor stap. We beginnen eenvoudig door met AI losse code te maken. Hierbij schakelen we al snel over naar Codex, een uitgebreidere omgeving die heel praktisch is voor ontwikkeling. Tevens installeren we een zogeheten MCP-server in Home Assistant die we toevoegen aan Codex. Hierdoor kan AI zelf jouw installatie onderzoeken, bijvoorbeeld door entiteiten, automatiseringen en statussen op te zoeken.

De assistent kan je ook helpen bij problemen of onderhoud en wijzigingen voorstellen, uitvoeren en controleren. Zo kun je bijvoorbeeld eenvoudig een geavanceerde automatisering laten maken, maar ook controleren of finetunen. We geven enkele praktische voorbeelden, waarbij we bijvoorbeeld met één prompt een gebruikersinterface met ESPHome en LVGL laten bouwen. Met een MCP-server groeit AI uit van een los hulpmiddel tot een echte assistent die je huis naar een hoger plan kan tillen.

Bij het knutselen met Home Assistant is een chatbot zoals ChatGPT, Gemini of Claude heel praktisch. Je kunt bijvoorbeeld de benodigde YAML voor een automatisering laten maken en uitleggen. Daarna plak je die in de beheerdersomgeving van Home Assistant. Dit geeft maximale controle, maar is vaak maar een halve oplossing voor het maken van werkende code.

Je moet nog veel zelf doen, zoals het opzoeken van de correcte entiteitsnamen, maar ook het controleren, testen en verfijnen van je automatisering. Het is veel praktischer om een MCP-server te gebruiken, zodat de AI-assistent rechtstreeks met Home Assistant kan communiceren. Om met zo’n MCP-server te kunnen werken, gebruiken we Codex, dat we eerst gaan installeren.

Codex is de programmeeragent van OpenAI. Het is sinds kort geïntegreerd in een nieuwe gecombineerde ChatGPT-desktopapp, beschikbaar voor Windows en macOS. Die app gebruiken we in dit artikel. Codex kan externe MCP-gereedschappen gebruiken om met bijvoorbeeld Home Assistant te communiceren.

Bovendien kun je binnen Codex met de modellen Sol, Terra en Luna werken. Terra is bij het sleutelen aan Home Assistant op zich een goede keuze, maar wij gebruiken meestal het krachtigere Sol. Die variant is vooral nuttig wanneer het ingewikkelder wordt. Je kunt eventueel de denkinspanning instellen. We houden het veelal bij Gemiddeld.

Codex werkt heel overzichtelijk en de recente modellen gaan grondig te werk bij het uitwerken van bijvoorbeeld codevoorbeelden. De uitleg bevat verwijzingen naar relevante websites, zoals de documentatie van Home Assistant. Klik je daarop, dan wordt een browser in een zijpaneel geopend. Als voorbeeld vragen we om een betrouwbare manier om de hoeveelheid neerslag voor de komende 24 uur te bepalen. Het stelt een sjabloon-sensor voor die de verwachting per uur voor de komende 24 uur bij elkaar optelt, zodat je een voortschrijdende periode van 24 uur hebt.

Hierbij maakt het tevens een binaire sensor aan die eenvoudigweg aangeeft of het droog blijft of niet. Soms werkt zo’n voorbeeld niet direct, bijvoorbeeld omdat het niet de juiste entiteit gebruikt. Je kunt dan over en weer vaak wel tot werkende code komen, maar dat voelt omslachtig. De integratie van een MCP-server is in dergelijke situaties een enorme meerwaarde. Het geeft veel vaker direct een werkende oplossing voor je probleem. Dat doen we in de volgende stappen voor Home Assistant.

We gebruiken bij deze masterclass het populaire project HA-MCP dat zichzelf The Unofficial and Awesome Home Assistant MCP Server noemt. Je kunt het op verschillende manieren installeren. Bij Home Assistant OS kun je het als app (voorheen add-on genoemd) installeren, maar ook via HACS. Daar kiezen we hier voor. Zorg dat je HACS hebt geïnstalleerd en open het via de beheerdersomgeving van Home Assistant.

Ga eerst naar het menu (via de drie puntjes rechtsboven) en kies Aangepaste repositories. Vul bij Repository de link https://github.com/homeassistant-ai/ha-mcp-integration in en kies als Type voor Integration. Klik dan op Toevoegen en sluit het venster. Zoek naar ha-mcp custom component. Kies Download en bevestig het downloaden van de laatste versie. Herstart hierna Home Assistant volledig. Je kunt nu de integratie toevoegen aan Home Assistant.

HA-MCP
HACS

Je kunt de integratie op de gangbare wijze toevoegen aan Home Assistant. Daarvoor ga je via Instellingen naar Apparaten en diensten. Kies Integratie toevoegen. Zoek de component op en installeer deze. Je kunt hierna kiezen tussen HA-MCP Server en HA-MCP File & YAML Tools. We raden aan om de eerste optie te kiezen. De tweede optie geeft de AI-assistent veel directere en bredere toegang tot bepaalde bestanden, wat voor normaal gebruik (waaronder het bijwerken van dashboards en automatiseringen) niet nodig is.

In het menu van Home Assistant zie je nu de verwijzing HA-MCP. Daarin zie je onder meer alle beschikbare gereedschappen. Je kunt ze individueel aan- of uitzetten via een vinkje. Gereedschappen hebben een handig label dat aangeeft of ze iets lezen, verwijderen of schrijven (zoals iets aanmaken of bijwerken).

Onder Automations zie je bijvoorbeeld gereedschappen voor respectievelijk het ophalen van je automatiseringen, het verwijderen van een automatisering en het maken of bijwerken van een automatisering. Bovenaan zie je ook een algemene Read Only Mode waarmee je gereedschappen die iets verwijderen of schrijven in één handeling uitzet.

Verschillende AI-assistenten, waaronder Codex, kunnen nu gebruik gaan maken van de MCP-server in Home Assistant. Via deze link kun je eventueel specifieke instructies krijgen. Bij deze masterclass gebruiken we de standaard beveiligde webhook-url. Deze enkele link is voldoende voor de verbinding.

Om die te achterhalen ga je via Instellingen naar Apparaten en diensten. Klik op HA-MCP Custom Component. Klik dan achter HA-MCP Server op het instellingenicoontje. Onder Connect URL(s) zie je een link waarin private_ en een reeks karakters (de beveiliging) staan. Kopieer die link naar je klembord. Open dan Codex. Open onder Bewerken de instellingen.

Ga vervolgens onder Integraties naar Plug-ins. Kies op het tabje MCP’s de optie Server toevoegen. Vul een naam in. Kies bij Type voor Streamable HTTP. Bij URL vul je de verbindings-url in. Klik dan op Opslaan. Hierna kun je vragen stellen over je huis en installatie van Home Assistant. Soms is het nodig om HA-MCP te noemen, als de assistent dat niet direct begrijpt. In het tweede deel geven we enkele praktische voorbeelden voor het werken met deze MCP-server.

Een goede eerste vraag is of Codex Home Assistant kan vinden via HA-MCP. Laat hierna bijvoorbeeld onderzoeken of je installatie fouten bevat. Dat geeft, zeker bij grotere installaties, vaak nuttige aanwijzingen. Denk aan automatiseringen die naar onbekende apparaten verwijzen, verouderde configuraties, ongeldige sensorwaardes of een volle schijf. Problemen kun je laten herstellen, maar je kunt het ook zelf met beleid doen.

Nog een handige toepassing is dat je bij een update van Home Assistant de release-notes kunt bijsluiten en kunt vragen of dit invloed heeft op jouw installatie. En na de update kun je vragen om te controleren of alles gezond is. Een andere meerwaarde is dat je eenvoudiger geavanceerde automatiseringen of dashboards kunt bouwen. Daar geven we hierna wat tips voor.

De AI ziet direct welke entiteiten moeten worden gebruikt. Als iets niet lukt via de MCP-server kan Codex ook zelf voorstellen om via een browserscherm in te loggen bij Home Assistant zodat het met computerbesturing acties kan uitvoeren. Dat is een heel andere route, en meestal niet de beste.

Automatiseringen vormen een belangrijk onderdeel van Home Assistant, maar je moet met veel rekening houden. Een automatisering bestaat uit een of meer triggers, eventuele aanvullende voorwaarden en acties. Ook binnen de acties kun je weer voorwaarden en keuzemogelijkheden opnemen. Via de visuele editor kun je dit vrij comfortabel instellen, maar door de vele mogelijkheden en onderlinge afhankelijkheden is een fout snel gemaakt.

Recent is dit wel verbeterd en iets intuïtiever. Zo kun je bij steeds meer triggers en voorwaarden een herkenbaar doel kiezen, zoals ‘er is beweging gedetecteerd in de tuin’. Je hoeft dan niet naar de technische staatverandering (zoals: de binaire sensor gaat van off naar on) te kijken. Achter de schermen worden automatiseringen nog steeds gewoon als YAML-configuratie opgeslagen.

Daarom kan AI goed helpen bij het maken, uitleggen, onderzoeken en verbeteren van automatiseringen. Hierbij kan het bepaalde skills van HA-MCP gebruiken voor een betere kwaliteit. Controleer en test het resultaat wel altijd zelf.

Met ESPHome kun je allerlei slimme hardware bouwen rondom een microcontroller. Je sluit bijvoorbeeld sensors, schakelaars of een scherm aan en beschrijft in een configuratiebestand wat er is aangesloten. Dit werkt vervolgens samen met Home Assistant. De configuratie is soms heel makkelijk, maar het wordt lastiger als je bijvoorbeeld logica wilt toevoegen om een ruwe analoge meetwaarde te kalibreren en om te rekenen naar een percentage, een Super Mario-deuntje wilt afspelen op een rttl-zoemer, of de C++-code voor een lambda nodig hebt om tekst en meetwaarden netjes op een scherm te plaatsen. Hier kan AI veel vrij omslachtige en foutgevoelige code voor je uitschrijven.

De MCP-server is ook heel nuttig, zeker als je rekening met entiteiten in Home Assistant moet houden. Bijvoorbeeld bij een scherm met gebruikersinterface, zoals we hieronder demonstreren. Merk op dat HA-MCP niet direct iets met ESPHome zelf kan doen. Er bestaan wel aparte MCP-servers voor ESPHome, die bijvoorbeeld configuraties lezen en aanpassen of firmware compileren. In deze masterclass hebben we ons beperkt tot wat er mogelijk is met HA-MCP.

In het verleden schreven we al eens over de LVGL-bibliotheek die je binnen ESPHome kunt gebruiken (zie dit artikel). Hiermee maak je zelf gebruikersinterfaces voor een touchscreen. Je kunt kiezen uit bijna 30 widgets, variërend van eenvoudige labels en knoppen tot tabbladen, toetsenborden, schuifregelaars, meters en QR-codes.

Met hulp van AI kun je zo’n gebruikersinterface veel sneller opbouwen. Als voorbeeld gebruiken we een CrowPanel met 7inch-aanraakscherm en ingebouwde ESP32-microcontroller. Als je het scherm uit de doos inschakelt, verschijnt een demonstratie van LVGL. Met hulp van AI maken we eerst een basisconfiguratie die vooral het bord en de wifi-instellingen bevat.

De configuratie maken we via de ESPHome Device Builder. Dit onderdeel kun je binnen Home Assistant als app installeren. We compileren hierin de firmware voor ESPHome en downloaden het resulterende .bin-bestand, dat we in de volgende stap gaan flashen.

Voor het flashen van de firmware gebruiken we ESPHome Web (https://web.esphome.io). Dit werkt vanaf elke pc. Als je het scherm daarna via usb-c opstart, kun je het direct toevoegen aan Home Assistant, onder Instellingen / Apparaten en diensten. Het apparaat is al bekend in ESPHome Device Builder, omdat we daar de basisconfiguratie hebben gemaakt. Heb je de firmware op een andere manier geïnstalleerd, dan moet je het apparaat eerst adopteren in de Device Builder voordat je de configuratie daarin verder kunt beheren.

Als volgende stap breiden we de configuratie met hulp van AI uit. Vooral het scherm en het touchscreen vereisen veel specifieke instellingen, met in dit geval ook verschillende hardwarerevisies van het CrowPanel. Een voorbeeldconfiguratie van internet is een nuttig uitgangspunt, maar werkt niet altijd direct op ieder exemplaar.

Gelukkig kan AI uitstekend verouderde configuraties aanpassen aan een recente ESPHome-versie en eventuele problemen stap voor stap oplossen. Na enkele iteraties hebben we een werkende gebruikersinterface met een knop en daarboven een teller die bijhoudt hoe vaak de knop is ingedrukt. Tijd om een geavanceerdere interface te maken!

We hebben nu een eenvoudige maar werkende basis, wat een ideaal startpunt is om een geavanceerde gebruikersinterface te bouwen. Met deze eerste eenvoudige prompt in Codex krijgen we al direct een mooi resultaat: “Maak een gebruikersinterface met LVGL voor de CrowPanel. Ik wil hierin de spots, het ledpaneel en de ledstrip (wled) met dimmogelijkheid. Knoppen voor scènes. Ik wil apparaten aan en uit kunnen zetten (hoofdversterkers, keyboard en sport). En schakelaars voor de verlichting in de berging links, rechts en de vliering. Gebruik eventueel tabbladen voor een logische scheiding.”

Het model kiest en controleert zelf de entiteiten en levert daarna drie aparte bestanden: instructies voor de installatie, een YAML-bestand met de belangrijkste code en een visuele preview, zodat je direct kunt beoordelen hoe het eruit gaat zien. Het YAML-bestand bevat ongeveer 750 regels met alle essentiële onderdelen en is gemakkelijk aan te passen. Als bijvoorbeeld een entiteitsnaam wijzigt, kun je dat onder substitutions: veranderen.

De installatie is eenvoudig. Je kunt het YAML-bestand met bijvoorbeeld File editor uploaden naar de juiste map in Home Assistant. In ons voorbeeld komt het onder /config/esphome/packages/crowpanel-kantoor-lvgl.yaml. We kunnen hierna het blok lvgl: uit onze oorspronkelijke code halen zodat het niet dubbelop is. In plaats daarvan verwijzen we naar het YAML-bestand:

packages:
  kantoor_ui: !include packages/crowpanel-kantoor-lvgl.yaml

Bij de ESPHome-integratie moeten we voorts nog een vinkje zetten bij de optie Toestaan dat het apparaat Home Assistant-acties uitvoert. Dan kun je de bedieningsknoppen daadwerkelijk gebruiken. Na het compileren werkt alles volledig. Wellicht wil je nog wat aanpassingen maken aan de indeling of het uiterlijk, maar je hebt een prima startpunt. Het scheelt wel tijd als je in je eerste prompt al je wensen aangeeft. Dat geldt ook voor bijvoorbeeld dashboards en automatiseringen.

Zoals je hebt gezien, kun je ervoor kiezen om alles handmatig aan te passen, wat bij ESPHome ook nodig is, omdat we hier geen MCP-server voor gebruikten. Maar je kunt bij Home Assistant met de MCP-server ook prima aanpassingen door AI laten maken. Het is wel fijn als je zelf alles controleert.

Ook is het nuttig om back-ups te maken van Home Assistant, zodat je bij een probleem alles gemakkelijk terug kunt zetten. Gelukkig heeft HA-MCP ook een ingebouwde back-upvoorziening. Als via één van de gereedschappen een bestand wordt bijgewerkt, wordt automatisch een back-up gemaakt. Je kunt na het openen van HA-MCP op het tabblad Backups de gemaakte back-ups bekijken. Ook kun je zien wat er is veranderd en een eerdere versie terugzetten. In het kader noemen we enkele andere valkuilen om rekening mee te houden.