.. _user/services/structure/resources/connection:

*****************
Cybus::Connection
*****************

A *connection* provides connectivity to some other things over some protocol
(see also :ref:`user/protocols/index`) and implements `connect` and `disconnect`
functionality.


Properties
==========

============== ========== ============
Property       Type       Required
============== ========== ============
`protocol`_    ``enum``   **Required**
`targetState`_ ``enum``   Optional
`agentName`_   ``string`` Optional
`connection`_  ``object`` **Required**
============== ========== ============

protocol
--------


Identifies the protocol for which a connection should be established

-  is **required**
-  type: ``enum``

  The value of this property **must** be equal to one of the below

  .. include:: ../../../shared/protocols.rstinc


targetState
-----------

The state this resource should be in, after start-up.

-  is optional
-  type: ``enum``, must be one of ``connected``, ``disconnected``
-  default: ``connected``

agentName
---------

Only set this property if your protocol-mapper runs as in a distributed mode,
i.e. on an :ref:`agent <user/agents>` instance separated from the Connectware.
If this is the case, specify the corresponding agent name here.

-  is optional
-  type: ``string``
-  default: ``protocol-mapper``


connection
----------

-  is **required**
-  type: ``object``

  Depending on the protocol type the connection provides the following properties:

  - ``Ads`` :ref:`user/protocols/ads_connection`
  - ``Bacnet`` :ref:`user/protocols/bacnet_connection`
  - ``EthernetIp`` :ref:`user/protocols/ethernetIp_connection`
  - ``GenericVrpc`` :ref:`user/protocols/genericVrpc_connection`
  - ``Focas`` :ref:`user/protocols/focas_connection`
  - ``Hbmdaq`` :ref:`user/protocols/hbmdaq_connection`
  - ``Heidenhain`` :ref:`user/protocols/heidenhain_connection`
  - ``Http`` :ref:`user/protocols/http_connection`
  - ``InfluxDB`` :ref:`user/protocols/influxdb_connection`
  - ``Kafka`` :ref:`user/protocols/kafka_connection`
  - ``Modbus`` :ref:`user/protocols/modbus_connection`
  - ``Mqtt`` :ref:`user/protocols/mqtt_connection`
  - ``Mssql`` :ref:`user/protocols/mssql_connection`
  - ``Opcda`` :ref:`user/protocols/opcda_connection`
  - ``Opcua`` :ref:`user/protocols/opcua/opcuaClient_connection`
  - ``Profinet`` :ref:`user/protocols/profinet_connection`
  - ``S7`` :ref:`user/protocols/s7_connection`
  - ``Shdr`` :ref:`user/protocols/shdr_connection`
  - ``Sinumerik`` :ref:`user/protocols/sinumerik`
  - ``Sopas`` :ref:`user/protocols/sopas_connection`
  - ``Sql`` :ref:`user/protocols/sql_connection`
  - ``Systemstate`` :ref:`user/protocols/systemstate_connection`
  - ``Werma`` :ref:`user/protocols/werma_connection`

  Most protocols expose a property ``connectionStrategy`` which allows configuring the
  incremental delays between re-connection attempts. Each protocol provides defaults
  for this configuration which is documented on each of them.
  In general an ``initialDelay`` property determines how many milliseconds to wait before
  the first attempt to re-connect is executed and then this value is multiplied by
  the configured ``incrementFactor``, replacing the original ``initialDelay``, up to a
  maximum configured ``maxDelay`` that once reached causes all subsequent re-connection
  attempts to occur after that many milliseconds. Once the connection is restablished the
  ``initialDelay`` is reset to its original value.
  The procotols Mqtt, Opcua, S7 and Sinumerik use their own strategy described in each
  of them.




Examples
========

*Mqtt*

.. code-block:: yaml
  :linenos:

  mqttConnection:
    type: Cybus::Connection
    properties:
      protocol: Mqtt
      connection:
        host: broker

*OPC UA*

.. code-block:: yaml
  :linenos:

  opcuaConnection:
    type: Cybus::Connection
    properties:
      protocol: Opcua
      connection:
        host: 127.17.0.1
        port: 50000
        username: user
        password: user

*Modbus*

.. code-block:: yaml
  :linenos:

  modbusConnection:
    type: Cybus::Connection
    properties:
      agentName: edge-mapper # uses the protocol-mapper agent 'edge-mapper'
      protocol: Modbus
      connection:
        host: 172.17.0.1
        port: 10502