LogoLogo
Contact Uscybus.io
Connectware 1.7.3
Connectware 1.7.3
  • Getting Started
    • Introduction
    • Installing Connectware
      • System Requirements
      • Acquiring your License Key
      • Installing Connectware on Docker
      • Installing Connectware on Kubernetes
    • Connectware Admin UI
    • Basic Components of Connectware
    • Connecting your First Machine
      • Your First Service Commissioning File
  • Documentation
    • Services
      • Structure of Commissioning Files
        • description
        • metadata
        • parameters
        • definitions
        • resources
          • Cybus::Connection
          • Cybus::Endpoint
          • Cybus:Mapping
          • Cybus::Container
            • Docker problem with network changes
          • Cybus::Link
          • Cybus::IngressRoute
          • Cybus::User
          • Cybus::Role
          • Cybus::Volume
          • Cybus::File
          • Cybus::Server
          • Cybus::Node
      • ServiceID
      • Inter-Service Referencing
      • Deviation
      • Working with Service Commissioning Files
      • Service Details View
      • Sample Service Commissioning Files
        • Modbus
          • “Bearbeitungszentrum BAZ” - Single File
          • “Bearbeitungszentrum BAZ” - Multiple Files
          • “Bearbeitungszentrum BAZ” - Single File and Custom Topics
          • “Bearbeitungszentrum BAZ” - Agent Mode
        • Machine Condition Monitoring : OPC UA + InfluxDB + Grafana Dashboard
          • “Machine Condition Monitoring Example” - Single File
        • Machine Utilization Example (Multi file service composition) : Modbus TCP + InfluxDB + Grafana + MSS
          • “Machine Utilization Example” - Machine Connectivity
          • “Machine Utilization Example” - Dashboards with role based access permission
          • “Machine Utilization Example” - Push data to MSSQL Database
      • Rule Engine
        • Data Processing Rules
        • Rule Sandbox
      • API Definition
    • Resources
      • Containers
      • Volumes
      • Connections
      • Endpoints
      • Mappings
      • Servers
      • Nodes
      • API Definition
    • User Management
      • Users and Roles View
      • Users
      • Roles
      • Permissions
      • Password Policy Rules
      • Default Admin User
      • MQTT Users
      • Adding a MQTT Publish Prefix for Users
      • Multi-Factor Authentication
      • Long lived JSON Web Tokens
      • Access Permissions for Admin-UI
        • UI Access
        • Minimum Access Role Pages
      • API Definition
    • Client Registry
      • Implicit Flow
      • Explicit Flow
      • Granting Access
      • API Definition
    • Certificates
    • Explorer
    • Workbench
      • Flows in Git Repositories
    • System Status
      • Info
      • Metrics
      • Status
      • Retrieving More System Information
      • System Health
      • API Definition
    • Backup and Restore
      • Volumes
      • User Database
    • Configuration
      • Environment Variables
      • LDAP Configuration
      • MFA Configuration
    • Agents
      • Installing Agents
        • Installing Agents via Docker
        • Installing Agents via Docker Compose
        • Installing Agents via Kubernetes
        • Using Mutual TLS for Agents
      • Registering Agents in Connectware
      • Using Agents
      • Monitoring Agents
      • Troubleshooting Agents
    • Industry Protocol Details
      • ADS
        • AdsConnection
        • AdsEndpoint
      • BACnet
        • BacnetConnection
        • BacnetEndpoint
      • EtherNet/IP
        • EthernetIpConnection
        • EthernetIpEndpoint
      • Focas
        • FocasConnection
        • FocasEndpoint
      • Generic VRPC
        • GenericVrpcConnection
        • GenericVrpcEndpoint
      • Hottinger Baldwin Messtechnik (HBM)
        • HbmdaqConnection
        • HbmdaqEndpoint
      • Heidenhain DNC
        • HeidenhainConnection
        • HeidenhainEndpoint
      • HTTP/REST
        • HttpConnection
        • HttpEndpoint
      • HTTP Server
        • HttpServer
        • HttpNode
      • InfluxDB
        • InfluxdbConnection
        • InfluxdbEndpoint
      • Kafka
        • KafkaConnection
        • KafkaEndpoint
      • Modbus/TCP
        • ModbusConnection
        • ModbusEndpoint
      • MQTT
        • MqttConnection
        • MqttEndpoint
      • MSSQL
        • MssqlConnection
        • MssqlEndpoint
      • OPC DA
        • OpcdaConnection
        • OpcdaEndpoint
      • OPC UA
        • OPC UA Client
          • OpcuaConnection
          • OpcuaEndpoint
        • OPC UA Server
          • OpcuaServer
          • OpcuaNode
        • OPC UA Object Types
        • OPC UA Server References
          • OpcuaReferenceNode
          • OpcuaObjectNode
      • Siemens SIMATIC S7
        • S7Connection
        • S7Endpoint
      • Shdr
        • ShdrConnection
        • ShdrEndpoint
      • Sinumerik
        • SinumerikConnection
        • SinumerikEndpoint
      • Sopas
        • SopasConnection
        • SopasEndpoint
      • SQL
        • SqlConnection
        • SqlEndpoint
      • Werma WIN Ethernet
        • WermaConnection
        • WermaEndpoint
      • Systemstate
        • SystemstateConnection
        • SystemstateEndpoint
      • API Definition
    • Connectware Licensing
    • Changelog
      • General changes from 0.x to 1.0
        • Upgrading from 0.x to 1.0
    • Upgrade Guide
      • Upgrading from 1.x to 1.7.0
      • Upgrading from 1.x to 1.5.0
