> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/1-10-1/documentation/services/service-commissioning-files/resources/cybus-connection.md).

# Cybus::Connection

A *connection* provides connectivity to some other things over some protocol (see also [Industry Protocol Details](/1-10-1/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-10-1/documentation/industry-protocol-details/ads.md#connection-properties)
* `Bacnet` [Connection Properties](/1-10-1/documentation/industry-protocol-details/bacnet.md#connection-properties)
* `EthernetIp` [Connection Properties](/1-10-1/documentation/industry-protocol-details/ethernet-ip.md#connection-properties)
* `Focas` [Connection Properties](/1-10-1/documentation/industry-protocol-details/focas.md#connection-properties)
* `Hbmdaq` [Connection Properties](/1-10-1/documentation/industry-protocol-details/hottinger-baldwin-messtechnik-hbm.md#connection-properties)
* `Heidenhain` [Connection Properties](/1-10-1/documentation/industry-protocol-details/heidenhain-dnc.md#connection-properties)
* `Http` [Connection Properties](/1-10-1/documentation/industry-protocol-details/http-rest.md#connection-properties)
* `InfluxDB` C[onnection Properties](/1-10-1/documentation/industry-protocol-details/influxdb.md#connection-properties)
* `Kafka` [Connection Properties](/1-10-1/documentation/industry-protocol-details/kafka.md#connection-properties)
* `Modbus` [Connection Properties](/1-10-1/documentation/industry-protocol-details/modbus-tcp.md#connection-properties)
* `Mqtt` [Connection Properties](/1-10-1/documentation/industry-protocol-details/mqtt.md#connection-properties)
* `Mssql` [Connection Properties](/1-10-1/documentation/industry-protocol-details/mssql.md#connection-properties)
* `Opcda` [Connection Properties](/1-10-1/documentation/industry-protocol-details/opc-da.md#connection-properties)
* `Opcua` [Connection Properties](/1-10-1/documentation/industry-protocol-details/opc-da.md#connection-properties)
* `S7` [Connection Properties](/1-10-1/documentation/industry-protocol-details/siemens-simatic-s7.md#connection-properties)
* `Shdr` [Connection Properties](/1-10-1/documentation/industry-protocol-details/shdr.md#connection-properties)
* `Sinumerik` [Connection Properties](/1-10-1/documentation/industry-protocol-details/sinumerik.md#connection-properties)
* `Sopas` [Connection Properties](/1-10-1/documentation/industry-protocol-details/sopas.md#connection-properties)
* `Sql` [Connection Properties](/1-10-1/documentation/industry-protocol-details/sql.md#connection-properties)
* `Systemstate` [Connection Properties](/1-10-1/documentation/industry-protocol-details/systemstate.md#connection-properties)
* `Werma` [Connection Properties](/1-10-1/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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cybus.io/1-10-1/documentation/services/service-commissioning-files/resources/cybus-connection.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.