PHAEMOS

Smart Maintenance Platform - collects real-time sensor data from ESP32/Arduino/STM32 hardware nodes, displays a live dashboard, fires alerts when readings exceed thresholds and uses machine learning to predict faults before they happen.

Name, Pronunciation, and Meaning

• Pronunciation: FAY-mos
• Meaning: "an ordered system that reveals"
• Origin: coined from Ancient Greek roots tied to revelation/appearance and structure/order

Why this fits: PHAEMOS reveals hidden machine behavior through telemetry, alerting, anomaly detection, and maintenance workflows before visible failure occurs.

Suggested tagline: Reveal before failure.

Quick Navigation

Architecture • Quickstart • Project Structure • Docs • Release Flow • Hardware • Tech Stack • Languages & Tools Used

Architecture

[ Hardware Layer - 4 nodes ]
  ESP32 Primary Node          -- 11 sensors, OLED, buzzer, RGB LED, relay
  STM32 Black Pill F411CEU6   -- MPU6050 at 100Hz + FFT, UART to ESP32
  Arduino Nano                -- BME280 + LDR + FC-28, serial to ESP32
  Raspberry Pi Pico 2W        -- BME280 + LDR + OLED, direct Wi-Fi POST
        |
  [ Firmware Layer ]
  Nano (serial 9600) -------> ESP32 (parses + merges payload)
  STM32 (UART 115200) ------> ESP32 (FFT peak Hz forwarded to API)
  Pico 2W (Wi-Fi) ----------> API directly
  ESP32 (Wi-Fi POST) -------> API every 5 seconds
        |
        | HTTP POST /api/v1/telemetry
        v
  [ Backend - FastAPI ]
  /telemetry  /devices  /alerts  /tickets  /auth  /ml  /ws
        |
   PostgreSQL 15 + Redis 7
        |
  [ ML Layer - Isolation Forest ]
  anomaly scoring on every ingest (Week 10 after hardware data collected)
        |
  [ Frontend - Next.js 15 ]
  live dashboard, sensor grid, device list, ticket system, admin panel
        |
  [ Observability ]
  Prometheus + Grafana monitoring overlay (docker-compose.monitoring.yml)

Quickstart

Prerequisites

• Docker + Docker Compose
• Node.js 18+
• Python 3.11+

Run with Docker

cp .env.example .env
make dev

Or without Make:

docker compose up --build

Frontend: http://localhost:3000 Backend API: http://localhost:8000 API Docs: http://localhost:8000/docs

Run without Docker

Backend

cd backend
python -m venv venv
venv\Scripts\activate       # Windows
pip install -r requirements.txt
uvicorn app.main:app --reload

Frontend

cd frontend
npm install
npm run dev

Quick API Smoke Test (No Hardware)

Run this when you want to validate core backend flows quickly without wiring sensors.

cd backend
uvicorn app.main:app --reload

In a second terminal:

python scripts/quick_api_smoke.py

What it tests:

• auth register/login
• device registration
• telemetry ingest with generated device API key
• latest telemetry fetch
• ML score endpoint

Project Structure

phaemos/
├── firmware/
│   ├── esp32/              v2 primary node (sensors/, outputs/, comms/, esp32.ino)
│   ├── stm32_blackpill/    HAL vibration node (Core/Src + Core/Inc)
│   ├── arduino_nano/       BME280 + LDR + FC-28 secondary node
│   └── pico_w/             MicroPython ambient node
├── backend/
│   ├── app/                FastAPI routes, models, schemas, services
│   ├── ml/                 Isolation Forest training and evaluation
│   ├── migrations/         SQL schema for all tables
│   └── tests/              pytest suite
├── frontend/
│   ├── app/                Next.js App Router pages
│   ├── components/         Dashboard, tickets, admin, UI primitives
│   ├── hooks/              useTelemetry, useAlerts, useWebSocketTelemetry
│   └── lib/                Axios API client, utility functions
├── hardware/
│   ├── schematics/         Proteus schematic placeholders (Phase 2)
│   ├── wiring/             Pin connection tables for all 4 nodes
│   └── pcb/                PCB design guide for Proteus ARES (Phase 3)
├── docs/                   Architecture, API reference, sensor reference, security, deployment
├── monitoring/             Grafana + Prometheus overlay
├── Makefile                make dev / test / lint / build / migrate / seed
├── docker-compose.yml
├── CHANGELOG.md
├── SUPPORT.md
├── SECURITY.md
├── .env.example
└── README.md