Powered by GitBook
LogoLogo

Cybus

  • Terms and Condition
  • Imprint
  • Data Privacy

© Copyright 2025, Cybus GmbH

On this page
  • Upgrading the Connectware installation
  • Migrating commissioning files
  • Service commissioning files
  • Device commissioning files
  • Specific Topics
  • Template Syntax
  • MQTT Topic Space
  • Frontend Routes
  • Docker options
  • Environment Variables
  • Examples
  • Grafana dashboard Example
  • Old file in 0.x
  • New file in 1.0

Was this helpful?

  1. Documentation
  2. Changelog
  3. General changes from 0.x to 1.0

Upgrading from 0.x to 1.0

PreviousGeneral changes from 0.x to 1.0NextUpgrade Guide

Last updated 8 months ago

Was this helpful?

This section descibes the upgrading of a Cybus Connectware installation from a previous 0.x version to 1.0.0. For an overview of concept changes, see .

Upgrading the Connectware installation

To upgrade the installed version from 0.x to 1.0, just download and run the connectware-online-installer.sh script as usual. If a 0.x installation is detected, the Connectware containers of the previous installation will be stopped and the container instances removed, but the container images will remain installed.

It is not possible to run both versions in parallel on the same computer, just as it is not possible to run more than one instance of the Connectware in parallel on one computer anyway. It is possible to have both versions installed and start either of both versions alternating, as long as one version is stopped completely (using docker compose down) before starting the other version. Make sure to reload your browser window (e.g. by Ctrl+F5) when switching between both versions, as sometimes the browser keeps the wrong version of the admin UI in its cache.

Currently, no automatic migration of user data, device configuration, or service configuration is implemented. Please contact Cybus support if you need help in migrating your data.

Migrating commissioning files

In the following, the necessary migration work for service and device commissioning files will be described.

In 1.0, the resources of one commissioning file can reference other resources not only from the same commissioning file and service, but also across different services using the . Hence, the complete system context can be described by one or or by multiple commissioning files, whatever fits best for the application. In particular, it is up to you whether the old device and service commissioning files are migrated into one or into two files. Both is possible.

Service commissioning files

To migrate the old service commissioning files into new service commissioning files with resources, the following steps must be performed with the respective sections in the old file:

  • Old general properties must be rewritten in the new top-level properties or metadata properties, see .

  • Old containers sections must be rewritten into resources

  • Old frontends sections must be rewritten into resources

  • For more information, feel free to contact Cybus Support.

Device commissioning files

To migrate the old device commissioning files into new service commissioning files with resources, the following steps must be performed with the respective sections in the old file:

  • For more information, feel free to contact Cybus Support.

Specific Topics

Template Syntax

Old

In 0.x Connectware, the installation specific parameters were made configurable using the {{...}} template syntax. When installing commissioning files with these templates, the user was being asked to give values for these templates.

New

MQTT Topic Space

Old

There were no special constraints on the MQTT topics to which device could write its messages, in particular no constraints on the topicPrefix of the target interface.

New

Frontend Routes

Old

