Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 2 Next »

Moeilijkheidsgraad: expert

Inhoud

Leerdoelen

Na het lezen van dit artikel zul je in staat zijn om:

  • Identificeer welke gegevenstypen worden ondersteund door Spacewell Workplace

  • Configureer webhook & autorisatietoken om uw externe gegevensbronnen te verbinden met Workplace

Stel dat er al sensoren zijn die gegevens verzamelen in het gebouw en u wilt deze gegevens opnemen in het Workplace IOT-platform. Spacewell biedt een generiek eindpunt (met webhooks) voor het grootste deel van zijn soorten sensorgegevensom sensorgegevens van platforms van derden te integreren, verwerken en op te slaan.

 External Data Sources for beginners - an analogy

Nu je toch op deze pagina bent: het lijkt erop dat de sensoren die gegevens naar het Workplace platform sturen, gegevens naar een platform of database sturen die niet met Workplace is verbonden. Op deze pagina zullen we ervoor zorgen dat er een verbinding is tussen de platforms en dat de gegevens worden verzonden in een formaat waarmee Workplace kan werken en dat Workplace weet hoe het de gegevens moet identificeren.

Het opzetten van externe gegevensbronnen en het verzenden van gegevens van een externe database naar het Workplace platform kan worden vergeleken met "Er komt een auto aan bij een poort. De auto is bekend bij de poortwachter en de persoon in de auto heeft een badge, omdat hij zijn contactpersoon van tevoren heeft verteld dat hij eraan kwam."

  1. We willen dat het externe platform gegevens verzenden naar Workplace, daarom gebruiken we webhook met HTTP-methode "post". Dit betekent dat de gegevens geduwd door het andere systeem, en Workplace zal niet moeten trek het ergens vandaan.

  2. Door een Externe gegevensbron te maken in de tenant, maak je een deur of poort naar het Workplace platform: de Webhook URL. U ontvangt ook de code om de poort te openen: het autorisatietoken. Door deze informatie aan de eigenaars van de database te geven, kunnen ze nu de deur bereiken.

  3. Maar ze moeten ons de gegevens presenteren op een manier die we kunnen consumeren! Dus moeten ze zich aan een aantal regels houden:

    1. de de gegevens die ze ons sturen moeten betekenisvol zijn: Workplace moet iets met die gegevens kunnen doen (bijvoorbeeld ze presenteren op een live plattegrond of in een dashboard). Dus de externe gegevensbron moet de gegevens leveren in een van de meer dan 10 ondersteunde gegevenstypen.

    2. Het is niet genoeg dat ze ons zomaar wat gegevens voor de voeten werpen. Om correct interpreteren die gegevens moeten voldoen aan een specifiek (payload) formaat. Op deze manier weten we welk deel van de informatie we moeten interpreteren als de apparaat-ID, welk deel als de waarde die we moeten opslaan in de Workplace database, enz.

  4. Voor Spacewell om te weten waar we de gegevens moeten opslaan in onze database, moet de sensor bij ons bekend zijn en gekoppeld zijn aan een locatie. Daarom moet het apparaat worden geregistreerd in Studio. Om het apparaat in Workplace Platform te registreren, moet je:

    1. Type apparaatdie eigenlijk een voorinstelling van gegevenstypes bevat (per gekozen DeviceType wordt een standaardset kanalen ingeschakeld).

    2. Apparaat-IDdie uniek moet zijn.

      1. Om deze ID uniek te maken voor alle huurders, bevat de indeling van de apparaat-ID de huurder-ID

      2. Om deze ID uniek te maken binnen de tenant, bevat de indeling van de apparaat-ID de Externe gegevensbron-ID

    3. Informatie over de locatie. Als een sensor niet is gekoppeld aan een locatie, worden de gegevens niet opgeslagen in de Spacewell-database.

  • het feit dat de auto aankomt bij de poort zonder dat Spacewell iets hoeft te doen, is de webhook

  • het ondersteunde gegevenstype was de instructie om te presenteren bij een specifieke poort

  • het merk en model van de auto is de payload, het voertuig dat wordt gebruikt om de gegevens te presenteren

  • de gegevens liggen in de kofferbak van de auto

  • de sensor-ID is de badge die wordt gebruikt voor identificatie

  • het apparaattype is het poortnummer

  • de poort is open dankzij het autorisatietoken

Spacewell consultants die meer willen weten over hoe Spacewell omgaat met gegevens die binnenkomen, kunnen kijken op /wiki/spaces/WM/pages/492237

De sensorverkoper moet voldoen aan de Spacewell webhook, ondersteunde gegevenstypen en payload.

