Machine Passport

1. Product Description

1.1. Solution Overview

Machine Passport (MP) is a Node.js-based dashboard application within the AIDEAS ecosystem, designed to centralize and visualize machine data in a factory environment. Its primary goal is to simplify machine data monitoring, helping users track performance and make informed decisions. MP provides:

• A centralized platform for accessing machine data from diverse sources.

• Visualization of machine data through intuitive charts and tables.

• Seamless integration with AIDEAS Solutions for enhanced data analysis.

1.2. Prerequisites

• Hardware Requirements

Machine Passport can run on any platform that supports Docker containers. Ensure the system has sufficient resources to handle the Node.js runtime, React frontend, MongoDB database, and any additional dependencies (e.g., file storage for CSV/Excel uploads or PDFs).

• Software Requirements

Machine Passport requires the following software to be installed:

• Docker Desktop (Windows, Mac, or Linux)

• Node.js

• npm (included with Node.js)

• MongoDB

• Kubernetes (Optional, for orchestration in production environments)

Machine Passport

1. Product Description

1.1. Solution Overview

Machine Passport (MP) is a Node.js-based dashboard application within the AIDEAS ecosystem, designed to centralize and visualize machine data in a factory environment. Its primary goal is to simplify machine data monitoring, helping users track performance and make informed decisions. MP provides:

• A centralized platform for accessing machine data from diverse sources.

• Visualization of machine data through intuitive charts and tables.

• Seamless integration with AIDEAS Solutions for enhanced data analysis.

1.2. Prerequisites

• Hardware Requirements

Machine Passport can run on any platform that supports Docker containers. Ensure the system has sufficient resources to handle the Node.js runtime, React frontend, MongoDB database (which stores PDF files), and sufficient disk space for storing CSV/Excel files on the filesystem.

• Software Requirements

Machine Passport requires the following software to be installed:

• Docker Desktop (Windows, Mac, or Linux)

• Node.js

• npm (included with Node.js)

• MongoDB

• Kubernetes (Optional, for orchestration in production environments)

• External Dependencies

Machine Passport relies on the following third-party services, libraries, or APIs:

• MongoDB: For storing and querying machine data, metadata and project-related documents. CSV and Excel files are stored in the project folder.

• Keycloak: For user authentication and single sign-on (SSO).

• Partner Endpoints: For GET Solutions, MP requires access to partner-provided endpoints; for POST Solutions, partners need access to MP’s endpoints.

2. Installation

2.1. Environment Preparation

Ensure that all dependencies, including Node.js, npm, Docker, MongoDB, and Keycloak, are installed. Optionally, set up Kubernetes for production orchestration. Clone the repository from the official GitLab project, set up the file storage directory, and configure the backend and frontend environments as needed.

• Install Node.js and npm from nodejs.org.

• Install Docker Desktop for containerized deployment.

• Install and configure MongoDB for storing machine data, metadata, and project-related documents (e.g., PDFs).

• Install and run Keycloak for authentication, following the Keycloak documentation. Configure a realm and client for Machine Passport.

• Optionally, set up a Kubernetes cluster (e.g., Minikube for local development or GKE/EKS for production).

• Clone the repository: git clone https://gitlab-cigip.alc.upv.es/aideas/machine-passport/mp.git cd machine-passport

• Edit the .env file in the project root with necessary variables (e.g., MONGO_URI, PORT).

2.2. Step-by-Step Installation Process

Local Installation: Requires installing dependencies and launching the application manually using npm.

Docker Installation: Uses a docker-compose.yml file to deploy the application.

Kubernetes Installation: Deploys the application on a Kubernetes cluster using provided manifests that are included and can be configured in the k8s folder in the project folder.

3. Initial Configuration

3.1. First Steps

• Login

Users must log in using GitLab authentication before accessing secured application features.

3.2. Interface Navigation

Upon successful login, access the dashboard.

The dashboard provides a user-friendly interface for managing machine data. The layout, as shown in the screenshot, consists of a sidebar on the left with four main buttons and a main content area on the right with slots for charts and tables.

