Drie manieren om aan te sluiten

Elke organisatie in buildinglinks draait een connector, of laat er een draaien. Wat je daarnaast zelf bouwt, hangt af van wat je met gebouwdata doet. Er zijn drie manieren, en een organisatie kan er meer dan één tegelijk hebben: per gebouw kun je rechthebbende, datahouder of dataontvanger zijn.

Je bent	Je hebt	Je bouwt	Werk
Datahouder	gebouwdata in een eigen systeem, zoals een BMS of een cloudplatform	een HTTP-API voor dat systeem, alleen bereikbaar voor je eigen connector	middel: een vertaallaag, tenzij je systeem het protocol al spreekt
Dataontvanger	een app die gebouwdata gebruikt	een HTTP-client die de gateway van je eigen connector aanroept	klein: één basis-URL en een sleutel per app
Rechthebbende zonder eigen systeem	zeggenschap over gebouwen, de data staat bij een ander	niets: alles gaat in de beheeromgeving	geen code

In alle drie de gevallen doet de connector het werk van de dataspace: lid zijn, overeenkomsten sluiten, toegangstokens bijhouden, elk verzoek ondertekenen en alles vastleggen als bewijs. Je eigen systemen en apps spreken gewoon HTTP en zien niets van DID’s, credentials of het Dataspace Protocol.

Als datahouder: je BMS achter de data plane

Je hebt de data van een of meer gebouwen in een eigen systeem. Je stelt die beschikbaar zonder dat een ander je systeem ooit rechtstreeks aanspreekt. Alleen je eigen connector praat met je systeem: de data plane haalt er data op, en alleen binnen een overeenkomst.

Twee situaties komen voor, en voor je systeem zijn ze gelijk:

Het gebouw is van jou. Je bent rechthebbende én datahouder. Je biedt de data zelf aan als product.
Je levert voor een ander. De rechthebbende, bijvoorbeeld de eigenaar van het gebouw, beslist wie de data krijgt. Jij levert uit je systeem namens die partij. Dat heet erkenning en aanwijzing.

Wat jij bouwt. Een HTTP-API op je systeem die het Buildinglinks-protocol spreekt: per gebouw de meetpunten en stuurpunten (discovery), de actuele waarden en, als je sturen toestaat, setpoints met een ontvangstbevestiging. Spreekt je systeem een eigen API, dan zet je er een vertaallaag voor. Het meeste werk zit in het beschrijven van je punten met een Brick-klasse en een eenheid. Een API met een ander protocol kan ook, maar dan bakent de dataspace alleen af op pad, niet per punt.

Wat de connector voor je doet. Hij publiceert de catalogus, sluit overeenkomsten, controleert het lidmaatschap van de dataontvanger, geeft toegangstokens uit en toetst elk verzoek: het token, het recht (lezen of sturen), het gebouw en de punten uit de overeenkomst, en de handtekening. Pas daarna gaat het verzoek naar je systeem, met jouw sleutel en, als het systeem het gebouw anders noemt, met jouw eigen id voor het gebouw. Het antwoord tekent hij en legt hij vast.

Hoeveel werk. Voor alleen lezen zijn twee endpoints genoeg. Voor sturen komen er setpoints bij, en eventueel een fallback-policy en groepscommando’s. Aan de kant van de connector is het configuratie: een systeem en een koppeling per gebouw, allebei te testen vanuit de beheeromgeving.

Checklist

Je connector draait en je organisatie is lid (installeren).
Je systeem spreekt het Buildinglinks-protocol, rechtstreeks of via een vertaallaag.
Je systeem is bereikbaar voor je connector (data plane en control plane), en alleen daarvoor.
Onder Systemen staat het systeem, met de sleutel die het vraagt, en Systeem testen slaagt.
Elk gebouw is gekoppeld, met de eigen id als je systeem het gebouw anders noemt, en Koppeling testen vindt de punten.
Het gebouw is aangeboden: als product van jezelf, of als levering voor de rechthebbende.

Lees verder bij een backend koppelen.

Als dataontvanger: je app via de gateway

