Merge pull request #135 from IBM/add_opcua_lab

Ready for first release

MkDocs/monitor_managed_gw_modbus_9.0/mkdocs.yml

@@ -1,7 +1,7 @@
 site_name: Monitor Managed Gateway Lab
 site_url: https://ibm.github.io/maximo-labs/
 site_author: Jan Ekstrøm
-site_description: "Maximo Monitor Monitor Managed Gateway Hands on Lab"
+site_description: "Maximo Monitor Managed Gateway Modbus Lab"
 site_dir: ../../site/monitor_managed_gw_modbus_9.0
 
 nav:

MkDocs/monitor_managed_gw_opcua_9.0/docs/add_device.md

@@ -0,0 +1,50 @@
+# Objectives
+In this Exercise you will learn how to add a device to the Device library.
+
+---
+*Before you begin:*  
+This Exercise requires that you have:
+
+1. completed the pre-requisites required for [all labs](prereqs.md)
+2. completed the previous exercises
+
+---
+
+Since PLC's are very customizable you will need to add a new device to the Device library instead of using a pre-configured device in the Device library, like a Variable frequency Drive communicating over Modbus.</br>
+
+Navigate to the Device library setup page:</br>
+![Navigate to Device library](img/add_device_01.png)</br></br>
+
+For OPC UA devices it is possible to either upload a device configuration or to use the built-in data tag autodetection functionality which is a lot easier.</br>
+Select `Add device to library` and the menu item `Scan for devices`:</br>
+![Scan for devices](img/add_device_02.png)</br></br>
+
+Select the OPC-UA protocol:</br>
+![Scan for devices](img/add_device_03.png)</br></br>
+
+Enter the device details and scroll down:</br>
+![Scan for devices](img/add_device_04.png)</br></br>
+
+Copy the Device scan command and don't click `Done` just yet:</br>
+![Scan for devices](img/add_device_05.png)</br>
+
+Open a terminal window (Mac/Linux) or Command window (Windows) and run the Device scan command:</br>
+![Scan for devices execution](img/add_device_06.png)</br></br>
+
+Wait until it has finalized and returned to the command prompt.</br>
+The new device has now been added to the Device library.</br>
+![Scan for devices execution](img/add_device_07.png)</br></br>
+
+Go back to the browser, click `Done`and then `Leave page`:</br>
+![Scan for devices end](img/add_device_08.png)</br></br>
+
+Search for your new device in the Device library:</br>
+![Scan for devices result](img/add_device_09.png)</br></br>
+
+Click on your new device to see the metrics (data tags) that was added to this device:</br>
+![Scan for devices result](img/add_device_10.png)</br>
+Click on `Cancel` once you are done looking at these beautiful data tags 🤗.</br>
+
+
+---
+Congratulations you have successfully added a device to the Device library.</br>

MkDocs/monitor_managed_gw_opcua_9.0/docs/create_gateway.md