Sidebar Buttons: The left sidebar contains the following buttons, each providing access to a key feature:

• Connectivity: Opens a modal to manage data sources, allowing users to import, edit and delete data from CSV/Excel files, MongoDB and other sources.

• Visual: Opens a modal to select the data to be visualized and the slots that will be used for visualization, then creates the selected charts or tables in the chosen slots.

• Machine: Opens a modal for the user to select any of the saved machines and display their details (e.g., Machine ID, Serial Number, Model, Manufacturer, Usage Hours, Efficiency) and all corresponding data in tables.

• UI Customization: Allows users to adjust the dashboard layout by choosing from four pre-defined layouts.

Chart/Table Slots: The main content area features a grid of five empty slots (three chart slots on the top row, two table slots on the bottom row). These slots are placeholders for displaying charts, tables, or other visualizations once data is imported and a visualization is launched via the Visual button.

Top-Right Buttons: The top-right corner of the screen features two buttons:

• Logout: Logs the user out of their account, ending the session.

• Main Page: Redirects the user to the AIDEAS main platform.

3.3. Main Workflows

• Workflow Description

This section details the primary workflows for using Machine Passport, including how to use each modal accessed via the dashboard buttons.

• Using the Connectivity Modal

The Connectivity modal allows users to manage data sources and entities in Machine Passport, including importing, editing, and deleting data from various sources. It provides a tabbed interface for handling different types of data, such as machine metadata, Excel files, databases, and PDFs.

• Tabs Overview: The modal includes the following tabs, each representing a type of data or entity:

  • Machine: Manage machine metadata, such as Machine ID, Serial Number, and Model.

  • Excel Files: Import and manage data from CSV/Excel files.

  • Mongo DB: Manage MongoDB connections that store related machine data (create or delete only).

  • PostgreSQL: Manage PostgreSQL connections that store related machine data (create or delete only).

  • Suite: Manage Suites (e.g., Design, Manufacturing) for organizing Solutions.

  • Solution: Manage Solutions (e.g., Excel/CSV, GET/POST endpoints) for data integration.

  • XAIs: Manage XAIs (feature importances) for explainability of Solutions.

  • PDF: Import, manage, and view PDF files, such as machine user manuals.

• Sub-Tabs Overview:

  • Create: Allows users to add a new entry for the selected data type (e.g., a new machine, a new Excel file). Each tab’s Create sub-tab typically provides a form to input the necessary details.

    

  • Edit: Enables users to modify the data of an existing entry (e.g., updating a machine’s serial number, editing a Solution’s fields). This sub-tab is available for all tabs except Mongo DB and PostgreSQL.

    

  • Delete: Allows users to select an existing entry and delete it (e.g., removing a machine or a Suite). This sub-tab is available for all tabs.

    

  • Viewer (PDF tab only): Displays a selected PDF file for viewing (e.g., a machine user manual).

    

---

Machine Tab The Machine tab is used to manage machine metadata. Users can create, edit, or delete machine records using the “Machine Details Form,” shown below in the Create sub-tab.

• Create: Provides a form to input details such as Machine ID, Serial Number, Model, Manufacturer, Contact, Production Date, and Technical Specifications.

  

• Edit: Select a Machine ID from the dropdown; all its fields are populated. Modify any field (e.g., change Manufacturer name) and press “Save” to update.

• Delete: Displays a dropdown with available Machine IDs. Select a Machine ID and click “Delete Machine” to remove it.

---

Excel Files Tab The Excel Files tab allows users to import and manage data from CSV/Excel files. Users can create, edit, or delete Excel file entries.

• Create: Provides a form or interface to upload a new CSV/Excel file and correlate it with an existing machine.

  

• Edit: Select an existing Excel or CSV file from the dropdown. Change its title or select a Machine ID from the dropdown to correlate it with a machine, then press “Save Changes”.

• Delete: Displays a dropdown with available Excel/CSV files. Select a file and click “Delete Excel” to remove it.

