Get Started!

• 1: 1. Installation
• 2: 2. Data Acquisition and Manipulation
• 3: 3. Data Visualization
• 4: 4. Instance Management & Troubleshooting

1 - 1. Installation

If you are new to the United Manufacturing Hub and need a place to start, this is the place to be. You will be guided through setting up an account, installing your first instance and connecting to an OPC UA simulator in no time.

Requirements

Device

• You will need an edge device, bare metal server or virtual machine with internet access. The device should meet the following minimum requirements or the installation will fail:

• ARM-based systems, such as a Raspberry Pi, are not currently supported.

Operating System

We support the following operating systems:

Newer or older versions of the operating system, or other operating systems such as Ubuntu, may work, but please note that we do not support them commercially.

Network

• A personal computer with a recent browser to access the Management Console.

• Ensure that management.umh.app is allowlisted on TCP port 443 for HTTPS traffic.

  You can also check our Recommended Firewall Settings.

Sign Up to the Management Console

1. Open the Management Console in the browser, click on Sign up now and create a new account.

2. Once logged in with your new account, click on Add Your First Instance.

Create your first Instance

1. First you have to set up your device and install the operating system. We support , but we strongly recommend using Rocky. You can find a list of the requirements and the image for Rocky by clicking on the REQUIREMENTS button on the right hand side of the Management Console.

2. Once you have successfully installed your operating system, you can configure your instance in the Management Console. For the first instance you should only change the Name and Location of the instance. These will help you to identify an instance if you have more than one.

3. Once the name and location are set, continue by clicking on the Add Instance button. To install the UMH, copy the command shown in the dialogue box, SSH into the new machine, paste the command and follow the instructions. This command will run the installation script for the UMH and connect it to your Management Console account.

4. If the UMH installation was successful, you can click the Continue button. Your instance should appear in the Instances and Topology sections of the left-hand menu after a few minutes.

What’s next?

Once you installed UMH, you can continue with the next page to learn how to connect an OPC UA server to your instance.

2 - 2. Data Acquisition and Manipulation

Once your UMH instance is up and running, you can follow this guide to learn how to connect the instance to an OPC UA server. For this example we will use the OPC UA simulator that is provided by your instance.

Connect to external devices

You can connect your UMH instances to external devices using a variety of protocols. This is done in the Management Console and consists of two steps. First you connect to the device and check that your instance can reach it. The second step is to create a protocol converter for the connection, in which you define the data you want to collect and how it should be structured in your unified namespace.

To allow you to experience the UMH as quickly as possible, the connection to the internal OPC UA simulator is already pre-configured.

Therefore, the Add a Connection section is included for reference only. You can skip to Add a Protocol Converter below.

Add a Connection

1. To create a new connection, navigate to the Connections section in the left hand menu and click on the + Add Connection button in the top right hand corner.

   If you want to configure the connection to the OPC UA simulator by yourself, delete the preconfigured connection named default-opcua-simulator-connection.

   Having two connections to the same device can cause errors when deploying the Protocol Converter!

2. Under General Settings select your instance and give the connection a name. Enter the address and port of the device you want to connect to. To connect to the OPC UA Simulator, use

   • IP: united-manufacturing-hub-opcsimv2-service.united-manufacturing-hub.svc.cluster.local
   • Port: 50000

   You can also set additional location fields to help you keep track of your of your connections. The fields already set by the selected instance are inherited and cannot be changed.

3. Once everything is set up, you can click Save & Deploy. The instance will now attempt to connect to the device on the specified IP and port. If there is no error, it will be listed in the Connections section.

4. Click on the connection to view its details, to edit click on the Configuration button in the side panel.

Add a Protocol Converter

To access the data from the OPC UA Simulator you need to add a Protocol Converter to the connection.

1. Click on the connection to the OPC UA Simulator in the Connections table. If you are using the preconfigured one, it is called default-opcua-simulator-connection. Click on the + Add Protocol Converter button in the opening menu.

2. First you need to select the protocol used to communicate with the device, in this case OPC UA. This can be found under General.

