# 🛰️ BLE AI Localizer - README

Progetto di localizzazione indoor basato su segnali Bluetooth (BLE) e Machine Learning (KNN).
Ambiente: MN reslevis 192.168.1.3 | Python 3.10.16 | Docker 27.4.1.

---

## 🛠️ Architettura e Struttura Progetto
Il sistema è diviso tra un **Core Engine** (background) e una **Management Suite** (UI Streamlit).

### File Operativi Principali
* **`web_suite.py`**: Punto d'ingresso unico (Login, UI Management, MQTT Logging).
* **`main.py`**: Orchestratore dei processi background (Inference & Training).
* **`infer_mode.py`**: Motore di calcolo real-time che processa il traffico MQTT.
* **`web_test_inference.py`**: Tool di validazione offline con mappa Folium interattiva.
* **`web_status.py`**: Monitoraggio infrastruttura (Core, MQTT Broker, API, Disco).

---

## 🚀 Note per l'Operatore: Campagna di Rilevazione

Per garantire la massima precisione del sistema, attenersi rigorosamente a queste linee guida durante la raccolta delle fingerprint.

### 1. Parametri Algoritmo (KNN)
* **Valore di k**: Rappresenta il calcolo sulla retta ($k=2$) o sul piano ($k>2$) tra i beacon di training.
* **Vincolo**: $k$ deve coincidere come minimo con il numero di beacon per stanza.
* **Consiglio**: Se si catturano 5 misure per stanza, impostare **$k=3$**. Il parametro è globale.

### 2. Linee Guida per la Raccolta (Training)
* **Distanza Pareti**: Rilevare i punti ad almeno **1m dalle pareti** (evitare angoli o pareti adiacenti).
* **Simmetria**: Per piani simmetrici, far coincidere le misure di ogni piano nello stesso punto spaziale.
* **Beacon di Test**: Durante la raccolta includere almeno un beacon di test per ogni potenza. Verrà escluso dal training ma usato per validare l'inferenza sul traffico registrato.

### 3. Configurazione Hardware Beacon
* **Fase di Raccolta**: TX Power variabile (0, -4, -8, -12 dBm) | TX Interval: **200 ms**.
* **Fase di Produzione**: Potenza ottimale risultata dai test | TX Interval: **1400 ms**.

### 4. Parametri Temporali (`config.yaml`)
* **Slot di raccolta**: 30 secondi per ogni punto di fingerprint.
* **Finestra di Inferenza**: 7 secondi.

---

## 🖥️ Management Suite (Interfaccia Web)

### Accesso
* **URL**: `http://192.168.1.3:8501`.
* **Credenziali**: Configurate nel `docker-compose.yml` (Default: `Admin` / `pwdadmin1`).

### Funzionalità InferTest (Validazione)
Nella tab **🧪 InferTest** è possibile validare i modelli caricando file di test:
* 🔵 **Celeste**: Punto di Test (posizione reale registrata).
* 🟠 **Arancione**: Punto Predetto (posizione calcolata dal modello).
* 🟡 **Linea Gialla**: Scostamento metrico (Errore Distanza).
La mappa supporta lo zoom persistente e la navigazione Folium.

### MQTT Raw Logging
Dalla Sidebar è possibile attivare la registrazione del traffico grezzo.
* **Log Directory**: `/data/mqtt_raw/`.
* **Comando interno**: `mosquitto_sub` filtrato su `publish_out` con parametri presi dinamicamente dal file `config.yaml`.

---

## ⚙️ Gestione Docker (SysAdmin)

####Aggiornamento del software
```bash
    cd /data/service/ble-ai-localizer
    docker compose up -d --build
    docker compose -p ble-ai-localizer build
    docker compose -p ble-ai-localizer up -d --build
    docker system prune
    docker rmi ble-ai-localizer:0.1.0

###Gestione Sart/Stop Container
```bash
    cd /data/service/ble-ai-localizer
    docker compose -p ble-ai-localizer up -d
    docker compose -p ble-ai-localizer logs -f --tail=200 --timestamps
    docker compose -p ble-ai-localizer stop
    docker compose -p ble-ai-localizer restart
    docker compose -p ble-ai-localizer down


###Accesso Web MajorNET ResLevis:
```bash
    https://10.251.0.30/frontend/app_reslevis/app.html#home

 Accesso Web a Container ble-ai-localizer
    URL: http://0.0.0.0:8501
    http://192.168.1.3:8501/
        username e password da file composer: docker-compose.yml
                UI_USER: "Admin"
                UI_PASSWORD: "pwdadmin1"  <-- facilitate per accesso da mobile