Je gebruikt gebouwdata in eigen software, zoals een klimaatoptimalisatie of een rapportage. Je app praat nooit met de partij die de data heeft. Hij praat alleen met de gateway van je eigen connector, met een basis-URL per abonnement en een eigen sleutel.

Wat jij bouwt. Een HTTP-client. Achter de basis-URL van een abonnement zet de app het pad van het gebouw, bijvoorbeeld /v1/buildings/nl.bag.pand.0599100000701251/points/values, en stuurt zijn sleutel mee als Authorization: Bearer. Fouten komen in één vorm terug, met retryable erbij, zodat de app weet of opnieuw proberen zin heeft.

Wat de connector voor je doet. Hij laat zien dat je organisatie lid is, vraagt de toegang aan, sluit de overeenkomst, start de levering, houdt het toegangstoken geldig, tekent elk verzoek en controleert de handtekening op het antwoord. Hij controleert ook je app: bij welke abonnementen hij mag, en of hij alleen leest of ook stuurt.

Hoeveel werk. Klein voor de koppeling zelf: een adres en een sleutel. Je eigen werk zit in wat je app met de punten doet. Toegang aanvragen en apps maken doe je in de beheeromgeving, of automatisch via de beheer-API.

Checklist

Je connector draait en je organisatie is lid.
Onder Data zoeken heb je toegang aangevraagd, en de rechthebbende heeft goedgekeurd.
Onder Apps staat een app met de abonnementen die hij nodig heeft, met de permissie Lezen tenzij hij moet sturen.
De sleutel van de app staat in de geheimen van je app, niet in de code.
De gateway van je data plane is bereikbaar voor je app, en niet vanaf internet.
De verbindingstest bij het abonnement slaagt.

Lees verder bij een app koppelen.

Als rechthebbende zonder eigen systeem

Je beslist over de data van gebouwen, bijvoorbeeld als eigenaar, maar de data staat in het systeem van een ander: de leverancier van het BMS, een installateur of een energieplatform. Je wijst die partij aan als datahouder, en je beslist zelf wie de data krijgt.

Wat jij bouwt. Niets. Alles gebeurt in de beheeromgeving van je connector: gebouwen toevoegen, een datahouder aanwijzen, producten aanbieden met voorwaarden, aanvragen beoordelen en zien wie je data gebruikt.

Wat de connector voor je doet. Hij is de contractpartij: jouw catalogus, jouw overeenkomsten, jouw bewijs. Is er een overeenkomst, dan start hij de levering bij de data plane van de datahouder. Hij krijgt ook een abonnement op je eigen data, zodat je die zelf kunt gebruiken zonder toegang aan te vragen.

Hoeveel werk. Geen code. Wel een connector om te draaien, met wat erbij hoort (zie architectuur), en iemand die aanvragen beoordeelt.

Checklist

Je connector draait, je identity provider is gekoppeld en je organisatie is lid.
Onder Gebouwen staan je gebouwen, met de datahouder aangewezen en de aanwijzing door hem geaccepteerd.
Onder Producten staan de producten met hun voorwaarden.
Iemand met de rol operator of admin beoordeelt Aanvragen. Een aanvraag om te sturen keur je altijd zelf goed.

TechnischWaarom ook een rechthebbende zonder systeem een data plane draait

De control plane van de rechthebbende sluit de overeenkomst en start de levering bij de data plane van de datahouder. De data gaat dus niet door de data plane van de rechthebbende. Toch hoort er een bij elke connector: het DID-document van de connector noemt hem, de beheeromgeving controleert hem, en de rechthebbende leest de punten en de indeling van zijn eigen gebouwen via de gateway van zijn eigen data plane, met een abonnement op de overeenkomst voor eigen gebruik.

Verder lezen

Architectuur van een connector: de onderdelen, wat ernaast moet draaien en wat bereikbaar moet zijn.
Installeren en lid worden: images, configuratie, omgevingen en sleutels.
Een backend koppelen en een app koppelen.
Identity provider koppelen: wie de connector mag beheren.
Zelf proberen zonder installatie: de simulatie lokaal.