@@ -0,0 +1,80 @@
+# Objectives
+In this Exercise you will learn how to create the Managed Gateway in Monitor.
+
+---
+*Before you begin:*  
+This Exercise requires that you have:
+
+1. completed the pre-requisites required for [all labs](prereqs.md)
+2. completed the previous exercises
+
+---
+
+#### Add a Managed Gateway
+
+Login to MAS and navigate to Monitor:
+![MAS Monitor](img/create_gateway_01.png)</br></br>
+
+Expand Setup in the left menu and select Gateways:
+![Create Gateway](img/create_gateway_02.png)</br></br>
+
+!!! note "New in MAS 9.0"
+    Gateways can now be created and managed in the Monitor UI.</br>
+
+
+Select `Add gateway`:
+![Create Gateway](img/create_gateway_03.png)</br></br>
+
+Define the gateway ID `XX_MGT_GW_01` and the gateway Type `XX_MGT_GW`.</br>
+
+!!! tip
+    XX in the gateway ID and Type should be your initials in case other people are following this lab in the same Maximo Application Suite environment.</br>
+
+Make sure the gateway Configuration is Managed and click `Save`:
+![Create Gateway](img/create_gateway_04.png)</br></br>
+
+!!! note "New in MAS 9.0"
+    The Managed Gateway is a new type of gateway introduced in MAS Monitor 9.0.</br>
+    It is an integrated flow in Monitor, which removes/replaces the tedious and error prone manual process of defining an Edge Data Collector Integration in prior versions.</br>
+
+You will now see your new Managed Gateway, including a `Managed` tag in both the list of Gateways as well as in the gateway definition:
+![Create Gateway](img/create_gateway_05.png)</br></br>
+
+!!! note "New in MAS 9.0"
+    Credentials are automatically "baked into" the docker image for the Managed Gateway.</br>
+    This means you no longer have to write down the credentials for this type of gateway and then enter that information manually into the configuration of the Maximo Monitor End-point. This is much more streamlined and eliminate the risk of error when manually entering the credentials.</br>
+    It also means that the credentials will not be presented to you, as you no longer need them.</br>
+
+</br>
+
+#### Add your new device to the Managed Gateway
+
+In the Managed Gateway click on `Add device`:</br>
+![Add device](img/create_gateway_06.png)</br></br>
+
+Since this is a Managed Gateway the `Use device library` is automatically selected, as it is only possible to use devices from the Device library.</br>
+Just click on Continue 🤗</br>
+![Add device](img/create_gateway_07.png)</br></br>
+
+Search for Siemens in the Manufacturer list:</br>
+![Add device](img/create_gateway_08.png)</br></br>
+
+Then search for S7 devices in the long list of Siemens devices - select you newly added device under `S7 OPC-UA Server`, and click `Next`:</br>
+![Add device](img/create_gateway_09.png)</br></br>
+
+Add the OPC UA server IP Address and Port, and click `Next`:</br>
+![Add device](img/create_gateway_10.png)</br></br>
+
+Define the Device type and Device ID (using your initials instead of XX), and click `Next`:</br>
+![Add device](img/create_gateway_11.png)</br></br>
+
+Set the Data frequency to 30000 ms (30 seconds) and select the following 7 data tags to be used as metrics in Monitor. Once done click `Save`:</br>
+![Add device](img/create_gateway_12.png)</br></br>
+
+You will now see your new added device being a part of your new Managed gateway:</br>
+![Add device](img/create_gateway_13.png)</br></br>
+
+
+
+---
+Congratulations you have successfully created the Managed Gateway in Monitor and added an instance of the newly added device in the Device library.</br>

MkDocs/monitor_managed_gw_opcua_9.0/docs/deploy.md

