Great to see you’re ready to start! This guide has 5 steps:
Installation, Managing the System, Data Acquisition & Manipulation, and
Moving to Production.
Contact Us!
Do you still have questions on how to get started? Message us on our
Discord Server.
1 - 1. Installation
Install the United Manufacturing Hub together with all required tools on a Linux Operating System.
The United Manufacturing Hub (UMH) can be deployed on various external devices,
including edge devices and virtual machines (VMs). For initial installations
or for development purposes, it is recommended to use a VM.
Software Requirements
The UMH installation requires one of the following Operaing System on your server:
Flatcar version current-2023 or higher (3510.3.1).
It is recommended that you have full control over the operating system. To install Flatcar on your server,
follow this guide.
Red Hat Enterprise Linux (RHEL) 9.0 and higher. Recommended when you can choose
only out of a small amount of potential Operating System in your large enterprise
Community Supported: Ubuntu 22.04.4 LTS. This approach is useful
when you’re for example trying to install the UMH on a cloud instance like AWS EC2
and struggle to install Flatcar or RHEL there.
While UMH is optimized for RHEL and Flatcar, it can theoretically run on other Linux distributions.
However, support is not guaranteed.
For Windows, you could try running one of the above described Operating Systems in a VM (e.g., Hyper-V).
If you experiment with other systems, we encourage sharing your experiences
on our Discord channel.
Hardware Requirements
CPU: Minimum 4 cores
Memory: 16 GB RAM
Disk Space: 32 GB available
Note: Systems at the edge of these requirements may experience longer installation times.
Close other programs during installation for optimal performance.
Network Requirements
Before proceeding with the installation, ensure your system meets the necessary network requirements.
To learn about configuring firewall and network rules for your UMH instances,
please refer to our dedicated Firewall Rules page.
When you are finished with the creation of your account, enter your information and click on SIGN IN.
If you are not a member, continue with sign up. Register your information and click on SIGN UP.
Click on +Add Instance button.
Select Install UMH Only.
Enter your instace name and then click on Create my command.
You should be able to see a create command. Copy and paste the following command into your server’s terminal (via ssh).
The installation script runs a lot of checking and setup. For example, it checks your operating system,
installation of required tools, and internet connection.
After the check phase, kubectl and Helm will be installed.
The script shall show you what actions will happen to your system in the next step.
If you want to proceed, type Y and press enter key.
In this step, k3s will be installed. Then, it installs the UMH Helm Chart in Kubernetes.
After that, the Management Companion will be installed into Kubernetes.
Until everything is set up, it can take a while.
After successful installation, you should be able to see messages like in the picture below.
Go back to the Management Console and click on Let’s Go!
Now, you should be able to see your instance on the dashboard.
Do you need more technical background information?
Once you installed UMH, you can continue with the
next page to learn how to manage the system,
for example, access to the microservices.
2 - 2. Managing the System
Learn how to manage your UMH instance with the Management Console.
In this chapter, you will learn how to monitor, manage and configure your UMH
instance with the Management Console.
At this stage, you should have already installed the UMH on your device. If you
have not done so, please follow the steps in the Installation
chapter first.
A Few Words About the Communication
Now that you have connected a UMH instance to the Management Console, you might
be curious about how the Management Console communicates with the instance.
The Management Companion, serving as an agent within each UMH instance, provides
a secure link to the Management Console. It enables comprehensive and secure
monitoring and management of the UMH, ensuring system health and streamlined
configuration, all while acting as a vigilant watchdog over system components and
connected devices.
The diagram below illustrates the communication flow between the Management
Console and the instance:
On the left side of the Management Console, you can view the list of your
instances. If you have just installed the UMH, you should see only one instance
in the list.
The status of your instance is indicated by color: green means everything is
working properly, while yellow indicates that there may be a connection issue.
The Messages Received statistic shows the number of messages received by you
from the instance since you opened the Management Console. It is usually a good
indicator of the health of the connection to the Companion.
If the number is not increasing for 10 seconds, the instance is considered
disconnected.
Monitoring the Instance’s Status
From the instance dashboard, in the overview tab, you can view the status of
your instance. There are multiple interfaces that display the status of each
component of the system.
Modules
A Module refers to a group of workloads in the United Manufacturing Hub
responsible for specific tasks. For example, the Historian & Analytics module
represents the microservices, storage, and connections that are responsible for
storing and analyzing data.
In the Modules tab, you can view the status of each module. If a module is
not healthy, it means that one or more of its components are not functioning
properly.
System
In the System tab, you can view the resource usage of your device, as well
as some system’s information.
If there is an overload on the device, you can view it here. An overloaded device
is unable to handle the workload, and you should consider upgrading the device.
Connection Management
In the Connection Management tab, you can view a brief overview of the data infrastructure,
which includes the rate of messages going through the message broker and the database. Any unhealthy
data sources or connections are also listed here.
Kubernetes
In the Kubernetes tab, you can check for any error events in the Kubernetes
cluster. Any errors suggest that the cluster is not operating correctly.
Additionally, this tab displays the version of the United Manufacturing Hub and
the Management Companion currently installed on your device.
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.
While a graphical user interface for managing the instance is not yet available,
you can still manage it via the command line.
Access the Command Line
Access your device’s shell either directly or via SSH. Note: Root user access is required for the following commands.
In UMH’s current version, add --kubeconfig /etc/rancher/k3s/k3s.yaml to each kubectl command. 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). These paths may not be in the root user’s PATH, so the commands below might appear complex.
Interact with the Instance
First, set this environment variable:
exportKUBECONFIG=/etc/rancher/k3s/k3s.yaml
You can bypass this by adding –kubeconfig /etc/rancher/k3s/k3s.yaml to your commands. All instructions in this chapter will include this flag.
Then, to get a list of pods, run:
sudo $(which kubectl) get pods -n united-manufacturing-hub --kubeconfig /etc/rancher/k3s/k3s.yaml
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:
exportKUBECONFIG=/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 error
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
# orexportPATH=$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.
TimescaleDB Logs: For real-time logging of the TimescaleDB, execute this command. It’s useful for tracking database operations and identifying potential issues.
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:
Now that you have learned how to monitor, manage and configure your UMH instance
with the Management Console, you can start creating your first data flow. To
learn how to do this, proceed to the Data Acquisition and Manipulation
chapter.
3 - 3. Data Acquisition and Manipulation
Learn how to connect various data sources to the UMH and format data into the
UMH data model.
The United Manufacturing Hub excels in its ability to integrate diverse data
sources and standardize data into a unified model, enabling seamless integration
of existing data infrastructure for analysis and processing.
Currently, data sources can be connected to the UMH through Benthos for OPC UA
and Node-RED for other types.
The UMH includes 3 pre-configured data simulators for testing connections:
OPC UA, often complex, can be streamlined using our Benthos-based OPC UA connector
accessible from the Management Console.
Create a Connection with the Management Console
After logging into the Management Console and selecting your instance, navigate
to the Connection Management tab, where you’ll find all your connections alongside their status.
Uninitialized Connections are established but not yet configured as data
sources, while Initialized Connections are fully configured.
The health status reflects the UMH-data source connection, not data transmission status.
To add a new connection, click Add Connection. Currently, we only provide two type of connections:
OPC-UA Server: represents a connection to an OPC-UA server.
n/a: represents a generic asset (useful for connections we don’t support yet).
Enter the required server details, which include the unique name and address with the format ip:port.
Optionally, you can also attach some notes to the connection, which can be useful for documentation purposes.
For testing with the OPC UA simulator, select the OPC-UA Server type and use the following address:
Test the connection, and if successful, click Add Connection to save and deploy it.
Initialize the Connection
Back at Connection Management, your new connection should be listed in the table, and surely you’ll notice that it’s health is reported as Not configured.
At this point, it’s worth discussing what initializing a connection means and why it’s important.
New connections are created in an “uninitialized” state, meaning they are not yet configured as data sources, hence the Not configured health status.
So for them to be actually useful, they need to be initialized, which will fully configure them as data sources and create a new Benthos deployment for data publishing to the UMH Kafka broker.
Initialize the connection by pressing the “play” button under the Actions column.
Enter authentication details (use Anonymous for no authentication, as with the
OPC UA simulator).
Specify OPC UA nodes to subscribe to in a yaml file, following the ISA95 standard:
Review and confirm the nodes, then proceed with initialization. Successful
initialization will be indicated by a green message.
The connection’s health status should now be marked as Healthy and display the current message rate. You can also check the tooltip for more details.
Connect MQTT Servers
There are a lot of options to connect an MQTT server to the UMH. For this guide,
we’ll use Node-RED to connect to the MQTT simulator and format data into the
UMH data model.
To access Node-RED’s web interface, navigate to:
http://<instance-ip-address>:1880/nodered
Replace <instance-ip-address> with your UMH instance’s IP. Ensure you’re on the
same network for access.
Add the MQTT Connection
In Node-RED, find the mqtt-in node from the node palette and drag it into your
flow. Double-click to configure and click the pencil button next to the
Server field.
Enter your MQTT broker’s details:
Server: united-manufacturing-hub-mqtt
Port: 1883
For the purpose of this guide, we’ll use the UMH MQTT broker, even though the
data coming from it is already bridged to Kafka by the
MQTT Kafka Bridge.
Since the simulated data is using the old Data Model, we’ll use Node-RED to
convert it to the new Data Model.
Click Add to save.
Define the subscription topic. For example,
ia/raw/development/ioTSensors/Temperature is used by the MQTT Simulator.
To test, link a debug node to the mqtt-in node and deploy. Open the debug pane
by clicking on the bug icon on the top right of the screen to view messages
from the broker.
Since the data is already processed from the previous step, use a function node
to convert the temperature from Celsius to Fahrenheit. Connect it to the
kafka-consumer node and paste the following script:
For more on UMH data modeling, consult the documentation.
Press Done and deploy.
Consider adding a debug node for visualizing output data.
Tag Browser
Returning to the Management Console, you’ll find the output data displayed within the Tag Browser,
which offers a user-friendly tree structure for browsing the tag hierarchy we defined in previous steps.
What’s next
Next, we’ll dive into Data Visualization,
where you’ll learn to create Grafana dashboards using your newly configured data
sources. This next chapter will help you visualize and interpret your data effectively.
4 - 4. Data Visualization
Build a simple Grafana dashboard with the gathered data.
In the following step, we will delve into the process of visualizing the data.
This chapter focuses on the construction of dashboards using Grafana. The
dashboard will be crafted around the OPC-UA data source and the Node-RED flow,
both of which were established in the previous chapter.
Creating a Grafana dashboard
If you haven’t done so already, open and log in to Grafana by following the instructions given in the
Acess Grafana section of chapter 2.
Once logged in, hover over the fourth icon in the left menu,
dashboards, and click on + New dashboard.
Click on Add a new panel, which will redirect you to the edit panel view.
Next, we’ll retrieve OPC-UA data from TimescaleDB. Before moving forward, ensure that the
UMH TimescaleDB data source is selected; it should be the default choice.
We’ll show you how to run queries with both the Builder mode (a graphical query builder) and the
Code mode (a code editor to write RAW SQL). Let’s begin with the graphical approach.
Let’s query all value, timestamp and name columns from the tag table. For some guidance, refer to the
image below.
Click on the Run Query button located next to the Builder/Code modes switcher.
You should now see a time series graph based on the query you just ran. The Builder mode is a great way to get
started, but it has its limitations. For more complex use cases, we recommend using the Code mode, which we’ll
cover in the next steps.
Open the code editor by switching from Builder to Code.
Now we’ll run a slightly more complex query. We’ll retrieve the same columns as before, but this time only for a
specific asset.
There are a few things to unpack here, so let’s break it down:
time_bucket is a TimescaleDB function that groups data into time intervals. The first argument is the
interval, which is set to $__interval to match the time range selected in the Grafana dashboard (1m, 6h, 7d, etc). The second
argument is the column to group by, which is timestamp, as defined in our data model.
The table we’re querying is tag, this varies depending on the tag’s data type, find more information in the data
model linked above.
The asset_id is retrieved using the get_asset_id function, which is a custom plpgsql function we provide to
simplify the process of querying tag data from a specific asset. Click here for more examples.
$__timeFilter is a Grafana function that filters the data based on a given time range. It receives one
argument, which is the column to filter by, in our case timestamp.
Finally, we group the data by time (timestamp alias), name, and value, and order it by time in descending order to display the most recent data first.
You can also select the desired tag in the Tag Browser of the Management Console, and directly copy the provided
SQL query from there.
Same as before, click on the Run Query button to execute the query. If you’ve been following along, you won’t
see any noticeable changes, since we only have one asset in our database.
Feel free to experiment with different queries to get a better feel for the data model.
Next, you can customize your dashboard. On the right side, you’ll find various
options, such as specifying units or setting thresholds. Playaround until it
suits your needs.
Once you’re done making adjustments, click on the blue Apply button in the
top right-hand corner to save the panel and return to the overview.
Congratulations, you have created your first Grafana dashboard, and for now it
should look similar to the one below.
What’s next?
The next topic is Moving to Production where we will explain what it
means to move the umh to a manufacturing environment.
Click here to proceed.
5 - 5. Moving to Production
Move the United Manufacturing Hub to production.
This chapter involves deploying the United Manufacturing Hub (UMH) on a virtual machine or an edge device, allowing you to connect with your production assets. However, we recognize the importance of familiarizing yourself with the United Manufacturing Hub beforehand. Feel free to delve deeper into our product, explore the specifics of local installation, or proceed with the production deployment. The guide below will kickstart your UMH journey in a production setting.
Check out our community
We are quite active on GitHub and Discord.
Feel free to join our community, introduce yourself and share your best-practices and experiences.
Learn more about the United Manufacturing Hub
If you like reading more about its features and architecture, check out the
following chapters:
Features to understand the capabilities of the United
Manufacturing Hub and learn how to use them.
Architecture to learn what is behind the United
Manufacturing Hub and how everything works together.
Ready to transition to production? Continue reading to discover how to install UMH and seamlessly connect multiple machines to your instance.
Set up your first instance and connect to a few machines
If you want to get a first impression of the UMH in a production environment, connecting to machines on your shop floor, follow these steps:
1. Choose an Edge Device or VM (Recommended: VM)
Before starting the installation process, decide whether to use virtual machine (VM), or a generic server or edge device. For ease of setup, we recommend using a VM. Ensure that the selected device has network access to the machines.
2. Select Machines with OPC UA for Testing
For testing purposes, it’s recommended to use machines with OPC UA. If your machines use other protocols, consider Node-RED as an alternative for data connection. Check the list of supported protocols and how to connect them to Node-RED.
3. Installation Process
The installation is well documented in the first chapter. But here’s a quick overview:
Click on the + Add Instance button in the instance dashboard of the Management Console, redirecting you to the installation process page.
Select the Install UMH Only option, redirecting you to the install command generation page.
Finally, follow the provided instructions to set up your instance. If everything went well, there should be a button at the bottom right corner
of the page, redirecting you back to the instance dashboard.
4. Network Configuration
Once your UMH instance is up and running, ensure it is placed in the same network as your machines. Additionally, verify that the device running the Management Console is also within the same network.
While basic management and monitoring with the Management Console don’t necessarily demand extensive network configuration, it’s important to note that various open-source tools integrated into UMH do.
Therefore, to take full advantage of the UMH, ensure that you can reach the IP of the server to access Grafana or Node-RED, and that the connection is not blocked by a firewall.
5. Configure Connections and Data Sources
The connections and data sources setup is documented in detail in the third chapter. But here’s a quick overview for OPC UA:
Assuming you have a selected instance running, navigate to the Data Connections tab and click on the + Add Connection button.
Click on the OPC UA Server option, redirecting you to the OPC UA connection setup page.
Follow the provided instructions, test the connection, and if succesful you’ll be able to deploy it.
Once successfully deployed and back to the Data Connections tab, you’ll see the new connection under Uninitialized Connections.
To initialize it, navigate to Data Sources > Uninitialized Connections, redirecting you to the data source setup page.
Again, follow the provided instructions. If you’re having trouble, refer to the more detailed guide.
Once successfully deployed and back to the Data Sources tab, you’ll see it under Data Sources.
Congratulations! Your OPC UA connection and data source are now configured, and your UMH instance is ready to gather valuable insights from your machines.
6. Alternative Protocols
The previous step exclusively covered OPC UA. If your machines use protocols other than OPC UA, we recommend exploring Node-RED as a versatile solution for connecting and gathering data.
You can use it to generate a new dataflow by using your machine’s data as input. This collected data can even be used in other tools, such as building a dashboard in Grafana.
If you encounter any issues, feel free to ask for help on our Discord channel.
Play around with it locally
If you want to get a first impression of the UMH in a local environment, we recommend checking out the following topics:
Grafana Canvas
If you’re interested in creating visually appealing Grafana dashboards, you
might want to try Grafana-Canvas. In our previous
blog article,
we explained why Grafana-Canvas is a valuable addition to your standard
Grafana dashboard. If you’d like to learn how to build one, check out our
tutorial.
OPC/UA-Simulator
If you want to get a good overview of how the OPC/UA protocol works and how to
connect it to the UMH, the OPC/UA-simulator is a useful tool. Detailed
instructions can be found in
this guide.
PackML-Simulator
For those looking to get started with PackML, the PackML Simulator is another
helpful simulator. Check out our
tutorial
on how to create a Node-RED flow with PackML data.
Benthos
Benthos is a highly scalable data manipulation and IT connection tool.
If you’re interested in learning more about it, check out our
tutorial.
Kepware
At times, you may need to connect different, older protocols. In such cases,
KepwareServerEx can help bridge the gap between these older protocols and the
UMH. If you’re interested in learning more, check out our
tutorial.
Deployment to production
Ready to go to production? Go install it!
Follow our step-by-step
tutorial
on how to install the UMH on an edge device or an virtual machine using
Flatcar. We’ve also written a blog article explaining why we use Flatcar
as the operating system for the industrial IoT, which you can find
here.
Make sure to check out our
advanced production guides,
which include detailed instructions on how to secure your setup and how to
best integrate with your infrastructure.