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:
| Expand |
|---|
| title | PIR: space occupancy |
|---|
|
| Code Block |
|---|
| {
"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
} |
|
| Expand |
|---|
| title | Headcount: for measuring number of people |
|---|
|
| Code Block |
|---|
| {
“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
} |
|
| Expand |
|---|
| title | Pulse: for door counters sending pulse values |
|---|
|
| Code Block |
|---|
| {
“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
} |
|
| Expand |
|---|
| title | Count: for door counters sending accumulated values |
|---|
|
| Code Block |
|---|
| {
“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
} |
|
| Expand |
|---|
|
| Code Block |
|---|
| {
“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
} |
|
| Expand |
|---|
|
| Code Block |
|---|
| {
“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
} |
|
| Expand |
|---|
|
| Code Block |
|---|
| {
“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:
| Expand |
|---|
|
| Code Block |
|---|
| {
“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
} |
|
| Expand |
|---|
|
| Code Block |
|---|
| {
“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:
| Expand |
|---|
|
| Code Block |
|---|
| {
“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
} |
|
| Expand |
|---|
| title | TVOC (Total volatile organic compounds) |
|---|
|
| Code Block |
|---|
{
“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
} |
|
| Expand |
|---|
|
| Code Block |
|---|
| {
“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
| Expand |
|---|
| title | 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)
|
| Expand |
|---|
| title | 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. |
| Expand |
|---|
| title | 1.3 Setup the location master data |
|---|
|
Make sure the master data (buildings, floors, locations) are already uploaded. |
| Expand |
|---|
| title | 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. | View file |
|---|
| name | Generic endpoint_Technical Documentation.docx |
|---|
|
| Info |
|---|
To make life easier, you can remove from the document all sensor types that are not in scope of the project.
If you’re targeting another type of sensor, please ask Workplace Product Management to look into the possibilities and create the API documentation. |
|
Step 2 - Make sure all questions are resolved
| Expand |
|---|
| title | 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. |
| Expand |
|---|
| title | 2.2 Handshake on what to do |
|---|
|
Agreement from both parties on the tasks ahead. |
Step 3 - Development & testing
| Expand |
|---|
|
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. |
| Expand |
|---|
|
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
| Expand |
|---|
| title | Sensor installation (optional) |
|---|
|
If not yet installed, sensors need to be installed according to 3rd party installation instructions. |
| Expand |
|---|
| title | 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. |
| Expand |
|---|
| title | Configuration in Studio |
|---|
|
Inquire the list of sensors (Sensors ID) and use download/upload excel functionality of Spacewell back-end Studio for batch upload. Fill in Device Type, Device ID and location ID 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 Spacewell back-end your environment (https://studio.cobundu.com ) and log in Select a location in the location treeGo to “Devices” > “Add New Device”the location, where you can manually add a sensor via "Add New Device" Select the Device Type "Generic …” (eg for PIR: "Generic PIR"). This will automatically link the device channel. Fill in the device ID: a "Device ID" prefix will be given by the Spacewell development team Give a meaningful name (incl sensor name)eg customer_floor number_area) in Device Name. Location will be filled in based on your pre-selection in the location treeSubmit your request to create a new device
For more information on how to add multiple new devices to Studio, check out Configure devices (add, remove, import/export). |
Step 5 - Validation & acceptance
| Expand |
|---|
|
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
|
| Expand |
|---|
| title | Acceptance & Project Closure |
|---|
|
Once the Project is implemented, make sure to finalize the project in an Acceptance Document. | View file |
|---|
| name | Acceptance document-Project.docx |
|---|
|
A successful project delivery is celebrated with a glass of Belgian beer, after we received the delivery sign-off. |
Search