# Cybus::Connection

A *connection* provides connectivity to some other things over some protocol (see also [Industry Protocol Details](https://docs.cybus.io/1-7-2/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 below
>
> * `Ads`
> * `Bacnet`
> * `EthernetIp`
> * `Focas`
> * `GenericVrpc`
> * `Hbmdaq`
> * `Heidenhain`
> * `Http`
> * `InfluxDB`
> * `Kafka`
> * `Modbus`
> * `Mqtt`
> * `Mssql`
> * `Opcda`
> * `Opcua`
> * `Profinet`
> * `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-7-2/industry-protocol-details/ads#connection-properties)
> * `Bacnet` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/bacnet#connection-properties)
> * `EthernetIp` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/ethernet-ip#connection-properties)
> * `GenericVrpc` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/generic-vrpc#connection-properties)
> * `Focas` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/focas#connection-properties)
> * `Hbmdaq` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/hottinger-baldwin-messtechnik-hbm#connection-properties)
> * `Heidenhain` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/heidenhain-dnc#connection-properties)
> * `Http` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/http-rest#connection-properties)
> * `InfluxDB` C[onnection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/influxdb#connection-properties)
> * `Kafka` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/kafka#connection-properties)
> * `Modbus` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/modbus-tcp#connection-properties)
> * `Mqtt` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/mqtt#connection-properties)
> * `Mssql` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/mssql#connection-properties)
> * `Opcda` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/opc-da#connection-properties)
> * `Opcua` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/opc-da#connection-properties)
> * `Profinet` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/profinet#connection-properties)
> * `S7` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/siemens-simatic-s7#connection-properties)
> * `Shdr` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/shdr#connection-properties)
> * `Sinumerik` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/sinumerik#connection-properties)
> * `Sopas` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/sopas#connection-properties)
> * `Sql` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/sql#connection-properties)
> * `Systemstate` [Connection Properties](https://docs.cybus.io/1-7-2/industry-protocol-details/systemstate#connection-properties)
> * `Werma` [Connection Properties](https://docs.cybus.io/1-7-2/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**

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

### **OPC UA**

<pre class="language-yaml"><code class="lang-yaml"><strong>opcuaConnection:
</strong>  type: Cybus::Connection
  properties:
    protocol: Opcua
    connection:
      host: 127.17.0.1
      port: 50000
      username: user
      password: user
</code></pre>

### **Modbus**

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