matlab-python/SETUP.md

# Setup e Installazione

Guida rapida per configurare e avviare il sistema di elaborazione dati sensori.

## Prerequisiti

### Sistema Operativo
- Linux (consigliato: Ubuntu 20.04+, CentOS 8+)
- macOS 10.15+
- Windows 10+ (con WSL2 consigliato)

### Software Richiesto
- **Python 3.8+**: `python --version`
- **pip**: Gestore pacchetti Python
- **MySQL/MariaDB**: Database server (5.7+ / 10.3+)
- **Git**: Version control (opzionale)

## Installazione

### 1. Clone/Download Repository

```bash
cd /path/to/workspace
# Se usando git:
git clone <repository-url>
cd matlab_func

# Oppure scarica e estrai l'archivio
```

### 2. Crea Virtual Environment (Consigliato)

```bash
# Crea virtual environment
python3 -m venv venv

# Attiva virtual environment
# Linux/macOS:
source venv/bin/activate

# Windows:
venv\Scripts\activate
```

Dovresti vedere `(venv)` nel prompt.

### 3. Installa Dipendenze Python

```bash
pip install --upgrade pip
pip install -r requirements.txt
```

Questo installerà:
- numpy
- pandas
- scipy
- mysql-connector-python
- openpyxl

### 4. Configura Database

#### Opzione A: Copia File Configurazione
```bash
cp DB.txt.example DB.txt
nano DB.txt  # oppure vim, code, etc.
```

Modifica con le tue credenziali:
```
nome_database
username
password
com.mysql.cj.jdbc.Driver
jdbc:mysql://host:porta/database?useLegacyDatetimeCode=false&serverTimezone=Europe/Rome
```

#### Opzione B: Crea Nuovo File
```bash
cat > DB.txt << EOF
ase_monitoring
myuser
mypassword
com.mysql.cj.jdbc.Driver
jdbc:mysql://192.168.1.100:3306/ase_monitoring?useLegacyDatetimeCode=false&serverTimezone=Europe/Rome
EOF
```

### 5. Verifica Connessione Database

```bash
python -c "
from src.common.database import DatabaseConfig, DatabaseConnection
config = DatabaseConfig('DB.txt')
with DatabaseConnection(config) as conn:
    print('✓ Database connection successful')
"
```

Se vedi errori:
- Verifica credenziali in DB.txt
- Controlla che MySQL server sia raggiungibile
- Verifica firewall rules
- Testa connessione con: `mysql -h host -u user -p`

## Configurazione

### 1. Verifica Struttura Database

Il database deve avere le seguenti tabelle (schema semplificato):

```sql
-- Tabelle dati grezzi
CREATE TABLE raw_rsn_data (...);
CREATE TABLE raw_tilt_data (...);
CREATE TABLE raw_atd_data (...);

-- Tabelle dati elaborati
CREATE TABLE elaborated_rsn_data (...);
CREATE TABLE elaborated_tilt_data (...);
CREATE TABLE elaborated_atd_data (...);

-- Tabelle configurazione
CREATE TABLE control_units (...);
CREATE TABLE chain_nodes (...);
CREATE TABLE sensor_calibration (...);
CREATE TABLE installation_parameters (...);

-- Tabelle monitoring
CREATE TABLE sensor_alerts (...);
CREATE TABLE alarm_devices (...);
```

**Nota**: Per schema completo, vedere documentazione database del progetto originale.

### 2. Verifica File Configurazione Sensori

Per ATD con calcolo stella, verificare presenza file Excel:
```
<IDcentralina>-<catena>.xlsx
```

Esempio: `CU001-A.xlsx`

### 3. Configura Logging

I log vengono salvati nella directory corrente. Per cambiarla:

```python
# In codice chiamante
from src.common.logging_utils import setup_logger

logger = setup_logger(
    control_unit_id="CU001",
    chain="A",
    module_name="RSN",
    log_dir="/var/log/sensor_processing"  # Directory personalizzata
)
```

## Test Installazione

### Test 1: Import Moduli

```bash
python << EOF
from src.common.database import DatabaseConnection
from src.rsn.main import process_rsn_chain
from src.tilt.main import process_tilt_chain
from src.atd.main import process_atd_chain
print("✓ All imports successful")
EOF
```

### Test 2: Esegui Esempi

```bash
python example_usage.py
```

Output atteso:
```
╔==========================================================╗
║  Sensor Data Processing System - Python Examples        ║
╚==========================================================╝

[... vari test ...]

Summary
============================================================
✓ PASS: Data Validation
✓ PASS: Logging Setup
✓ PASS: Database Connection

Total: 3/3 examples passed
```

### Test 3: Elaborazione Dati Reali

```bash
# RSN
python -m src.rsn.main CU001 A

# Tilt
python -m src.tilt.main CU001 B

# ATD
python -m src.atd.main CU001 C
```

Verifica:
1. File log creati: `LogFile_<MODULE>-<UNIT>-<CHAIN>-*.txt`
2. Dati scritti nel database
3. Nessun errore critico nei log

## Configurazione Produzione

### 1. Variabili d'Ambiente

Invece di DB.txt, usa variabili d'ambiente:

```bash
export DB_HOST="192.168.1.100"
export DB_PORT="3306"
export DB_NAME="ase_monitoring"
export DB_USER="sensor_user"
export DB_PASSWORD="securepassword"
```