3. Input: Many of the required details are already set based on the connection details. For this tutorial, we will subscribe to a tag and a folder on the OPC UA server. Tags and folders can be selected manually using the NodeID or by using the OPC UA Browser.

   If you want to select the nodes via the OPC UA Browser, uncheck the Root box, navigate to Root/Objects/Boilers/Boiler #2 and select the ParameterSet folder. Next navigate to Root/Objects/OpcPlc/Telemetry/Fast and select the FastUInt1 tag, then click Apply at the bottom.

   To add the nodes manually, close the OPC UA Browser by clicking on the OPC UA BROWSER button at the right edge of the window. The nodes must be added as Namespaced String NodeIDs. Now copy the code below and replace the current nodeIDs: with it.

   nodeIDs:
     - ns=4;i=5020
     - ns=3;s=FastUInt1
   

   In the input section, you must also specify the OPC UA server username and password, if it uses one.

   The Input should now look like this. Note that the indentation is important.

    opcua:
      endpoint: opc.tcp://united-manufacturing-hub-opcsimv2-service.united-manufacturing-hub.svc.cluster.local:50000
      username: "optional_username"
      password: "optional_password"
      subscribeEnabled: true
      useHeartbeat: true
      nodeIDs:
        - ns=4;i=5020
        - ns=3;s=FastUInt1
   

4. Processing: In this section you can manipulate the incoming data and sort it into the desired asset. The auto-generated configuration will sort each tag into the same asset based on the location used for the instance and connection, while the tag name will be based on the name of the tag on the OPC UA server.

   Further information can be found in the OPC UA Processor section next to the Processing field, for example how to create individual assets for each tag.

5. Output: The output section is generated entirely automatically by the Management Console.

6. Now click on Save & Deploy. Your Protocol Converter will be added.

7. To view the data, navigate to the Tag Browser on the left. Here, you can see all your tags. The tree on the left is build from the asset of each tag, you can navigate it by clicking on the asset parts.

Find out more about Data Modelling in the Unified Namespace in the Learning Hub.

What’s next

Next, we’ll dive into Data Visualisation, where you’ll learn how to create Grafana dashboards with your newly collected data.

3 - 3. Data Visualization

After bringing the data from the OPC UA simulator into your Unified Namespace, you can use Grafana to create dashboards to display it. If you haven’t already connected the OPC UA simulator to your instance, you can follow the previous guide.

Accessing Grafana

1. Make sure you are on the same network as your instance to access Grafana.

2. In the Management Console, select Applications from the left hand menu. Click on Historian (Grafana) for the instance to which you have connected the OPC UA simulator. You can search for your instance’s applications by entering its name in the Filter by name or instance field at the top of the page.

3. Click on the URL displayed in the side panel that opens. This will only work if you have set the correct IP address for your instance during the installation script. If you can’t connect to Grafana, find out the IP address of your instance and enter the following URL in your browser

   http://<IP-address-of-your-instance>:8080
   

4. Copy the Grafana password by clicking on it in the side panel of the application. The user name is admin.

5. To add a dashboard, click on Dashboards in the left menu and then on the blue + Create Dashboard button in the middle of the page. On the next page click + Add visualisation.

6. Select the UMH TimescaleDB data source in the Select data source dialogue box.

7. To access data from your Unified Namespace in Grafana, you can use SQL queries generated by the Management Console for each tag. Open the Tag Browser and navigate to the desired tag, e.g. CurrentTemperature from the ParameterSet folder of the OPC UA Simulator. The query is located at the bottom of the page under SQL Query. Make sure it is set to Grafana and then copy it.

8. In Grafana, change the query mode to Code by toggling the Builder/Code switch located on the right hand side of the page next to the blue Run query button. Paste the query you copied from the Management Console into the text box.

9. Click the blue Run query button. If everything is set up correctly you should see the data displayed in a graph.

10. There are many ways to customise the graph on the right hand side of the page. For example, you can use different colours or chart styles. You can also add more queries at the bottom of the page.

