Documentazione SmactBot

Indice

1. Panoramica
2. Requisiti
3. Configurazione
4. Struttura del Progetto
5. Descrizione Dettagliata dei File
6. Funzionalità Principali
7. Comandi del Bot
8. Variabili e Configurazioni
9. Avvio del Progetto
10. Personalizzazione
11. Risoluzione dei Problemi
12. Contribuire
13. Licenza

Panoramica

SmactBot è un bot Telegram avanzato progettato per interagire con varie fonti di dati, generare report e fornire monitoraggio e avvisi in tempo reale. Il bot supporta il recupero di dati da Modbus, OPCUA e richieste API, e può generare report giornalieri in formato PDF. È ideale per ambienti industriali o di monitoraggio che richiedono una supervisione costante e report dettagliati.

Requisiti

Per eseguire SmactBot, assicurati di avere installato Python 3.7 o versioni successive. Inoltre, è necessario installare i seguenti pacchetti Python. Crea un file

nella directory principale del progetto con il seguente contenuto:

pyTelegramBotAPI==4.12.0
pandas==2.0.3
influxdb-client==1.26.0
plotly==5.12.0
numpy==1.24.4
Pillow==10.0.0
reportlab==3.6.0
qrcode==7.3.1

Per installare tutte le dipendenze, esegui il seguente comando nella directory del progetto:

Configurazione

La configurazione di SmactBot avviene principalmente attraverso il file

. Crea questo file nella directory principale del progetto con il seguente contenuto:

Assicurati di sostituire 'IL_TUO_TOKEN_BOT_TELEGRAM' con il token effettivo del tuo bot Telegram e 'la_tua_password' con una password sicura per l'autenticazione degli utenti.

Struttura del Progetto

Il progetto SmactBot è organizzato nei seguenti file Python:

SmactBot/
│
├── main.py
├── data_handler.py
├── graph_utils.py
├── report_generator.py
├── monitoring.py
├── config.py
├── requirements.txt
└── README.md

Descrizione Dettagliata dei File

main.py

Questo è lo script principale che inizializza ed esegue il bot. Include vari gestori per diversi comandi e funzionalità come autenticazione, recupero dati, generazione di grafici, invio di report e monitoraggio delle variabili.

Funzioni principali:

• handle_start(message)
  : Gestisce il comando '/start'.
• handle_password(message)
  : Gestisce l'autenticazione dell'utente.
• handle_category(message)
  : Presenta le opzioni per le categorie di dati.
• handle_query(call)
  : Gestisce le query inline per la visualizzazione dei dati.
• handle_daily_report(message)
  : Genera e invia il report giornaliero.
• handle_monitor_toggle(message)
  : Attiva/disattiva il monitoraggio per l'utente.

data_handler.py

Questo script gestisce il recupero dei dati da InfluxDB. Utilizza la libreria influxdb-client per interrogare i dati in base alla categoria e alla metrica specificate.

Funzioni principali:

• fetch_data(category, metric, period='-1h')
  : Recupera i dati da InfluxDB in base alla categoria e alla metrica specificate.

graph_utils.py

Questo script crea grafici dai dati utilizzando la libreria plotly.

Funzioni principali:

• create_graph(dataframe, title, metric, current_value)
  : Crea un grafico utilizzando Plotly e lo restituisce come immagine.

report_generator.py

Questo script genera report giornalieri in formato PDF utilizzando la libreria reportlab.

Funzioni principali:

• generate_daily_report()
  : Genera un report giornaliero PDF e restituisce il contenuto del report e il percorso del file.

monitoring.py

Questo script contiene una funzione di monitoraggio che controlla continuamente le modifiche in una variabile specifica e invia notifiche agli utenti.

Funzioni principali:

• monitor_variable()
  : Monitora continuamente una variabile specifica e invia notifiche in caso di cambiamenti.

Autenticazione

Il bot richiede agli utenti di autenticarsi con una password prima di accedere alle funzionalità. Questo è gestito nella funzione

in

bot_handler.py

.

Recupero Dati

I dati vengono recuperati da InfluxDB utilizzando la funzione

in

data_handler.py

. Questa funzione supporta diverse categorie di dati (Modbus, OPCUA, API) e metriche specifiche.

Generazione di Grafici

I grafici vengono creati utilizzando la funzione

in

graph_utils.py

. Questa funzione utilizza Plotly per generare grafici interattivi che vengono poi convertiti in immagini.

Report Giornalieri

I report giornalieri vengono generati utilizzando la funzione

in

report_generator.py

. Questa funzione crea un PDF con un riepilogo delle metriche e lo salva localmente.

Monitoraggio in Tempo Reale

Il monitoraggio in tempo reale è gestito dalla funzione

in

monitoring.py

. Questa funzione controlla continuamente le modifiche in una variabile specifica e invia notifiche agli utenti quando vengono rilevate variazioni.

Comandi del Bot

Il bot supporta i seguenti comandi:

• /start
  : Avvia il bot e richiede la password.
