Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 2 Next »

Difficulty: expert

Content

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.

Once that connection is established, it’s possible to create custom device types for a more streamlined and efficient sensor management experience:

  • Clear and descriptive device type names help distinguish between sensors, allowing for quick & accurate identification when troubleshooting or replacing sensors

  • Customizable threshold settings for each device type trigger alerts and proactive maintenance actions, ensuring optimal sensor performance

Prerequisites

The sensor vendor needs to comply with the Spacewell webhook, supported data types & payload, see External Data Sources

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.

Configure Device Types on Workplace

How to access

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

  • Login with your credentials

  • Select Integrations > Device Types in the Studio 2.0 interface

  • Select “Add New”

General

  1. Device Type Name

  2. Device Type ID is used as a unique identifier of your device type, for example in batch device import

    1. Custom Device Type IDs always include the prefix “Generic|”

Device Type ID should only include lowercase alphabetic characters, numeric characters or - symbol

  1. External Data Source

    1. select a specific External Data Source if the data for this device type will always be provided from 1 External Data Source. Establishing this 1-on-1-connection is beneficial for device registration in Workplace (see below chapter “Configure devices in Workplace“)

    2. select “Any” if the data for this device type might come from different External Data Sources. In this case, device registration in Workplace is a bit more complex (see below chapter “Configure devices in Workplace“)

  2. Status: enable to select the Device Type from the Device Type drop down when configuring devices in Workplace

  3. Device Image: keep the default icon, select a generic icon or upload a picture of your device type. This image will be visible on the device label

image-20240522-160705.png

Sensor Health

Sensor Health is derived from the last communication from the sensor to the Workplace Platform. The communication can be a sensor value or a heartbeat. Since every type of device has its own heartbeat frequency, the health of the device is evaluated per device type. For more information, see How to monitor Sensor Health

Fill in numeric values that will be used to change the status of devices linked to the device type:

  1. To Check

  2. Offline

    1. value needs to be larger than To Check value

image-20240523-154234.png

Sensor Details

From the list of supported data types, select which channels are relevant for the device type that you’re creating. In other words: which kind of sensor data will be send to Workplace by devices that are set up according to this device type?

  • CO₂

  • Counter

  • Footfall Pulse (in)

  • Footfall Pulse (out)

  • Headcount

  • Humidity

  • Presence*

  • Pulse

  • Radon

  • Temperature

  • VOC

* Presence

When it comes to presence / motion sensors, there is a difference in how some confirm or just don’t confirm the absence of presence :

  • Select "No" if the device sends presence data to confirm occupancy, and might send data to confirm vacancy, but does not send this vacancy confirmation as soon as the location is available (~ is not reliable in confirming vacancy)

  • Select "Yes" if the device sends presence data to confirm occupancy, and also sends data to confirm vacancy as soon as the location is available again

This has nothing to do with sensor accuracy or “the sensor itself being reliable of sending data”. It’s about the reliability of the statement “occupied” after no presence detection for some time.

When a sensor is unreliable in confirming vacancy, meaning that we’re not 100% sure when the location is available again, you can configure icon decay on live floor plan through https://spacewell.atlassian.net/wiki/spaces/KB/pages/491694/Live+floorplan+settings#Occupancy-settings.

 Examples for (un)reliable conveying the absence of presence

Example 1. PIR motion sensor

The PIR motion sensor in this example sends data confirming “presence detected” as soon as it’s triggered. In this sense, the sensor is reliable in conveying occupancy confirmations.

Yet if the user moves away from the sensor, and objectively the room is vacant, the sensor does not immediately send a status change. So the sensor is unreliable in conveying vacancy confirmations.

Upon creation of this Device Type, select “unreliable”.

Example 2. Headcount sensor providing occupancy data

The headcount sensor in this example sends data every minute:

  • The data can be 1 or higher, meaning at least 1 person is detected. This can be interpreted as “presence detected”, since the location is occupied.

  • The data can be value “0”, meaning no headcount detected - which actually can be translated to “no presence detected” or “this location is vacant”.

In this case, even if someone walks into a room to get something and immediately leaves the room, after latest 2 minutes, Workplace is updated with the information that there is no (longer) any occupancy detected in that location.

Upon creation of this Device Type, select “reliable”.

Configure devices in Workplace

Prerequisites

Depending on the (known) connection between the Device Type and a specific External Data Source, different information is required to configure devices in Workplace:

1. If Device Type is set up to connect to a specific External Data Source

Having set up a 1-on-1-connection between Device Type and External Data Source, is beneficial for device registration in Workplace Studio:

  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 relevant Device Type from the drop-down list. As per the chosen DeviceType, a default set of channels is enabled

  4. Fill in the Device ID that is used in the payload to report on this data point*

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

  6. Location will be filled in based on your pre-selection in the location tree

* In Workplace, a prefix referring to the tenant ID and external data source ID will be added to the device ID. This will be visible in Devices Export.

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

Make sure to include tenant and source ID (in format “<tenant_id>-<source_id>”) if you’re creating devices through Device Import feature. For more information, see below.

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.

2. If Device Type is set up to connect to “Any” External Data Source

Select “Any” if the data for this device type might come from different External Data Sources. In this case, device registration in Workplace is a bit more complex:

  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 relevant Device Type from the drop-down list. As per the chosen DeviceType, a default set of channels is enabled

  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>

 Example 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 case of 3rd party vendor will need to be provided by the 3rd party)

  • 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, and export).

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

 What 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 Spacewell 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.

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.

Troubleshooting

 Successfull connection message, but sensor is not loading any data

Make sure the following configuration is in place:

Search

  • No labels