2.4.2. Physical environment

Space information contains properties related to the description of a place within a facility’s physical environment and its relationship with other spaces. For example the surface area of a floor and in which building it is located.

Being able to get access to the space information and the hierarchical relationship between spaces defines the digital twin representation of the entire facility property environment that the resource owner can use to locate the connected devices throughout the smart buildings.

The physical environment Web API provides the capability for a client application to retrieve the digital twin from a physical environment information provider. It also provides the device location management interface that gives the flexibility to maintain the placement of a wide variety of devices.

2.4.2.1. Definitions

Common definitions

Object model definitions

2.4.2.1.1. Web API

Endpoint

The URL to access a service implemented on the server of an information provider with the aim to provide responses to requests sent by a client application

https://soapinc.com/fds/v2/specifications is the endpoint to access the specifications of my soap dispensers

Request

The action to be performed by the endpoint and requested by the client application. The action is identified by a HTTP method and can be

• GET: to retrieve item information from the provider

• POST: to let an information consumer create an item managed by the information provider

• PUT: to modify the content of an item managed by the information provider

• DELETE: to remove an item managed by the information provider

GET https://soapinc.com/fds/v2/specifications is the request to retrieve the specifications of my soap dispensers

Response

The information supplied by the information provider server in response of the request

The response to the GET https://soapinc.com/fds/v2/specifications is a list of device objects

Query parameters

Parameters added to the end of a request to specify additional information about the response expected by the server of the client application

To get the status of a soap dispenser, add the ‘ids’ query parameter with the device ID for the dispenser

Request header

A set of metadata information about the request provided by the client application that the server uses to manage the response

The authentication token in the request header lets the server assess if this is a valid request

Request body

A set of JSON-formatted data provided as part of the request that contains item information requested by the server of the client application

When defining the location of the soap dispenser, put the device ID in the request body of the POST https://soapinc.com/fds/v2/devices_location request

Response body

A set of JSON-formatted data part of the response that contains the information provided by the server of the information provider

The soap dispenser specifications will be found in the response body of the GET https://soapinc.com/fds/v2/specifications request/

2.4.2.2. FDS compliance requirements for new space types

This section provides the FDS compliance requirements when implementing the endpoints related to the physical environment and devices location in this environment.

2.4.2.2.1. Requirements common to all space-related endpoints

• All endpoints must provide the authorization token in the HTTPS header

• If a request is unauthorized, the information provider must return

  • a 401 HTTP status code in the response header

  • an error object in the response body with a “unauthorized_request” message

• If a query parameter name is invalid, the information provider must return

  • a 400 HTTP status code in the response header

  • an error object in the response body with a “invalid_parameter” message

• if a parameter provided appears more than once in the request, the information provider must return

  • a 400 HTTP status code in the response header

  • an error object in the response body with a “duplicate_parameter” message

2.4.2.2.2. Physical environment management

2.4.2.2.2.1. Spaces endpoint

• The digital twin information provider must expose the spaces endpoint to provide the list of spaces representing the physical physical_environment owned or managed by a resource owner

GET https://{Digital twin provider URL}/fds/v2/spaces

• The spaces enpoint must accept the query parameters

parameter	Type	Description
changed_since	date	The space objects that have been defined or changed since the specified date required To get the initial full list of space objects returned for the authorized space owner, provide a date long in the past

• If no query parameter is provided in the request, the information provider must return

  • a 400 HTTP status code in the response header

  • an error object in the response body with a “missing_parameter” message

• If the changed_since date is invalid or not properly formatted, the information provider must return

  • a 403 HTTP status code in the response header

  • an error object in the response body with a “invalid_date” message

• The information provider must return the full list of spaces found

• If no spaces are found in the query, the information provider must return an empty list of spaces

  • a 200 HTTP status code in the response header

  • the spaces object with an empty array of data

• Successful spaces information retrieval must return

  • a 200 HTTP status code in the response header

  • the spaces object containing the space object for each space

The following diagram provides a high level description of the spaces endpoint:

2.4.2.2.3. Device location management

These Web API endpoints provide the functionality for information consumers to manage the location of devices on the device location information provider’s side.