Binnen 1 vendor ID moeten sensor-ID's uniek zijn en voorafgegaan worden door de vendor ID.
Het combineren van apparaat-ID's van meerdere derde partijen in 1 externe gegevensbron verhoogt het risico op conflicten.

Hoe stel ik deze verbinding in?

Stappen beschreven op deze pagina:

  1. In de externe database (klant of derde partij): Gegevenslading configureren

  2. De verbinding tussen Externe gegevensbron en Workplace configureren

  3. Ga naar de database en vul URL en token in, zorg ervoor dat je de verbinding test

  4. Apparaten configureren op het Workplace-platform

  5. Apparaten sturen gegevens naar het Workplace-platform

Gegevenslading configureren

Webhooks

Webhooks bieden een snelle en veilige manier om betrouwbaar sensorgegevens van andere systemen door te sturen.
Van de sensorprovider wordt verwacht dat hij updates post naar het Spacewell eindpunt.
Het webhook eindpunt verwacht een enkel HTTP verzoek dat een afzonderlijk bericht van de sensor voorstelt.

Ondersteunde gegevenstypen en payload

Voor alle gegevenstypen is het zinvol om te controleren of gegevens regelmatig worden verzonden of niet; zie https://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#FAQ

Datatypes met betrekking tot ruimtebezetting:

 PIR*: space occupancy
{
"device": "<unique_device_id>", // string: unique id of the device
"type": "pir", // string: pir for occupancy
"timestamp": "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
"value": "1" // string: 0 or 1, 0 = not occupied, 1 = occupied
}
 Headcount*: for measuring number of people
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "headcount", // string: headcount for measuring number of people
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "10" // string: value is unsigned integer
}
 Pulse: for door counters sending pulse values
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "pulse", // string: pulse for door counters sending pulse values
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "1" // string: count of pulses expressed as unsigned integer
}
 Count: for door counters sending accumulated values
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "count", // string: count for door counters sending accumulated values 
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "10" // string: value is unsigned integer
}
 Footfall-in pulse*
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "footfall-in-pulse", // string: footfall in pulse sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "5" // string: count of in pulses expressed as unsigned integer
}
 Footfall-out pulse*
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "footfall-out-pulse", // string: footfall out pulse sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "3" // string: count of out pulses expressed as unsigned integer
}
 Parking*
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "pir", // string: pir for occupancy
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "1" // string: 0 or 1, 0 = not occupied, 1 = occupied
}

* Afhankelijk van de betrouwbaarheid van de sensor kan het zijn dat de ruimtebezettingsgegevens alleen gegevens bevatten over bevestiging "beweging" (aanwezigheid, aantal hoofden, voetstappen in de ene of de andere richting enz. afwezigheid van beweging... Om dit in het Workplace-platform aan te pakken, is er een vervalfunctie geïntroduceerd die het mogelijk maakt om de bezetting/hoofdaantallen op de live (naar de eindgebruiker gerichte) plattegronden langer te visualiseren dan wat de gegevens ons werkelijk vertellen.

Voor een voorbeeld van hoe verval werkt, zie https://spacewell.atlassian.net/wiki/spaces/KB/pages/491737/Motion+sensor#How-is-Motion-sensor-data-reflected-in-Workplace-Live-Views%3F

Zie voor een mogelijke oplossing voor gegevenslacunes in de dashboards (gegevens kopiëren in tijdslots) https://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#FAQ

Comfort-gerelateerde gegevenstypen:

 Temperature
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "temperature", // string: temperature sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "25.5" // string: value in Celsius expressed as double with dot as decimal separator
}
 Humidity
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "humidity", // string: humidity sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "75.5" // string: value in percentage 0-100
                     // expressed as double with dot as decimal separator
}

Aan binnenluchtkwaliteit gerelateerde gegevenstypen:

 CO2
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "co2", // string: co2 for carbon dioxide sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "555.5" // string: measured value of CO2 in the air (parts per million)
                       // expressed as double with dot as decimal separator
}
 TVOC (Total volatile organic compounds)
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "voc", // string: voc for volatile organic compounds
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "1.0" // string: measured value of VOC in the air (parts per billion)
                   // expressed as double with dot as decimal separator
}
 Radon
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "radon", // string: radon sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "19.0" // string: radon level measured is Becquerels per cubic meter, Bq/m3
                     // expressed as double with dot as decimal separator

}

De verbinding tussen Externe gegevensbron en Workplace configureren

Hoe krijg ik toegang

  1. Selecteer "Nieuw toevoegen".

  2. Huurder-ID wordt ingevuld op basis van de omgeving waarop je bent ingelogd

  3. Vul Source ID in met een unieke naam, verwijzend naar uw externe gegevensbron

