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

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)

# 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

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

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

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

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):

-- 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:

# 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

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

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

# 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:

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:

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:

[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:

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

crontab -e

Aggiungi:

# 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:

sudo apt-get install supervisor  # Ubuntu/Debian

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

[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:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status

5. Docker (Opzionale)

Crea 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:

docker build -t sensor-processing .
docker run -d --name rsn-cu001 sensor-processing

Troubleshooting

Problema: ModuleNotFoundError

ModuleNotFoundError: No module named 'src'

Soluzione:

# 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:

# In db_write.py, aumenta batch size
BATCH_SIZE = 10000  # invece di 1000

2. NumPy Threads

export OMP_NUM_THREADS=4
export MKL_NUM_THREADS=4

3. MySQL Tuning

In /etc/mysql/mysql.conf.d/mysqld.cnf:

[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

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

Contatti

• Documentazione: src/README.md
• Migration Guide: MIGRATION_GUIDE.md
• Issue tracker: [repository issues]

---

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