@@ -0,0 +1,86 @@
+# Objectives
+In this Exercise you will learn how to:
+
+* Deploy the Managed Gateway
+* Verify connectivity and data inflow
+
+---
+*Before you begin:*  
+This Exercise requires that you have:
+
+1. completed the pre-requisites required for [all labs](prereqs.md) and for this exercise
+2. completed the previous exercises
+3. verified the simulator is running as described in [exercise 1](setup_simulator.md){target=_blank}
+
+---
+
+#### Deploy the Managed Gateway
+
+While looking at your Managed Gateway in the Gateways list,</br>
+press the `View deployment instructions`. </br>
+Click on the docker command to copy it to the clipboard:
+![Deployment Guide](img/deploy_verify_01.png)</br></br>
+
+Open a terminal window (Mac/Linux) or Command window (Windows) where you want to run the Managed Gateway and then paste the docker command line from the clipboard.</br>
+Click enter to execute it, and you should see something similar to the following:
+![Start EDC edge](img/deploy_verify_02.png)</br></br>
+
+#### Verify connection and data flowing into IoT Tool
+
+Navigate to the IoT Tool from the App Switcher in the upper right hand corner or from the main home page:
+![Navigate to IoT Tool](img/deploy_verify_03.png)</br></br>
+
+Since the gateway and the devices uses the same prefix, then it is easy to search for them.</br>
+Verify the gateway `XX_MGT_GW_01` is in Connected state and the device `XX_OPC_UA_Server_01` is in disconnected state.
+![EDC devices in IoT Tool](img/deploy_verify_04.png)</br></br>
+
+!!! tip
+    The devices belonging to the gateway will always be in Disconnected state, as they receive their data through the gateway.
+
+!!! note "New in MAS 9.0"
+    Both the Managed Gateway and the OT Devices have been created by the Monitor UI when creating the Managed Gateway and adding the OT Devices, i.e. the devices will no longer be created by the gateway when data have been collected as in previous versions.
+
+Select the simulated Siemens S7 OPC UA Server and navigate to `Recent Events`.</br>
+Wait for a couple of minutes (you know those 30000ms defined when adding the device) until you see the first messages coming through:
+![View device in Connect](img/deploy_verify_05.png)</br></br>
+
+Click on the last received payload: and see the data points that you selected when adding the device to the Device library:
+![View device payload in Connect](img/deploy_verify_06.png)</br></br>
+
+And see the data points that was selected being send on the status event type:
+
+``` json
+{
+	"timestamp": "2024-10-21T15:15:52.662245Z",
+	"opcplc-telemetry-anomaly-dipdata": -84.4327925502015,
+	"opcplc-telemetry-anomaly-negativetrenddata": -210.39999999999998,
+	"opcplc-telemetry-anomaly-positivetrenddata": 410.5,
+	"opcplc-telemetry-anomaly-spikedata": -84.4327925502015,
+	"opcplc-telemetry-basic-alternatingboolean": false,
+	"opcplc-telemetry-basic-randomsignedint32": -1944417017,
+	"opcplc-telemetry-basic-randomunsignedint32": 2131461779
+}
+```
+</br>
+
+#### Verify data flowing into Monitor
+
+Go to the Setup of Device types and search for your device, then click to open it:</br>
+![View device payload in Connect](img/deploy_verify_07.png)</br></br>
+
+!!! note "New in MAS 9.0"
+    You can also see the incoming data directly in Monitor.</br>
+
+
+Select the `Resent event` and wait a little bit:</br>
+![View device payload in Connect](img/deploy_verify_08.png)</br></br>
+
+Click on `View payload` for the last incoming message:</br>
+![View device payload in Connect](img/deploy_verify_09.png)</br>
+and once again you can see tha data flowing.</br></br>
+
+Potentially the stored data could be used in a dashboard for the Siemens S7 device:</br>
+![View device payload in Connect](img/deploy_verify_10.png)</br></br>
+
+---
+Congratulations you have successfully deployed and verified the connectivity and data inflow, and thereby completed this Maximo Lab.</br>

MkDocs/monitor_managed_gw_opcua_9.0/docs/extra.css