• 🔧 Modbus
  : Visualizza le metriche disponibili in Modbus.
• 📊 OPCUA
  : Visualizza le metriche disponibili in OPCUA.
• 🌐 Richiesta API
  : Visualizza le metriche disponibili nelle richieste API.
• 📝 Report Giornaliero
  : Genera e invia un report giornaliero.
• 🔔 Monitora Variabile
  : Attiva/disattiva il monitoraggio delle variabili.
• ❓ Aiuto
  : Mostra un messaggio di aiuto con tutti i comandi disponibili.
• 🗑️ Elimina Chat
  : Elimina tutti i messaggi nella chat corrente.
• 🔗 Condividi Chat
  : Genera un codice QR e un link per invitare altri utenti.

Variabili e Configurazioni

Le principali variabili di configurazione sono definite nel file

:

• INFLUXDB_URL
  : L'URL del server InfluxDB.
• INFLUXDB_TOKEN
  : Il token di autenticazione per InfluxDB.
• INFLUXDB_ORG
  : Il nome dell'organizzazione in InfluxDB.
• INFLUXDB_BUCKET
  : Il nome del bucket in InfluxDB dove sono memorizzati i dati.
• TOKEN
  : Il token del bot Telegram.
• PASSWORD
  : La password per l'autenticazione degli utenti.
• INITIAL_IMAGE_PATH
  : Il percorso dell'immagine iniziale mostrata all'avvio del bot.
• BACKGROUND_IMAGE_PATH
  : Il percorso dell'immagine di sfondo utilizzata nei report PDF.
• ICON_PATH
  : Il percorso dell'icona utilizzata nei report PDF.

Altre variabili importanti:

• In
  report_generator.py
  , il dizionario
  fixed_metrics
  definisce le metriche disponibili per ogni categoria di dati.

Avvio del Progetto

Per avviare SmactBot, segui questi passaggi:

1. Assicurati di aver installato tutte le dipendenze elencate in
   requirements.txt
   .
2. Configura correttamente il file
   config.py
   con le tue impostazioni specifiche.
3. Posizionati nella directory principale del progetto.
4. Esegui il seguente comando:

Il bot si avvierà e attenderà le interazioni dell'utente. Puoi interagire con il bot utilizzando i comandi e le opzioni fornite nell'interfaccia Telegram.

Personalizzazione

Puoi personalizzare il comportamento del bot modificando le seguenti parti:

• Aggiungi nuove metriche nel dizionario
  fixed_metrics
  in
  report_generator.py
  .
• Modifica la frequenza di monitoraggio cambiando il valore di
  time.sleep()
  in
  monitoring.py
  .
• Personalizza il layout del report PDF modificando la funzione
  generate_daily_report
  in
  report_generator.py
  .
• Aggiungi nuovi comandi o funzionalità modificando
  main.py
  e aggiungendo nuovi gestori di messaggi.

Risoluzione dei Problemi

Se incontri problemi durante l'esecuzione del bot:

1. Verifica che tutte le dipendenze siano installate correttamente eseguendo
   pip list
   e confrontando con
   requirements.txt
   .
2. Controlla che il token del bot Telegram in
   config.py
   sia valido provando a crearne uno nuovo con BotFather su Telegram.
3. Assicurati che l'URL e le credenziali di InfluxDB in
   config.py
   siano corretti tentando una connessione manuale al database.
4. Controlla i log per eventuali errori specifici. Puoi aggiungere più stampe di debug nei vari file per tracciare il flusso di esecuzione.
5. Se il monitoraggio non funziona, verifica che la funzione
   monitor_variable
   in
   monitoring.py
   sia chiamata correttamente e che la connessione a InfluxDB sia stabile.
6. Per problemi con la generazione di grafici, assicurati che Plotly sia installato correttamente e che i dati recuperati da InfluxDB siano nel formato atteso.

Contribuire

Se desideri contribuire al progetto SmactBot, segui questi passaggi:

1. Forkare il repository su GitHub.
2. Clonare il fork sul tuo computer locale.
3. Creare un nuovo branch per le tue modifiche:

   git checkout -b feature/nuova-funzionalita
   

4. Apportare le modifiche e committarle:

   git commit -am 'Aggiunta nuova funzionalità'
   

5. Pushare il branch sul tuo fork:

   git push origin feature/nuova-funzionalita
   

6. Creare una Pull Request dal tuo fork al repository originale su GitHub.

Assicurati di seguire le best practices di codifica e di documentare adeguatamente qualsiasi nuova funzionalità o modifica.

Licenza

Questo progetto è distribuito sotto la licenza MIT. Vedi il file

nella directory principale del progetto per ulteriori dettagli.

La licenza MIT permette l'uso, la copia, la modifica, la fusione, la pubblicazione, la distribuzione, la sublicenza e/o la vendita di copie del software, a condizione che l'avviso di copyright e questa nota di permesso siano inclusi in tutte le copie o parti sostanziali del software.