Gebruik in het veld Source ID alleen alfanumerieke waarden. De bron-ID wordt later gebruikt als onderdeel van de apparaat-ID's.

  1. (Optioneel) Vul een beschrijving in, waarin staat wat voor soort gegevens via de externe gegevensbron komen

  2. Kopieer de meegeleverde webhook URL + autorisatietoken om de webhook aan te maken in de externe gegevensbron naar Spacewell Workplace

  3. Zorg ervoor dat je je instellingen inschakelt in Workplace

Het is mogelijk om het autorisatietoken te vernieuwen in Studio. Vergeet niet dat dit nieuwe token nu ook moet worden bijgewerkt in het platform van de 3e partij.

Test je opstelling

Zodra de webhook is aangemaakt in de database van de 3e partij met de bovenstaande URL en token, moet u de verbinding testen.

Deze stap moet worden uitgevoerd door de partij die gegevens naar Spacewell Workplace wil sturen.

Controleer met een programma als Postman of je opstelling werkt:

  • Als het verzoek niet succesvol is, retourneert het eindpunt 4xx-5xx statuscodes afhankelijk van de opgetreden kwestie.

  • Als het verzoek succesvol is, retourneert het eindpunt 200 statuscode met een leeg lichaam.

Raadpleeg bij twijfel het hoofdstuk "Problemen oplossen" hieronder.

De sensoren configureren in Workplace