2.4.2.2.3.1. Get the location of devices

• The device location information provider must expose the GET request on the device_locations endpoint to provide in which spaces one or multiple devices are currently located

GET https://{Device Location Information Provider URL}/fds/v2/device_locations

• The device_locations enpoint must accept the query parameters

parameter	Type	Description
device_ids	Comma separated list of device IDs	The list of devices to query Optional If not specified, tag_ids must be provided
tag_ids	Comma separated list of tag IDs	the list of tags to query Optional If not specified, device_ids must be provided

• The information provider must accept both the device_ids and tag_ids parameter in the same request

• If no query parameter is provided in the request, the information provider must return

  • a 400 HTTP status code in the response header

  • an error object in the response body with a “missing_parameter” message

• If one or multiple device IDs do not exist on the information provider side, the information provider must return a successful response with an item_error object for each of the device information not available

  • a 200 HTTP status code in the response header

  • the device_locations object

  • The errors property must contain

    • the item_error objects for each device not found with

      • the device ID of the device

      • the item type must be “device”

      • the message must be “invalid_device”

• If one or multiple tags do not exist on the information provider side, the information provider must return a successful response with an item_error object for each of the tags not found

  • a 200 HTTP status code in the response header

  • the device_locations object

  • The errors property must contain

    • the item_error objects for each tag not found with

      • the tag ID of the tag

      • the item type must be “tag”

      • the message must be “invalid_tag”

• The device information provider can limit the number of device locations returned to avoid potentially large responses

• When response size limit is implemented and the limit is reached, the information provider must return

  • a 403 HTTP status code in the response header

  • an error object in the response body with

    • a “over_limit” message

    • the maximum number of device_location objects that can be returned

• Successful devices locations retrieval must return

  • a 200 HTTP status code in the response header

  • the device_locations object containing the device_location object for each device

The following diagram provides a high level description of the device_locations endpoint:

2.4.2.2.3.2. Specify the initial location of devices

• The device location information provider can expose the POST request on the device_locations endpoint to let a client application assign the initial location of devices in the physical environment.

POST https://{Device Location Information Provider URL}/fds/v2/device_locations

• The POST device_locations endpoint is optional. If the POST device_locations endpoint is not implemented, the information provider must return

  • a 204 HTTP status code

  • an error object in the response body with a “not_implemented” message

• The request body must contain a device_locations object

  • The device_locations object must only contain the data property

• If the device_locations object is not provided in the request body, the information provider must return

  • a 400 HTTP status code

  • an error object in the response body with a “missing_device_locations” message

• The devices must be unique in the list of devices to assign location to (a device cannot be assigned to multiple spaces)

• If a device is listed more than once, the information provider must abort the request for all devices in the list and return

  • a 403 HTTP status code

  • an error object in the response body with a “duplicate_devices” message

• The device information provider can limit the number of devices to assign to avoid potentially large transactions

• When the request size limit is implemented and the limit is reached, the information provider must return

  • a 403 HTTP status code in the response header

  • an error object in the response body with

    • a “over_limit” message

    • the maximum number of device_location objects that can be provided

• When assigning a device location to a space, the space ID must exist on the information provider side and belong to the resource owner or resource manager

• If one or multiple space IDs do not exist on the information provider side, the information provider must return a successful response with an item_error object for each invalid space ID

  • a 200 HTTP status code in the response header

  • the device_locations object

  • The errors property must contain

    • the item_error objects for each unavailable space with

      • the space ID of the space

      • the item type must be “space”

      • the message must be “invalid_space”

• If one or multiple devices are already assigned to a space, the information provider must return a successful response with an item_error object for each already assigned device

  • a 200 HTTP status code in the response header

  • the device_locations object

  • The errors property must contain

    • the item_error objects for each unavailable space with

      • the device ID of the device

      • the item type must be “device”

      • the message must be “already_assigned”

• Successful device location assignment must return

  • a 200 HTTP status code in the response header

  • the device_locations object

    • The data property must contain the device_location object for each device successfully assigned

The following diagram provides a high level description of the POST device_location request:

2.4.2.2.3.3. Change the location of devices

