Language: English · فارسی

TinyML Complete Kit

TinyML Complete Kit is a free, practical, end-to-end learning package for building TinyML on your own machine: train small models on CPU, quantize to INT8 TFLite, emit C arrays, and deploy to microcontrollers — plus a flagship industrial vibration anomaly project with live monitoring and a Unity digital twin.

TinyML does not need an expensive GPU. Models are kilobytes to hundreds of kilobytes and typically train in minutes to about an hour on a modern CPU.

---

Table of contents

• What this is
• Why it exists
• Features
• Architecture
• Prerequisites
• Quick start
• Installation
• Usage / learning path
• Flagship project
• Repository layout
• Zero-budget path
• Documentation
• Troubleshooting
• Contributing
• Security
• License
• Credits

---

What this is

A kit, not a single library: curated docs, copy-pasteable Python labs, firmware templates, datasets guidance, and one production-shaped industrial demo (anomaly detection → FastAPI dashboard → Unity twin).

Audience: students, makers, and engineers who want MCU-side ML without cloud lock-in.

---

Why it exists

• Most TinyML material is either marketing slides or fragmented blog posts.
• GPU-centric ML tutorials push people toward hardware they do not need for TinyML.
• Deploy gaps (quantize → C array → TFLM / Arduino) are where learners stall.
• Industrial PdM demos rarely ship with honest sim-to-real limits and monitoring UX.
• Persian learners lacked a deep practical kit; this repo is bilingual (English default, Persian full).

---

Features

Area	What you get
Learning pipeline	Sine → MNIST CNN → quantize INT8 → C header
System check	python/tools/check_system.py
Firmware starters	Arduino hello-sine + ESP32 TFLM template
Industrial PdM	Vibration AE + classifier, INT8, ESP32 headers
Live monitor	FastAPI + HTML dashboard (:8787)
Digital twin	Unity VibraSenseTwin + optional WebGL host (:8088)
Docs	Roadmap, hardware strategy, model zoo links, install verify
Honesty	Explicit “simulation ≠ plant floor” commissioning notes

---

Architecture

Three layers — train on PC, ship a tiny artifact, run inference on MCU:

[1] Your PC (CPU)          → data + train + quantize
[2] .tflite / model.h      → INT8 compressed model
[3] Microcontroller        → live sensor inference (no full training)

flowchart LR
  subgraph PC["PC / CPU"]
    D[Data / Digital Twin]
    T[Train Keras]
    Q[Quantize INT8 TFLite]
    C[C array / headers]
  end
  subgraph Edge["MCU / Edge"]
    S[Sensor]
    I[TFLM / firmware]
    A[Alarm / Actuator]
  end
  subgraph Monitor["Optional product shell"]
    API[FastAPI :8787]
    UI[HTML dashboard]
    U3[Unity / WebGL]
  end
  D --> T --> Q --> C --> I
  S --> I --> A
  I -.-> API
  API --> UI
  API --> U3

Loading

Flagship vibration path (preserved industrial diagram):

Digital Twin (machine physics)
   -> MEMS model (ADXL345-class)
   -> 0.5s window @ 3200 Hz
   -> 48-D features (time + spectral + envelope)
   -> (A) Autoencoder on NORMAL  => anomaly score
   -> (B) Multiclass fault classifier
   -> INT8 TFLite + C headers for ESP32

---

Prerequisites

Item	Recommendation
OS	Windows 10/11 (PowerShell examples); Linux/macOS adaptable
Python	3.10 or 3.11 (see python/requirements.txt)
Disk	Several GB for venv + TensorFlow
Optional MCU	ESP32-S3 / Pico / Nano 33 BLE Sense when ready
Optional Unity	2022.1.24f1 for the digital twin

---

Quick start

From the repository root (after clone):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r python\requirements.txt
python python\tools\check_system.py

Expect RESULT: READY, then run the first labs:

python python\01_hello_tinyml_sine.py
python python\02_train_mnist_tiny_cnn.py
python python\03_quantize_to_tflite.py --model models\mnist_tiny_cnn.keras
python python\04_tflite_to_c_array.py --tflite models\mnist_tiny_cnn_int8.tflite --out firmware\hello_sine_arduino\model_data.h

If Persian / Unicode console output breaks:

$env:PYTHONIOENCODING = "utf-8"

---

Installation

Full verified install notes (this kit was exercised on the profile above):

• English: docs/06-INSTALL-AND-VERIFY.md
• فارسی: docs/06-INSTALL-AND-VERIFY-FA.md

Monitoring stack (dashboard + twin):

cd projects\industrial_vibration_anomaly\monitoring
pip install -r requirements.txt
python run.py

Open http://127.0.0.1:8787 — see projects/industrial_vibration_anomaly/monitoring/README.md.

Unity one-click (FastAPI + editor):

cd projects\industrial_vibration_anomaly\monitoring\unity
.\Start-VibraSenseTwin.ps1

