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
}
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
}
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.
Copy Data in time slots
Depending on the kind of sensor, they might not send heartbeats or data regularly. If they send data and then only send a message upon value change, you might find yourself with bits and pieces of data (eg 1 time slot of 15 minutes with data about temperature, and nothing the rest of the day), which would cause confusion when you try to read the dashboards.
To work around this, you can opt to have us copy the data, per generic endpoint / device type level for any desired amount of time.
For example for the sensor type "Generic PIR" we could set a "copy in further time slots" and this value would be valid for all Generic PIR sensor values, which come to us for your tenant. Of course, the data is only copied until new data comes in again. So if a value comes in on Monday at 9am, and the configuration says "copy for 7 days", and on Wednesday at 8am a new value comes in, then from Wednesday at 8am the new value is taken for 7 days, or until a new value comes in.
This also means that we will only see in Workplace if a sensor is NOT transmitting data after the configured time has expired (in previous example: after 7 days).
Project steps
The following chapter describes step by step how to set up a generic endpoint and sensor data stream.
Prerequisites: We assume that this is part of an existing collaboration, where a tenant and locations are already set up.
Step 1 - Project start-up
1.1 Launch the Generic Endpoint API mini project
Reach out to your Spacewell Account Manager to inform us 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)
1.2 Schedule the Kickoff meeting
In a Kickoff meeting with the stakeholders from all 3 parties, the goal of the project and next steps are discussed.
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 the API documentation to the sensor provider. In the document, 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 team.
Step 2 - Make sure all questions are resolved
2.1 Info session between Spacewell and 3rd party
Any questions regarding the API document should be addressed to the Spacewell Implementation Consultant, who will take them up with Workplace 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 the Spacewell API using the provided documentation. The Customer 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.
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 Spacewell back-end Studio for configuring sensors.
Configuration in Studio
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 your environment (https://studio.cobundu.com ) and log in
Select the location, where you can manually add a sensor via "Add New Device"
Select the (most relevant) Device Type "Generic …” (eg for PIR: "Generic PIR") from the drop-down list. As per the chosen DeviceType, a default set of channels is enabled
If a device is able to gather data on a channel, that is not part of the DeviceTypes' default set of channels : it’s possible to manually add these in Advanced
Fill in the device ID: a "Device ID" prefix will be given by the Spacewell development team
Give a meaningful name (eg customer_floor number_area) in Device Name.
Location will be filled in based on your pre-selection in the location tree
For more information on how to add multiple new devices to Studio, check out Configure devices (add, remove, import/export).
Sensor mapping
Go to your environment and change the location ID for each Sensor in Sensor Management.
Step 5 - Validation & acceptance
Validation checks
High level sub-steps:
Sensor sanity check
Before rolling out the entire floor or adding additional floors, 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 Workplace dashboard
Acceptance & Project Closure
Once the Project is implemented, make sure to finalize the project in an Acceptance Document.
A successful project delivery is celebrated with a glass of Belgian beer, after we received the delivery sign-off.
Search