• The device location information provider can expose the PUT request on the device_locations endpoint to let a client application change the location of devices in the physical environment.

PUT https://{Device Location Information Provider URL}/fds/v2/device_locations

• The PUT device_locations endpoint is optional. If the PUT device_locations endpoint is not implemented, the information provider must return

  • a 204 HTTP status code

  • an error object in the response body with a “not_implemented” message

• The request body must contain a device_locations object

  • The device_locations object must only contain the data property

• If the device_locations object is not provided in the request body, the information provider must return

  • a 400 HTTP status code

  • an error object in the response body with a “missing_device_locations” message

• The devices must be unique in the list of devices to assign location to (a device cannot be assigned to multiple spaces)

• If a device is listed more than once, the information provider must abort the request for all devices in the list and return

  • a 403 HTTP status code

  • an error object in the response body with a “duplicate_devices” message

• The device information provider can limit the number of devices to change to avoid potentially large transactions

• When the request size limit is implemented and the limit is reached, the information provider must abort the request for all devices in the list and return

  • a 403 HTTP status code in the response header

  • an error object in the response body with

    • a “over_limit” message

    • the maximum number of device_location objects that can be provided

• When assigning a device location to a space, the space ID must exist on information provider side and belong to the resource owner or resource manager

• If one or multiple space IDs do not exist on the information provider side, the information provider must return a successful response with an item_error object for each invalid space ID

  • a 200 HTTP status code in the response header

  • the device_locations object

  • The errors property must contain

    • the item_error objects for each unavailable space with

      • the space ID of the space

      • the item type must be “space”

      • the message must be “invalid_space”

• If one or multiple devices are not already assigned to a space, the information provider must return a successful response with an item_error object for each already assigned device

  • a 200 HTTP status code in the response header

  • the device_locations object

  • The errors property must contain

    • the item_error objects for each unavailable space with

      • the device ID of the device

      • the item type must be “device”

      • the message must be “not_assigned”

• Successful device location assignment must return

  • a 200 HTTP status code in the response header

  • the device_locations object

    • The data property must contain the device_location object for each device successfully changed

The following diagram provides a high level description of the PUT device_location request:

2.4.2.2.3.4. Remove devices from the physical environment

• The device location information provider can expose the DELETE request on the device_locations endpoint to let a client application remove devices from the physical environment.

DELETE https://{Device Location Information Provider URL}/fds/v2/device_locations

• The DELETE device_locations endpoint is optional. If the DELETE device_locations endpoint is not implemented, the information provider must return

  • a 204 HTTP status code

  • an error object in the response body with a “not_implemented” message

• The request body must contain a device_locations object

  • The device_locations object must only contain the data property

• If the device_locations object is not provided in the request body, the information provider must return

  • a 400 HTTP status code

  • an error object in the response body with a “missing_device_locations” message

• The devices must be unique in the list of devices to remove (a device cannot be removed from multiple spaces)

• If a device is listed more than once, the information provider must abort the request for all devices in the list and return

  • a 403 HTTP status code

  • an error object in the response body with a “duplicate_devices” message

• The device information provider can limit the number of devices to remove to avoid potentially large transactions

• When the request size limit is implemented and the limit is reached, the information provider must abort the request for all devices in the list and return

  • a 403 HTTP status code in the response header

  • an error object in the response body with

    • a “over_limit” message

    • the maximum number of device_location object that can be provided

• When assigning a device location to a space, the space ID must exist on information provider side and belong to the resource owner or resource manager

• If one or multiple space IDs do not exist on the information provider side, the information provider must return a successful response with an item_error object for each invalid space ID

  • a 200 HTTP status code in the response header

  • the device_locations object

  • The errors property must contain

    • the item_error objects for each unavailable space with

      • the space ID of the space

      • the item type must be “space”

      • the message must be “invalid_space”

• If one or multiple devices are not already assigned to a space, the information provider must return a successful response with an item_error object for each already assigned device

  • a 200 HTTP status code in the response header

  • the device_locations object

  • The errors property must contain

    • the item_error objects for each unavailable space with

      • the device ID of the device

      • the item type must be “device”

      • the message must be “not_assigned”

