> 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/discover/how-connectware-works.md). # How Connectware Works Learn how Connectware turns fragmented shop floor data into a single, structured data layer for your industrial data use cases. This page walks through how a service commissioning file becomes live data flowing from industrial devices to your applications. It covers services, resources, endpoints, mappings, and the Unified Namespace, and shows how they form a data pipeline. If you have not read [What Is Connectware?](/discover/what-is-connectware.md) yet, start there for a platform overview. ## Core Concepts The following terms appear throughout this page: | Term | Meaning | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | **Service** | A packaged unit of connectivity that contains all resources needed to connect devices and route data. | | **Resource** | A building block within a service, such as a connection, endpoint, mapping, or container. | | **Connection** | Defines how to reach a device: protocol, address, credentials, and protocol-specific settings. | | **Connector** | The protocol driver, such as OPC UA, Modbus/TCP, or S7, that runs inside a connection. | | **Endpoint** | A specific data point on a device — for example, a sensor tag, PLC register, or OPC UA node. | | **Mapping** | Routes data from endpoints to Unified Namespace MQTT topics, optionally transforming it via the Rule Engine. | | **Unified Namespace (UNS)** | Structured MQTT topic hierarchy that mirrors your production environment and serves as the single source of truth for data. | | **CybusMQ** | Connectware's internal MQTT broker. All topic routing flows through it. | | **Service commissioning file** | The YAML file that declares a service and all its resources — the configuration-as-code representation of your setup. | ## The Service Commissioning File A **service commissioning file** is a YAML file that declares what to connect, what data to read, and how to route it to your applications. You install it as a service, which is when you set its parameters, and then enable it, which is when Connectware creates every resource it describes. When you disable it, Connectware removes them again. This is configuration as code. The file is the source of truth, so you can store it in Git, review changes in pull requests, and deploy the same setup across factories. ### How Data Flows Through Connectware The service commissioning file creates a data pipeline: 1. **Connection**: Establishes communication with a device using the specified protocol. 2. **Endpoint**: Subscribes to or reads a specific data point on the device. 3. **Mapping**: Routes the data to a structured MQTT topic, applying any transformations. 4. **CybusMQ**: Connectware's internal MQTT broker holds the topic hierarchy. 5. **Applications**: Consumers (dashboards, MES, analytics, AI) subscribe to topics there. You describe the pipeline, and Connectware creates and manages the underlying infrastructure. ### Example Service Commissioning File The following example connects to an OPC UA server on a CNC milling machine and publishes its spindle speed to the Unified Namespace. The same pattern applies to any supported connector, and only the connector-specific properties change, for example Modbus register addresses instead of OPC UA node IDs. {% code title="connect-your-first-machine.yaml" lineNumbers="true" expandable="true" %} ```yaml description: > Connects to the OPC UA server on the CNC milling machine on line 1 and publishes spindle speed via MQTT. metadata: name: CNC Mill Line 1 - OPC UA version: 1.0.0 provider: cybus homepage: https://www.cybus.io parameters: opcuaHost: type: string description: OPC UA server address of the CNC mill default: 192.168.10.10 opcuaPort: type: integer description: OPC UA server port default: 4840 resources: opcuaConnection: type: Cybus::Connection properties: protocol: Opcua connection: host: !ref opcuaHost port: !ref opcuaPort spindleSpeed: type: Cybus::Endpoint properties: protocol: Opcua connection: !ref opcuaConnection subscribe: nodeId: ns=2;s=SpindleSpeed spindleSpeedMapping: type: Cybus::Mapping properties: mappings: - subscribe: endpoint: !ref spindleSpeed publish: topic: factory/line1/cnc-mill-1/spindle-speed ``` {% endcode %} ### Tools for Writing Service Commissioning Files The [Cybus Connectware VS Code Extension](/tools/cybus-connectware-extension-vs-code.md) provides schema validation and autocompletion as you edit [service commissioning files](/data-flows/service-commissioning-files.md). [Cybus Connectware GPT](/tools/cybus-connectware-gpt.md) is an AI assistant that generates them from plain-language descriptions, which helps when you prototype a new device integration or scaffold a configuration before refining it. In production, service commissioning files live in Git repositories, and CI/CD pipelines deploy them using GitOps practices. ## Sections of a Service Commissioning File These sections connect devices, read data, and route it to consumers: ### Parameters The `parameters` section makes a service commissioning file reusable across environments and sites. Instead of hard-coding server addresses, you declare them as parameters with default values: {% code title="connect-your-first-machine.yaml - Parameters" overflow="wrap" lineNumbers="true" %} ```yaml parameters: opcuaHost: type: string description: OPC UA server address of the CNC mill default: 192.168.10.10 opcuaPort: type: integer description: OPC UA server port default: 4840 ``` {% endcode %} When you install a service, you can override any parameter without editing the file. The same template can connect to different machines across development, staging, and production sites. ### Connections The `resources` section contains the building blocks of the service. A [`Cybus::Connection`](/data-flows/service-commissioning-files/resources/cybus-connection.md) defines how to reach a device: the protocol, host, port, and credentials. {% code title="connect-your-first-machine.yaml - Connection" overflow="wrap" lineNumbers="true" %} ```yaml opcuaConnection: type: Cybus::Connection properties: protocol: Opcua connection: host: !ref opcuaHost port: !ref opcuaPort ``` {% endcode %} The `!ref` tags resolve to the parameter values you set when installing the service. Connectware supports industrial protocols such as OPC UA, Modbus/TCP, Siemens S7, MQTT, and HTTP/REST. Each has its own connection properties but follows the same configuration pattern. ### Endpoints A [`Cybus::Endpoint`](/data-flows/service-commissioning-files/resources/cybus-endpoint.md) uses a connection to subscribe to or read from a specific data point on a device: {% code title="connect-your-first-machine.yaml - Endpoint" overflow="wrap" lineNumbers="true" %} ```yaml spindleSpeed: type: Cybus::Endpoint properties: protocol: Opcua connection: !ref opcuaConnection subscribe: nodeId: ns=2;s=SpindleSpeed ``` {% endcode %} This endpoint subscribes to the `SpindleSpeed` node on the CNC mill's OPC UA server. Every time the node publishes a new value, Connectware receives it. Multiple endpoints can share the same connection; define one endpoint per data point. ### Mappings A [`Cybus::Mapping`](/data-flows/service-commissioning-files/resources/cybus-mapping.md) routes data from endpoints to MQTT topics in the Unified Namespace. The topic path you define reflects the physical and logical structure of your production environment, for example `factory/line1/cnc-mill-1/spindle-speed`. A consumer subscribes to that path without knowing which device or protocol produced the value. {% code title="connect-your-first-machine.yaml - Mapping" overflow="wrap" lineNumbers="true" %} ```yaml spindleSpeedMapping: type: Cybus::Mapping properties: mappings: - subscribe: endpoint: !ref spindleSpeed publish: topic: factory/line1/cnc-mill-1/spindle-speed ``` {% endcode %} All topic routing flows through [CybusMQ](/broker/cybusmq.md), Connectware's internal MQTT broker. ### Rule Engine (Optional) A mapping without rules passes data through unchanged, as in the example above. Attach [Rule Engine](/data-flows/rule-engine.md) rules to a mapping entry to normalize tag names, filter noise, compute derived values, convert units, or apply conditional logic. Rules process messages before the messages reach subscribers. {% code title="Example - Mapping with Rules" overflow="wrap" lineNumbers="true" %} ```yaml mapping: type: Cybus::Mapping properties: mappings: - subscribe: endpoint: !ref machineRunState publish: topic: factory/line1/cnc-mill-1/run-state rules: - transform: expression: '$.value > 0 ? "running" : "stopped"' ``` {% endcode %} ## Operating Connectware Once data is flowing, the following features cover day-to-day operation: * **Service lifecycle**: Install, enable, update, and disable services through the Admin UI or API. When you disable a service, Connectware removes every resource it created, leaving no orphaned connections behind. See [Services](/data-flows/services.md). * **Containerized applications**: Services can include Docker containers that process or consume UNS data — dashboards, analytics, and AI inference pipelines. See [Resources](/data-flows/service-commissioning-files/resources.md). * **Transactional data flows**: When a consumer must confirm that a write or command succeeded, FlowSync carries the response or error back through the data flow. See [FlowSync](/data-flows/flowsync.md). * **Agents**: Agents run next to devices on isolated networks and connect outbound to Connectware, so the network needs no inbound connectivity. See [Agents](/data-flows/agents.md). * **Monitoring**: The Data Explorer and service status views let you verify live data flows and diagnose connection issues. See [Data Explorer](/monitoring/data-explorer.md). * **User management**: Role-based access control, SSO, and MFA govern who can access which parts of the system. See [User Management](/access/user-management.md). * **GitOps**: Service commissioning files live in Git, changes go through pull requests, and a CI/CD pipeline deploys to Connectware on merge. ## Next Steps Continue with one of the following:
ConnectorsBrowse connectors for your machines: OPC UA, Modbus, S7, and many more. Each page includes configuration examples.cards-connectors.pngShop Floor Connectors
Service Commissioning FilesBuild your own service with the complete reference covering every resource type and property.cards-services.pngService Commissioning Files
MonitoringUse the Data Explorer and Live Data tab to verify that data flows correctly and monitor your connections.cards-data-explorer.pngData Explorer
User ManagementCreate accounts, assign roles, and restrict access with role-based access control.cards-user-management.pngUser Management
AgentsDeploy agents to bridge isolated networks when machines cannot reach Connectware directly.cards-agents.pngAgents
--- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cybus.io/discover/how-connectware-works.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.