Object models ============= The object models define how the content of the information exposed is formatted based on the semantics of the information. The models are organized along categories that define the operational state of the facility: - **The Device model** defines the digital 'population' that communicates and interacts in the facility - **The Space model** defines the geographical environment of the facility - **The Event model** defines the changes happening in the ecosystem, whether in the devices, the environment, or the operations - **The Tag model** defines logical organizations and groupings .. note:: Other models such as a **Task model** that will define the activities and scheduled operations in the facility will be added in future versions with the aim to complete the definition of the operational state of the facility Definitions ----------- :doc:`Common definitions <../common/common_definitions>` .. include:: ../common/object_model_definitions.rst .. include:: ../common/tags_definitions.rst .. include:: ../common/errors_definitions.rst FDS compliance requirements --------------------------- The core structure '''''''''''''''''' All object models must follow the same **item root structure** - an **ID** that uniquely identifies an item (device, space, message, or tag) across the digital world - a **generic** object that contains properties that are common to an item (device type, space type, message code, or tag) - the generic object is **required** - Properties in the generic object must always be required *For example, every device has a manufacturer that must be exposed* - a **specific** object that contains properties that only apply to a specific type of an item (device type, space type, message code, or tag type) - the specific object is **optional** - Properties in the specific object can be required or optional *For example, trash bins are a type of device that have specific information such as the bin volume* When representing information for a collection of items, the object model must follow the **collection root structure** - a **data** property that contains an array of item objects - The item object depends on the structure of the information being represented *For example, when retrieving the status of a collection of devices, the item object is a status object* - an **errors** property that contains an array of **item_error** objects for each item containing an error - Information about an item must be in only one of the data array or errors array - an optional **count** property that contains the number of items in the data array Properties '''''''''' - Properties must follow the JSON key-value pair definition. - Some of the properties can be defined as objects, allowing for a hierarchical object model structure Required properties """"""""""""""""""" - Required properties must always be included in the response with a valid value. - If a provider is unable to expose a required property, then the 500 HTTP status code must be returned, and the response must contain an ‘error ' object which must contain a message clearly identifying the data that is not available. Optional properties """"""""""""""""""" If a data provider does not expose an optional property, or if the data is not available for any reasons at the time of the request, the property must not be included in the response. For example, a 'specification' object model for a device type has the following required and optional properties: .. code-block:: { device_id: required generic: required device_type: required manufacturer: required device_type_specific: optional country: optional production_date: optional } - Case 1: the provider **exposes** the optional data .. code-block:: json { "device_id": "CLEANINC_C1_1234", "generic": { "device_type": "cleaning_machine", "manufacturer": "Clean Inc." }, "device_type_specific": { "country": "USA", "production_date": "2020-02-15T00:00:00Z" } } - Case 2: the provider **doesn't expose** the optional data .. code-block:: json { "device_id": "CLEANINC_C1_1234", "generic": { "device_type": "cleaning_machine", "manufacturer": "Clean Inc." } } - Case 3: the provider **exposes** the optional data but production_date **is not available** .. code-block:: json { "device_id": "CLEANINC_C1_1234", "generic": { "device_type": "cleaning_machine", "manufacturer": "Clean Inc." }, "device_type_specific": { "country": "USA" } } Unique ID ''''''''' All entities (device, space, event, tag) must be identifiable by a unique ID using Universally Unique Identifiers as defined in standard ISO/IEC 9834-8 (`Information technology — Procedures for the operation of object identifier registration authorities — Part 8: Generation of universally unique identifiers (UUIDs) and their use in object identifiers `__) This applies to: - Device IDs - Space IDs - Event IDs - Tag IDs .. Attention:: FDS Version 1 defined a different format for Device IDs: - The device ID must be formed by the concatenation of - The manufacturer - String of at least 3 characters - The model - String of at least 2 characters - The serial number - String of at least 1 character - The device ID must follow the format - "__" Devices defined in FDS version 1 will work in FDS version 2. All new devices defined using FDS version 2 shall use the UUID definition. Errors '''''' The following diagram provides an overview of the **error** and **item_error** objects. .. figure:: ../_static/error_object_model.png :width: 100% - Error information related to an error in the communication protocol must be provided in the **error** object - Every error must contain the status code - The status code must be one of - 204 - 400 - 401 - 403 - Every error must contain a language-independent descriptive message - The descriptive message must be one of - "not_implemented" - "unauthorized_request" - "invalid_parameter" - "duplicate_parameter" - "missing_parameter" - "invalid_parameter_combination" - "invalid_date" - "invalid_start_date" - "invalid_end_date" - "missing_device_locations" - "duplicate_devices" - "missing_tag" - "invalid_tag" - "invalid_tag_object" - "invalid_entities" - "tag_already_exists" - "invalid_associations" - "over_limit" - For example, a request to get device specifications since January 1st 2021 with an invalid date format would return an error object similar to: .. code-block:: json { "status": 400, "message": "invalid_date", "additional_info": "not_iso_8601_compliant" } - Error information related to an item (device, space, message, tag...) must be provided in the **item_error** object - Every item error must contain the ID of the item - Every item error must contain the type of the item - The item type must be one of - "device" - "space" - "message" - "message_code" - "tag" - Every item error must contain a language-independent descriptive message - The descriptive message must be one of - "invalid_device" - "invalid_tag" - "invalid_space" - "invalid_message_code" - "invalid_location" - "duplicate_devices" - "already_assigned" - "not_assigned" - For example, a request to get device statuses for 2 device IDs known by the information provider and 2 unknown device IDs would return: .. code-block:: json { "data": [ { "" }, { "" } ], "errors": [ { "item_id": "0312c7a7-1e59-5990-7ed7-e99535f3826d", "item_type": "device", "message": "invalid_device" }, { "item_id": "22850fd0-2871-3813-832f-4f73abf0857f", "item_type": "device", "message": "invalid_device" } ], "count": 2 } Images '''''' Information about images that can be displayed in a browser environment must be provided in the **image** Object. The following diagram provides an overview of the image and device_image objects. .. figure:: ../_static/image_object_model.png :width: 100% - Every image must contain a public url of the location of the image - When provided, the content type of the image must be one of - "jpg" - "png" - "pdf" - "gif" - "bmp" - "png" - Images about a device must be provided in the **device_image** object - A device image must contain an **image** object with the path of the full size image The detailed API specifications for each object can be found in the `reference <../reference>`__ chapter. Geolocation ''''''''''' Information about geolocation (longitude and latitude) of an entity (device or space) must be provided in the **geolocation** object. The following diagram provides an overview of the geolocation and device_geolocation objects. .. figure:: ../_static/geolocation_object_model.png :width: 100% - The **geolocation** object must comply to the GeoJSON format defined in (`RFC 7946 `__) - the type must be "Point" - the coordinates must be an array of two elements. - The first element must be the longitude - The second element must be the latitude - For example .. code-block:: json { "type": "Point", "coordinates": [-93.3131726, 44.9138571] } - Geolocation of a device must be provided in the **device_geolocation** object - A device geolocation must contain a **geolocation** object - A device geolocation can provide an accuracy and timestamp information - For example, a mobile device can provide its geolocation within a 100m radius accuracy: .. code-block:: json { "geolocation": { "type": "Point", "coordinates": [-93.3131726, 44.9138571] }, "geolocation_accuracy": { "not_better_than": 0.1, "not_worse_than": 100.0 }, "geolocation_timestamp": "2021-02-25T23:45:23Z" } The detailed API specifications for each object can be found in the `reference <../reference>`__ chapter. Health Status ''''''''''''' The health status of a device or a component of a device is provided in the **health** object. The following diagram provides an overview of the health object. .. figure:: ../_static/health_object_model.png :width: 100% - The health status must be one of - "operational" - "maintenance_required" - "defective" - "unknown" - Additional information can be provided in the health_details array. When defined, the health details must be one or multiple message codes as defined in the event Model - The following example shows the health status of a device no longer operational because it got damaged by an impact and the battery reached its end of life .. code-block:: json { "health_status": "defective", "health_timestamp": "2021-02-25T23:45:23Z", "health_details": ["impact", "critical_battery_level"] } The detailed API specifications for each object can be found in the `reference <../reference>`__ chapter. Battery Information ''''''''''''''''''' Information about battery systems in a device is provided in the **battery** object. The following diagram provides an overview of the battery object. .. figure:: ../_static/battery_object_model.png :width: 100% - This object applies for both non-rechargeable and rechargeable battery systems - For rechargeable batteries, information about the last charge cycle can be provided in the **charge** Object - The following example shows the minimum battery status information for a non-rechargeable Battery .. code-block:: json { "battery_level": 0.9, "battery_timestamp": "2021-02-25T23:45:23Z" } - The following example shows the status of a rechargeable battery that reached its end of life .. code-block:: json { "battery_level": 0.5, "battery_timestamp": "2021-02-25T23:45:23Z", "battery_health": { "health_status": "maintenance_required", "health_timestamp": "2021-02-25T05:20:00Z", "health_details": ["impact", "critical_battery_level"] }, "battery_last_charge": { "charge_cycle": 769, "last_charge_initial_level": 0.1, "last_charge_final_level": 1.0, "last_charge_start_time": "2021-02-25T05:03:00Z", "last_charge_end_time": "2021-02-25T05:20:00Z" } } The detailed API specifications for each object can be found in the `reference <../reference>`__ chapter. Signal Information ''''''''''''''''''' Most devices communicate their data through a wireless mechanism. Signal information is provided in the **signal** object. The following diagram provides an overview of the signal object. .. figure:: ../_static/signal_object_model.png :width: 100% - The signal strength, or the signal level, or both must be provided - If the signal strength is not being reported, then the signal level must be provided - If the signal level is not being reported, then the signal level must be provided - When provided, the signal technology must be one of: - "wifi" - "2g" - "3g" - "4g" - "5g" - "lte" - "lte_m" - "bluetooth_4.1" - "bluetooth_4.2" - "Bluetooth_5" - "ble" - "lora" - "wirepas" - "enocean" - "rfid" - "nb_iot" - The following example shows the signal information for a device communicating through 4G .. code-block:: json { "signal_strength": -32.0, "signal_level": 3, "signal_timestamp": "2021-02-25T23:45:23Z", "signal_technology": "4g" } The detailed API specifications for the signal object can be found in the `reference <../reference>`__ chapter. Usage Variation Recordings '''''''''''''''''''''''''' When reporting dynamic information with large variation between two readings, such as power usage, motor RPM, or device temperature, information providers can use the generic **variation_recording** object. The following diagram provides an overview of the geolocation and device_geolocation objects. .. figure:: ../_static/variation_recording_object_model.png :width: 100% - Because the object is generic, the variation recording must provide the unit of the recording - The supported units are +--------------------------------+---------------------------------------+ | Recording | Unit | +================================+=======================================+ | distance | "m" | +--------------------------------+---------------------------------------+ | surface | "m2" | +--------------------------------+---------------------------------------+ | volume | "m3" | +--------------------------------+---------------------------------------+ | temperature (degrees Celsius) | "celsius" | +--------------------------------+---------------------------------------+ | voltage (Volt) | "v" | +--------------------------------+---------------------------------------+ | current (aAmp) | "a" | +--------------------------------+---------------------------------------+ | power consumption (Watt) | "w" | +--------------------------------+---------------------------------------+ | Energy consumed (Watt-Hour) | "wh" | +--------------------------------+---------------------------------------+ | Motor speed (RPM) | "rpm" | +--------------------------------+---------------------------------------+ | Pressure (Pascal) | "pa" | +--------------------------------+---------------------------------------+ - the last reading and the timestamp of the last reading must be provided - The information provider can also specify the minimum and maximum readings in the last 24 hours, along with the average value over a 24 hours period - The following example shows the device internal temperature Recordings .. code-block:: json { "unit": "celsius", "last_reading": 22, "last_reading_timestamp": "2021-02-25T23:45:23Z", "average_24h": 20, "max_24h": 30, "min_24h": 10 } The detailed API specifications for each object can be found in the `reference <../reference>`__ chapter. The Device Model '''''''''''''''' The following diagram provides an overview of the Device Model .. figure:: ../_static/device_object_model.png :width: 100% - Every device must be associated to a device type - The device type must be one of - "cleaning_machine" - "dispenser" - "bin" - "waste_station" - "smart_handle" - The object model for all device types depends on the type of information exposed - Static information throughout the life of a device must be exposed in the **specification** object - Dynamic information about the latest known state of the device must be exposed in the **status** object - Aggregated historical information of a device must be exposed in the **statistic** object - Predictive information about a device must be exposed in the **diagnostic** object - The specification, status, statistic, and diagnostic objects must follow the item core structure - The content of the generic object is defined for each of these objects - The content of the specific object is defined at the device type level - A collection of specification, status, statistic, or diagnostic objects must follow the collection core structure - The item object for a collection of specifications must be the **specification** object - The item object for a collection of statuses must be the **status** object - The item object for a collection of statistics must be the **statistic** object - The item object for a collection of diagnostics must be the **diagnostic** object - Errors related to exposing information about a specific device must be exposed in a **item_error** object - The item type in the item_error object must be **"device"** The detailed API specifications for each object can be found in the `reference <../reference>`__ chapter The Space Model '''''''''''''''' Physical environment """""""""""""""""""" The space information must be exposed through the **space** object. The following diagram provides an overview of the Space Model .. figure:: ../_static/space_object_model.png :width: 100% - Every space must be associated to a space type - The space type must be one of - "site" - "building" - "floor" - "suite" - "room" - "restroom" - "toilet" - "hallway" - "corridor" - "aisle" - "cubicle" - "section" - The space object must follow the item core structure - The content of the specific object is defined at the space type level - The creation date must be the date the space was built or defined - For example, if a site first became operational in May 2010, with only one building, then the creation date will be May 2010 for all spaces. - If a new building was completed in October 2011, then the creation date will be October 2011 for this building and all spaces in the building. - If a floor in a building has been remodeled in July 2012, then all the new spaces on that floor will have a creation date of July 2012, but the floor itself will maintain its original creation date. - The space model must define a hierarchical tree structure of the physical environment - a space must be part of one and only one larger space - a space must be composed of one or multiple smaller spaces - A space object must provide the full upward hierarchy to represent a space in the context of the full physical environment - The upward hierarchy must be exposed through the **space_chain** object - A special self-contained space object representing a void must be exposed - the space ID must be "00000000-0000-0000-0000-000000000000" - the space type must be "nothing" - the nothing space must be part of nothing - the nothing space must be composed of nothing .. code-block:: json { "space_id": "00000000-0000-0000-0000-000000000000", "generic": { "space_type": "nothing", "name": "nothing", "part_of": { "space_id": "00000000-0000-0000-0000-000000000000", "space_type": "nothing" } } } - The top level space in the hierarchical tree must be part of nothing - The lowest (most granular) space in the hierarchical tree must be composed of nothing - When one or multiple devices are associated to a space, the space object must define the "contains_devices" property in the space type specific object - A collection of space objects must follow the collection core structure - The item object for a collection of spaces must be the **space** object - Errors related to exposing information about a specific space must be exposed in the **item_error** object - The item type in the item_error object must be **"space"** The detailed API specifications for each object can be found in the `reference <../reference>`__ chapter. Device Location """"""""""""""" The relationship between a device and the space where it is located must be exposed through the **device_location** object. - A collection of device locations must follow the collection core structure - The item object for a collection of device locations must be the **device_location** object - Errors related to exposing information about a specific device location must be exposed in the **item_error** object - The item type in the item_error object must be **"device"** The Event model ''''''''''''''' The following diagram provides an overview of the Event Model. .. figure:: ../_static/event_object_model.png :width: 100% - The event information must be exposed through the **message** object - Every event must have an "alert" or "notification" category - Every event must be associated with an entity ID (device ID or space ID) - Every event must be associated with the entity type (all supported device types and all supported space types) - Every event must be associated with a message code - The message code must be one of: +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | Message code | Description | Message category | Message code specific object | +================================+=======================================+==================+========================================+ | out_of_order | The device is out of order | alert | **out_of_order_details** property | | | and needs service intervention | | - array of information provider codes | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | out_of_order_recovery | The device is operational again | notification | **correlation_id** property | | | following an out of order problem | | - UUID of out of order event | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | regular_maintenance | The device is due for its regular | notification | None | | | maintenance service | | | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | regular_maintenance_completed | The regular device maintenance | notification | **correlation_id** property | | | was performed | | - UUID of regular maintenance event | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | impact | An impact on the machine was detected | notification | None | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | opportunity_charging | An opportunity charging of a | notification | **opportunity_charge** | | | lead acid battery has been detected | | - Charge object | | | (battery not fully charged) | | | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | low_battery_level | The device has a low battery level | notification | **battery_level** property | | | and needs to be recharged or replaced | | | | | soon | | | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | critical_battery_level | The device battery level is critically| alert | **battery_level** property | | | low and will no longer be operational | | | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | offline | The device is not communicating | notification | **last_contact** property | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | charging_cycle_started | The device has been put on charge | notification | **charging_cycle** property | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | charging_cycle_stopped | The device has been disconnected | notification | **battery_level** property | | | from the charger, or the charger | | | | | provided an end of charge signal | | | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | power_on | The device has been powered on | notification | None | | | and is operational | | | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | bin_overflow | The bin is more than 100% full | alert | None | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | mold_detected | Mildew or mold has been detected | alert | None | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ | low_wireless_signal | A low wireless signal has been | notification | **signal_strength** property | | | detected | | | +--------------------------------+---------------------------------------+------------------+----------------------------------------+ - The list of supported message codes within the list of possible codes must be defined at the entity (device, space) type level - The message object must follow the core structure - The content of the specific object is defined at the message code level - A collection of messages must follow the collection core structure - The item object for a collection of messages must be the **message** object - Errors related to exposing information about a specific message must be exposed in the **item_error** object - The item type in the item_error object must be **"message"** - When an information provider supplies detailed information about a message code, the detailed information must be exposed through the **event_specification** object - The detailed information must contains at least a description of the message code - Any detailed information is language-dependent and must be provided in at least one language. - The information in each language must be exposed through the **locale** object - When access to external resources is provided as part of the detailed information, the external resource information must be exposed through the **resource** object - Detailed information for a collection of message codes must follow the collection core structure - The item object for a collection of messages must be the **event_specification** object - Errors related to exposing information about a specific message code must be exposed in the **item_error** object - The item type in the item_error object must be **"message_code"** The detailed API specifications for each object can be found in the `reference <../reference>`__ chapter. The Tag model ''''''''''''' The following diagram provides an overview of the tag Model. .. figure:: ../_static/tag_object_model.png :width: 100% - the tag information must be exposed through the **tag** object - Every tag must be associated to a tag type - the "organization_grouping" must be the only type defined - A tag must apply to one or multiple entities (devices and/or spaces) - A collection of tags must follow the collection core structure - The item object for a collection of messages must be the **tag** object - Errors related to exposing information about a specific message must be exposed in the **item_error** object - The item type in the item_error object must be **"tag"** The detailed API specifications for the tag object can be found in the `reference <../reference>`__ chapter. .. include:: ../common/use_case_object_model.rst