How to run the Rexroth ROKIT Locator on ctrlX CORE X5 / ctrlX CORE X7

Introduction

The Rexroth ROKIT Locator is packaged as a Docker image for easy installation on a variety of different environments. To run the ROKIT Locator on the ctrlX CORE X5 or ctrlX CORE X7, the image must be repackaged in a snap and installed alongside the Container Engine App. The Container Engine App will start the ROKIT Locator as a Docker container running on the ctrlX CORE X5 or ctrlX CORE X7.

This article covers what requirements must be satisfied, how to create the ROKIT Locator snap and how to install it on the ctrlX CORE X5 or ctrlX CORE X7. This does only work with real ctrlX CORE hardware and ctrlX CORE^virtual is not supported.

Requirements

To run the ROKIT Locator on the ctrlX CORE X5 or ctrlX CORE X7, the following requirements must be satisfied:

• ctrlX CORE X5 or ctrlX CORE X7 with OS version 1.* or 2.*
• Container Engine app installed on ctrlX CORE X5 or ctrlX CORE X7
• Docker image of ROKIT Locator Client 1.9
• License file for Container Engine app
• License file for ROKIT Locator Client 1.9
• License Dongle (mat. no. 3842564524)
• USB-A to USB-C adapter
• snapcraft (multipass not required)
  
  

Before installation

Read the documentation

Carefully read the provided documentation for:

• ROKIT Locator Client
• Container Engine App

A general understanding of command line, Docker and snaps is recommended.

Create all required files

Multiple files are required to repackage the ROKIT Locator Docker image as a snap. Create them according to the following structure under some folder (in this example we use ~/rokit-locator-client)

rokit-locator-client/
├── codemeter
│   ├── 60-codemeter-lite.rules
│   └── Server.ini
├── docker-compose
│   ├── codemeter-image.tar
│   ├── docker-compose.env
│   ├── docker-compose.yml
│   └── rokit-locator-client-image.tar
└── snap
    ├── hooks
    │   └── install
    └── snapcraft.yaml

rokit-locator-client-image.tar
The rokit-locator-client-image.tar file must contain the ROKIT Locator Client Docker image. This can be done with one of the following ways:

• copy and rename the received Docker image 

cp folder-of-extracted-locator-zip/Build/corei7-64/ROKIT_Locator_client.docker ~/rokit-locator-client/docker-compose/rokit-locator-client-image.tar

• save Docker image which is stored in local Docker daemon (replace x with patch version number)

docker save rokit_locator_client:lls-1.9.x-final -o ~/rokit-locator-client/docker-compose/rokit-locator-client-image.tar

codemeter-image.tar
The codemeter-image.tar file must contain the wibusystems/codemeter image. This can be done with the following steps:

1. pull the image form Docker Hub
2. save Docker image which is stored in local Docker daemon

docker pull wibusystems/codemeter:8.10

docker save wibusystems/codemeter:8.10 -o ~/rokit-locator-client/docker-compose/codemeter-image.tar

60-codemeter-lite.rules
The 60-codemeter-lite.rules file can be downloaded here. After the file has been downloaded open the .deb file and extract the 60-codemeter-lite.rules located in /lib/udev/rules.d to the ~/rokit-locator-client/codemeter directory.

Server.ini
Please create the Server.ini file with following content in the ~/rokit-locator-client/codemeter directory.

[General]
EnabledContainerTypes=15

docker-compose.env
This file contains environment variables which can be used in the docker-compose.yml. It is automatically loaded by the Container Engine App after installation of the ROKIT Locator Snap. It specifies the Docker image names and tags. Make sure to correctly set the patch version number in the image tag. It must match the previously create image file!

ROKIT_IMAGE_NAME=rokit_locator_client
ROKIT_IMAGE_TAG=lls-1.9.x-final
CODEMETER_IMAGE_NAME=wibusystems/codemeter
CODEMETER_IMAGE_TAG=8.10

docker-compose.yml
This file contains the Docker compose service for the ROKIT Locator and CodeMeter. It is automatically loaded by the Container Engine App after installation of the ROKIT Locator Client App. The service will (re)start automatically on boot up or failures. Make sure to only specify the ports required (further information in ROKIT Locator documentation) and avoid port conflicts with other apps / services. The two volumes of the ROKIT Locator are needed for data persistence on restarts of the service (e.g. on reboot of device). Please keep in mind that a reinstallation of the snap will cause recreation of volumes and therefore all data (configuration values, map, ...) will be lost.

version: "3.7"
networks:
  rokit-bridge:
    ipam:
      config:
        - subnet: 172.20.0.0/16
services:
  rokit-locator-client:
    image: ${ROKIT_IMAGE_NAME}:${ROKIT_IMAGE_TAG}
    container_name: rokit-locator-client
    restart: always
    ports:
      - 8080:8080
      - 8084:8084
      - 9002-9014:9002-9014
      - 9016:9016
      - 9019-9022:9019-9022
      - 6060-6061:6060-6061/udp # laser ports
      - 8443:8443
      - 8447:8447
      - 9442-9454:9442-9454
      - 9456:9456
      - 9459-9462:9459-9462
    volumes:
      - ${SNAP_DATA}/docker-volumes/rokit-locator-client/lls:/var/lls
      - ${SNAP_DATA}/docker-volumes/rokit-locator-client/lls-recovery:/var/lls-recovery
    environment:
      - DONGLEHOST=172.20.0.5
    networks:
      rokit-bridge:
        ipv4_address: 172.20.0.10
    logging: # limit logging to keep required disk space bound
      driver: "json-file"
      options:
        max-size: "500m" 
        max-file: "5"
  codemeter:
    image: ${CODEMETER_IMAGE_NAME}:${CODEMETER_IMAGE_TAG}
    container_name: codemeter
    restart: always
    volumes:
      - ${SNAP_DATA}/docker-volumes/codemeter/Server.ini:/etc/wibu/CodeMeter/Server.ini
    devices:
      - "/dev/bus/usb"
    environment:
      - CM_NETWORK_SERVER=on
    networks:
      rokit-bridge:
        ipv4_address: 172.20.0.5
    logging: # limit logging to keep required disk space bound
      driver: "json-file"
      options:
        max-size: "500m" 
        max-file: "5"