Vereisten voor deze stap:

  • de bevestiging hebben dat de test succesvol was (endpoint retourneert 200 statuscode met een leeg lichaam)

  • de bevestiging hebben welk gegevenstype wordt gebruikt om de gegevens over te brengen

  • de lijst met apparaat-ID's hebben die gegevens van de externe gegevensbron naar het Workplace-platform sturen

  1. Ga naar je omgeving (https://studio.cobundu.com ) en log in

  2. Selecteer de locatie en voeg handmatig een sensor toe via "Nieuw apparaat toevoegen".

  3. Selecteer de (meest relevante) Type apparaat "Generic ..." (bijv. voor PIR: "Generic PIR") uit de vervolgkeuzelijst. Afhankelijk van het gekozen DeviceType wordt een standaardset kanalen ingeschakeld

    1. Als een apparaat gegevens kan verzamelen op een kanaal dat geen deel uitmaakt van de standaard set kanalen van de DeviceTypes: het is mogelijk om deze handmatig toe te voegen in Gevorderd*

  4. Vul de Apparaat-IDGebruik de ID van de huurder en de bron-ID die beschikbaar zijn in Instellingen > Externe gegevensbronnen. Houd u aan het formaat <huurder_id>-<bron_id>|<apparaat_id>

 Example device ID

bijvoorbeeld

  • als u een sensor wilt configureren met ID "123" (unique_device_id die zal worden vermeld in de nuttige lading; in het geval van een externe leverancier moet deze door de externe partij worden geleverd)

  • in een omgeving met huurder-ID "spacewell".

  • waar een Externe gegevensbron met bron-ID "testgeneric" is ingesteld

wordt de Spacewell-apparaat-ID

"spacewell-testgeneric|123"

  1. Geef een betekenisvolle naam (bijv. customer_floor number_area) in Device Name.

  2. De locatie wordt ingevuld op basis van uw voorselectie in de locatiestructuur

Ga voor meer informatie over het toevoegen van meerdere nieuwe apparaten aan Studio naar Configure devices (add, remove, import/export).

Binnen 1 vendor ID moeten sensor-ID's uniek zijn en voorafgegaan worden door de vendor ID.
Het combineren van apparaat-ID's van meerdere derde partijen in 1 externe gegevensbron verhoogt het risico op conflicten.

* Als een apparaat gegevens kan verzamelen op een kanaal dat geen deel uitmaakt van de standaard set kanalen van de DeviceTypes: het is mogelijk om deze handmatig toe te voegen in Geavanceerd

  1. Selecteer het relevante sensortype in het vervolgkeuzemenu

  2. Vul de waarde "kanaal" in zoals vermeld in de https://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#Supported-data-types-%26-payload

 Concrete example to set up a device for which there is no Generic DeviceType available

In dit voorbeeld stellen we een sensor in die gegevens levert over het aantal voetstappen (die gegevens verstuurt telkens wanneer een persoon een (virtuele) lijn in de ene of in de andere richting oversteekt).

  1. Selecteer het DeviceType dat het apparaat het beste beschrijft (in dit voorbeeld kunnen we "Generic Pulse" gebruiken).

  2. Vul Apparaat-ID, een betekenisvolle naam, locatie enz. in zoals hierboven vermeld

  3. Open het gedeelte "Geavanceerd

  4. Verwijder alle sensortypes die standaard zijn geselecteerd maar niet relevant zijn voor uw sensor.

  5. Selecteer "Nieuwe sensor toevoegen" en voeg zoveel nieuwe sensortypes toe als relevant zijn voor je sensor, in dit geval:

    1. Sensortype "Aantal voetstappen (in)".

    2. Sensortype "Voetval (uit)".

  6. Vul het Kanaal in met de informatie "type" waarde zoals vermeld in de https://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#Supported-data-types-%26-payload

FAQ

 What if the sensor does not regularly send data? Is it possible to copy data in timeslots?

Afhankelijk van het soort sensor kan het zijn dat ze niet regelmatig hartslagen of gegevens verzenden. Als ze gegevens verzenden en dan alleen een bericht sturen als de waarde verandert, kan het zijn dat je met stukjes en beetjes gegevens zit (bijvoorbeeld 1 tijdslot van 15 minuten met gegevens over de temperatuur, en de rest van de dag niets), wat verwarring kan veroorzaken als je de dashboards probeert te lezen.

Om dit te omzeilen, kunt u ervoor kiezen om Spacewell de gegevens te laten kopiëren, per generiek eindpunt / apparaattype niveau voor elke gewenste hoeveelheid tijd.

Bijvoorbeeld voor het sensortype "Generieke PIR" kunnen we een "kopie in verdere tijdslots" instellen en deze waarde zou geldig zijn voor alle Generieke PIR-sensorwaarden die bij ons binnenkomen voor je huurder. Natuurlijk worden de gegevens alleen gekopieerd totdat er weer nieuwe gegevens binnenkomen. Dus als een waarde op maandag om 9 uur 's ochtends binnenkomt en de configuratie zegt "7 dagen kopiëren", en op woensdag om 8 uur 's ochtends komt er een nieuwe waarde binnen, dan wordt vanaf woensdag om 8 uur 's ochtends de nieuwe waarde 7 dagen meegenomen, of totdat er een nieuwe waarde binnenkomt.

Bijgevolg zal Workplace alleen visualiseren of rapporteren als een sensor GEEN gegevens verstuurt nadat de geconfigureerde tijd is verstreken (in het vorige voorbeeld: na 7 dagen).

Neem contact op met je accountmanager om dit op te zetten.

 Is it possible to connect multiple external data sources through the same endpoint in Workplace?

Het is mogelijk om de externe gegevensbroninformatie opnieuw te gebruiken (verificatietoken + URL).

Dus als apparaten hetzelfde gedrag hebben, maar gekoppeld zijn aan verschillende externe gegevensbronnen, is het mogelijk om slechts 1 eindpunt in Studio in te stellen en de 2 externe gegevensbronnen gegevens naar datzelfde Workplace-eindpunt te laten sturen.

Binnen 1 vendor ID moeten sensor-ID's uniek zijn en voorafgegaan worden door de vendor ID.
Het combineren van apparaat-ID's van meerdere derde partijen in 1 externe gegevensbron verhoogt het risico op conflicten.

Problemen oplossen

 Not getting a 200 status code (indicating succesful connection)?

Zorg ervoor dat de volgende configuratie aanwezig is:

  • de verbindingsgegevens die worden gebruikt in de externe gegevensbron zijn de gegevens die worden geleverd door Spacewell

  • controleer of de autorisatiecode niet is bijgewerkt / gewijzigd in Workplace

  • voldoen aan de vereiste ondersteunde gegevenstypen en payload

 Successfull connection message, but sensor is not loading any data

Zorg ervoor dat de volgende configuratie aanwezig is:

 Seeing "Created by Spacewell" and not able to refresh the token or enable/disable the external data source?

Zie het hoofdstuk "Generieke eindpuntinstelling voor oudere versies" hieronder.

 Not able to refresh the token or enable/disable the external data source?

Om veiligheidsredenen: Als een gebruiker zich aanmeldt met een account voor meerdere huurders, kan hij geen wijzigingen aanbrengen in externe gegevensbronnen.

Generieke eindpuntinstelling

In het verleden werden sommige externe gegevensbronnen via een iets ander formaat aan Spacewell gekoppeld. Hierdoor is er alleen een beperking voor de legacy / oude generieke eindpunten:

  1. De oude / legacy Generic Endpoints worden in Studio getoond met het label 'Gemaakt door Spacewell'.

  2. De gebruiker kan geen acties ondernemen (Vernieuw Autorisatie token, Inschakelen / Uitschakelen worden allemaal grijs weergegeven)

  3. Gebruiker kan alleen URL/autorisatietoken bekijken en kopiëren.

Neem contact op met je Account Manager om het autorisatietoken in/uit te schakelen of te vernieuwen.

Zoek op

  • No labels