---

Mongo DB Tab The Mongo DB tab enables users to connect to, fetch and save data from an external MongoDB database. Users can create or delete MongoDB data entries (editing is not supported).

• Create: Provides a form to input MongoDB connection details (e.g., IP Address and Port of the database) and correlate it with an existing machine.

  

• Delete: Displays a dropdown with available MongoDB connections. Select a connection and click “Delete Mongo Connection” to remove it.

---

PostgreSQL Tab The PostgreSQL tab enables users to connect to, fetch and save data from an external PostgreSQL database. Users can create or delete PostgreSQL data entries (editing is not supported).

• Create: Provides a form to input PostgreSQL connection details (e.g., IP Address and Port of the database) and correlate it with an existing machine.

  

• Delete: Displays a dropdown with available PostgreSQL connections. Select a connection and click “Delete PostgreSQL Connection” to remove it.

---

Suite Tab The Suite tab allows users to manage Suites, which group related Solutions (e.g., Design, Manufacturing). Users can create, edit, or delete Suites.

The Default suite cannot be deleted. When a suite is deleted, all the solutions included in this suite are transferred to the Default suite.

• Create: Provides a form to define a new Suite, specifying its title.

  

• Edit: Select a Suite from the dropdown and change its title, then press “Save Changes”.

• Delete: Displays a dropdown with available Suites. Select a Suite and click “Delete Suite” to remove it.

---

Solution Tab The Solution tab allows users to manage Solutions for data integration (e.g., Excel/CSV, GET/POST endpoints). Users can create, edit, or delete Solutions.

• Create: Provides a form to define a new Solution (e.g., Solution type, endpoint URL). A Solution has to be correlated with an existing Suite and can be correlated with an existing machine. Its type can be selected from a dropdown. There are 3 types of Solutions:

  • Excel/CSV type Solution: The data is fetched through a Excel/CSV file that is directly imported to the dashboard.

    

  • GET type Solution: The data is fetched through a http GET request to a specified endpoint that stores the data. The URL of the endpoint has to be provided in the URL field.

    

  • POST type Solution: In that case an endpoint is created and can be shared (e.g. with a partner) to send the data through a http POST request to this specific endpoint. The data sent in this way is appended to the existing data field of the solution. The path of the endpoint created, needs to be specified in the URL field.

    Note that only the path is needed here, e.g. if MP runs on http://localhost:3000 and the URL field is filled with “TestPostSolution”, then the created endpoint will be accessible through: http://localhost:3000/solution/postSolution/TestPostSolution

    

• Edit: Select a Solution from the dropdown. Change its title, select a Machine from the dropdown to correlate it with a specific machine, and select a Suite from the dropdown to move it to another Suite, then press “Save Changes”.

• Delete: Displays a dropdown with available Solutions. Select a Solution and click “Delete Solution” to remove it.

---

XAIs Tab The XAIs tab allows users to manage XAIs (feature importances) for explainability of Solutions. Users can create, edit, or delete XAIs.

• Create: Provides a form to define a new XAI (e.g., feature name, importance value). A new XAI has to be correlated with an existing Solution. There are 2 ways to import an XAI:

  • Pasting the JSON of the data in the corresponding field.

    

  • Adding attribute-value pairs (automatically generates the JSON and stores it in the data field of the XAI).

  

• Edit: Select an XAI from the dropdown; its info appears underneath. Change its title, select a Solution from the dropdown to correlate it with a Solution, and edit or add more field-value pairs, then press “Save Changes”.

• Delete: Displays a dropdown with available XAIs. Select an XAI and click “Delete XAI” to remove it.

---

PDF Tab The PDF tab allows users to import, manage, and view PDF files, such as machine user manuals. Users can create, edit, delete, or view PDFs.

• Create: Provides a form or interface to upload a new PDF file and correlate it with an existing machine.

  

• Edit: Select a PDF from the dropdown. Change its title, correlate it with a machine by selecting one from the Machine dropdown, then press “Save Changes”.