WebGL host (build must exist): .\Start-WebGL.ps1 → http://127.0.0.1:8088/

---

Usage / learning path

Step	Read / run	Notes
1	docs/00-START-HERE.md	One-page map
2	docs/01-TinyML-Complete-Guide.md	Full concepts
3	docs/02-Hardware-Your-GPUs.md	Your GPUs
4	docs/03-Model-Zoo-Links.md	Ready CNN refs
5	docs/04-Microcontroller-Deploy.md	Flash to MCU
6	docs/05-Roadmap-0-to-100.md	0→100 plan
7	docs/06-INSTALL-AND-VERIFY.md	Real results
—	resources/cheatsheet.md	Cheat sheet · FA
—	resources/links.md	Golden links · FA

Persian mirrors use the -FA.md suffix (same folder). Index: docs/DOCUMENTATION-INDEX.md.

Two parallel tracks

• Track A — full control (this kit): Python → Keras → TFLite INT8 → model.h → Arduino / PlatformIO
• Track B — faster for beginners: Edge Impulse free tier → web train → Arduino library

Learn both: A for depth, B for speed.

---

Flagship project (industrial vibration)

Predictive maintenance — vibration anomaly detection:
projects/industrial_vibration_anomaly/

cd projects\industrial_vibration_anomaly
python scripts\run_full_pipeline.py

Pipeline: industrial atomic tests (BPFO/BPFI/kurtosis) → domain-randomized dataset → train → eval → unseen-machine robustness → quantize.

Acceptance targets (engineering goals, not marketing slogans):

Metric	Target
AUC	≥ 0.98
Fault recall	≥ 0.95
False alarm rate	≤ 0.02
Classifier accuracy	≥ 0.90

Fault classes: normal · imbalance · misalignment · bearing_outer · bearing_inner · looseness

Target MCU: ESP32-S3 + 3-axis accelerometer (ADXL345 / MPU6050 / IIS3DWB).

---

Repository layout

TinyML-Complete-Kit/
├── docs/                 Documentation (EN default + *-FA.md)
├── python/               Train, quantize, convert to C
├── firmware/             Arduino / ESP32 templates
├── models/               Model outputs (.keras / .tflite) — mostly gitignored
├── datasets/             Dataset guidance
├── resources/            Links & cheatsheet
├── notebooks/            Optional Colab/Kaggle ideas
├── projects/             Full industrial projects (vibration, …)
├── CONTRIBUTING.md       How to contribute
├── SECURITY.md           Vulnerability reporting
├── CODE_OF_CONDUCT.md    Community norms
├── CHANGELOG.md          Release notes
├── LICENSE               MIT
├── README.md             English (default)
└── README.fa.md          فارسی

---

Zero-budget path

Priority	Action	Cost
1	Train on this PC’s CPU	Free
2	Simulate TFLite inference on PC	Free
3	Edge Impulse free account (no board)	Free
4	Cheap board when ready (ESP32-S3 / Pico)	~$5–15 when you can
5	GT 610 / CUDA 13 for TinyML	Skip

---

Documentation

Doc	English	فارسی
Index	DOCUMENTATION-INDEX.md	—
Architecture	ARCHITECTURE.md	ARCHITECTURE-FA.md
Troubleshooting	TROUBLESHOOTING.md	TROUBLESHOOTING-FA.md
Start here	00-START-HERE.md	00-START-HERE-FA.md
Complete guide	01-…	01-…-FA
Monitoring	monitoring/README.md	unity/README-FA.md

---

Troubleshooting

Short list (full page: docs/TROUBLESHOOTING.md):

Symptom	Fix
pip / TensorFlow install fails	Use Python 3.10/3.11 64-bit; recreate .venv
Garbled console text	$env:PYTHONIOENCODING = "utf-8"
Port 8787 in use	Health-check http://127.0.0.1:8787/api/health — do not start a second run.py
WebGL file:// blocked	Serve with Start-WebGL.ps1 on :8088
Unity HTTP blocked	VibraSense insecure-HTTP setting; rebuild WebGL if needed
Expecting CUDA on GT 610	Do not — TinyML path is CPU

---

Contributing

See CONTRIBUTING.md · فارسی.
By participating you agree to the CODE_OF_CONDUCT.md.

---

Security

Do not file security issues in public GitHub issues.
Report privately per SECURITY.md · فارسی.

---

License

MIT — SPDX: MIT.

---

Credits

• Brand mark & banner: docs/assets/branding/ (regeneration prompts included).
• Built for deep, practical, sustainable TinyML learning — without dependence on expensive GPUs.
• Stack inspiration: TensorFlow Lite / TFLM, Edge Impulse ecosystem, MLCommons Tiny, CWRU/MIMII-style industrial validation literature.
• Community standards shaped by Standard Readme, banger-readme anatomy, and OSS_SPEC.

Maintainer / origin: Ali-Rashidi-80/TinyML-Complete-Kit

---

Built for hands-on mastery — from first sine wave to MCU inference and industrial monitoring.