united-manufacturing-hub · DaruZero · Mar 14, 2023 · Mar 14, 2023 · Mar 14, 2023 · Mar 14, 2023
@@ -0,0 +1,19 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+content_type: grafana-plugin
+description: |
+The technical documentation of the {{ .Name }} plugin,
+which
+weight: 0
+---
+
+<!-- overview -->
+
+<!-- body -->
+
+<!-- Add the prerequisites section only if needed -->
+## {{% heading "prerequisites" %}}
+
+## {{% heading "howitworks" %}}
+
+## {{% heading "configuration" %}}
@@ -155,6 +155,7 @@ div.notices {
   margin: 2rem 0;
   position: relative;
   min-height: 100px;
+  max-width: 80%;
 }
 div.notices p {
     padding: 20px;

@@ -78,6 +78,7 @@ section = ["HTML"]
 copyright = "UMH Systems GmbH"
 privacy_policy = "https://www.umh.app/data-security"
 favicon = "favicon.png"
+custom_css = ["css/copy-button.css"]
 # First one is picked as the Twitter card image if not set on page.
 # images = ["images/project-illustration.png"]
 
@@ -108,6 +109,9 @@ archived_version = false
 # point people to the main doc site.
 url_latest_version = "https://umh.docs.umh.app"
 
+# See codenew shortcode
+githubWebsiteRaw = "raw.githubusercontent.com/united-manufacturing-hub/umh.docs.umh.app"
+
 # Repository configuration (URLs for in-page links to opening issues and suggesting changes)
 github_repo = "https://github.com/united-manufacturing-hub/umh.docs.umh.app"
 # An optional link to a related project repo. For example, the sibling repository where your product code lives.

@@ -153,7 +153,9 @@ The data between both brokers is bridged automatically using the mqtt-to-kafka m
 
 If you're curious about the benefits of this dual approach to MQTT/Kafka, check out our blog article about [Tools & Techniques for Scalable Dataprocessing in Industrial IoT](https://learn.umh.app/blog/tools-techniques-for-scalable-data-processing-in-industrial-iot/).
 
-<!-- For more information on the Unified Namespace feature and how to use it, check out our documentation. -->
+{{% notice tip %}}
+For more information on the Unified Namespace feature and how to use it, check out the detailed description of the [Unified Namespace feature](/docs/features/unified-namespace/).
+{{% /notice %}}
 
 ### Microservices
 - [HiveMQ](/docs/architecture/microservices/core/mqtt-broker/) is an MQTT broker used for receiving data from IoT devices on the shop floor. It excels at handling large numbers of unreliable connections.
@@ -166,6 +168,9 @@ If you're curious about the benefits of this dual approach to MQTT/Kafka, check
 
 The United Manufacturing Hub stores events according to our [datamodel](/docs/architecture/datamodel/). These events are automatically stored in TimescaleDB, an open-source time-series SQL database. From there, you can access the stored data using Grafana, a visualization and analytics software. With Grafana, you can perform on-the-fly data analysis by executing simple min, max, and avg on tags, or extended KPI calculations such as OEE. These calculations can be selected in the umh-datasource microservice.
 
+{{% notice tip %}}
+For more information on the Historian or Analytics feature and how to use it, check out the detailed description of the [Historian feature](/docs/features/historian/) or the [Analytics features](/docs/features/analytics/).
+{{% /notice %}}
 ### Microservices
 - [kafka-to-postgresql](/docs/architecture/microservices/core/kafka-to-postgresql/) stores data in selected topics from the Kafka broker in a PostgreSQL compatible database such as TimescaleDB.
 - [TimescaleDB](/docs/architecture/microservices/core/database/), which is an open-source time-series SQL database 

@@ -30,8 +30,8 @@ topics in the Topics tab.
 
 - Deployment: `{{< resource type="deployment" name="kafkaconsole" >}}`
 - Service:
-  - Internal ClusterIP: `{{< resource type="service" name="kafkaconsole" >}}` at
-    port 8080
+  - External LoadBalancer: `{{< resource type="service" name="kafkaconsole" >}}` at
+    port 8090
 - ConfigMap: `{{< resource type="configmap" name="kafkaconsole" >}}`
 - Secret: `{{< resource type="secret" name="kafkaconsole" >}}`
 

@@ -26,14 +26,14 @@ different microservices and forwarding them to the
 - StatefulSet: `{{< resource type="statefulset" name="mqttbroker" >}}`
 - Service:
   - Internal ClusterIP:
-    - Generic: `{{< resource type="service" name="mqttbroker" >}}` at
-      port 1883 (MQTT) and 8883 (MQTT over TLS)
     - HiveMQ local: `{{< resource type="service" name="mqttbroker-hivemq-local" >}}` at
       port 1883 (MQTT) and 8883 (MQTT over TLS)
     - VerneMQ (for backwards compatibility): `{{< resource type="service" name="mqttbroker-verne" >}}` at
       port 1883 (MQTT) and 8883 (MQTT over TLS)
     - VerneMQ local (for backwards compatibility): `{{< resource type="service" name="mqttbroker-verne-local" >}}` at
       port 1883 (MQTT) and 8883 (MQTT over TLS)
+  - External LoadBalancer: `{{< resource type="service" name="mqttbroker" >}}` at
+    port 1883 (MQTT) and 8883 (MQTT over TLS)
 - ConfigMap:
   - Configuration: `{{< resource type="configmap" name="mqttbroker-config" >}}`
   - Credentials: `{{< resource type="configmap" name="mqttbroker-credentials" >}}`

@@ -2,8 +2,8 @@
 title: "Factoryinput-panel"
 content_type: task
 description: |
-    This page has the technical documentation of the microservice factoryinput-panel, which allows for easy execution of MQTT messages inside the UMH stack from a Grafana panel.
-weight: 9000
+    This page contains the technical documentation of the plugin factoryinput-panel, which allows for easy execution of MQTT messages inside the UMH stack from a Grafana panel.
+weight: 3000
 ---
 
 {{% notice warning %}}

@@ -0,0 +1,59 @@
+---
+title: "Umh Datasource V2"
+content_type: grafana-plugin
+description: |
+    This page contains the technical documentation of the umh-datasource-v2 plugin,
+    which allows for easy data extraction from factoryinsight.
+weight: 1000
+---
+
+<!-- overview -->
+
+The plugin, **umh-datasource-v2**, is a Grafana data source plugin that allows you to fetch
+resources from a database and build queries for your dashboard.
+
+<!-- body -->
+
+## {{% heading "howitworks" %}}
+
+1. When creating a new panel, select **umh-datasource-v2** from the Data source drop-down menu. It will then fetch the resources
+   from the database. The loading time may depend on your internet speed.
+
+   ![selectingDatasource](/images/grafana-plugins/grafanaPluginsSelectingV2.png/?width=85%)
+
+2. Select the resources in the cascade menu to build your query. **DefaultArea** and **DefaultProductionLine** are placeholders
+   for the future implementation of the new data model.
+
+   ![selectingDatasource](/images/grafana-plugins/grafanaPluginsSelectingWorkCell.png/?width=85%)
+
+3. Only the available values for the specified work cell will be fetched from the database. You can then select which data value you want to query.
+
+   ![selectingDatasource](/images/grafana-plugins/grafanaPluginsSelectingValue.png/?width=85%)
+
+4. Next you can specify how to transform the data, depending on what value you selected.
+   For example, all the custom tags will have the aggregation options available. For example if you query a **processValue**:
+   - **Time bucket**: lets you group data in a time bucket
+   - **Aggregates**: common statistical aggregations (maximum, minimum, sum or count)
+   - **Handling missing values**: lets you choose how missing data should be handled
+
+   ![selectingDatasource](/images/grafana-plugins/grafanaPluginsSelectingOptions.png/?width=85%)
+
+## {{% heading "configuration" %}}
+
+1. In Grafana, navigate to the Data sources configuration panel.
+
+   ![selectingConfiguration](/images/grafana-plugins/grafanaPluginsConfigurationPanel.png/?width=15%)
+
+2. Select **umh-v2-datasource** to configure it.
+
+   ![selectingConfiguration](/images/grafana-plugins/grafanaPluginsSelectingConfiguration.png/?width=85%)
+
+3. Configurations:
+    - Base URL: the URL for the factoryinsight backend. Defaults to `http://{{< resource type="service" name="factoryinsight" >}}/`.
+    - Enterprise name: previously **customerID** for the old datasource plugin. Defaults to **factoryinsight**.
+    - API Key: authenticates the API calls to factoryinsight.
+      Can be found with UMHLens by going to Secrets → {{< resource type="secret" name="factoryinsight" >}} → apiKey. It should follow the format `Basic xxxxxxxx`.
+
+   ![selectingConfiguration](/images/grafana-plugins/grafanaPluginsConfuguringDatasourceV2.png/?width=85%)
+
+   {{< resource type="grafanaplugin" name="baseurlfactoryinsight" >}}
@@ -1,44 +1,46 @@
-+++
-title = "umh-datasource"
-menuTitle = "umh-datasource"
-chapter = false
-weight = 5
-draft = false
-description = "The technical documentation of the microservice umh-datasource, which allows for easy data extraction from factoryinsight."
-+++
+---
+title: "Umh Datasource"
+content_type: grafana-plugin
+description: |
+    This page contains the technical documentation of the plugin umh-datasource, which allows for easy data extraction from factoryinsight.
+weight: 2000
+---
 
-UMH Datasource provides a Grafana 8.X compatible plugin, allowing easy data extraction from the UMH factoryinsight microservice.
+<!-- overview -->
 
-## Get started
+{{% notice warning %}}
+We are no longer maintaining this microservice. Use instead our new microservice datasource-v2 for data extraction from factoryinsight.
+{{% /notice %}}
 
-For development, the steps to build the plugin from source are described here. 
+The **umh datasource** is a Grafana 8.X compatible plugin, that allows you to fetch resources from a database
+and build queries for your dashboard.
 
-1. Clone the datasource repository `[email protected]:united-manufacturing-hub/united-manufacturing-hub-datasource.git`
+<!-- body -->
 
-2. Install dependencies
+## {{% heading "howitworks" %}}
 
-```bash
-yarn install
-```
+1. When creating a new panel, select **umh-datasource** from the Data source drop-down menu. It will then fetch the resources
+   from the database. The loading time may depend on your internet speed.
 
-3. Build plugin in development mode or run in watch mode
+   ![selectingDatasource](/images/grafana-plugins/grafanaPluginsSelectingV1.png/?width=85%)
 
-```bash
-yarn dev
-```
+2. Select your query parameters **Location**, **Asset** and **Value** to build your query.
 
-4. Build plugin in production mode (not recommended due to [Issue 32336](https://github.com/grafana/grafana/issues/32336)).
-```bash
-yarn build
-```
-5. Move the resulting dis folder in your Grafana plugins directory.
+   ![selectingDatasource](/images/grafana-plugins/grafanaPluginsSelectingValuesV1.png/?width=85%)
 
-- Windows: `C:\Program Files\GrafanaLabs\grafana\data\plugins`
-- Linux: `/var/lib/grafana/plugins`
+## {{% heading "configuration" %}}
 
-6. Rename the folder to umh-datasource.
+1. In Grafana, navigate to the Data sources configuration panel.
 
-7. Enable the [enable development mode](https://grafana.com/docs/grafana/latest/administration/configuration/) to load unsigned plugins.
+   ![selectingConfiguration](/images/grafana-plugins/grafanaPluginsConfigurationPanel.png/?width=15%)
 
-8. restart your Grafana service.
+2. Select **umh-datasource** to configure it.
 
+   ![selectingConfiguration](/images/grafana-plugins/grafanaPluginsSelectingConfiguration.png/?width=85%)
+3. Configurations:
+    - Base URL: the URL for the factoryinsight backend. Defaults to `http://{{< resource type="service" name="factoryinsight" >}}/`.
+    - Enterprise name: previously **customerID** for the old datasource plugin. Defaults to **factoryinsight**.
+    - API Key: authenticates the API calls to factoryinsight.
+      Can be found with UMHLens by going to Secrets → {{< resource type="secret" name="factoryinsight" >}} → apiKey. It should follow the format `Basic xxxxxxxx`.
+
+   ![selectingConfiguration](/images/grafana-plugins/grafanaPluginsConfiguringDatasourceV1.png/?width=85%)
@@ -21,6 +21,9 @@ After you add a new file with a code snippet in the `examples` directory, you ca
 reference it in your documentation using the `codenew` shortcode with the `file`
 parameter set to the path to the file, relative to the `examples` directory.
 
+A *Copy* button is automatically added to the code snippet. When the user clicks
+the button, the code is copied to the clipboard.
+
 Here's an example:
 
 ```go-html-template

@@ -0,0 +1,7 @@
++++
+title = "Features"
+menuTitle = "Features"
+description = "Do you want to understand the capabilities of the United Manufacturing Hub, but do not want to get lost in technical architecture diagrams? Here you can find all the features explained on few pages."
+weight = 1500
++++
+
@@ -0,0 +1,76 @@
++++
+title = "Shopfloor KPIs / Analytics"
+menuTitle = "Shopfloor KPIs / Analytics"
+description = "The Shopfloor KPI/Analytics feature of the United Manufacturing Hub provides equipment-based KPIs, configurable dashboards, and detailed analytics for production transparency. Configure OEE calculation and track root causes of low OEE using drill-downs. Easily ingest, process, and analyze data in Grafana."
+weight = 3
++++
+
+The Shopfloor KPI / Analytics feature of the United Manufacturing Hub provides a configurable and plug-and-play approach to create "Shopfloor Dashboards" for production transparency consisting of various KPIs and drill-downs.
+
+![](/images/features/analytics/grafana-canvas.png?width=50%)
+![](/images/features/analytics/oee-dashboard.png?width=50%)
+
+{{% notice tip %}}
+Click on the images to enlarge them. More examples can be found in this [YouTube video](https://www.youtube.com/watch?v=n3roOntfsgI) and in our [community-repo on GitHub](https://github.com/united-manufacturing-hub/community-repo). 
+{{% /notice %}}
+
+## When should I use it?
+
+If you want to create production dashboards that are highly configurable and can drill down into specific KPIs, the Shopfloor KPI / Analytics feature of the United Manufacturing Hub is an ideal choice. This feature is designed to help you quickly and easily create dashboards that provide a clear view of your shop floor performance. 
+
+## What can I do with it?
+
+The Shopfloor KPI / Analytics feature of the United Manufacturing Hub allows you to:
+
+### Query and visualize
+
+In Grafana, you can:
+
+- Calculate the OEE (Overall Equipment Effectiveness) and view trends over time
+    - Availability is calculated using the formula `(plannedTime - stopTime) / plannedTime`, where `plannedTime` is the duration of time for all machines states that do not belong in the Availability or Performance category, and `stopTime` is the duration of all machine states configured to be an availability stop.
+    - Performance is calculated using the formula `runningTime / (runningTime + stopTime)`, where `runningTime` is the duration of all machine states that consider the machine to be running, and `stopTime` is the duration of all machine states that are considered a performance loss. Note that this formula does not take into account losses caused by letting the machine run at a lower speed than possible. To approximate this, you can use the LowSpeedThresholdInPcsPerHour configuration option (see further below).
+    - Quality is calculated using the formula `good pieces / total pieces`
+- Drill down into stop reasons (including histograms) to identify the root-causes for a potentially low OEE.
+- List all produced and planned orders including target vs actual produced pieces, total production time, stop reasons per order, and more using job and product tables.
+- See machine states, shifts, and orders on timelines to get a clear view of what happened during a specific time range.
+- View production speed and produced pieces over time.
+
+### Configure
+
+In the database, you can configure:
+
+- **Stop Reasons Configuration:** Configure which stop reasons belong into which category for the OEE calculation and whether they should be included in the OEE calculation at all. For instance, some companies define changeovers as availability losses, some as performance losses. You can easily move them into the correct category.
+- **Automatic Detection and Classification:** Configure whether to automatically detect/classify certain types of machine states and stops:
+    - **AutomaticallyIdentifyChangeovers:** If the machine state was an unspecified machine stop (UnknownStop), but an order was recently started, the time between the start of the order until the machine state turns to running, will be considered a Changeover Preparation State (10010). If this happens at the end of the order, it will be a Changeover Post-processing State (10020).
+    - **MicrostopDurationInSeconds:** If an unspecified stop (UnknownStop) has a duration smaller than a configurable threshold (e.g., 120 seconds), it will be considered a Microstop State (50000) instead. Some companies put small unknown stops into a different category (performance) than larger unknown stops, which usually land up in the availability loss bucket.
+    - **IgnoreMicrostopUnderThisDurationInSeconds:** In some cases, the machine can actually stop for a couple of seconds in routine intervals, which might be unwanted as it makes analysis difficult. One can set a threshold to ignore microstops that are smaller than a configurable threshold (usually like 1-2 seconds).
+    - **MinimumRunningTimeInSeconds:** Same logic if the machine is running for a couple of seconds only. With this configurable threshold, small run-times can be ignored. These can happen, for example, during the changeover phase.
+    - **ThresholdForNoShiftsConsideredBreakInSeconds**: If no shift was planned, an UnknownStop will always be classified as a NoShift state. Some companies move smaller NoShift's into their category called "Break" and move them either into Availability or Performance.
+    - **LowSpeedThresholdInPcsPerHour**: For a simplified performance calculation, a threshold can be set, and if the machine has a lower speed than this, it could be considered a LowSpeedState and could be categorized into the performance loss bucket.
+- **Language Configuration:** The language of the machine states can be configured using the languageCode configuration option (or overwritten in Grafana).
+
+{{% notice tip %}}
+You can find the configuration options in the [configurationTable](/docs/architecture/datamodel/database/configurationtable/)
+{{% /notice %}}
+
+
+## How can I use it?
+
+Using it is very easy:
+1. Send messages according to the [UMH datamodel](/docs/architecture/datamodel/) to the [Unified Namespace](/docs/features/unified-namespace/) (similar to the [Historian feature](/docs/features/historian/))
+2. Configure your OEE calculation by adjusting the configuration table
+3. Open Grafana, select your equipment and select the analysis you want to have. More information can be found in the [umh-datasource-v2](/docs/architecture/microservices/grafana-plugins/umh-datasource-v2/).
+
+For more information about what exactly is behind the Analytics feature, check out our [our architecture page](/docs/architecture/) and [our datamodel](/docs/architecture/datamodel/)
+
+## What are the limitations?
+
+At the moment, the limitations are:
+- Speed losses in Performance are not calculated and can only be approximated using the LowSpeedThresholdInPcsPerHour configuration option
+- There is no way of tracking losses through reworked products. Either a product is scrapped or not.
+
+## Where to get more information?
+- Learn more about the benefits of using open-source databases in our blog article, [Historians vs Open-Source databases - which is better?](https://learn.umh.app/blog/historians-vs-open-source-databases-which-is-better/)
+- Learn more about the United Manufacturing Hub's architecture by visiting [our architecture page](/docs/architecture/).
+- Learn more about the datamodel by visiting [our datamodel](/docs/architecture/datamodel/)
+- To build visual dashboards, [check out our tutorial on using Grafana Canvas](https://learn.umh.app/blog/building-shopfloor-dashboards-with-the-united-manufacturing-hub-and-grafana-canvas/)