# Cybus Connectware Extension (VS Code)

The Cybus Connectware Extension provides YAML language support for Visual Studio Code when working with service commissioning files. Designed for developers and engineers working with YAML-based Connectware configurations, it provides schema validation, autocompletion, and inline documentation to support authoring Connectware configuration files.

{% hint style="warning" %}
Cybus Connectware Extension for VS Code is currently in the **beta** stage. Always validate results using your established development and testing processes.

Questions or issues? Contact: <support@cybus.io>
{% endhint %}

<figure><img src="https://639096190-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfDpOJO2upcq5EpoSahvK%2Fuploads%2Fgit-blob-4513db654966f056d496d9fbc010a545e5e92c4f%2Fcybus_connectware_extension_for_vscode.gif?alt=media" alt="Cybus Connectware Extension for VS Code"><figcaption><p>Cybus Connectware Extension for VS Code</p></figcaption></figure>

Cybus Connectware Extension for VS Code is available on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=cybusio.cybus-yaml).

## Key Features

* **Schema-aware Validation & Linting:** Real-time validation against official Cybus schemas. Errors and warnings appear in VS Code's **Problems** view so issues are visible in the editor before deployment.
* **Intelligent Autocompletion:** Suggestions for valid YAML structures, attributes, and values based on the cursor position and active schema.
* **Inline Documentation:** Hover over configuration elements to view descriptions and direct links to the [official Cybus documentation](https://docs.cybus.io) without leaving your editor.
* **Snippets & Templates:** Create new services quickly using predefined snippets and example templates for common configurations.

## Supported File Patterns

The extension automatically recognizes the following file patterns:

* `*.scf.yaml`, `*.scf.yml`, `*.scf`
* `*.cw.yaml`, `*.cw.yml`
* `*/connectware/scf*/*.yaml`

## Getting Started

1. Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=cybusio.cybus-yaml).
2. Open a service commissioning file matching any of the [supported file patterns](#supported-file-patterns).
3. Start typing. The extension provides autocompletion and validation as you edit the file.

## Keyboard Shortcuts

| Action                   | Windows / Linux                                           | Mac                                                     |
| ------------------------ | --------------------------------------------------------- | ------------------------------------------------------- |
| Trigger autocomplete     | <kbd>Ctrl</kbd>+<kbd>Space</kbd>                          | <kbd>Option</kbd>+<kbd>Esc</kbd>                        |
| Open **Command Palette** | <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>             | <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>            |
| Use Quick Fix            | <kbd>Ctrl</kbd>+<kbd>.</kbd>                              | <kbd>Cmd</kbd>+<kbd>.</kbd>                             |
| Open **Problems** panel  | <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd>             | <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd>            |
| Show hover info          | <kbd>Ctrl</kbd>+<kbd>K</kbd> <kbd>Ctrl</kbd>+<kbd>I</kbd> | <kbd>Cmd</kbd>+<kbd>K</kbd> <kbd>Cmd</kbd>+<kbd>I</kbd> |

## Snippets & Templates

Type these prefixes and [trigger autocomplete](#keyboard-shortcuts) to insert templates:

**Service Templates**

| Prefix                               | Description          |
| ------------------------------------ | -------------------- |
| `template:opcua:bridge:read`         | OPC UA read bridge   |
| `template:modbus:bridge:read`        | Modbus read bridge   |
| `template:s7:bridge:read-write`      | S7 read/write bridge |
| `template:mqtt:bridge:publisher-tls` | MQTT TLS publisher   |
| `template:influxdb:app:deploy`       | InfluxDB deployment  |
| `template:grafana:app:deploy`        | Grafana deployment   |

**Resource Snippets**

| Prefix                                     | Description             |
| ------------------------------------------ | ----------------------- |
| `snippet:opcua:resource:connection`        | OPC UA connection       |
| `snippet:modbus:resource:connection`       | Modbus connection       |
| `snippet:mqtt:resource:endpoint-subscribe` | MQTT subscribe endpoint |

{% hint style="success" %}
Type `template:` or `snippet:` and browse all options with autocomplete.
{% endhint %}

## Tips & Tricks

#### Reference Resources with `!ref`

**Example**

{% code lineNumbers="true" %}

```yaml
connection: !ref myOpcuaConnection
```

{% endcode %}

#### String Substitution with `!sub`

**Example**

{% code lineNumbers="true" %}

```yaml
topic: !sub 'devices/${deviceId}/data'
```

{% endcode %}

#### Show Object Examples (Not Just Properties)

Place your cursor after the space following a colon and [trigger autocomplete](#keyboard-shortcuts) to see full object examples or available object properties.

**Show object examples**

{% code lineNumbers="true" %}

```yaml
Anyobject: # ← cursor here, then Ctrl + Space (Windows/Linux) or Option + Esc (Mac) → shows full object examples
```

{% endcode %}

**Show object properties**

{% code lineNumbers="true" %}

```yaml
Anyobject:
  # ← cursor here, then Ctrl + Space (Windows/Linux) or Option + Esc (Mac) → shows available object properties
```

{% endcode %}

## Best Practices

A practical way to create a Connectware service is to start from a template and customize it.

{% stepper %}
{% step %}

#### Create: Start with a Template

* Create a new file with `.scf.yaml` extension.
* Type `template:` and [trigger autocomplete](#keyboard-shortcuts).
* Choose a template matching your use case (e.g., `template:opcua:bridge:read`).
* The template includes an example with all required sections.
  {% endstep %}

{% step %}

#### Customize: Modify the Service

* Remove unused endpoints, mappings, or parameters (the linter will flag broken references).
* Add new resources: type `snippet:` to add connections, endpoints, mappings, etc.
* Reference existing resources with `!ref resourceName`.
* Modify values: update connection parameters, adjust endpoints, customize mappings.
  {% endstep %}

{% step %}

#### Validate: Continuously Check for Errors

* Watch the **Problems** panel (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd>) for errors.
* Hover over red underlines to see error details.
* Use Quick Fix (<kbd>Ctrl</kbd>+<kbd>.</kbd>) for suggested corrections.
* Ensure all `!ref` references point to existing resources.
  {% endstep %}

{% step %}

#### Deploy: Upload to Connectware

* Once validation passes, deploy the service to your Connectware instance.

{% hint style="warning" %}
We recommend to keep the template comments at first to understand each section, but remove them before deploying.
{% endhint %}
{% endstep %}
{% endstepper %}

## Example: Building an OPC UA to MQTT Bridge

{% code lineNumbers="true" %}

```yaml
# 1. Started from: template:opcua:bridge:read
# 2. Customized: Changed IP, added second endpoint, modified mapping

description: OPC UA to MQTT Bridge

parameters:
  opcuaHost:
    type: string
    default: '192.168.1.100' # ← Modified for my PLC

resources:
  opcuaConnection:
    type: Cybus::Connection
    properties:
      protocol: Opcua
      connection:
        host: !ref opcuaHost
        port: 4840

  temperatureEndpoint: # ← Kept from template
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref opcuaConnection
      subscribe:
        nodeId: ns=2;s=Temperature

  pressureEndpoint: # ← Added using snippet
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref opcuaConnection
      subscribe:
        nodeId: ns=2;s=Pressure

  temperatureMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref temperatureEndpoint
          publish:
            topic: 'plant/sensors/temperature'
```

{% endcode %}

## Privacy

This extension does **not** collect or transmit any telemetry or usage data.

## License

Cybus Connectware Extension is licensed under the MIT license.