Author: Christophe Lucas Last Updated: 23 April 2024
Disclaimer: This tutorial is delivered as-is and is NOT formal IBM product documentation in any way
- Introduction & Overview
- Prerequisites
- Install Ubuntu on VMWare on Mac
- Install MVI Edge
- Integrate MVI Edge with MVI & Monitor
- Configure MVI Edge & Monitor for automated inspections
- Create data items & Dashboard in Monitor - Find Gold !
In this tutorial, you will learn how to:
- install Maximo Visual Inspection Edge (aka MVI Edge) on a Ubuntu VMWare on your Mac
- setup MVI Edge to run in CPU only mode
- integrate MVI Edge with a MAS MVI instance and a MAS Monitor instance
- download and deploy a provided MVI Rock-recognizing TinyYOLO model to your MVI Edge
- setup MVI Edge station and inspections
- run MVI Edge inspections using the provided Rocks_Samples images data set and send inspection results to Monitor
- create data items in Monitor and dashboards to count the amount of Gold found during the inspections
Expected Tutorial Duration: 1st time = 3 hours, 2nd time = 27 minutes.
The following image highlights the main screens that you will encounter while executing this tutorial:

Acronyms used & Product Documentation links: MVI = IBM Maximo Visual Inspection, MVI Edge = IBM Maximo Visual Inspection Edge, Monitor = IBM Maximo Monitor, MAS = IBM Maximo Application Suite.
One can find a story of how this tutorial logic was first used in this article How we built an AI-driven eWaste Visual Inspection Demo Machine.
To complete this tutorial, you will need:
- VMWare Fusion or similar software to create a Ubuntu image
- an IBM ID
- access to an instance of MAS with Administrator access to both MVI and Monitor MAS Applications
- access to the OpenShift Container Platform (OCP) of your MAS instance (to get Monitor's Analytics Service API key & token)
- either an (older) Mac runnning on 'Intel Processor' OR a (newer) Mac running on 'Apple silicon' with VMWare Fusion 13 minimum (see Supported host operating systems for VMware Fusion and VMware Fusion Pro (2088571)).
This tutorial was built using:
- VMWare Fusion 12.2.3 on a Mac (macOS Ventura 13.5.1, Radeon Pro 560X 4 GB Intel UHD Graphics 630 1536 MB)
- Ubuntu 20.04.6 LTS (Focal Fossa)
- Maximo Visual Inspection (aka MVI, 8.8.1) + Maximo Monitor (aka Monitor, 8.10.4) running on Maximo Application Suite (aka MAS 8.10.4) + Maximo Visual Edge (aka MVIE, 8.8)
22 April 2024 Update: This tutorial was run with a later Ubuntu version (22.04.4), and the latest MVI Edge (8.9.0) and MVI (8.9.1) on a MAS 8.11.9 version. Except for some minor UI changes, the steps of this tutorial still work.
21 January 2024 Update: This tutorial was run with a later Ubuntu version (22.04.3), and the latest MVI Edge (8.8.1). Except for some minor UI changes, the same steps still work.
The following image highlights the main screens that you will encounter while executing this section:

Let's first download and install Ubuntu in a VMWare:
- Go to Ubuntu's official release page Ubuntu 20.04.6 LTS (Focal Fossa) and download the ubuntu-20.04.6-desktop-amd64.iso file.
- Launch VMWare Fusion and drag and drop the
.isofile you just downloaded on theInstall from disc or image. ClickContinue. - Enter a password for your VMWare. Click
Continue. - Click
Customize Settingsand changeDisk Sizeto e.g.40 GB- you just want to be on the safe side in case you plan to collect or inspect many and/or heavy images. ClickFinish. It will take up to 5 minutes for Ubuntu to be installed within the VMWare - you will see the progress on the screen. Final screen should be the Ubuntu login page as per bottom-right screen in image above. - In your
Virtual Machine-Network Adaptermenu, selectBridge (Auto Detect). When you launch your VMWare, it should automatically connect to the Wifi your Mac is connected to.
For future usage comfort, let's update a couple of VMWare settings. From the desktop of your Ubuntu VMWare, right-click and selectSettings:
- In the
Date & Timemenu, select your localTime zone. - In the
Displaysmenu, set a comfortableResolutione.g.(1024 x 768). - In the
Privacy - Screen Lockchoose yourAutomatic Screen Lockoption. - Check that you can copy-text/drag-files (from your Mac) and paste-text/drop-files (into a Finder in your Ubuntu VMWare). If not, open a Terminal in your VMWare and run
sudo apt install open-vm-tools-desktopto install VM tools (and restart the VMWare).
The following image highlights the main screens that you will encounter while executing this section:
We are following the Installing Docker® and nvidia-docker2 Procedure - Ubuntu section of the MVI Documentation (select On x86_64 sub section).
Open a Terminal on your VMWare and from your home folder:
- Run
sudo apt-get update. - Run
sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common. - Run
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -. - Run
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable". - Run
sudo apt-get update. - Run
sudo apt-get install docker-ce.
NOTE: Because we will be using MVI Edge in CPU-only mode, it is NOT required to install nvidia-docker2 as per section 2 of the Installing Docker® and nvidia-docker2 Procedure - Ubuntu documentation.
This section is a concatenated mix of the Installing and uninstalling MVI Edge documentation and IBM Maximo Visual Inspection Edge Inception Internals information.
Login to this IBM Cloud Entitlement Key using your IBM ID.
An Entitlement keys(1) page will appear. On the bottom right, just click Copy the key. Paste and save it locally in e.g. a Notebook for further use. We'll call it YOUR_ENTITLEMENT_KEY in future sections and it should look like a long string e.g. JJQk0gTWFya2V0blablablakNWU0Y2.
Open a Terminal in your Ubuntu VMWare and from your home directory:
- Run
mkdir MVIE88, thencd MVIE88/, thenmkdir vision-edgethencd vision-edge/. - From your
/MVIE88/vision-edge/directory, runsudo docker login cp.icr.io --username cp --password YOUR_ENTITLEMENT_KEY. You should get aLogin Succeededat the end of the output. - Run the MVI Edge inception process, i.e. run:
sudo docker run --rm -v `pwd`:/opt/ibm/vision-edge -e hostname=`hostname -f` --privileged -u root cp.icr.io/cp/visualinspection/vision-edge-inception:8.8.0
Observe how that command created the following file structure:
MVIE88/
├── vision-edge/
│ ├── startedge.sh
│ ├── restartedge.sh
│ ├── stopedge.sh
│ ├── volume/
│ │ ├── bin
│ │ ├── data
│ │ ├── run
Under the /MVIE88/vision-edge/volume/run/var/config folder, edit the vision-edge.properties file to set MVI Edge in CPU-only mode.
- Run
sudo gedit vision-edge.properties&(orsudo nano vision-edge.propertiesif gedit not installed). That will open the file. - Locate the
DLE_ENABLE_CPU_FALLBACK=FALSEline and replace it byDLE_ENABLE_CPU_FALLBACK=TRUE. Save.
Under the /MVIE88/vision-edge folder, let's start MVI Edge for the first time:
- Run
sudo ./startedge.sh. WriteYESon License Agreement line (get there quickly by typingq). This can take up to 15 minutes depending on your internet download speed. - Notice how a new
monitordirectory appeared under/MVIE88/vision-edge/volume/run/var/config/after having runstartedge.shfor the first time.
IMPORTANT NOTE: Do not forget to take note of the password for default user masadmin at the end of the output as it is the ONLY time you will see it.
******************************************************************
******************************************************************
- The default username and password are:
- username: masadmin
- password: vp7KE^blabla(K2sf%AW
******************************************************************
******************************************************************
******************************************************************
** **
** PLEASE SAVE THE PASSWORD - IT WILL NOT BE DISPLAYED AGAIN. **
** **
******************************************************************
******************************************************************
Access the console at https://ubuntu
- Launch https://ubuntu in Firefox and check the MVI Edge login page appears. Do not login yet.
Change the default node_prefix (that will be the root name of Monitor Device Types), i.e.:
- Under the
/MVIE88/vision-edge/volume/run/var/config/monitorfolder, Run$sudo gedit monitor.jsonto open the file. - Find the line containing
"node_prefix": "MVI"and change it to e.g."node_prefix": "MVIE88A_". Note that because the value ofnode_prefixis what will appear in front of all Device Types you will later create in Monitor, do NOT choose too-long a name (+ using an underscore_at the end is a good idea). - Under
/MVIE88/vision-edgefolder, runsudo ./restartedge.sh
The following image highlights the main screens that you will encounter while executing this section:

First get your MVI Server endpoint and API Key:
- On MVI Server, click the left
Services - API keymenu. - Copy both the values of
API keyandAPI end pointand save locally.
Then, setup in MVI Edge:
- Login for the first time with ID
masadmintohttps://ubuntu. - On the
Welcome to Maximo Visual Inspectionpage, clickNext. On theMaximo Visual Inspection Settingspage, enter theAPI keyvalue you just copied. For theURLvalue, enter theAPI end pointvalue without the/apiat the end - note that URL is also the URL of your MVI Server homepage - for examplehttps://mygeo.visualinspection.mvimas.gtm-pat.com. ClickSave, wait a second and you should see a green indicator appear next to theAPI keyfield.
First you will need the API Key & Token values of both the Platform Service and Analytics Service of your Monitor instance, as per Monitor APIs instructions.
This requires access to the OpenShift Container Platform (OCP) of your MAS instance.
In summary, to get the API Key & Token of the Analytics Service, do:
- From the OCP console, click
Project. In theSearch by namefield, start typingmas-monitorand locate the 1 e.g.mas-masgeo-monitorProject. Open the Project. - On the
Inventorycard, clickSecrets. Search for and openmonitor-api. - Copy and save
as_apikeyandas_tokenvalues.
In summary, to get the API Key & Token of the Platform Service, do:
- From Monitor's home page, click
Open the Iot Tool. This will open Monitor's Watson IoT Platform. - In the WIoTP tool, click
Appsleft menu. ClickGenerate API keytop right button. Enter a description and setAPI Key ExpirestoOFFthen click Next. From the Role list, selectBackend Trusted Application, then clickGenerate Keybutton. - Copy and save the API key and authentication token that are displayed.
Finally, let's now copy paste those values in MVI Edge:
- Click MVI Edge
Settings - Maximo Monitormenu. - On he
Monitor Dashboard URLfield, enter the homepage URL of your Monitor instance e.g.https://mygeo.monitor.mygeomas.gtm-pat.com/. - On the
Platform ServiceandAnalytics Servicesections, enter the values you saved at start of this section. ClickCreate Connection. - Check that the connection has been well established by verifying that a
Generic Device Typehas been created on theConnectiontab.
NOTE Notice that the Generic Device Type that we just created is also accessible in the Monitor application where, via the Monitor menu, you will now see a new MVIE88A_Generic_Type. THAT is the integration point between MVI Edge and Monitor.
In this section, we will download and deploy a TinyYOLO model that was trained on an MVI server to recognise a set of 9 various rocks moving on a conveyor belt (Calcite, Fluorite, Lepidolite, MilkyQuartz, RoseQuartz, Obsidian, Glass, RedJasper and 1 special rock from Kalgoorlie in Western Australia which contains Gold). We will then download a sample Data Set containing 31 images of those rocks, create an Input Source using it, and import a ready-to-use Inspection.
- Download the following Rocks_TinyYOLOv3.zip MVI Model file, save it. Drag & Drop it from your Mac to within a directory (e.g.
Desktop) on your Ubuntu VMWare. - In MVI Edge
Modelsmenu, clickDrag and drop file here or click to uploadand upload theRocks_TinyYOLOv3.zipfile. Select the Model and clickDeploy. When in statusDeployed, the model is ready to be used. - Download the following Rocks_Samples.zip MVI sample data set, save it. Drag & Drop it from your Mac to within a directory (e.g.
Desktop) on your Ubuntu VMWare. Unzip the file into a folder on your Ubuntu VMWare - note the folder will contain both.jpgand.xmlfiles (containing the inference data associated to the images - disregard). - In MVI Edge
Input Sourcesmenu, clickCreateand selectImage Folder. EnterRocks_Samplein bothFolder NameandInput Source Namefields. ClickSave. Reopen the Input Source. In theAdd filesbox, drag and drop the 31.jpgfiles (disregard the.xmlfiles) that you unzipped in previous step 3. - In MVI Edge
Stationmenu, clickCreate, nameRocks_Station, Save. - Download the following Inspection001.json Inspection Template file, save it.
- Open the
Rocks_Stationand clickDrag and drop file here or click to upload, select theInspection001.json. That will create anInspection001.
Let's now configure the Inspection, then run it.
- Open
Inspection001. SetInspection modetoInspecting. If nothing appears inProject, clickNew Projectand call itRocks_Project. - In
Inspecting data set, ifRocks_Inspectiondoes not appear, clickNew datasetand call itRocks_Inspection. - Set
Deployed model locationtoLocal. InDeployed modelsection, theRocks_TinyYOLOv3that you deployed in previous section should appear. - Notice how just after you selected
Rocks_TinyYOLOv3, a set of 11 rules appeared in theRulessection. Have a look at those rules and observe that there is 1Ruleper rock (e.g.Calcite,Lepidoliteetc) which triggers aPassresult whenConfidence scoreisGreater than 0.5, except forGoldandMilkyQuartzwhich have 2 asssociated Rules: one which triggers aPasswhenConfidence scoreisGreater than 0.8(i.e.GoldandMilkyQuartz), and another which triggers aFailwhenConfidence scoreisLess than 0.8(i.e.Gold_ToCheckandMilkyQuartz_ToCheck). - Leave
Device typein theMonitorsection blank for now. - In the
Input source, select theRocks_Samplethat you created in previous section. ClickEdit input sourceand thenTest input sourceto check. - Tick the
Time-based triggerand setTrigger interval in secondsto1. - Click
Review Inspection. Check that results are returned i.e. that rocks are being idenitifed. ClickBack. - Click
Enable Inspection. Then switch from theConfigurationtab to theImagestab of your Inspection and regularly (e.g. every 7 seconds) use the top-rightRefreshbutton. You will observe that the top-leftTotal Imagescount goes from 0 to 31, and that more and more pictures are being insspected as time goes by. Expect no more than 17 seconds for all the 31 pictures to have been infered. Click on any of them and notice how various rocks were detected, each with a certain confidence score.
If 1-9 worked well, it's now time to associate a Monitor Device Type to the Inspection:
- In the
Settings - Maximo Monitormenu, clickCreate. Name your Device TypeRocks, tick all boxes includingDevice,MVI VersionandModel UUID. ClickCreate. Check in Monitor that a new Device Type calledMVIE88A_Rockshas been created. - Back to the
Configurationtab ofInspection001, select the just createdRocksinMaximo Monitor - Device Typesection, click OK. Notice how theRuleshave been updated: theAlert type - Maximo Monitor Settingsis now ticked and aiot-2/type/MVIE88A_Rocks/id/MVIE88A_Inspection003/evt/result/fmt/jsontopic has been created, as well as aAlert message. Our inspection results are ready to flow into Monitor. This action has created a Device calledMVIE88A_Inspection001of Device TypeMVIE88A_Rocks.
Now, set yourself up to the ability to trigger Inspections on-demand:
- Open a new Firefox tab and go to the
Input Sourcemenu and selectRocks_Samples. Keep that tab always open. - Notice the
ProcessedandUnprocessedboxes there, and more specifically, the littleRefresh Wheelnext toProcessed. The idea is that wheneverUnprocessedis at0, it means that the Inspection has 'consumed' all available images. You then need to simply press thatRefresh Wheelnext toProcessedand you will see thatUnprocessedthen gets back to31and fastly gets to0. - So, click on the
Refresh Wheelany time you want a new Inspection on the 31 data set to be trigerred. You'll need to do that once in a while during a couple of days if you want to start creating relevant Monitor dashboards ... as per next section.
I invite you to create more Inspections (e.g. Inspection002, Inspection003) using different sets of data. For that purpose, feel free to create new Input Sources using e.g. this Rocks_Samples_Big.zip file which contains 109 pictures (vs. just 31) - great for you to simulate anomalies by e.g. 'usually' running an Inspection with Rocks_Samples.zip, then once running it with Rocks_Samples_Big.zip.
The following image highlights the main screens that you will encounter while executing this section:

Let's create data items that will allow us to count the number of times the various rocks have been detected.
- In Monitor, go to the
Setupmenu andDevicestab. SelectMVIE88A_Rocksand click top-rightSet up device typebutton. - Click
Create metric+link under theBatch data metric (calculated). SelectPythonExpressionfrom the list. Keep defaults on fist screen and clickNext. - On the
New data itemscreen, in theexpressionfield, enterdf['objectlabel']=='Gold'. ClickNext. - Unclick
Auto scheduleand setExecuting everyto5 minutesandCalculating the lastto5 days. Name your data itemGold, clickCreate.
Repeat 1-4 for: Calcite, Fluorite, Glass, Gold, Lepidolite, MilkyQuartz, Obsidian, RedJasper, RoseQuartz.
We will now create an Anomaly Detection data item which, hopefully, should react when an anomalous quantity of Gold rocks is found (e.g. more or less than usual)
- Click
Create metric+link under theBatch data metric (calculated). SelectKMeansAnomalyScorefrom the list. Keep defaults on fist screen and clickNext. - In the
input_itemfields, selectGold. Setwindowsizeto12. ClickNext. - Unclick
Auto scheduleand setExecuting everyto5 minutesandCalculating the lastto5 days. Name your data itemGold_KMeans_Anomaly, clickCreate.
Finally, we will create 1 Inspection-level Dashboard ...
- In Monitor, go to the
Monitormenu and selectMVIE88A_Inspection001. On top, click+to create a new Dashboard. Name itOverview. ClickConfigure dashboard. - Add
Simple Barcard. InGroup byselectTime intervaland inData itemselectCalcite. - Clone card
Calcitex 8 and create similar card forMilkyQuartzetc. - For the Gold, create a
Time series linecard and addGoldandGold_KMeans_Anomalydata items.
... and 1 Summary Dashboard:
- In Monitor, go to the
Monitormenu and selectMVIE88A_Rocks. On top, click+to create a new Dashboard. - In
Summary dashboard name, enterHourly. InTime grain, selectHourly. Tick allDimensions. ClickNext. - Select all
Data Itemsand in theAggregation Methodcolumn (1) for theStringtypes, selectlastandcount, (2) forMetric (calculated), selectcount,last,max,sum,std,mean. ClickConfigureDashboard. Leave as-is. ClickCreate. Wait 5 minutes.
Now that you have all the data items that are needed, you can start creating your own Dashboards.
Feel free to explore and try-out and e.g. reproduce this Summary dashboard just by looking at the picture.
If you are reading this final line, you made it ! Well done, thanks for your time, hope you enjoyed and see you in future labs.