install
The following install hook copies the Server.ini file to the correct location. It is automatically being executed right after installation of the snap.

#!/bin/sh -e

# copy Server.ini to docker volumes
mkdir -p "$SNAP_DATA"/docker-volumes/codemeter/
cp "$SNAP"/codemeter/Server.ini "$SNAP_DATA"/docker-volumes/codemeter/

snapcraft.yaml
The snapcraft.yaml defines how to build the snap. It is recommended to set the version equal to the ROKIT Locator Docker image tag. Make sure that the base matches the OS version of the ctrlX CORE X5 or ctrlX CORE X7 on which the ROKIT Locator will be deployed. The OS version of the ctrlX CORE can be read out from the web interface (Settings -> System Information -> Operating system). Two parts specify which files are being added to the snap:

• docker-compose: all files under ./docker-compose which are required to start the services specified
• codemeter: all files under ./codemeter which are required for codemeter

Two slots provide access to these files:

• docker-compose: Make docker-compose files available to the Container Engine App
• docker-volumes: Make docker-volumes folders available to the Container Engine App

Further details can be found in the Container Engine App documentation.

name: rokit-locator-client
version: 'lls-1.9.x-final'
base: core22 # use core20 for OS 1.* and core22 for OS 2.*
summary: ROKIT Locator Docker image app
description: |
  This snap contains the Docker image of the Rexroth ROKIT Locator Client.
grade: stable
confinement: strict

parts:
  docker-compose:
    plugin: dump
    source: ./docker-compose
    organize:
      '*': docker-compose/${SNAPCRAFT_PROJECT_NAME}/
  codemeter:
    plugin: dump
    source: ./codemeter
    organize:
      'Server.ini': /codemeter/Server.ini
      '60-codemeter-lite.rules': /lib/udev/rules.d/60-codemeter-lite.rules

slots:
  docker-compose:
    interface: content
    content: docker-compose
    source:
      read:
        - $SNAP/docker-compose/${SNAPCRAFT_PROJECT_NAME}
  docker-volumes:
    interface: content
    content: docker-volumes
    source:
      write:
        - $SNAP_DATA/docker-volumes/${SNAPCRAFT_PROJECT_NAME}
        - $SNAP_DATA/docker-volumes/codemeter

Create ROKIT Locator image app

Change into the folder containing all previously created files and create the snap using snapcraft in destructive mode (this is not harmful, because only dump plugins are being used to copy files): 

cd ~/rokit-locator-client
snapcraft --destructive-mode

This should generate a *.snap file which contains all required files for the ROKIT Locator Client image app.

Installation of ROKIT Locator Client image app

Some changes must be made, before the newly created snap file can be run.

Enable IP port forwarding

If IP port forwarding is not enabled the ports specified previously in the docker-compose.yml file will not be accessible from any other device. It is therefore required to enable it for network interfaces which are being used to access the ROKIT Locator (e.g. for setup phase using the ROKIT Locator aXessor). Please note that this will allow access to the internal Docker network from any device connected to the interface. A warning ("Insecure Network Device") will show up when enabling the option. It is therefore recommended to disable the option again for a productive use case. Enabling and disabling can be done via the ctrlX CORE web interface in the network settings section:

Allow installation of apps from unknown sources

The ROKIT Locator Client Docker image app was manually created and is not verified by Rexroth. Therefore, it is required to allow the installation of apps from unknown sources. This can be done in the settings menu of the web interface:

Install Container Engine App

The Container Engine App must be installed and licensed, to run Docker containers on the ctrlX CORE X5 or ctrlX CORE X7. 

Install ROKIT Locator Client image app

After all the previously mentioned requirements are satisfied, the ROKIT Locator Client Image App can be installed using the "Install from file" button in the app overview of the web interface. Please note that the ctrlX CORE X5 or ctrlX CORE X7 must be in "Service" mode (only if PLC App is installed).

Setup of ROKIT Locator Client

After installation the ROKIT Locator Client Docker image should appear, after some seconds, in the Container Engine images overview page. Additionally, a container should be spawned automatically and appear in the Container Engine containers overview page:

Congratulations 🥳. You successfully installed the ROKIT Locator Client on the ctrlX CORE. You may now continue with setting up the ROKIT Locator Client (for example using the graphical interface of the ROKIT Locator called aXessor). Use Wibu dongle as licensing method. Refer to the ROKIT Locator user manual for further setup steps.

Troubleshooting

In case of problems that occur during the installation process (e.g. ROKIT Locator image is not showing up), this page may help diagnosing the problem.

Licensing Dongle not found error

In case the aXessor reports Licensing Dongle not found please try to restart the codemeter container via the web interface of the ctrlX CORE mentioned above.

Container does not show up

The ROKIT Locator and CodeMeter Docker images should be loaded automatically and a container instances should be started, after installation of the app. If no container shows up in the containers overview page the most common reason is a wrong "*_IMAGE_NAME" or "*_IMAGE_TAG" in the docker-compose.env file. Check if these values match the corresponding "Tags" entry of the image in the image overview.

Not able to access the ROKIT Locator

If it is not possible to access the ROKIT Locator from another computer (e.g. using the ROKIT Locator aXessor), then check if the IP port forwarding is enabled (see section above).