• Delete: Displays a dropdown with available PDFs. Select a PDF and click “Delete PDF” to remove it.

• Viewer Sub-Tab: Displays a selected PDF file for viewing.

• Visualizing Data with the Visual Modal

• Using the Visual Modal

  The Visual modal allows users to select data for visualization and configure how it is displayed on the dashboard. The sub-tabs (e.g., Chart 1, Table 1) correspond to slots in the selected dashboard layout and may vary depending on the layout configuration (e.g., a default layout has four chart slots and two table slots).

  • Workflow Description:

    • Accessing the Modal: Click the Visual button on the sidebar to open the modal.

      

    • Selecting a Slot: Choose a sub-tab corresponding to a specific slot in the dashboard layout (e.g., Chart 1, Chart 2, Chart 3, Chart 4, Table 1, Table 2). For example, selecting Chart 1 targets the first slot in the first row (1-1) of the layout for a chart visualization, while Table 1 targets the first table slot.

    • Selecting a Data Source: Use the Source dropdown to choose the data source (Excel, Mongo, Postgres, Solution, or XAI). Depending on the source, additional steps are required:

      • Excel: Select a specific Excel file (e.g., Excels_predictive_maintenance.xlsx) from a secondary dropdown, and its attributes (e.g., Air temperature [K], Torque [Nm]) are displayed as checkboxes.

      • Mongo: Select a database from the Mongos dropdown. Once selected, a Collections dropdown is populated, allowing the user to choose a collection. The attributes from the chosen collection are then displayed as checkboxes.

      • Postgres: Select a database from the Postgress dropdown. Once selected, a Tables dropdown is populated, allowing the user to choose a table. The attributes (columns) from the chosen table are then displayed as checkboxes.

      • XAI: Select an XAI dataset from the XAI dropdown, and its attributes are displayed as checkboxes.

      • Solution: Select a suite from the Suite Selection dropdown (e.g., Design, Manufacturing, Repair/Reuse/Recycle). Once selected, the Phase section populates with radio buttons for Solutions in that suite. Choose a Solution, and its attributes are displayed as checkboxes.

    • Choosing a Visualization Type: For chart slots, select the chart type from the Chart dropdown (e.g., Bar, Pie, Line, Horizontal Bar). For table slots, no chart type selection is available, and the visualization defaults to a table.

    • Selecting Attributes:

      • Charts: Select up to 3 attributes to visualize:

        • Check an attribute (e.g., Spindle performances), and its existing values are displayed below (e.g., MaxSpeed: 4000, Torque: 51.210).

        • Optionally, select specific values to include in the visualization, or leave them unselected to include all values.

        • Repeat for up to 3 attributes. If the user tries to select more than 3 attributes, a warning appears, and the selected attributes are deselected.

        • Numerical Attributes: If any selected attribute is numerical, a range bar appears showing the attribute’s range of values, for bin grouping the data in the visualization. A “Selection of mode” modal then appears, allowing the user to choose Quantitatively (raw values), MAX/MIN (maximum or minimum value), or AVG (average value). Select a metric and a mode and click FINISH to proceed.

      • Tables: Select any number of attributes to include in the table:

        • Check an attribute (e.g., Machine ID, Spindle performances), and all values for that attribute are automatically included (no individual value selection is displayed).

        • Repeat for as many attributes as needed, with no limit on the number of selections.

    • Saving the Configuration: Click Save to store the configuration for the current slot. The user can then select another slot (e.g., Chart 2 or Table 2) and repeat the process, clicking Save for each slot.

    • Rendering Visualizations: Once all desired slots are configured, click Finished to render all charts and tables simultaneously on the dashboard.

    • Adjusting Visualizations: Reopen the Visual modal to modify the source, chart type (for charts), attributes, or other settings, or use Close to discard changes without saving.

  • Examples or Use Cases:

  • Chart Example using Excel Source:

    1. Select an Excel file from the dropdown.

    

    2. After the file is selected, its attributes automatically load and then select attribute(s) (up to 3) to visualize in the same chart. After the attributes are selected, press “Save”.

    

    4. If any of the selected attributes is a numerical type, a new window will appear to choose the metric and the type of the calculation. Then press “Finish” to continue.

    

    5. After that the you will be back in the previous modal, having the opportunity to create other charts/tables. To continue press “Finished”.

       

       6. The selected chart appears in the slot.

    

  • Table Example using Solution source:

    1. Select Solution from the source dropdown

       

    2. Select a Suite from the dropdown

       

    3. Select a Solution from the radio buttons

       

    4. Select the attributes to be included in the table

       

    5. Press “Save” and then “Finished” to create the table.

    

