# Cybus::Connection

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cybus.io/1-8-0/documentation/services/service-commissioning-files/structure-of-service-commissioning-files/resources/cybus-connection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.