@@ -0,0 +1,48 @@
+table {
+  margin-bottom: 2em
+}
+
+table tr th {
+  padding: 5px 10px;
+  background-color: #ddd;
+  border:1px solid #aaa !important
+}
+
+table tr td {
+  padding: 5px 10px;
+  border:1px solid #aaa !important
+}
+
+table tr:nth-child(even) {
+  background-color: #eee;
+}
+
+/* If an unordered list immediately follows a normal paragraph, set negative
+   margin so that it flows better */
+div[role=main] p + ul {
+  margin-top: -20px
+}
+
+/* Ensure we keep the margin if the previous paragraph is an admonition title */
+div[role=main] p.admonition-title + ul {
+  margin-top: 0
+}
+
+img {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.wy-nav-content {
+  max-width: 1200px !important;
+}
+
+.wy-table-responsive table td, .wy-table-responsive table th {
+  white-space: normal !important;
+}
+
+h2 {
+  margin-top: 2em;
+  border-bottom: 2px solid black
+}

MkDocs/monitor_managed_gw_opcua_9.0/docs/index.md

@@ -0,0 +1,40 @@
+# Welcome to the </br>Maximo Monitor Managed Gateway OPC UA Lab
+
+!!! note "New in MAS 9.0"
+    From MAS 9.0 the setup of the Edge Data Collector capability have changed dramatically in order to streamline and simplify the configuration process.</br>
+    This means you will no longer see the `Edge Data Collactor` or `EDC` in the UI, as it has been implemented as a third Gateway type in Monitor, called a Managed Gateway:</br></br>
+    ![Architecture](img/index_01.png)</br></br>
+    Further it is no longer needed to:</br>
+    - create a gateway in the IoT Tool, as that is now done in the Monitor UI</br>
+    - create the device type up front for the devices in the Monitor UI</br>
+    - stick with a fixed device type per canonical model
+
+---
+
+You will learn about how to setup a Managed Gateway within Maximo Monitor.
+
+In this lab you will learn the steps needed to successfully use an OPC UA simulator to act as a Siemens S7 PLC and get the data from the Siemens S7 into Maximo Monitor using a Managed Gateway. .</br></br>
+
+![Architecture](img/index_02.png)</br></br>
+
+
+!!! tip
+    If you want to know more about OPC UA Servers, then go to the [OPC Foundation OPC UA Server page](https://reference.opcfoundation.org/Core/Part1/v104/docs/6.3){target=_blank}
+
+The exercises will cover:
+
+* Setting up the OPC UA simulator
+* Adding a new device to the library by utilizing device scanning
+* Create a Managed Gateway and add the device
+* Verify data flow from Siemens S7 PLC via OPC UA all the way into Maximo Monitor
+* Have fun
+
+!!! note
+    Expected time needed to run the complete lab: 1 hour
+
+
+---
+
+**Updated: 2024-11-07**
+
+---

MkDocs/monitor_managed_gw_opcua_9.0/docs/prereqs.md

@@ -0,0 +1,34 @@
+# Pre-Requisite Instructions
+
+Here are the pre-requisites for the Maximo Monitor Edge Data Collector exercises.  
+
+!!! attention
+    This lab requires Maximo Monitor 9.0 or later.</br>
+    MAS application entitlement must be `Limited` or higher.
+
+# All Exercises
+
+All Exercises require that you have:
+
+1.  A computer with a Chrome or Firefox browser and internet connectivity.
+
+2.  User access to a Maximo Application Suite environment that can create a managed gateways in Monitor. This require:</br>
+o Your user must have access to Monitor and the IoT Tool</br>
+o Your user must have administrator access to Maximo Application Suite.</br>
+Your Exercise facilitator should have provided you with the information on your access.
+
+3.  An IBM ID.  If you don't have an IBM ID you can get one [here](https://www.ibm.com/account/reg/signup?){target=_blank}:<br>
+o Click `Login to MY IBM` button<br>
+o Click `Create an IBM ID` link
+
+4.  Test your access to the Maximo Application Suite environment.
+
+# Exercise 1 and 4
+
+Docker must be running on your local machine while acting as the Managed Gateway instance.</br>
+There are different ways to install the Docker engine depending of the package and the OS.</br>
+One multi platform option is Rancher Desktop. It is fairly easy to install Rancher Desktop,</br>
+as you just have to follow this guide: [Running Docker locally](https://docs.rancherdesktop.io/getting-started/installation/){target=_blank}</br>
+
+!!! tip
+    Podman and Docker Desktop should also work, but I have not tested it.

MkDocs/monitor_managed_gw_opcua_9.0/docs/release_notes.md

@@ -0,0 +1,21 @@
+
+# Contributors to this Maximo Lab
+
+#### Author & Developer:
+
+- Jan Ekstrøm - <[email protected]>
+
+#### Assistance with the OPC UA Simulator:
+
+- Gregorio Guerretta - <[email protected]>
+
+---
+
+# Change Information
+
+|Date     |By             | Description                                           |
+|:--------|:--------------|:------------------------------------------------------|
+|2024-11-07|Jan Ekstrøm|Lab is ready for the first release. |
+
+
+---