11. When you are happy, click the blue Apply button in the top right corner. You will now see the dashboard. You can adjust the size and position of the graph or access other options by clicking on the three dots in the top right hand corner of the graph. To add another graph, click Add and then Visualisation from the menu bar at the top of the page.

12. To save your dashboard, press Ctrl + S.

Further Reading

If you would like to find out more about the United Manufacturing Hub, here are some links to get you links to get you started.

General knowledge, updates and guidance? Check out our Learn page:

• Our Blog
• Grafana Guides

Do you need more technical background information?

• Introduction IT
• Introduction OT
• Introduction IIoT
• The Architecture of the UMH

If you don’t want to read all that, you can check out our YouTube channel where we have also covered these topics:

• Unified Namespace (UNS) Basics
• Introduction into IT / OT

If you need help, want to stay up to date with product news, or just want to connect with like-minded people, join our community:

• Discord
• Linked In
• GitHub

4 - 4. Instance Management & Troubleshooting

This chapter covers the management and troubleshooting of your United Manufacturing Hub (UMH) instance. The usual way to interact with your UMH instance is through the Management Console. However, for heavy troubleshooting or automations, you might want to interact with your instance through the command line. This chapter will guide you through the process of accessing your instance, as well as provide you with some common commands and how to resolve issues.

Manage the Instance

Before you begin, ensure that you are connected to the same network as the instance for accessing the various services and features discussed below.

Access the Command Line

Access your device’s shell either directly or via SSH. Note: Root user access is required for the following commands.

Interact with the Instance

First, set this environment variable:

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

You can bypass this by adding the flag --kubeconfig /etc/rancher/k3s/k3s.yaml to all your kubectl commands. Root privileges are needed to access it. The installation path of kubectl might vary (e.g., /usr/local/bin/kubectl on RHEL/Linux, /opt/bin/kubectl on flatcar).

Then, to get a list of pods, run:

sudo $(which kubectl) get pods -n united-manufacturing-hub  --kubeconfig /etc/rancher/k3s/k3s.yaml

For a comprehensive list of commands, refer to the Kubernetes documentation.

Always specify the namespace when running a command by adding -n united-manufacturing-hub or set the default namespace with kubectl config set-context --current --namespace=united-manufacturing-hub.

Access Node-RED

Node-RED is used in UMH for creating data flows. Access it via:

http://<instance-ip-address>:1880/nodered

Access Grafana

UMH uses Grafana for dashboard displays. Get your credentials:

sudo $(which kubectl) get secret grafana-secret --kubeconfig /etc/rancher/k3s/k3s.yaml -n united-manufacturing-hub -o jsonpath="{.data.adminuser}" | base64 --decode; echo
sudo $(which kubectl) get secret grafana-secret --kubeconfig /etc/rancher/k3s/k3s.yaml -n united-manufacturing-hub -o jsonpath="{.data.adminpassword}" | base64 --decode; echo

Then, access Grafana here:

http://<instance-ip-address>:8080

Use the retrieved credentials to log in.

Access the RedPanda Console

Manage the Kafka broker via the RedPanda Console:

http://<instance-ip-address>:8090

Interact with the Database

UMH uses TimescaleDB. Open a psql session:

sudo $(which kubectl) exec -it $(sudo $(which kubectl) get pods --kubeconfig /etc/rancher/k3s/k3s.yaml -n united-manufacturing-hub -l app.kubernetes.io/component=timescaledb -o jsonpath="{.items[0].metadata.name}") --kubeconfig /etc/rancher/k3s/k3s.yaml -n united-manufacturing-hub -- psql -U postgres

This command will open a psql shell connected to the default postgres database.

Run SQL queries as needed. For an overview of the database schema, refer to the Data Model documentation.

Connect MQTT to MQTT Explorer

Use MQTT Explorer for a structured overview of MQTT topics. Connect using the instance’s IP and port 1883.

Troubleshooting

Error: You must be logged in to the server while using the 'kubectl' Command

If you encounter the error below while using the kubectl command:

E1121 13:05:52.772843  218533 memcache.go:265] couldn't get current server API group list: the server has asked for the client to provide credentials
error: You must be logged in to the server (the server has asked for the client to provide credentials)

