Difficulty: expert

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:

vendor needs to comply with the Spacewell webhook, supported data types & payload.

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:

  • EU: <https://bohemian.us1eu1.cloud.cobundu.com/generic/<sensor_vendor>/data>

• HTTP method used: POST

• HTTP headers:

  • Authorization: Bearer <token>

  • US: <https://bohemian.us1.cloud.cobundu.com/generic/<sensor_vendor>/data>

• HTTP method used: POST

• HTTP headers:

  • Authorization: Bearer <token>

  • Content-Type: application/json

Supported data types & payload

Space occupancy related data types:

{
"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
}

{
“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
}

{
“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
}

{
“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
}

{
“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
}

{
“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
}

{
“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:

{
“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
}

{
“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:

{
“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
}

{
“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
}

{
“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

Step 2 - Make sure all questions are resolved

Step 3 - Development & testing

Step 4 - Sensor Installation  & configuration

Step 5 - Validation & acceptance

Once the Project is implemented, make sure to finalize the project in an Acceptance Document.

Configure the connection between External Data Source and Workplace

How to access

• Go to https://studio.cobundu.com/

• Login with your credentials

• Select Settings > External Data Sources in the Studio 2.0 interface

1. Select “Add New”

2. Tenant ID will be filled in based on the environment that you logged in to

3. Fill in Source ID with a unique name, referring to your external data source

4. (Optional) Fill in a description, detailing what kind of data will come through the external data source

5. Copy the provided webhook URL + Authorization token to create the webhook in the external data source towards Spacewell Workplace

6. Make sure to enable your setup in Workplace

Image Added

Test your setup

• In case request is not successful, the endpoint returns 4xx-5xx status codes depending on the occurred issue.

• In case of successful request, the endpoint returns 200 status code with an empty body.

Image Added

Check below chapter “Troubleshooting” in case of doubts.

Configure the sensors in Workplace

For more information on how to add multiple new devices to Studio, check out Configure devices (add, remove, import/export).

Custom: 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).

Reach out to your Account Manager to set this up.

Troubleshooting

Legacy Generic End-Point Set-up

In the past, some external data sources were connected to Spacewell through a slightly different format. Because of that, there is a limitation only for the legacy / old generic endpoints:

1.  The old / legacy Generic Endpoints will be shown in Studio with the label 'Created by Spacewell'

2. User will not be take actions (Refresh Authorization token, Enable / Disable will all be greyed out)

3. User can only View, and Copy URL / Authorization token.

To Enable / Disable or Refresh authorization token, reach out to your Account Manager.

Search