Basics
Ik ga de hele site niet overtikken maar om even een kapstok neer te zetten. openHAB werkt in de basis met bindings, things met channels, een model, items, pages, widgets en rules. Al deze zaken kan je met code (YAML) of de GUI aanmaken en configuren. Naast de standaard functionaliteit kan je uitbreiden met add-ons. Belangrijkste add-ons zijn bindings, automation (inclusief transformations), UI en overig. Naast de add-ons vanuit openHAB zelf is er ook een marketplace waar gebruikers onderling hun bindings, widgets en rules kunnen delen. Vermoedelijk is de meestgebruikte add-on de JSONPATH transformation omdat veel apparaten hun gegevens via JSON ter beschikking stellen.
Wil je meteen een grondige uitleg, ga dan naar de openHAB startersgids, openHAB configuratie gids en forum. Dit is wel in het engels. Wil je liever nederlands, ook op tweakers is er een openHAB topic. Hieronder een korte toelichting (ik gebruik de Engelse begrippen om verwarring te voorkomen) met een voorbeeld en link naar de juiste sectie in de openHAB documentatie.
Binding
Een binding is een verbinding met de buitenwereld, meestal hardware maar het kan ook een (externe) website/service of iets op je netwerk zijn. Denk aan een USB Zigbee stick, een webservice op een website, een TV, een modem, een thermostaat, een chromecast of je zonnepanelen. Per type apparaat heb je één binding. Je kan ze zoeken via de add-on marketplace.
Thing
Een thing is de verbinding van openHAB met één specifiek apparaat. Stel je hebt 3 chromecasts of 3 samsung TV's. Dan heb je voor voor deze twee type apparaten twee bindings en in totaal zes things. Deze zijn specifiek gemaakt door bijvoorbeeld het IP adres of de naam van het betreffende apparaat op je netwerk. Als je een thing opent krijg je drie tabbladen te zien (hierboven). De GUI configutatie, de channels en de YAML code. De code is erg makkelijk om een thing te copieren of te delen. Hij is compact en je kan hem gewoon knippen, plakken en of bewerken. Deze die je dan meestal ook in github of op het forum. Als je die wilt gebruiken,maak een nieuw thing en ga gelijk naar het tabblad code. En copieer hierop de YAML die je gevonden hebt. Opslaan en klaar. Het channel scherm gebruik je vaak omdat helemaal onderaan de optie 'Add equipement to Model' ziet. Deze maakt namelijk van je thing automatisch het bijbehorende model en de items. En dat scheelt veel werk!
Meer over bindings en things ...
YAML code
config:
colNum: 8
fixedType: grid
hideNavbar: false
label: Netsjels Huis
layoutType: fixed
margin: 5
scale: false
screenHeight: 773
screenHeightOld: 756
screenWidth: 1275
showFullscreenIcon: true
sidebar: true
style:
--f7-card-bg-color: "#202020"
--f7-navbar-bg-color: "#202020"
--f7-navbar-border-color: "#101010"
--f7-navbar-border-size: 3px
--f7-navbar-font-size: 14px
--f7-navbar-height: 26px
--f7-navbar-link-color: gray
--f7-navbar-shadow-image: none
--f7-navbar-text-color: gray
--f7-page-bg-color: black
--f7-theme-color: gray
blocks: []
masonry: null
grid:
- component: oh-grid-item
config:
h: 2
w: 3
x: 3
y: 0
slots:
default:
- component: widget:lineChart_1h
config:
height: "289"
item: netto_totaal_avg
item1: netto_totaal_ref
widgetId: energie_W2
- component: oh-grid-item
config:
h: 2
style:
--f7-card-bg-color: "#702020"
w: 2
x: 1
y: 0
slots:
default:
- component: widget:widget_ronde_meter
config:
height: "100"
item: EnergieMeter_nettototaal
- component: oh-grid-item
Een thing is een mooi voorbeeld van de opzet binnen openHAB waar je de configuratie zowel via GUI als YAML code kan doen door het bijbehorende tabblad te keuzen. De code variant maakt copieren, bewerken en delen een stuk makkelijker (als je bijvoorbeeld een vraag stelt op een forum zet je er meestal de code op). De GUI en code werken elkaar wederzijds bij, dus een aanpassing in de GUI zie je daarna ook in de code. En omgekeerd. Qua bewerken zijn inspringingen erg belangrijk, dus iets dat 2 spaties naar rechts of links opschuift kan als fout worden weergegeven. Andersom als de inspringing en formaat juist is kan je code woorden invoegen die niks betekenen maar wel blijven staan (ze kunnen na opslaan en weer openen verdwijnen). Bovenstaande voorbeeld is een stukje van de configuratie van een page. Je ziet een structuur van label : waarde waarbij zaken op hetzelfde niveau inspringing bij elkaar horen. Beginnen ze met een '-' zijn het herhalingen, je mag meerdere van dezelfde blokken opgeven. In deze pagina zijn het de configuratie van de verschillende tiles op de page.
Meer over YAML code ...
Channel
Een thing kan je zien als het apparaat. Elke losse eigenschap (waarde, knop, gegeven, invoermogelijkheid) van dit apparaat is een channel. Als je denkt aan de TV zou dit volume, zender en aan/uit knop kunnen zijn. Daarmee heeft een thing meestal meerdere channels. Deze zijn in openHAB bij het thing zelf te vinden. Elke channel wordt een item in het model.
Meer over channels in things ...
Model
Het model en de items zitten dicht bij elkaar. Het grote verschil is dan in een model een structuur zit (denk aan mappen in een verkenner). Je kan een model voor een TV hebben met daarin items voor de aan/uit knop, de volume regelaar en de zender. Iets dergelijks is groeperen, denk aan drie lampen in één overkoepelende groep. Waarmee je als je de groep aanzet meteen alle drie lampen aanzet. Maar ze ook apart kan bedienen. Meestal maak je het model vanuit de thing. Er zit in de GUI hiervan een knop om de model te genereren uit de thing (zie daar voor een screenshot).
Meer over model en items ...
Item
De items zijn een opsomming van alle zaken die je kan uitlezen of besturen. Denk aan het 'platgeslagen' model. Dit is meestal het niveau waarop je je GUI of Rules laat werken.
Meer over model en items ...
Page
Dit zijn de pagina's (GUI) waarmee je alles kan besturen. Standaard geinstalleerd is Basic UI, waarin je kiest voor een bepaalde layout (denk tabs op pagina, een map/kaart, een dashboard met tiles, een response site, etc). Hierop kan je items zetten in een bepaalde weergave. Denk aan een mooie knop voor lampen. Of een ronde meter voor je energieverbruik. Er is een hele reeks componenten beschikbaar die meestal al werken als je aangeeft welk item ze moeten gebruiken. Uiteraard kan je daarna van alles instellen, minimum, maximum, schaal, icoontjes, kleur, etc.
Widget
Je kan die onderdelen van de pagina helemaal van de grond af aan opbouwen. Maar ze ook via een widget herbruikbaar maken. Denk als je een mooie opzet hebt van een ronde meter met daarnaast een historische grafiek kan je hier 1 widget van maken. Die je dan in allerlei plekken kan herbruiken. En als je die ene widget aanpast, verandert hij op alle plekken op alle pagina's waar je hem hebt gebruikt. Je kan hierbij ook YAML code van je pagina naar je widget copieren. Of nog beter ... naar de add-on marketplace. Widgets van anderen staan hier onder de UI sectie.
Meer over widgets ...
Rule
Rules gebruik je om te automatiseren. Denk aan lees het item uit hoe licht het nog is en als het te donker wordt doe je lampen aan. Of als ik de TV aanzet, doe dan de radio uit. Alles kan, de eenvoudige dingen kan je geheel via de GUI bij elkaar klikken. De ingewikkelde dingen kan je uitprogrammeren via 'echte' code of een grafisch hulpmiddel met bouwblokken (blockly). Zelf gebruik ik javascript maar via de add-ons kan je ook andere talen zoals python of ruby gebruiken. Ben je minder handig op dit vlak kan je ook door anderen gemaakte rules downloaden via de marketplace.
Transformation
Vaak wil je in things transformaties gebruiken omdat de gegevens niet binnen komen zoals jij ze nodig hebt. Hiervoor kan je transformatie add-ons downloaden. Denk aan een stukje uit een JSON antwoord halen met JSONPATH of een tekst interpreteren met een reguliere expressie. Of een lijstje 0,1 en 2 omzetten in 'ja','nee' en 'misschien' met een MAP.
Meer over transformations ...
Lijst met alle transformations.
JSON en JSONPATH
{
"firstName": "John",
"lastName": "doe",
"age": 26,
"address": {
"streetAddress": "naist street",
"city": "Nara",
"postalCode": "630-0192"
},
"phoneNumbers": [
{
"type": "iPhone",
"number": "0123-4567-8888"
},
{
"type": "home",
"number": "0123-4567-8910"
}
]
}
Wil je het type van de eerste telefoon uit de lijst:
JSONPATH:$.phoneNumbers[0].type
Veel van de webservices zijn in JSON formaat. Een formaat waarin gegevens in een leesbaar formaat staan (zie hierboven). De basis zijn labels en waarden gescheiden door komma's tussen accolades. Een waarde kan ook weer een andere JSON zijn als deze omgeven is door extra accolades. Of een waarde kan een lijst zijn als deze omgeven is door vierkante haken. Hiermee kan je alle gegevenssets in één stuk tekst vatten. In een channel wil je vaak één waarde uit de JSON vissen. De JSONPATH transformation is wat je dan nodig hebt. Hiermee kan je bijvoorbeeld in een channel met JSPONPATH:$.label de waarde laten ophalen met de gegeven label. En er zijn allerlei varianten als de JSON ingewikkelder in elkaar zit (voorbeeld hierboven voor het type van het 1e voorkomen in een lijst telefoonnummers).
Meer over JSON ...
Meer over JSONPATH ...
Meer over JSONPATH transformation ...
Online hulpmiddel om JSONPATH's uit te proberen ...
Add-on
Ze zijn allemaal al een paar keer gevallen, add-ons bevatten extra functionaliteit voor openHAB. Je vindt ze via het instellingen menu onder add-ons. Ze zijn ingedeeld in bindings, automation, user interface en other maar eigenlijk maakt het niet uit welke je kiest. Je komt op hetzelfde scherm waar de vier categorien een tabblad zijn en je zo naar een andere kan doorklikken. De zoekfunctie werkt over alles heen, dus als je wilt weten wat er voor een 'samsung' is krijg je de add-ons in alle categorien die bij het zoekwoord passen.Bij klikken krijg je een startpagina waar je meer kan lezen, naar de documentatie kan springen of hem kan installeren. Add-ons kunnen ook generieke functionaliteit bevatten, denk aan een andere database dan de standaard óf integratie met de Google Assistent.
Meer over add-ons ...
Marketplace
Het wordt vaak de Community Marketplace genoemd maar het zit op dezelfde plek als de add-ons in dezelfde indeling. Hier kan je bindings, widgets en rules vinden die anderen gemaakt hebben die je kan overnemen. Of andersom als je zelf iets moois gemaakt hebt erop kan publiceren.
Meer over marketplace ...