For making specific ports of service containers accessible to the outside, in 0.x Connectware one would specify these proxy rules in the frontends section of the service commissioning file. The URLs were created in a scheme that contains the string services, then the provider name and service-identifier, followed by the slug.

New

Docker options

Old

If the docker containers in a service need to be started with special options, such as device capabilities or xxxx mode, one would use the section alice with some extra parameters.

New

Environment Variables

Old

For passing environment variables to containers, a property section env was added to the containers section in the commissioning file. The actual env variables were written in a syntax with equal sign, like so: MQTT_HOST=foo.bar.

New

Examples

Grafana dashboard Example

This service runs a Grafana visualization for data, an InfluxDB as data source of the container, and a connector container for data input. The comparison shows how the syntax for specifying containers needs to be changed when upgrading.

Old file in 0.x

---
#------------------------------------------------------------------------------#
# CYBUS SERVICE COMMISSIONING
#------------------------------------------------------------------------------#
general:
    title: Generic Dashboard
    identifier: generic-dashboard
    version: 1.2.1
    description: >
        The generic Grafana dashboard visualizes all Connectware data with just a few
        clicks and offers a wide range of options for creation of graphs and analyzes.
    provider: cybus
    homepage: https://cybus.io
    terms: Prototype
#------------------------------------------------------------------------------#
# GRANTEES
#------------------------------------------------------------------------------#
grantees:
    - identifier: influxdb-connector
      credentials: token
      token: $password
      purpose: Forwards data to InfluxDB
      type: container
#------------------------------------------------------------------------------#
# PERMISSIONS
#------------------------------------------------------------------------------#
policies:
    - grantee: influxdb-connector
      purpose: Reads data from any MQTT topic
      policy: ReadData
      constraints:
          topic: '#'
#------------------------------------------------------------------------------#
# CONTAINERS
#------------------------------------------------------------------------------#
containers:
    - image: registry.cybus.io/cybus-services/generic-grafana:1.2.1
      name: generic-grafana
      env:
          - GF_SERVER_ROOT_URL=/services/cybus/generic-dashboard/web
          - GF_AUTH_ANONYMOUS_ENABLED=true
          - INFLUX_HOST=generic-influxdb
          - INFLUX_PORT=8086
          - INFLUX_DB=generic
      alice:
          HostConfig:
              Binds:
                  - 'grafana:/var/lib/grafana'
    - image: registry.cybus.io/cybus-services/influxdb-push:0.0.3
      name: influxdb-push
      env:
          - MQTT_HOST=connectware
          - MQTT_USER=influxdb-connector
          - MQTT_PORT=1883
          - MQTT_PASS=$password
          - MQTT_ROOT_TOPIC=#
          - INFLUX_HOST=generic-influxdb
          - INFLUX_PORT=8086
          - INFLUX_DB=generic
          - HTTP_ROOT=/services/cybus/generic-dashboard/red
    - image: registry.cybus.io/cybus-services/influxdb:1.7.8-alpine
      name: generic-influxdb
      env:
          - INFLUXDB_DB=generic
      alice:
          HostConfig:
              Binds:
                  - 'genericdb:/var/lib/influxdb'
              PortBindings:
                  '8086/tcp':
                      - HostPort: '8086'
#------------------------------------------------------------------------------#
# FRONTENDS
#------------------------------------------------------------------------------#
frontends:
    - type: http
      name: Grafana
      slug: web
      target:
          path: '/'
          container: generic-grafana
          port: 3000
      buttons:
          - name: Open Grafana
            href: '/services/cybus/generic-dashboard/web'

New file in 1.0

Download:

description: >
    The generic Grafana Service

metadata:
    name: Generic Grafana Dashboard
    icon: https://www.cybus.io/wp-content/uploads/2017/10/for-whom3.svg
    provider: cybus
    homepage: https://www.cybus.io
    version: 1.2.1

definitions:
    SID: !ref Cybus::ServiceId
    CYBUS_MQTT_ROOT: 'services'