• If one or multiple devices are not currently located at the space provided in the request, the information provider must return a successful response with an item_error object for each device associated to the wrong space

  • a 200 HTTP status code in the response header

  • the device_locations object

  • The errors property must contain

    • the item_error objects for each unavailable space with

      • the device ID of the device

      • the item type must be “device”

      • the message must be “invalid_location”

• Successful device location removal must return

  • a 200 HTTP status code in the response header

  • the device_locations object

    • The data property must contain the device_location object for each device successfully removed

The following diagram provides a high level description of the DELETE device_location request:

2.4.2.3. Workflow

This section provides a guideline and best practice to use the physical environment Web API endpoints.

2.4.2.3.1. Retrieving the digital twin

Once a business agreement is in place between a resource owner (the owner or manager of facilities) and the digital twin producer, the resource owner can retrieve the digital twin of the facilities through the spaces endpoint. Because a physical environment doesn’t change often, it is recommended to store the collection of space objects locally on the client application. How the spaces are stored locally is up to the client application.

Note that there is no rules on the order of the spaces in the collection returned by the spaces endpoint, and the client application should assume that they are un-ordered. However, it is always possible to build the tree hierarchy locally. One of the possible workflow is described in the following diagram:

Even if infrequent, changes happen to the physical environment. There are two types of changes that can happen to a facility (other than change of ownership)

• a change in the physical environment (a building is added to a site, or a building is remodeled for example)

• devices are added or removed in part of the physical environment

It is strongly recommended that the digital twin producer always remains the ground truth of the physical environment, and that the client application keeps the local digital twin information up-to-date through a periodic (weekly or monthly) call to the spaces endpoint similar to the following workflow diagram:

Regarding changes in the physical environment:

• If a space object is added to a facility (for example a new office is built on a floor), the digital twin producer will return the new space object and also the next level up space object with the new space ID in the composed_of property.

  • The following workflow diagram shows an example of how to manage new spaces

• If a space object is removed (for example a toilet is removed in a bathroom), the digital twin producer will only return the space object of the next level up with the space ID of the obsolete space removed from the composed_of property. Note that if a removed space was composed of smaller spaces (for example a suite composed of offices is demolished) then all the space objects for the smaller space are assumed to be deleted as well.

  • The following workflow diagram shows an example of how to manage deleted spaces

• If a space is being reallocated or other properties have changed (the space type is changed from a room to a suite, or the space name is changed form “John’s office” to “Mary’s office”), The digital twin producer will only return the space object of the space that was modified.

Regarding devices:

• If a device is added to a space (for example a people counter at the entrance of a building), the digital twin producer will return the existing space object with the updated contains_devices property listing the new device ID

• If a device is removed from a space (for example a broken paper dispenser), the digital twin producer will return the existing space object with the updated contains_devices property with the device ID removed from the list

• If a device has changed location (for example a trash bin moved from one office to another), the digital twin producer will return two space objects:

  • The space object of the office where the device was previously located with the device ID removed from the contains_devices property

  • the space object of the office where the device is now located with the device ID added to the contains_devices property

In all cases it is up to the client application to manage the changes locally.

2.4.2.3.2. Device location management

There can be multiple use cases regarding who is managing the physical installation of devices in the physical environment:

• The digital twin producer is also responsible for the management of the smart building and therefore also maintains the location of the devices in the physical environment

• A third party is responsible for the digitalization of a facility, decides which devices should be installed where, and manages the devices locations. In this case it is strongly recommended that the device location manager gets the digital twin information from the digital twin producer, and then become the only interface to the client application

• The resource owner or resource manager (a facility manager for example) is responsible for installing the devices and manages the devices locations

• A combination of actors (the resource manager and digital twin producer for example) manage the devices locations based on the type of devices. For example, the resource manager can manage the location of the mobile cleaning equipment, while the digital twin producer manages all the fixed devices.

The following diagram provided the recommended relationship between possible parties, with the objective to maintain a single ground truth keeper:

When the client application manages the location of devices, it is strongly recommended that it maintains its local digital twin from the ground source keeper instead of updating the local space objects, as described in the following workflow diagram:

2.4.2.4. Use case example

Note

Join FDS to get access to examples and use cases.