Bearer device
=============

A bearer device is a device that can manage other devices. In other words, it can forward payloads to them. In the payloads below, the BEARER_DEVICE_UID value refers to the bearer device uid while the MODULE_UID value refers to the managed device

.. toctree::
   :maxdepth: 2
   :caption: Payloads:


.. glossary::

   [DEVICE_IDENTIFIER]
     unique identifier for this device on the bearer side

   [DEVICE_TYPE]
     type of the device on the bearer side

   [BRAND_IDENTIFIER]
     unique brand identifier in hexadecimal format

   [BRAND_NAME]
     unique brand name key to identify this brand

   [SUBMODEL_IDENTIFIER]
     unique submodel identifier in hexadecimal format (among other submodels in the same brand)

   [SUBMODEL_NAME]
     unique submodel name key to identify this submodel. Most of the time, the submodel name is identical to its model name


Associate
---------

To associate a device to be managed by a bearer, use the following payload. However such association needs to be validated (see "validate" below) :

.. uml::
   
   hide footbox
   title Payload direction
   clients -> devices: associate payload

Payload
^^^^^^^
   
.. code-block::

   {
    "action": "associate",
    "timestamp":"[TIMESTAMP]",
    "uid":"[PAYLOAD_UID]",
    "modules": [
        {
            "id":"[MODULE_UID]",
            "device":{
                "identifier":"[DEVICE_IDENTIFIER]", // optional
                "type":"[DEVICE_TYPE]", // optional
                "bearerId":"[BEARER_DEVICE_UID]",
                "brandIdentifier":"[BRAND_IDENTIFIER]", // optional
                "brandName":"[BRAND_NAME]", // optional
                "modelIdentifier":[DEVICE_MODEL_ID], // optional
                "modelName":"[DEVICE_MODEL_NAME]", // optional
                "submodelIdentifier":"[SUBMODEL_IDENTIFIER]", // optional
                "submodelName":"[SUBMODEL_NAME]", // optional
                "code":"[YCB_CODE]", // optional
                "[SUBDEVICE_NAME]s":[
                    {same payload found in "modules" above},
                    ...
                ]
            }
        }
    ]
   }

See :term:`[TIMESTAMP]`, :term:`[PAYLOAD_UID]`, :term:`[BEARER_DEVICE_UID]`, :term:`[DEVICE_MODEL_ID]`, :term:`[DEVICE_MODEL_NAME]`, :term:`[DEVICE_IDENTIFIER]`, :term:`[DEVICE_TYPE]`, :term:`[BRAND_IDENTIFIER]`, :term:`[BRAND_NAME]`, :term:`[SUBMODEL_IDENTIFIER]`, :term:`[SUBMODEL_NAME]`

Validate
--------

Once a device is successfully associated to their bearer (see "associate" above), it needs to be validated to be usable

.. uml::
   
   hide footbox
   title Payload direction
   clients -> devices: validate payload

Payload
^^^^^^^

.. code-block::

   {
    "action": "validate",
    "timestamp":"[TIMESTAMP]",
    "uid":"[PAYLOAD_UID]",
    "modules": [
        {
            "id":"[MODULE_UID]",
            "device":{
                "bearerId":"[BEARER_DEVICE_UID]",
                "code":"[YCB_CODE]",
                "[SUBDEVICE_NAME]s":[
                    {same payload found in "modules" above},
                    ...
                ]
            }
        }
    ]
   }


See :term:`[TIMESTAMP]`, :term:`[PAYLOAD_UID]`, :term:`[BEARER_DEVICE_UID]`

Remove
------

You can remove a managed device from their bearer using such payload

.. uml::
   
   hide footbox
   title Payload direction
   clients -> devices: validate payload

Payload
^^^^^^^
.. code-block::
   
   {
    "action": "remove",
    "timestamp":"[TIMESTAMP]",
    "uid":"[PAYLOAD_UID]",
    "modules": [
        {
            "id":"[MODULE_UID]",
            "device":{
                "bearerId":"[BEARER_DEVICE_UID]"
            }
        }
    ]
   }

See :term:`[TIMESTAMP]`, :term:`[PAYLOAD_UID]`, :term:`[BEARER_DEVICE_UID]`