People counter
==================

This section provides the API specifications for people counter devices.

Definitions
-----------

:doc:`Common definitions <../../common/common_definitions>`

:doc:`Common definitions <../../common/object_model_definitions>`

.. include:: ../../common/people_counter_definitions.rst

FDS compliance requirements
---------------------------

Object Model
''''''''''''

Specification object for the people counter device type 
"""""""""""""""""""""""""""""""""""""""""""""""""""""""

- the device information provider must provide a **specification** object that contains a **device_type_specific** object defined in the following diagram

.. figure:: ../../_static/people_counter_specification_object_model.png
    :width: 100%

- When provided, the sensor technology can be 

  - "radar"
  - "time_of_flight"
  - "image"
  - "sonar"
  
Status object for the people counter device type 
""""""""""""""""""""""""""""""""""""""""""""""""

- The device information provider must provide a **status** object that contains a **device_type_specific** object defined in the following diagram

.. figure:: ../../_static/people_counter_status_object_model.png
    :width: 100%

Statistic object for the people counter device type 
"""""""""""""""""""""""""""""""""""""""""""""""""""

- The device information provider must provide a **statistic** object that contains a **device_type_specific** object defined in the following diagram

.. figure:: ../../_static/people_counter_statistic_object_model.png
    :width: 100%


Diagnostic object for the people counter device type 
""""""""""""""""""""""""""""""""""""""""""""""""""""

.. note::

    The Diagnostic object is not being defined for people counters in FDS Version 2

Web API (Pull Model)
''''''''''''''''''''

- The device information provider must expose the **specifications** endpoint to get the list of available devices and their specifications

.. code-block::

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

- The device information provider must expose the **statuses** endpoint to get the latest status for one or multiple devices

.. code-block::

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

- The device information provider must expose the **statistics** endpoint to get the statistics for one or multiple devices

.. code-block::

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

.. note::

    The **diagnostics** endpoint to expose the prognostic and predictive information is not being defined for people counters in FDS Version 2

    A call to:
    
    .. code-block::

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

    must return an error object

    .. code-block:: json

        {
            "status": 204,
            "message": "not_implemented"
        }

- The device information provider must expose the **POST** request on the **tag** endpoint to let a client application create a new tag

.. code-block::

    POST https://{Entity Information Provider URL}/fds/v2/tag

- The device information provider must expose the **GET** request on the **tag** endpoint to provide the content of a tag

.. code-block::

    GET https://{Entity Information Provider URL}/fds/v2/tag

- The device information provider must expose the **DELETE** request on the **tag** endpoint

.. code-block::

    DELETE https://{Entity Information Provider URL}/fds/v2/tag/<tag_id>

- The device information provider must expose the **PUT** request on the **tag/<tag_id>/entities** endpoint

.. code-block::

    PUT https://{Entity Information Provider URL}/fds/v2/tag/<tag_id>/entities

- The device information provider must expose the **DELETE** request on the **tag/<tag_id>/entities** endpoint

.. code-block::

    DELETE https://{Entity Information Provider URL}/fds/v2/tag/<tag_id>/entities

Publish/Subscribe (Push model)
''''''''''''''''''''''''''''''

Events
""""""

- The device information provider must publish the following alerts and notifications

+--------------------------------+---------------------------------------+------------------+----------------------------------------+
| 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 |
+--------------------------------+---------------------------------------+------------------+----------------------------------------+
| offline                        | The device is not communicating       | notification     |  **last_contact** property             |
+--------------------------------+---------------------------------------+------------------+----------------------------------------+

Publish status information
""""""""""""""""""""""""""

.. note::

    No status information is being published by people counter device information providers in FDS Version 2

Publish predictive and prognostic information
"""""""""""""""""""""""""""""""""""""""""""""

.. note::

    No predictive and prognostic information is being published by people counter device information providers in FDS Version 2