Motor Shield

AI-Powered Motor Fault Detection & Health Monitoring System

Features • Installation • Training • Usage • Documentation

---

Overview

Motor Shield is a full-stack intelligent motor health monitoring system under development. It uses deep learning to detect and classify motor faults, featuring advanced AI models and an intuitive web dashboard designed to provide early fault detection, preventing costly equipment failures and downtime.

Fault Detection Capabilities

Motor Shield can detect and classify the following motor conditions:

• Healthy: Normal motor operation
• Open Circuit Fault: Broken or disconnected motor phases
• Inter-Turn Short Circuit: Winding insulation breakdown
• Control Switch Fault: Controller or switching component failures

Project Status

Note: This project is currently under active development. The frontend dashboard and AI/ML backend are being developed independently and are not yet connected. The backend ML models are fully functional for training and inference via command-line tools, while the frontend provides UI components and visualization framework.

Current State:

• AI/ML Backend: Fully functional (training, inference, validation)
• Frontend Dashboard: UI components and pages implemented
• API Integration: In progress (backend API server and frontend integration pending)
• Real-time Data Streaming: Planned

Features

AI/ML Backend

• Multiple Neural Architectures: CNN with Residual Connections, Transformer-based models, and Ensemble methods
• Real-time Fault Detection: Processes motor sensor data with sliding window approach
• High Accuracy: 95%+ classification accuracy across fault types
• Data Leakage Prevention: Robust train/validation/test splits at the file level
• Scalable Training Pipeline: Support for CPU, CUDA, and Apple Silicon (MPS)

Frontend Dashboard

• Modern UI Components: Dashboard, alerts, and analytics pages built with Next.js 15
• Responsive Design: Modern interface built with TailwindCSS and HeroUI
• Dark Mode Support: Theme switching for better user experience
• Visualization Framework: Ready for real-time motor health data integration
• Coming Soon: Live data integration with backend API

Architecture

Current Architecture (Development)

┌─────────────────────────────────────────────────────────────┐
│                Frontend (Next.js) - Port 3000               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  Dashboard   │  │   Alerts     │  │   Analytics  │     │
│  │     (UI)     │  │     (UI)     │  │     (UI)     │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

                    [Integration Layer - TBD]
                         │ (Coming Soon)
                         │ REST API / WebSocket

┌─────────────────────────────────────────────────────────────┐
│              AI Backend (Python CLI Tools)                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Dataset    │→ │  ML Training │→ │  Inference   │     │
│  │  Generation  │  │  (PyTorch)   │  │   (CLI)      │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

Planned Architecture (Production)

Once integrated, the system will include:

• FastAPI/Flask backend server exposing ML inference endpoints
• WebSocket support for real-time motor data streaming
• Frontend API client for data fetching and visualization
• Database for storing motor health history and alerts

Prerequisites

Frontend Requirements

• Node.js: 18.x or higher
• npm/pnpm/yarn: Latest version

Backend/AI Requirements

• Python: 3.8 or higher
• pip: Latest version
• CUDA (optional): For GPU acceleration

Installation

1. Clone the Repository

git clone https://github.com/noahteitlebaum/Motor-Shield.git
cd Motor-Shield

2. Frontend Setup

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install
# or
pnpm install
# or
yarn install

# For pnpm users: add to .npmrc if not already present
echo "public-hoist-pattern[]=*@heroui/*" >> .npmrc

# Run development server
npm run dev

The frontend will be available at http://localhost:3000

3. Backend/AI Setup

# Navigate to AI directory
cd AI

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Training the Model

Motor Shield provides flexible training options with multiple neural architectures.

Quick Start

# Generate dataset from raw CSV files
cd AI
python src/core/generate_dataset.py

# Train default Improved CNN model
python train_model.py --model_type improved --epochs 20 --batch_size 32

Training Options

1. Improved CNN (Recommended)

Best for: High accuracy with efficient training time

python train_model.py \
  --model_type improved \
  --epochs 20 \
  --batch_size 32 \
  --lr 0.001 \
  --dropout 0.5 \
  --device cuda

2. Transformer Model

Best for: Capturing long-range temporal dependencies

python train_model.py \
  --model_type transformer \
  --d_model 128 \
  --nhead 4 \
  --num_layers 3 \
  --dim_feedforward 256 \
  --epochs 20 \
  --batch_size 32 \
  --device cuda

3. Ensemble Model

Best for: Maximum accuracy through model averaging

python src/analysis/ensemble_model.py \
  --mode train \
  --n_models 5 \
  --output_dir artifacts/ensemble

Training Arguments