• Displaying Machine Metadata with the Machine Modal

Describes how to view machine metadata using the Machine modal.

• Open the Machine modal by clicking the Machine button on the dashboard.

  

• Select a saved machine from the list to view its details (e.g., Machine ID, Serial Number, Model, Manufacturer, Usage Hours, Efficiency).

  

• View the machine’s corresponding data (e.g. correlated excel files, solutions, manuals) in tables.

  

Note: A unique url is created for every machine imported. This url can be used to directly access the Machine modal with this Machine selected and its fields loaded. e.g. if the MP runs on http://localhost:3000/main and a machine with ID “PZ8221” exists, the unique url in the case will be: http://localhost:3000/main?machine_id=PZ8221.

Along with this unique url a QR code image is also created and stored for each machine in the database. When the QR code is scanned it redirects the user to this unique url.

• Customizing the UI with the UI Customization Modal

Describes how to adjust the dashboard layout using the UI Customization modal.

• Open the UI Customization modal by clicking the UI Customization button on the dashboard.

• Choose from four pre-defined layouts to adjust the dashboard’s appearance.

  

• Apply the selected layout to update the dashboard. E.g after applying Template 2:

4. General Queries

4.1. Installation and Configuration Contact

For assistance with installation or configuration of Machine Passport, users can contact the AIDEAS research team at Centre For Research & Technology Hellas. Support is available through the following channels:

• Email: For technical assistance you can contact the AIDEAS technical team from CERTH:

  • gtzionis@iti.gr

  • dkaram@iti.gr

  • kougka@iti.gr

• GitLab Issues: Submit an issue on the project’s GitLab repository at https://gitlab-cigip.alc.upv.es/aideas/machine-passport/mp/-/issues to report bugs or request support. Note: Support availability may depend on the AIDEAS team’s schedule. For urgent issues, include detailed logs or screenshots in your request.

  

4.2. Licensing and Support

• The solution is licensed under AGPLv3 or PRIVATE licensing models.

• Pricing and licensing details are available upon request.

  Subject	Value
  Payment Model	Quotation under request
  Price	Quotation under request

5. Appendices

5.1. Glossary of Terms

• AIDEAS: An ecosystem of tools and solutions developed at Universitat Politècnica de València (UPV) for industrial data analysis and decision-making. Machine Passport is part of this ecosystem.

• Machine Metadata: Information about a machine, such as Machine ID, Serial Number, Model, Manufacturer, Usage Hours, and Efficiency, used for contextual analysis in Machine Passport.

• Suites: Categories in Machine Passport (e.g., Design, Manufacturing) that group related Solutions for organizational purposes.

• Solutions: Data integration methods in Machine Passport, supporting Excel/CSV files, GET endpoints, or POST endpoints for fetching or receiving machine data.

• XAIs: Explainable AI components (feature importances) that provide insights into the significance of data features within Solutions.

• GET Solution: A type of Solution where Machine Passport fetches data from a partner-provided endpoint using an HTTP GET request.

• POST Solution: A type of Solution where Machine Passport creates an endpoint for partners to send data via an HTTP POST request, appending the data to the Solution.

• MongoDB: A NoSQL database used by Machine Passport to store machine data, metadata, and project-related documents (e.g., PDFs).

• PostgreSQL: A relational database supported by Machine Passport for storing and querying machine data.

