search
Contact Uscybus.io
Page cover

Basic Components of Connectware

From service commissioning files to connected systems.

Connectware is built around several core components that work together to enable seamless industrial connectivity and data integration. Understanding these fundamental building blocks will help you effectively design, deploy, and manage your industrial IoT solutions.

hashtag
Service Commissioning Files

A service commissioning file is a human-readable YAML file that defines an entire service: its description and metadata, and the set of resources the service manages. When you enable the service, Connectware creates those resources. When you disable it, they are cleanly removed.

Example structure of a service commissioning file
# Cybus Connectware Service Commissioning File
description: OPC UA → MQTT with a tiny dashboard
metadata:
  name: OPC UA to MQTT w/ Dashboard
version: '1.0.0'

resources:
  opcuaConnection:
    type: Cybus::Connection
    properties:
      protocol: Opcua
      connection:
        host: 192.168.0.10
        port: 4840
        options:
          securityPolicy: None
          # optional tuning (see docs)
          connectionStrategy:
            maxRetry: 100
            initialDelay: 1000

  serverStatus:
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref opcuaConnection
      subscribe:
        # Example node on many OPC UA servers; adjust to your model
        nodeId: 'ns=0;i=2256'

  machineRunState:
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref opcuaConnection
      subscribe:
        nodeId: 'ns=2;s=Machine/RunState'

  opcuaToMqtt:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref serverStatus
          publish:
            topic: factory/machine1/serverStatus
          rules:
            - burst:
                interval: 1000 # ms
        - subscribe:
            endpoint: !ref machineRunState
          publish:
            topic: factory/machine1/runState

  webContent:
    type: Cybus::Volume
    properties: {}

  indexHtml:
    type: Cybus::File
    properties:
      volume: !ref webContent
      filepath: /usr/share/nginx/html/index.html
      content: |
        <!doctype html>
        <html>
          <head><meta charset="utf-8"><title>Machine KPI</title></head>
          <body>
            <h1>Machine KPI</h1>
            <p>Status and run state via MQTT topics:</p>
            <ul>
              <li>factory/machine1/serverStatus</li>
              <li>factory/machine1/runState</li>
            </ul>
          </body>
        </html>

  dashboard:
    type: Cybus::Container
    properties:
      image: nginx:alpine
      volumes:
        - !sub webContent:/usr/share/nginx/html

  dashboardRoute:
    type: Cybus::IngressRoute
    properties:
      container: !ref dashboard
      type: http
      slug: kpi
      # For raw TCP services, use type: tcp and the port fields
      # containerPort: 80
      # connectwarePort: 18080

  dashboardLink:
    type: Cybus::Link
    properties:
      name: Machine KPI Dashboard
      ingressRoute: !ref dashboardRoute
      href: '' # relative to the ingress route; empty = container root

Learn more about service commissioning files.

hashtag
Services

While Connectware provides interfaces for individually performing all actions (like managing users, setting permissions, starting containerized applications, etc.), the idea of services is to bundle all these activities into a single point of configuration and execution. This means that when a service is enabled it will perform a set of operations on Connectware and when disabled these operations will be removed.

Learn more about services.

Examples of use cases for services

Think of a simple machine that produces a metal part. Whether a metal part is being made at any point in time may not be important, but the average amount being made over a given time period may be useful for knowing if the machine is underperforming. We can accomplish this by connecting the machine to Connectware, and then deploying a service alongside that takes the raw data from the data broker, calculates the average over a given period of time, then uploads the result to the data broker for some other application to consume. This type of application is classified as a preprocessor as it allows us to perform some operation on the data before it is consumed elsewhere.

hashtag
Resources

Resources define what a service needs to establish a connection. All resources such as connections, endpoints, users, permissions, and containerized applications are configured here.

Learn more about resources.

hashtag
Connections & Endpoints

Connections define how to reach a third-party system (e.g., PLC, broker, database). The connection is referenced by endpoints.

Learn more about Cybus::Connection.

hashtag
Endpoints

Endpoints use connections to read/subscribe from, or write to, a specific address or topic. Each endpoint represents one direction and mode (read/subscribe/write). Protocol-specific address shapes are validated automatically.

Learn more about Cybus::Endpoint.

hashtag
Mappings

Mappings move and reshape data between interfaces. A mapping typically subscribes to one or more endpoints, optionally applies rule-based processing, and publishes to a target (commonly MQTT topics). Use mappings to:

  • Normalize tag names and structures

  • Filter noisy signals or forward only on change

  • Compute KPIs or unit conversions using rules

Learn more about Cybus::Mapping.

hashtag
Volumes

Volumes provide persistent storage for containers. This is ideal for configuration, caches, or uploaded content.

Learn more about Cybus::Volume.

hashtag
Files

File resources write configuration or assets into a target volume at a defined path. This is useful for templated config files that a container reads at startup.

Learn more about Cybus::File.

hashtag
Containers

Containers are the runnable applications your service manages. These containers can either come from the Official Docker Registryarrow-up-right or from the Cybus Registryarrow-up-right. This means any application that is deployed on Connectware can take full advantage of all the containerized software on Docker Hub and your custom containerized software delivered securely through the Cybus Registry.

Learn more about Cybus::Container.

hashtag
Ingress Routes

Ingress routes expose a container to users or networks. Use type: http with a short slug for browser access, or type: tcp with explicit port mappings for raw TCP services.

Learn more about Cybus::IngressRoute.

hashtag
Links

Links add convenient shortcuts to your service card—either to an external URL or to a route provided by one of your ingress routes.

Learn more about Cybus::Link.

hashtag
Agents

Agents enable decentralized data processing and communication in industrial environments. These lightweight components are deployed separately from the main Connectware system, making them ideal for handling protocol mapping, data forwarding, and integration with legacy systems that use non-secure hardware protocols.

Using the MQTT protocol, agents provide secure and efficient data transmission without requiring inbound connectivity, enhancing network security.

Learn more about agents.

hashtag
MQTT

MQTT (Message Queuing Telemetry Transport) is a lightweight publish/subscribe protocol and the de facto standard for Industrial IoT messaging. Connectware's internal MQTT broker CybusMQ makes it easy to integrate your industrial data.

PreviousAdmin UINextConnecting your First Machine

Last updated

Was this helpful?