Argument	Default	Description
--dataset	artifacts/dataset.npz	Path to preprocessed dataset
--output_dir	artifacts	Directory for saving models and artifacts
--model_type	improved	Model architecture: improved, simple, transformer
--epochs	20	Number of training epochs
--batch_size	32	Training batch size
--lr	0.001	Learning rate
--dropout	0.5	Dropout rate
--patience	15	Early stopping patience
--device	Auto-detect	Compute device: cpu, cuda, mps
--train_noise_std	0 (off)	Gaussian noise on train batches only (e.g. 0.02) for hardware-like robustness; val/test stay clean

Device Selection

The training script automatically selects the best available device:

# Force CPU training
python train_model.py --device cpu

# Use NVIDIA GPU (CUDA)
python train_model.py --device cuda

# Use Apple Silicon GPU (M1/M2/M3)
python train_model.py --device mps

Dataset Generation

If you need to regenerate the dataset from raw CSV files:

# Place CSV files in AI/files/ directory following this structure:
# AI/files/
# ├── Healthy/
# │   └── *.csv
# └── Faulty/
#     ├── OpenCircuit/
#     │   └── *.csv
#     ├── InterTurn/
#     │   └── *.csv
#     └── ControlSwitch/
#         └── *.csv

# Generate dataset
python src/core/generate_dataset.py \
  --input_dir files \
  --output artifacts/dataset.npz \
  --window_size 200 \
  --stride 10

Monitoring Training

Training outputs include:

• Progress bars: Real-time epoch progress
• Metrics: Training/validation loss and accuracy
• Best model: Auto-saved when validation loss improves
• Artifacts: Saved in artifacts/<model_type>/

Example output:

Epoch 1/20: 100%|██████████| 156/156 [00:15<00:00, 10.02it/s]
Train Loss: 0.4521, Train Acc: 83.45%
Val Loss: 0.3012, Val Acc: 89.23%
✓ New best model saved!

Usage

Making Predictions

# Run inference on new motor data
python src/core/inference.py \
  --model artifacts/improved/motor_fault_model.pth \
  --metadata artifacts/improved/model_metadata.pkl \
  --csv path/to/motor_data.csv \
  --output predictions.csv

Validation & Analysis

# Validate dataset for data leakage
python src/validation/validate_no_leakage.py

# Visualize features
python src/analysis/visualize_features.py

# Analyze training results
python src/analysis/visualize_results.py --artifact_dir artifacts/improved

Project Structure

Motor-Shield/
├── frontend/                 # Next.js web application
│   ├── app/                 # Next.js 15 app directory
│   │   ├── Dashboard/       # Dashboard page
│   │   ├── LearnMore/       # Information pages
│   │   ├── MeetTheTeam/     # Team information
│   │   └── components/      # React components
│   ├── components/          # Shared UI components
│   ├── config/              # Configuration files
│   ├── public/              # Static assets
│   └── styles/              # Global styles
│
├── AI/                      # Python ML backend
│   ├── src/
│   │   ├── core/           # Core training & inference
│   │   │   ├── generate_dataset.py
│   │   │   ├── train_model.py
│   │   │   ├── inference.py
│   │   │   └── transformer_model.py
│   │   ├── analysis/       # Model analysis tools
│   │   │   ├── ensemble_model.py
│   │   │   ├── visualize_features.py
│   │   │   └── visualize_results.py
│   │   └── validation/     # Validation utilities
│   │       ├── validate_no_leakage.py
│   │       └── check_leakage.py
│   ├── files/              # Training data (CSV)
│   ├── docs/               # Documentation
│   ├── artifacts/          # Trained models & outputs
│   ├── requirements.txt    # Python dependencies
│   └── README.md          # AI module documentation
│
├── .gitignore
├── LICENSE
└── README.md               # This file

Technologies Used

Frontend

• Next.js 15 - React framework with App Router
• TypeScript - Type-safe JavaScript
• TailwindCSS - Utility-first CSS framework
• HeroUI - Modern React component library
• Framer Motion - Animation library

Backend/AI

• PyTorch - Deep learning framework
• NumPy - Numerical computing
• Pandas - Data manipulation
• scikit-learn - Machine learning utilities
• Matplotlib & Seaborn - Data visualization

Documentation

Detailed documentation is available in the following locations:

• AI Module: AI/README.md
• Model Architecture: AI/docs/model_architecture.md
• Data Preprocessing: AI/docs/preprocessing.md
• Data Leakage Prevention: AI/docs/data_leakage_prevention.md

Development

Frontend Development

cd frontend

# Run dev server with Turbopack
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run linter
npm run lint

Backend Development

cd AI

# Run tests
python -m pytest tests/

# Check for data leakage
python src/validation/validate_no_leakage.py

# Regenerate dataset
./regenerate_dataset.sh

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Team

Visit our Meet The Team page to learn more about the contributors.

Acknowledgments

• Motor fault detection dataset and research methodology
• Open-source community for amazing tools and libraries
• All contributors who have helped improve this project

---

Report Bug • Request Feature