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. Definitions ----------- :doc:`Common definitions <../../common/common_definitions>` :doc:`Object model definitions <../../common/object_model_definitions>` .. include:: ../../common/pull_model_definitions.rst 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. 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 Physical environment management ''''''''''''''''''''''''''''''' 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 .. code-block:: 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: .. figure:: ../../_static/spaces_endpoint.png :width: 100% 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. 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 .. code-block:: 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 | - The list of devices to query | | | of device IDs | - Optional | | | | - If not specified, tag_ids must be provided | +--------------------+-------------------------+-----------------------------------------------------+ | tag_ids | Comma separated list | - the list of tags to query | | | of tag IDs | - 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: .. figure:: ../../_static/get_device_locations_endpoint.png :width: 100% 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. .. code-block:: 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: .. figure:: ../../_static/post_device_locations_endpoint.png :width: 100% 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. .. code-block:: 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: .. figure:: ../../_static/put_device_locations_endpoint.png :width: 100% 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. .. code-block:: 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: .. figure:: ../../_static/delete_device_locations_endpoint.png :width: 100% Workflow -------- This section provides a guideline and best practice to use the physical environment Web API endpoints. 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: .. figure:: ../../_static/space_hierarchy_workflow.png :width: 100% 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: .. figure:: ../../_static/spaces_update_workflow.png :width: 100% 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 .. figure:: ../../_static/new_space_workflow.png :width: 100% - 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 .. figure:: ../../_static/spaces_delete_workflow.png :width: 100% - 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. 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: .. figure:: ../../_static/device_location_management_workflow.png :width: 100% 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: .. figure:: ../../_static/device_location_update_workflow.png :width: 100% .. include:: ../../common/use_case_pull_model_physical_environment.rst