Introduction
Suppose there are already sensors collecting data in the building and you want to include its data into the Workplace IOT platform. Spacewell provides a generic endpoint (using webhooks) for most of its sensor data types, to integrate, process and store sensor data from 3rd party platforms.
Webhooks
Webhooks provide a fast and secure way to reliably stream sensor data through from other systems.
The sensor provider is expected to post updates to the Spacewell endpoint.
The webhook endpoint expects a single HTTP request which represent a distinct message from the sensor.
The webhook URL:
HTTP method used: POST
HTTP headers:
Supported data types & payload
Space occupancy related data types:
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
}
Comfort related data types:
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
}
Indoor Air Quality related data types:
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
}
How it works
The sensor vendor needs to comply with the Spacewell webhook, which means a joint project between Spacewell, the customer and the 3rd party sensor provider.
Spacewell will first create a vendor ID, which is descriptive and unique, as a Generic Endpoint. Usually, it refers to a tenant ID, or it can refer to the name of a sensor platform.
Within 1 vendor ID, sensor IDs need to be unique and prepended with the vendor ID.
So if you're thinking of combining device IDs from multiple third parties in 1 Generic Endpoint, there could be a potential risk of conflicts.
The following chapter describes step by step how to set up a generic endpoint and sensor data stream.
Note: We assume that this is part of a bigger project, where a tenant and locations are already set up.
Step 1 - Project start-up
1.1 Inform the Spacewell Support Team
Book a ticket on the Spacewell Extranet under "Cobundu requests > Other service request" (nature: "Cobundu Others") to inform the support team about this new API-project.
Include following information:
Indicate which tenant is involved
Indicate which type of sensors are targeted (PIR, Headcount, Doorcount, ...)
Request an end-point → you will receive a vendor ID and authentication token (needed for step 1.4)
Request a "Device ID" prefix (needed for step 6.1)
Indicate NetSuite task ID
1.2 Kickoff meeting
Organize a Kickoff with the stakeholders from all 3 parties.
1.3 Setup the location master data
Make sure the master data (buildings, floors, locations) are already uploaded.
1.4 Share the Integration Documentation
Send this page to the 3rd party sensor provider. On this page you'll see that there is a placeholder for the <sensor vendor> URL and for the bearer <token>.
Let the 3rd party know what their specific url and token are based on the information you receive from the Spacewell support team from step 1.1.
ℹ️ To make life easier for your customer and the sensor provider, you can of course remove all sensor types that are not in scope of your project.
If you’re targeting another type of sensor, please ask Workplace Product Management to look into the possibilities and set up the API documentation
Step 2 - Make sure all questions are resolved
2.1 Info session between Spacewell and 3rd party
If the client or sensor provider has any questions regarding the API document, take up these questions with Product Management.
The Workplace Team might also have questions for the sensor provider and needs to provide the bearer token.
2.2 Handshake on what to do
Agreement from both parties on the tasks ahead
Step 3 - Development & testing
Development
The sensor provider develops the link between their sensors and Spacewell’s API using the provided documentation. The Customer delivers stays involved by providing location master data if necessary.
Testing
Ask the sensor provider to activate some sensors to see if they’re reaching our webhook (ask Ihor to check the logs).
In case request is not successful, the endpoint returns 4xx-5xx status codes depending on the occurred issue. The requestor may want to store failed requests and try re-sending them later.
In case of successful request, the endpoint returns 200 status code with an empty body.
Step 4 - Sensor Installation & configuration
Sensor installation (optional)
If not yet installed, sensors need to be installed according to 3rd party installation instructions.
Sensor configuration
Make sure you have sensor IDs, Location master data, sensor plan (if available), and mapping between rooms and sensor IDs. From this step, you follow the normal setup process in Studio for configuring sensors
Configuration in Studio
Inquire the list of the sensors (Sensors ID) and use download/upload excel function of Studio for batch upload.
Fill in Device Type, Device ID and location if already available
Please be aware that only after the next data package is send, data for this sensor will be visible in your tenant. (This means that depending on time of upload to Studio and activity at the customer site, this can take a while.)
You can manually add a record via "Add New Device"
Go to Studio and log in
Select a location
Select the source "Generic'
Fill in the device ID: a "Device ID" prefix will be given by the development team
Give a meaningful name (incl sensor name)
Select the model, e.g. for PIR: "Generic PIR"
Select the correct organization/tenant
Click save
Sensor mapping
Go to your tenant and change the location ID for each Sensor in the tenant's Sensor Devices.
Step 5 - Validation & acceptance
Validation checks
High level sub-steps:
Sensor sanity check
Before rolling out the entire floor(s), plan a sanity check to make sure every installed sensor is alive
Once the sanity check is OK, continue the installation
Reporting sanity check
After 1 day, you should see the data coming in the dashboard
Check How to test generic endpoint.pptx
Acceptance & Project Closure
Once the Project is implemented, make sure the customer signs an Acceptance Document (example here: Acceptance document-Project.docx)
A successful project delivery is celebrated with a glass of Belgian beer, after we received the delivery sign-off
