Difficulty: expert

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:

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

  • 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
}

Expand
title External Data Sources for beginners - an analogy
Since you’re on this page: looks like the sensors, that are in scope of sending data to the Workplace platform, are sending data to a platform or database that is not connected to Workplace. Working your way down this page, we’ll make sure that there is a connection set up between the platforms, that the data is send is a format that Workplace can work with and knows how to identify. Setting up External Data Sources and sending data from an external database to the Workplace platform can be compared to “A car arrives at a gate. The car is known to the gate keeper, and the person in the car has a badge, because he told his contact person up front that he was coming.” Image Added We want the external platform to send data to Workplace, which is why we use webhook with HTTP method “post”. This means the data gets pushed by the other system, and Workplace will not have to pull it from somewhere. By creating an External Data Source in the tenant, you create a door or gate towards the Workplace platform: the Webhook URL. You’ll also receive the code to open the gate: the Authorization Token. Providing this information to the owners of the database, they are now able to reach the door. But they need to present us the data in a way that we can consume! So they need to adhere to some rules: the data they send us must be meaningful: Workplace needs to be able to do something with that data (for example present them on a live floor plan or in a dashboard). So the External Data Source needs to provide the data in any of the 10+ supported data types. it’s not enough that they would just throw some data at us. In order to correctly interpret that data, it needs to adhere to a specific (payload) format. In this way, we know which part of the information to interpret as the device ID, which part as the value we need to store in the Workplace database etc. For Spacewell to know where we need to store the data in our database, the sensor needs to be known on our end, and linked to a location. This is why the device needs to be registered in Studio. To register the device in Workplace Platform, you need: Device Type, which actually contains a preset of data types (per chosen DeviceType, a default set of channels is enabled). Device ID, which needs to be unique. In order to make this ID unique across all tenants, the device ID format includes the tenant ID In order to make this ID unique within the tenant, the device ID format includes the External Data Source ID Location information. If a sensor is not linked to a location, data is not stored in the Spacewell database. Image Added the fact that the car is arriving at the gate without Spacewell needing to do anything is the webhook the supported data type was the instruction to present at a specific gate the brand and model of the car is the payload, the vehicle that is used to present the data the data is in the trunk of the car the sensor ID is the badge used for identification the device type is the gate number the gate is open thanks to the authorization token Spacewell consultants that want to learn more about how Spacewell treats data that comes in, can check out /wiki/spaces/WM/pages/492237

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

How to set up this connection?

Steps described on this page:

1. In the external (customer or 3rd party) database: Configure data payload

2. Configure the connection between External Data Source and Workplace

3. Go to database and fill in URL and token, make sure to test the connection

4. Configure devices on Workplace platform

5. Devices send data to Workplace platform

Configure Data 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.eu1.cloud.cobundu.com/generic/<sensor_vendor>/data>

  • 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

For all data types, it makes sense to verify if data will be send regularly or not; see https://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#FAQ

Space occupancy related data types:

{
“device”"device": "<unique_device_id>", // string: unique id of the device
“type”"type": "footfall-in-pulsepir", // string: footfallpir infor pulse sensor
“timestamp”occupancy
"timestamp": "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "5"value": "1" // string: count of in pulses expressed as unsigned integer 0 or 1, 0 = not occupied, 1 = occupied
}

If your headcount device is able to track multiple count areas, you can send us the data of the individual count areas by replacing "<unique_device_id>"

through "<unique_area_id>".

{
“device”: "<unique_device_id>", // string: unique id of the device or count area
“type”: "footfall-out-pulseheadcount", // string: footfallheadcount outfor pulsemeasuring sensor
“timestamp”number of people
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "310" // string: count of out pulses expressed asvalue is unsigned integer
}

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "pirpulse", // string: pirpulse for occupancy door counters sending pulse values
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "1" // string: 0count orof 1,pulses 0expressed =as not occupied, 1 = occupied
}

unsigned integer
}

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "temperaturecounter", // string: temperature sensor count for door counters sending accumulated values 
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "25.510" // string: value inis Celsiusunsigned expressed as double with dot as decimal separator
}

integer
}

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "humidityfootfall-in-pulse", // string: footfall in humiditypulse sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "75.5" // string: count valueof in percentagepulses 0-100expressed as unsigned                    // expressed as double with dot as decimal separator
}

Indoor Air Quality related data types:

integer
}

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "co2footfall-out-pulse", // string: co2footfall forout carbonpulse dioxide sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "555.53" // string: measured valuecount of CO2out inpulses theexpressed airas (partsunsigned 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)
                   // 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
}

* Depending on the reliability of the sensor, space occupancy data may only contain data confirming “movement” (presence, headcount, footfall in one or the other direction etc), not the absence of movement… To tackle this in the Workplace platform, a decay feature has been introduced, which allows to visualize occupancy/headcount on the live (end user facing) floor plans for longer than what the data really tells us.

For an example on how Decay works, see https://spacewell.atlassian.net/wiki/spaces/KB/pages/491737/Motion+sensor#How-is-Motion-sensor-data-reflected-in-Workplace-Live-Views%3F

For a potential solution for data gaps in the dashboards (copy data in time slots), see https://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#FAQ

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”: "radonhumidity", // string: radonhumidity sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "1975.05" // string: radonvalue levelin measured is Becquerels per cubic meter, Bq/m3percentage 0-100
                     // 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

}

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

}

Configure the connection between External Data Source and Workplace

How to access

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

• Login with your credentials

• Select Integrations > 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

Once the webhook is created in the 3rd party database with above provided URL and token, make sure to test the connection.

This step is to be performed by the party that wants to send data to Spacewell Workplace.

Verify in a tool like Postman if your setup works:

• 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.

Next steps

To create custom Device Types and configure your third party sensors in Workplace, see Custom Device Types

FAQ

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.

Image Added

Search