Docs

• Architecture Overview
• Database Schema
• API Reference
• Sensor Reference
• Security Controls
• Deployment Guide
• Deployment Checklist
• Development Timeline
• Decision Log
• Verification Tracker
• Support
• Changelog

Release Flow

PHAEMOS uses tag-based releases with changelog validation.

1. Update CHANGELOG.md with a new version section: ## [X.Y.Z] - DD-MM-YYYY
2. Commit and merge to main.
3. Create and push the tag:

git tag vX.Y.Z
git push origin vX.Y.Z

1. The GitHub Actions Release workflow validates the changelog entry and creates the GitHub release.

See docs/deployment.md for the full VPS, Vercel and DNS setup guide, and docs/deployment-checklist.md for the pre-release checklist.

Hardware

Board	Language	Role
ESP32 DevKit	C++ (Arduino IDE)	Primary node - 11 sensors, Wi-Fi POST, OLED, buzzer, RGB LED, relay
STM32 Black Pill F411CEU6	C (STM32 HAL)	Vibration node - MPU6050 at 100Hz, FFT, UART to ESP32
Arduino Nano	C++ (Arduino IDE)	Secondary node - BME280, LDR, FC-28, serial CSV to ESP32
Raspberry Pi Pico 2W	MicroPython	Ambient node - BME280, LDR, OLED, direct Wi-Fi POST

Sensor	Measures	Interface	Node
BME280	Temperature, humidity, pressure	I2C 0x76	ESP32, Nano, Pico 2W
MPU6050	Acceleration + gyroscope (6-axis)	I2C 0x68	ESP32, STM32
INA219	Bus voltage, current, power	I2C 0x40	ESP32
MLX90614	Contactless IR surface temperature	I2C 0x5A	ESP32
VL53L0X	Time-of-flight distance	I2C 0x29	ESP32
MQ-2	Gas and smoke concentration	Analog GPIO34	ESP32
AS5600	Magnetic shaft angle and RPM	I2C 0x36	ESP32
MAX4466	Acoustic / sound level	Analog GPIO32	ESP32
DS18B20	Precision contact temperature	OneWire GPIO4	ESP32
LDR	Ambient light	Analog GPIO33	ESP32, Nano, Pico 2W
FC-28	Moisture / water ingress	Analog GPIO36	ESP32, Nano

See hardware/wiring/ for full pin connection tables and docs/sensor_reference.md for library details.

Tech Stack

Layer	Technology
Frontend	Next.js 15 + TypeScript + Tailwind CSS
Backend	FastAPI (Python 3.11)
Database	PostgreSQL 15
Cache	Redis 7
ML	scikit-learn (Isolation Forest), pandas, numpy
Auth	JWT (python-jose), bcrypt
Firmware	C++ (Arduino IDE), C (STM32 HAL), MicroPython
Hardware	ESP32, STM32 Black Pill F411CEU6, Arduino Nano, Raspberry Pi Pico 2W
Containers	Docker + Docker Compose
Monitoring	Prometheus + Grafana
Deployment	Vercel (frontend + docs), DigitalOcean VPS (backend + DB)

Languages & Tools Used

Frontend

Next.js	React	TypeScript	Tailwind CSS	JavaScript

Backend & Data

Python	FastAPI	PostgreSQL	Redis	Scikit-Learn

Infrastructure & DevOps

Docker	GitHub	Vercel	DigitalOcean	Git

Firmware & Hardware

Arduino	C	C++	Shell/Bash	STM32	ESP32

---

Contributing

Contributions are welcome. Read CONTRIBUTING.md for the branch naming convention, commit format, code standards and PR checklist before opening a pull request.

Community

• GitHub Discussions - questions, ideas and show-and-tell
• GitHub Issues - bug reports and feature requests

Contact and Support

For general enquiries use the contact form or email contact@phaemos.com. For user support email support@phaemos.com.