# Cybus::Connection

The **Cybus::Connection** resource enables connectivity to external systems or devices using various protocols. The following describes its properties, supported protocols, and configuration examples.

## Connection Properties

| Property                    | Type     | Required |
| --------------------------- | -------- | -------- |
| [protocol](#protocol)       | `enum`   | Required |
| [targetState](#targetstate) | `enum`   | Optional |
| [agentName](#agentname)     | `string` | Optional |
| [connection](#connection)   | `object` | Required |

### protocol

Specifies the protocol to be used for establishing the connection.

* **Required**
* Type: `enum`

The value of this property **must** be one of the following:

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

### targetState

Defines the desired state of the resource after startup.

* **Optional**
* Type: `enum`
* Allowed values:
  * `connected`
  * `disconnected`
* Default: `connected`

### agentName

Specifies the agent name if the protocol-mapper operates in distributed mode. For example, on a separate agent instance from Connectware. Use this property to identify the corresponding agent.

* **Optional**
* Type: `string`
* Default: `protocol-mapper`

### connection

Defines the connection details required for the specified protocol.

* **Required**
* Type: `object`

Each protocol has its own set of connection properties:

* `Ads` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/ads/adsconnection)
* `Bacnet` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/bacnet/bacnetconnection)
* `EthernetIp` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/ethernet-ip/ethernetipconnection)
* `Focas` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/focas/focasconnection)
* `Hbmdaq` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/hottinger-baldwin-messtechnik-hbm/hbmdaqconnection)
* `Heidenhain` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/heidenhain-dnc/heidenhainconnection)
* `Http` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/http-rest/httpconnection)
* `Influxdb` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/influxdb/influxdbconnection)
* `Kafka` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/kafka/kafkaconnection)
* `Modbus` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/modbus-tcp/modbusconnection)
* `Mqtt` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/mqtt/mqttconnection)
* `Mssql` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/mssql/mssqlconnection)
* `Opcda` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/opc-da/opcdaconnection)
* `Opcua` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/opc-ua/opc-ua-client/opcuaconnection)
* `S7` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/siemens-simatic-s7/s7connection)
* `Shdr` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/shdr/shdrconnection)
* `Sinumerik` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/sinumerik/sinumerikconnection)
* `Sopas` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/sopas/sopasconnection)
* `Sql` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/sql/sqlconnection)
* `Systemstate` [Connection Properties](https://github.com/cybusio/user-documentation/blob/release/2.0.6/documentation/generated/industry-protocol-details/SystemstateConnection.md)
* `Werma` [Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/werma-win-ethernet/wermaconnection)

Most protocols include a `connectionStrategy` property to configure incremental delays between reconnection attempts. This typically includes:

* `initialDelay`: Time in milliseconds before the first reconnection attempt.
* `incrementFactor`: Multiplier applied to the delay after each attempt.
* `maxDelay`: Maximum delay in milliseconds for subsequent attempts.

Once the connection is re-established, the `initialDelay` resets to its original value. Note that MQTT, OPC UA, S7, and Sinumerik protocols use their own reconnection strategies, detailed in their respective documentation.

## Examples

### MQTT

{% code lineNumbers="true" %}

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

{% endcode %}

### OPC UA

{% code lineNumbers="true" %}

```yaml
opcuaConnection:
  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 %}