Modifica `common/database.py` per leggere env vars:
```python
import os

class DatabaseConfig:
    def __init__(self):
        self.config = {
            'database': os.getenv('DB_NAME'),
            'user': os.getenv('DB_USER'),
            'password': os.getenv('DB_PASSWORD'),
            # ...
        }
```

### 2. Systemd Service (Linux)

Crea `/etc/systemd/system/sensor-rsn@.service`:

```ini
[Unit]
Description=Sensor RSN Processing for %i
After=network.target mysql.service

[Service]
Type=oneshot
User=sensor
WorkingDirectory=/opt/sensor_processing
Environment="PYTHONUNBUFFERED=1"
ExecStart=/opt/sensor_processing/venv/bin/python -m src.rsn.main %i A
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

Attiva:
```bash
sudo systemctl daemon-reload
sudo systemctl enable sensor-rsn@CU001.service
sudo systemctl start sensor-rsn@CU001.service
sudo systemctl status sensor-rsn@CU001.service
```

### 3. Cron per Elaborazione Periodica

```bash
crontab -e
```

Aggiungi:
```cron
# Elabora RSN ogni ora
0 * * * * cd /opt/sensor_processing && /opt/sensor_processing/venv/bin/python -m src.rsn.main CU001 A >> /var/log/sensor/rsn.log 2>&1

# Elabora Tilt ogni 6 ore
0 */6 * * * cd /opt/sensor_processing && /opt/sensor_processing/venv/bin/python -m src.tilt.main CU001 B >> /var/log/sensor/tilt.log 2>&1

# Elabora ATD una volta al giorno alle 02:00
0 2 * * * cd /opt/sensor_processing && /opt/sensor_processing/venv/bin/python -m src.atd.main CU001 C >> /var/log/sensor/atd.log 2>&1
```

### 4. Monitoring con Supervisor

Installa supervisor:
```bash
sudo apt-get install supervisor  # Ubuntu/Debian
```

Crea `/etc/supervisor/conf.d/sensor-processing.conf`:

```ini
[program:sensor-rsn-cu001]
command=/opt/sensor_processing/venv/bin/python -m src.rsn.main CU001 A
directory=/opt/sensor_processing
user=sensor
autostart=true
autorestart=true
stderr_logfile=/var/log/sensor/rsn-cu001.err.log
stdout_logfile=/var/log/sensor/rsn-cu001.out.log
```

Ricarica:
```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status
```

### 5. Docker (Opzionale)

Crea `Dockerfile`:

```dockerfile
FROM python:3.9-slim

WORKDIR /app

# Installa dipendenze
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copia codice
COPY src/ ./src/
COPY DB.txt .

# Entry point
ENTRYPOINT ["python", "-m"]
CMD ["src.rsn.main", "CU001", "A"]
```

Build e run:
```bash
docker build -t sensor-processing .
docker run -d --name rsn-cu001 sensor-processing
```

## Troubleshooting

### Problema: ModuleNotFoundError

```
ModuleNotFoundError: No module named 'src'
```

**Soluzione**:
```bash
# Assicurati di essere nella directory corretta
cd /path/to/matlab_func

# Aggiungi al PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

# Oppure installa come package
pip install -e .
```

### Problema: MySQL Connection Refused

```
Error 2003: Can't connect to MySQL server
```

**Soluzioni**:
1. Verifica MySQL in esecuzione: `sudo systemctl status mysql`
2. Controlla bind-address in `/etc/mysql/mysql.conf.d/mysqld.cnf`
3. Verifica firewall: `sudo ufw allow 3306`
4. Testa connessione: `telnet host 3306`

### Problema: Permission Denied per log files

```
PermissionError: [Errno 13] Permission denied: 'LogFile_...'
```

**Soluzioni**:
1. Crea directory log: `mkdir -p /var/log/sensor && chmod 755 /var/log/sensor`
2. Cambia ownership: `sudo chown sensor:sensor /var/log/sensor`
3. Oppure usa directory home: `log_dir="~/sensor_logs"`

### Problema: Dati non trovati

```
No data found for unit CU001, chain A
```

**Verifiche**:
1. Controlla database: `SELECT COUNT(*) FROM raw_rsn_data WHERE IDcentralina='CU001'`
2. Verifica date iniziali nella configurazione
3. Controlla log per errori di query

## Performance Tuning

### 1. Batch Size

Per grandi volumi di dati:
```python
# In db_write.py, aumenta batch size
BATCH_SIZE = 10000  # invece di 1000
```

### 2. NumPy Threads

```bash
export OMP_NUM_THREADS=4
export MKL_NUM_THREADS=4
```

### 3. MySQL Tuning

In `/etc/mysql/mysql.conf.d/mysqld.cnf`:
```ini
[mysqld]
innodb_buffer_pool_size = 2G
max_allowed_packet = 64M
bulk_insert_buffer_size = 256M
```

## Supporto

### Log Files
- Controllare sempre i log file generati
- Livello di log regolabile in `logging_utils.py`

### Debug Mode
```bash
# Attiva logging verbose
export LOG_LEVEL=DEBUG
python -m src.rsn.main CU001 A
```

### Contatti
- Documentazione: [src/README.md](src/README.md)
- Migration Guide: [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md)
- Issue tracker: [repository issues]

---

**Data setup**: 2025-10-12
**Versione**: 1.0
**Python richiesto**: 3.8+