3D representation

Prerequisites

Before you begin, make sure you have the following:

• A container manager: Currently tested on Docker and ContainerD.
• Access to a Kubernetes (recommended) or K3s cluster.
• kubectl installed and properly configured.

Deploy

To integrate OpenTwins with a 3D representation using Unity, you need to add a specific plugin to Grafana. For more details on its functionality and how it connects with other components, refer to the architecture section.

info

This plugin only displays 3D models developed in Unity and exported as WebGL. It does not support model development. To create or modify 3D models, you need to install Unity.

Unity panel plugin for Grafana

The code of this plugin can be found in his repository and the latest version of the plugin will always be compiled in a zip file as a release.

The installation of the Unity plugin in Grafana will depend on how Grafana was installed and the version you are using. Below, we explain the process for installations done via Helm and for local installations. However, it is highly recommended to check the official Grafana documentation for detailed instructions on plugin installation, as there may be specific variations depending on your environment or version.

Helm

To install the plugin you need to add its compiled code in a folder with the same name as its ID inside the Grafana plugins folder, which is /var/lib/grafana/plugins by default. For Helm-based deployments, you can achieve this by adding an extraInitContainer to your values.yaml file. This container will navigate to the plugins folder, download the latest release zip file, and unzip it.

Below is the necessary configuration:

danger

Some keys may overlap with existing ones in your values.yaml file. Do not copy and paste blindly, merge them carefully.

values.yaml

extraInitContainers:
- name: install-opentwins-plugins
  image: busybox
  command:
    - /bin/sh
    - -c
    - |
      #!/bin/sh
      set -euo pipefail
      mkdir -p /grafana-storage/plugins
      cd /grafana-storage/plugins
      wget --no-check-certificate -O ertis-unity-panel.zip https://github.com/ertis-research/grafana-panel-unity/releases/download/latest/ertis-unity-panel.zip
      unzip -o ertis-unity-panel.zip
      rm ertis-unity-panel.zip
  volumeMounts:
  - name: storage
    mountPath: /grafana-storage

Since the plugin is currently unsigned, you need to explicitly allow its use in Grafana by adding its ID (ertis-unity-panel) to the list of unsigned plugins in your values.yaml file. This step ensures Grafana recognizes the plugin; otherwise, it will not appear in the UI. Below is what you need to add (note that if you have followed the manual installation of the essential functionality you should already have it configured.).

values.yaml

grafana.ini:
  plugins:
    allow_loading_unsigned_plugins: ertis-opentwins,ertis-unity-panel

Once this is configured, update the Grafana Helm deployment:

helm upgrade grafana grafana/grafana -n opentwins --version 8.5.0 -f values.yaml

Verify that the Grafana pod is in Running and Ready state. The Unity panel plugin should now be available in Grafana as a panel type.

Local

To install the plugin on a locally hosted Grafana instance, follow these steps:

1. Download the zip file of the latest plugin release.

2. Locate the Grafana configuration file on your system. Refer to the Grafana documentation to find its exact location, name, and how to modify it.

3. Open the configuration file and uncomment/add the following:

[plugins]
# Enter a comma-separated list of plugin identifiers to identify plugins to load even if they are unsigned. Plugins with modified signatures are never loaded.
allow_loading_unsigned_plugins = ertis-unity-panel

4. In the same configuration file, check or modify the path to the plugins folder (see Grafana documentation).

5. Navigate to the plugins folder and extract the downloaded zip file. Ensure the extracted folder is named ertis-unity-panel and contains the correct structure (no intermediate folders).

6. Restart Grafana for the changes to take effect. Consult the Grafana restart guide for specific instructions based on your operating system.

The Unity panel plugin should now be available as a panel type in Grafana.

Connect

This plugin does not require any additional configuration to connect. It should be available in Grafana's plugin list and as an option in the plugin types when creating a panel in a dashboard.