# Cybus::Connection

A *connection* provides connectivity to some other things over some protocol (see also [Industry Protocol Details](https://docs.cybus.io/1-10-0/documentation/industry-protocol-details)) and implements *connect* and *disconnect* functionality.

## Properties

| Property                    | Type     | Required |
| --------------------------- | -------- | -------- |
| [protocol](#protocol)       | `enum`   | Required |
| [targetState](#targetstate) | `enum`   | Optional |
| [agentName](#agentname)     | `string` | Optional |
| [connection](#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 following values:

* `Ads`
* `Bacnet`
* `EthernetIp`
* `Focas`
* `GenericVrpc`
* `Hbmdaq`
* `Heidenhain`
* `Http`
* `InfluxDB`
* `Kafka`
* `Modbus`
* `Mqtt`
* `Mssql`
* `Opcda`
* `Opcua`
* `S7`
* `Shdr`
* `Sinumerik`
* `Sopas`
* `Sql`
* `Systemstate`
* `Werma`

### 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 agent 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` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/ads#connection-properties)
* `Bacnet` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/bacnet#connection-properties)
* `EthernetIp` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/ethernet-ip#connection-properties)
* `GenericVrpc` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/generic-vrpc#connection-properties)
* `Focas` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/focas#connection-properties)
* `Hbmdaq` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/hottinger-baldwin-messtechnik-hbm#connection-properties)
* `Heidenhain` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/heidenhain-dnc#connection-properties)
* `Http` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/http-rest#connection-properties)
* `InfluxDB` C[onnection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/influxdb#connection-properties)
* `Kafka` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/kafka#connection-properties)
* `Modbus` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/modbus-tcp#connection-properties)
* `Mqtt` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/mqtt#connection-properties)
* `Mssql` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/mssql#connection-properties)
* `Opcda` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/opc-da#connection-properties)
* `Opcua` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/opc-da#connection-properties)
* `S7` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/siemens-simatic-s7#connection-properties)
* `Shdr` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/shdr#connection-properties)
* `Sinumerik` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/sinumerik#connection-properties)
* `Sopas` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/sopas#connection-properties)
* `Sql` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/sql#connection-properties)
* `Systemstate` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/systemstate#connection-properties)
* `Werma` [Connection Properties](https://docs.cybus.io/1-10-0/industry-protocol-details/werma-win-ethernet#connection-properties)

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 lineNumbers="true" %}

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

{% endcode %}

### OPC UA

{% code lineNumbers="true" %}

```yaml
opcuaConnection:
</strong>  type: Cybus::Connection
  properties:
    protocol: Opcua
    connection:
      host: 127.17.0.1
      port: 50000
      username: user
      password: user
```

{% endcode %}

### Modbus

{% code lineNumbers="true" %}

```yaml
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
```

{% endcode %}