resources:
    #----------------------------------------------------------------------------
    # VOLUMES
    #----------------------------------------------------------------------------

    grafanaVolume:
        type: Cybus::Volume

    influxdbVolume:
        type: Cybus::Volume

    #----------------------------------------------------------------------------
    # FRONTENDS
    #----------------------------------------------------------------------------

    # Grafana
    grafanaURL:
        type: Cybus::IngressRoute
        properties:
            container: !ref genericGrafana
            type: http
            slug: grafana
            target:
                path: '/'
                port: 3000

    dashboard:
        type: Cybus::Link
        properties:
            name: Dashboard
            ingressRoute: !ref grafanaURL
            href: ''

    #----------------------------------------------------------------------------
    # Cybus Timeseris & Dashboard service containers
    #----------------------------------------------------------------------------

    influxdbPush:
        type: Cybus::Container
        properties:
            image: registry.cybus.io/cybus-services/influxdb-push:0.0.3
            environment:
                MQTT_HOST: !ref Cybus::MqttHost
                MQTT_USER: !ref Cybus::MqttUser
                MQTT_PORT: !ref Cybus::MqttPort
                MQTT_PASS: !ref Cybus::MqttPassword
                MQTT_ROOT_TOPIC: !sub 'services/#'
                INFLUX_HOST: !ref influxdb
                INFLUX_PORT: 8086
                INFLUX_DB: generic
                HTTP_ROOT: /

    influxdb:
        type: Cybus::Container
        properties:
            image: registry.cybus.io/cybus-services/influxdb:1.7.7-alpine
            ports:
                - 8086:8086/tcp
            volumes:
                - !sub '${influxdbVolume}:/var/lib/influxdb'
            environment:
                INFLUXDB_DB: generic

    genericGrafana:
        type: Cybus::Container
        properties:
            image: registry.cybus.io/cybus-services/generic-grafana:1.2.1
            volumes:
                - !sub '${grafanaVolume}:/var/lib/grafana'
            environment:
                GF_SERVER_ROOT_URL: !sub '/services/${SID}/grafana'
                GF_AUTH_ANONYMOUS_ENABLED: true
                INFLUX_DB: generic
                INFLUX_HOST: !ref influxdb
                INFLUX_PORT: 8086

Old source sections must be rewritten into resources

Old target sections are not needed as separate entries anymore. For the definition of the target topic prefix, either the default from the global parameter is used, or the endpoint’s property needs to be defined.

Old mappings sections must be rewritten into resources

Default settings that were used in multiple mappings (now: multiple endpoints) now need to be defined using and used by !merge in the .

In 1.0 Connectware, the installation specific parameters are noted as . They are defined in the parameters section of the , then used by the !sub function for value substitution. Example: !sub 'My Workbench ${ID}'

In 1.0 Connectware, every service hat its own namespace in MQTT as given by its . Other services cannot read data from each other’s namespace directly. A service has its own scope. If this is intended to be changed, the global parameter can be redefined to some global pattern. And also in a resource, you are allowed to write to anything, but not in the endpoint.

In 1.0 Connectware, making ports accessible to the outside is achieved by specifying a . The URL still contains the string services, but then the serviceId followed by the specified slug. Watch out: No trailing slash is appended automatically now. This has to be specified explicitly if wanted.

In 1.0 Connectware, all extra docker options are available as parameters below the resource, in particular the , , and parameters.

Defining environment variables for a container is done by adding the parameter below the . The actual variables are now written in a syntax of yaml object assignment, as follows: MQTT_HOST: foo.bar.

It is also common to use a in this place by reference !ref or substitution !sub, like so: MQTT_HOST: $ref Cybus::MqttHost or MQTT_HOST: '!sub ${myParameter}'

More examples are also .

This example shows the comparison between the old file to the new file. More examples are also .

See also the full example here:

The example below uses an additional Docker image provided by Cybus that requires a suitable license. You can check the current capabilities and permissions of your Connectware license in the Cybus Portal (). If your license is not eligible to use the example Docker image, please contact Cybus Sales ().

Changelog from 0.x to 1.0
service ID
Structure of Commissioning Files
Cybus::Container
Cybus::IngressRoute
Cybus::Connection
Cybus::MqttRoot
topic
Cybus::Mapping
definitions
properties
parameters
commissioning file
ServiceID
CYBUS_MQTT_ROOT
Cybus::Mapping
Cybus::IngressRoute resource
Cybus::Container
devices
ports
capAdd
environment
Cybus::Container resource
parameter
shown here
shown here
“Machine Utilization Example” - Dashboards with role based access permission
https://portal.cybus.io
sales@cybus.io
3KB
utilization-grafana.yml