> 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/data-flows/service-commissioning-files/resources/cybus-connection.md).

# Cybus::Connection

Connect to a machine or an external system over OPC UA, Modbus/TCP, MQTT, or another protocol, from Connectware or from an agent.

The **Cybus::Connection** resource connects Connectware to one machine or external system over one protocol. [Cybus::Endpoint](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-endpoint.md) resources reference the connection to read or write its data points.

The [protocol](#protocol) decides which properties you set in [connection](#connection), such as the address of the device. A connection runs in Connectware by default, or on an [agent](#agentname) that is separate from Connectware.

## Connection Properties

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

### protocol

The protocol of the connection. It also decides which properties [connection](#connection) takes.

* **Required**
* Type: `string`

For the connectors that ship with Connectware, the value **must** be one of the following:

| Value          | Connection Properties                                                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `Ads`          | [ADS Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/ads/adsconnection.md)                                 |
| `Bacnet`       | [BACnet Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/bacnet/bacnetconnection.md)                        |
| `EthernetIp`   | [EtherNet/IP Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/ethernet-ip/ethernetipconnection.md)          |
| `File`         | [File Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/file/fileconnection.md)                              |
| `Focas`        | [FOCAS Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/focas/focasconnection.md)                           |
| `Heidenhain`   | [Heidenhain DNC Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/heidenhain-dnc/heidenhainconnection.md)    |
| `Http`         | [HTTP/REST Connection Properties](https://docs.cybus.io/connectors/enterprise-connectors/http-rest/httpconnection.md)                    |
| `Influxdb`     | [InfluxDB Connection Properties](https://docs.cybus.io/connectors/enterprise-connectors/influxdb/influxdbconnection.md)                  |
| `Influxdb3`    | [InfluxDB 3 Connection Properties](https://docs.cybus.io/connectors/enterprise-connectors/influxdb/influxdb3connection.md)               |
| `Kafka`        | [Kafka Connection Properties](https://docs.cybus.io/connectors/enterprise-connectors/kafka/kafkaconnection.md)                           |
| `Modbus`       | [Modbus/TCP Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/modbus-tcp/modbusconnection.md)                |
| `Mqtt`         | [MQTT Connection Properties](https://docs.cybus.io/connectors/enterprise-connectors/mqtt/mqttconnection.md)                              |
| `Mssql`        | [MSSQL Connection Properties](https://docs.cybus.io/connectors/enterprise-connectors/mssql/mssqlconnection.md)                           |
| `Opcda`        | [OPC DA Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/opc-da/opcdaconnection.md)                         |
| `Opcua`        | [OPC UA Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/opc-ua/opc-ua-client/opcuaconnection.md)           |
| `Openprotocol` | [Open Protocol Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/open-protocol/openprotocolconnection.md)    |
| `S7`           | [Siemens S7 Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/siemens-simatic-s7/s7connection.md)            |
| `S7plus`       | [Siemens S7+ Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/siemens-simatic-s7-plus/s7plusconnection.md)  |
| `Shdr`         | [SHDR Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/shdr/shdrconnection.md)                              |
| `Sinumerik`    | [SINUMERIK Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/sinumerik/sinumerikconnection.md)               |
| `Sopas`        | [SOPAS Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/sopas/sopasconnection.md)                           |
| `Sql`          | [SQL Connection Properties](https://docs.cybus.io/connectors/enterprise-connectors/sql/sqlconnection.md)                                 |
| `Systemstate`  | None. Set `connection: {}`.                                                                                                              |
| `Werma`        | [Werma WIN Ethernet Connection Properties](https://docs.cybus.io/connectors/shop-floor-connectors/werma-win-ethernet/wermaconnection.md) |

A [custom connector](https://docs.cybus.io/connectors/custom-connectors/using-custom-connectors.md) uses its own protocol name.

### connection

The connection details, such as the host and port of the machine. The available properties depend on the [protocol](#protocol). The table in [protocol](#protocol) links the properties of each protocol.

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

#### connectionStrategy

Most protocols retry a failed connection with a growing delay. You configure the delays with the `connectionStrategy` property inside `connection`. It typically has the following properties:

* `initialDelay`: The delay before the first retry, in milliseconds.
* `incrementFactor`: The factor that multiplies the delay after each retry.
* `maxDelay`: The longest delay between two retries, in milliseconds.

When Connectware re-establishes the connection, the delay starts again at `initialDelay`.

MQTT, OPC UA, S7, Sinumerik, and Kafka use their own reconnection strategies. See their connection properties.

### targetState

The desired state of the connection after startup.

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

### agentName

The name of the [agent](https://docs.cybus.io/data-flows/agents.md) that runs the connection. Set it when the connection runs in distributed mode, on an agent that is separate from Connectware. The default, `protocol-mapper`, runs the connection in the Protocol Mapper of Connectware.

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

## Examples

### MQTT

{% code lineNumbers="true" %}

```yaml
mqttConnection:
  type: Cybus::Connection
  properties:
    protocol: Mqtt
    connection:
      host: broker.example.com
      port: 1883
```

{% endcode %}

### OPC UA

The following connection signs in to the OPC UA server with a username and a password. Both come from parameters, so the credentials are not part of the service commissioning file. The password is a [secret parameter](https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md#secret-parameters), so the API and the Admin UI do not show its value:

{% code lineNumbers="true" %}

```yaml
parameters:
  opcuaUser:
    type: string
  opcuaPassword:
    type: string
    secret: true

resources:
  opcuaConnection:
    type: Cybus::Connection
    properties:
      protocol: Opcua
      connection:
        host: 192.168.1.100
        port: 4840
        username: !ref opcuaUser
        password: !ref opcuaPassword
```

{% endcode %}

### Modbus/TCP on an Agent

{% code lineNumbers="true" %}

```yaml
modbusConnection:
  type: Cybus::Connection
  properties:
    protocol: Modbus
    agentName: edge-agent # runs the connection on the agent named edge-agent
    connection:
      host: 192.168.1.100
      port: 502
```

{% 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/data-flows/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.
