Versions Compared

Version Old Version 26 New Version 27
Changes made by

Julie Isebaert

Julie Isebaert

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Difficulty: expert

Content

Table of Contents
minLevel1
maxLevel1

Learning Objectives

After reading this article, you’ll be able to:

  • Identify which data types are supported by Spacewell Workplace

  • Configure webhook & authorization token to connect your external data sources to Workplace

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.

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

Info

Within 1 vendor ID, sensor IDs need to be unique and prepended with the vendor ID.
Combining device IDs from multiple third parties in 1 External Data Source, raises the potential risk of conflicts.

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.

Supported data types & payload

Space occupancy related data types:

Expand
titlePIR: space occupancy
Code Block
languagejson
{
"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
titleHeadcount: for measuring number of people
Code Block
languagejson
{
“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
titlePulse: for door counters sending pulse values
Code Block
languagejson
{
“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
titleCount: for door counters sending accumulated values
Code Block
languagejson
{
“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
titlefootfall-in pulse
Code Block
languagejson
{
“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
titleFootfall-out pulse
Code Block
languagejson
{
“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
titleParking
Code Block
languagejson
{
“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
titleTemperature
Code Block
languagejson
{
“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
titleHumidity
Code Block
languagejson
{
“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
titleCO2
Code Block
languagejson
{
“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
titleTVOC (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
titleRadon
Code Block
languagejson
{
“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

  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

Note

In Source ID field, only use alphanumeric values. The Source ID will later be used as a component of the device IDs.

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

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

  3. Make sure to enable your setup in Workplace

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.

Check below chapter “Troubleshooting” in case of doubts.

Configure the sensors in Workplace

  1. Go to your environment (https://studio.cobundu.com ) and log in

  2. Select the location, and manually add a sensor via "Add New Device"

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

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

  4. Fill in the Device ID, using the tenant ID and source ID available in Settings > External Data Sources. Adhere to the format <tenant_id>-<source_id>|<device_id>

Expand
titleExample device ID

for example

  • if you want to configure a sensor with ID “123” (unique_device_id that will be mentioned in the payload)

  • in an environment with tenant ID “spacewell”

  • where an External Data Source with source ID “testgeneric” has been set up

the Spacewell Device ID will be

“spacewell-testgeneric|123"

  1. Give a meaningful name (eg customer_floor number_area) in Device Name.

  2. 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).

Info

Within 1 vendor ID, sensor IDs need to be unique and prepended with the vendor ID.
Combining device IDs from multiple third parties in 1 External Data Source, raises the potential risk of conflicts.

FAQ

Expand
titleWhat if the sensor does not regularly send data? Is it possible to copy data in timeslots?

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.

Info

Consequently, Workplace will only visualize or report 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.

Expand
titleIs it possible to connect multiple external data sources through the same endpoint in Workplace?

It's possible to re-use the external data source information (Authentication token + URL).

So if devices have the same behavior, but are linked to different external data sources, it’s possible to only set up 1 endpoint in Studio, and have the 2 external data source send data to that same Workplace endpoint.

Info

Within 1 vendor ID, sensor IDs need to be unique and prepended with the vendor ID.
Combining device IDs from multiple third parties in 1 External Data Source, raises the potential risk of conflicts.

Troubleshooting

Expand
titleNot getting a 200 status code (indicating succesful connection)?

Make sure the following configuration is in place:

  • the connection details used in the external data source are the ones provided by Spacewell

  • verify the authorization code has not been updated / changed in Workplace

  • adhere to the required supported data types & payload

Expand
titleSuccessfull connection message, but sensor is not loading any data

Make sure the following configuration is in place:

Expand
titleSeeing "Created by Spacewell" and not able to refresh the token or enable/disable the external data source?

See “Legacy Generic End-Point Set-up” chapter below

Expand
titleNot able to refresh the token or enable/disable the external data source?

For security reasons: If a user logs in with a multi-tenant account, they are not able to make any changes to any external data sources.

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

Live Search