Versions Compared

Version Old Version 2 New Version Current
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.

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

Infonote

Within 1 vendor IDyour Workplace environment, 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|”

Note

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

Info

After saving, in Edit mode, it’s not possible to update Device Type ID anymore

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

Info

After saving, in Edit mode, it’s not possible to update External Data Source link anymore

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

  2. Device Image: keep the default

icon

  1. image, select a generic

icon

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

Note

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.

Expand
titleExamples 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

Info

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

Info

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.

Note

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>

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

Note

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

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 delete a Device Type?

In Workplace, it’s possible to disable a Device Type, but you can’t delete. Deletion would impact devices that have been created with this device type.

Troubleshooting

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

Make sure the following configuration is in place:

Expand
titleCreated a Device Type but not showing in Add New Device drop down

If you’ve created a Device Type but it’s not showing in “Add New Device” drop down, make sure your Device Type status is enabled.

Search

Live Search