• Keycloak: An open-source identity and access management solution used for user authentication in Machine Passport.

5.2. API Documentation

Machine Passport provides API endpoints for interacting with its data and functionality. This includes dynamically created endpoints for POST Solutions (as defined in the Connectivity modal) and predefined endpoints for creating, retrieving, and managing resources programmatically. All endpoints require authentication via Keycloak, and a valid access token must be included in the Authorization header as a Bearer token.

• POST Solution Endpoint

Dynamically created endpoints for POST Solutions allow partners to send machine data to the dashboard. These endpoints are generated when a POST Solution is defined in the Connectivity modal or preloaded on startup.

• URL: http://< base-url >/solution/postSolution/< solution-path >

  • < base-url >: The base URL where Machine Passport is hosted (e.g., http://localhost:3000).

  • < solution-path >: The path specified in the URL field when creating the POST Solution, or defined in the preloaded Solutions.

  • Preloaded POST Solution Endpoints: The following < solution-path > values are preloaded on startup for the AIDEAS project:

    [
      "solutionName=PrescriptiveMaintenance&param=RiskAssessment",
      "solutionName=PrescriptiveMaintenance&param=RUL",
      "solutionName=AnomalyDetector",
      "solutionName=AdaptiveController&param=Training",
      "solutionName=AdaptiveController&param=Results",
      "solutionName=ConditionEvaluator",
      "solutionName=QualityAssurance2D",
      "solutionName=QualityAssurance3D",
      "solutionName=DeliveryOptimizer"
    ]
    

  • Example URLs:

    • http://localhost:3000/solution/postSolution/solutionName=PrescriptiveMaintenance&param=RiskAssessment (for AI-PM-RiskAssessment)

    • http://localhost:3000/solution/postSolution/solutionName=PrescriptiveMaintenance&param=RUL (for AI-PM-RUL)

    • http://localhost:3000/solution/postSolution/solutionName=AnomalyDetector (for AI-AD)

    • http://localhost:3000/solution/postSolution/solutionName=AdaptiveController&param=Training (for AI-AC-Training)

    • http://localhost:3000/solution/postSolution/solutionName=AdaptiveController&param=Results (for AI-AC-Results)

    • http://localhost:3000/solution/postSolution/solutionName=ConditionEvaluator (for AI-CE)

    • http://localhost:3000/solution/postSolution/solutionName=QualityAssurance2D (for AI-QA-2D)

    • http://localhost:3000/solution/postSolution/solutionName=QualityAssurance3D (for AI-QA-3D)

    • http://localhost:3000/solution/postSolution/solutionName=DeliveryOptimizer (for AI-DO)

• GET Solutions (External Data Fetching)

Machine Passport supports GET Solutions, where it fetches data from external partner-provided endpoints via HTTP GET requests. These endpoints are not hosted by Machine Passport but are defined in the Connectivity modal or preloaded on startup. Partners must ensure their endpoints are accessible and return data in a format compatible with Machine Passport (e.g., JSON).

• Preloaded GET Solution URLs: The following external URLs are preloaded on startup for the AIDEAS project:

  [
    "https://ai-fo-pama-backend.aideas-srv.cigip.upv.es/dataMP",
    "https://ai-sr-backend.aideas-srv.cigip.upv.es/dataMP"
  ]
  

• Details:

  • https://ai-fo-pama-backend.aideas-srv.cigip.upv.es/dataMP (for AI-FO, Suite: Manufacturing)

  • https://ai-sr-backend.aideas-srv.cigip.upv.es/dataMP (for AI-SR, Suite: Repair/Reuse/Recycle)

• Note: These are external URLs, not Machine Passport endpoints. Machine Passport will fetch data from these URLs during startup.

5.3. Console Commands List

docker-compose up --build Use this command to build and start Machine Passport in a Dockerized environment, ensuring all dependencies (e.g., MongoDB) are running.

npm run dev Use this command to start Machine Passport in development mode on your local machine, typically after installing dependencies with npm install.