This issue can be resolved by setting the KUBECONFIG environment variable. Run the following command:

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

Alternatively, use the --kubeconfig flag to specify the configuration file path:

sudo $(which kubectl) --kubeconfig /etc/rancher/k3s/k3s.yaml get pods -n united-manufacturing-hub

“Permission Denied” Error with ‘kubectl’ Command

Encountering the error below while using the kubectl command:

error: error loading config file "/etc/rancher/k3s/k3s.yaml": open /etc/rancher/k3s/k3s.yaml: permission denied

Indicates the need for root access. Run the command with sudo, or log in as the root user.

kubectl: command not found

If you encounter the error below while using the kubectl command:

kubectl: command not found

The solution is to use the full path to the kubectl binary. You can do this by prefixing the command with /usr/local/bin/ (for RHEL and other Linux systems), or /opt/bin/ (for flatcar) or by adding it to your PATH environment variable:

/usr/local/bin/kubectl get pods -n united-manufacturing-hub

# or

export PATH=$PATH:/usr/local/bin

Viewing Pod Logs for Troubleshooting

Logs are essential for diagnosing and understanding the behavior of your applications and infrastructure. Here’s how to view logs for key components:

• Management Companion Logs: To view the real-time logs of the Management Companion, use the following command. This can be helpful for monitoring the Companion’s activities or troubleshooting issues.

  sudo $(which kubectl) logs -f mgmtcompanion-0 -n mgmtcompanion --kubeconfig /etc/rancher/k3s/k3s.yaml
  

• TimescaleDB Logs: For real-time logging of the TimescaleDB, execute this command. It’s useful for tracking database operations and identifying potential issues.

  sudo $(which kubectl) logs -f united-manufacturing-hub-timescaledb-0 -n united-manufacturing-hub --kubeconfig /etc/rancher/k3s/k3s.yaml
  

Restarting a Pod for Troubleshooting

Sometimes, the most straightforward troubleshooting method is to restart a problematic pod. Here’s how to restart specific pods:

• Restart Management Companion: If you encounter issues with the Management Companion, restart it with this command:

  sudo $(which kubectl) delete pod mgmtcompanion-0 -n mgmtcompanion --kubeconfig /etc/rancher/k3s/k3s.yaml
  

• Restart TimescaleDB: Should TimescaleDB exhibit unexpected behavior, use the following command to restart it:

  sudo $(which kubectl) delete pod united-manufacturing-hub-timescaledb-0 -n united-manufacturing-hub --kubeconfig /etc/rancher/k3s/k3s.yaml
  

Troubleshooting Redpanda / Kafka

For insights into your Kafka streams managed by Redpanda, these commands are invaluable:

• List All Topics: To get an overview of all topics in your Redpanda cluster:

  sudo $(which kubectl) exec -it --kubeconfig /etc/rancher/k3s/k3s.yaml -n united-manufacturing-hub  united-manufacturing-hub-kafka-0 -- rpk topic list
  

• Describe a Specific Topic: For detailed information about a specific topic, such as umh.v1.e2e-enterprise.aachen.packaging, use:

  sudo $(which kubectl) exec -it --kubeconfig /etc/rancher/k3s/k3s.yaml -n united-manufacturing-hub united-manufacturing-hub-kafka-0 -- rpk topic describe umh.v1.e2e-enterprise.aachen.packaging
  

• Consume Messages from a Topic: To view messages from a topic like umh.v1.e2e-enterprise.aachen.packaging, this command is useful for real-time data observation:

  sudo $(which kubectl) exec -it --kubeconfig /etc/rancher/k3s/k3s.yaml -n united-manufacturing-hub united-manufacturing-hub-kafka-0 -- rpk topic consume umh.v1.e2e-enterprise.aachen.packaging
  

What’s next?

In this chapter, you learned how to:

• Access and manage your UMH instance
• Use essential kubectl commands
• Troubleshoot common issues
• Access key services like Node-RED, Grafana, and RedPanda

Now that you have these essential management skills, you can proceed to Data Acquisition and Manipulation to start creating your first data flow.