🛰️ 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

    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