# Schema protocolli

Il sistema MAPO impiega vari modi per comunicare tra client e server, di seguito la descrizione analitica dei meccanismi.

IN termini generali abbiamo degli acquisitori di campo (IOB-PI e IOB-WIN) che dialogano in modo elettrico o tramite protocolli di rete con le amchcine e colelazionano informazioni che poi trasferiscono al server MAPO cerntrale come elenco di segnali o come flusso log di paraetri/variabili rilevate.

| Vers | Data | Descrizione |
| -- | -- | -- |
| 0.9 | 2021.12.29| Prima versione documento specifiche |

## Glossario

Di seguito i principali termini impiegato ier MAPO

| Lemma | Descrizione |
| -- | -- |
| Ingresso / Segnale | Sono i segnali elettrici rilevabili nel quadro di una amchcina: esempio segnali 24v delle luci del fungo di segnalazione (verde/giallo/rosso), machcina accesa, contatto contapezzi. Equivalente ad un boolean / singolo bit|
| Evento | E' un informazione definita da tempo (datetime macchina poi con calcolo offset riportato a datetime server ufficiale) + codice evento. Genericamente un evento rappresenta un **fatto** riportato dalla amcchina/PLC/CNC, come ad esempio PowerON perso, Emergenza premuta, Allarme attivo, inizio stato manuale, segnalazione contapezzi |
| Stato | Indica quale sia, in un dato momento (e quindi "integrando l'informazione" per un intero periodo) la condizione (=stato) della amcchina: ad esempio macchina accesa, macchina in lavorazione, machcina in emergenza, amcchina in manuale...|
| Famiglia Ingressi | E' il codice univoco che indica una famiglia di machcine/impianti caratterizzate dal riportare lo stesso SET di segnali (esempio: emergenza armata = 1, emergenza premuta = 0 su un dato BIT, stato allarme quando un altro bit è 1... ) |
| Famiglia Macchina | E' il gruppo omogeneo con cui più macchine definiscono la loro specifica reazione agli eventi, per cui data una catena di eventi la macchina passa in uno stato|
| Tab Trans Ingressi | E' la tabella che codifica, per una specifica FamigliaIngressi, dato un micro-stato + un INSIEME di segnali rilevati (come condizione di N bit contemporaneamente rilevati) quale sia l'eventuale nuovo miscro-stato macchina + evento da inviare a MAPO IO |
| Tab Trans Stati | Indica, per una specifica famiglia di machcine, il comportamento che data una catena di eventi porta ad uno stato amcchina + eventualmente altri ricalcoli (es conteggio pezzi singoli, conteggio pezzi a gruppi, gestione machcine multipallet/multiprodotto, aggiornamento dati in cascata per impianti parent/child... ) |

<div style="page-break-after: always;"></div>


## Schema di funzionamento generale

Di base gli strati implementati normalizzano il meccanismo di acquisizione dati, comunicazione col server e gestione dello storico dei dati per un gruppo eterogeneo di oggetti (PLC/CNC/...) gestiti dal MES.

Per implementarlo con il massimo dell'efficienza computazionale si è scelto di utilizzare macchine a stati "congelate" in forma di tabelle di transizione chiave/valore in cui la chiave di ogni riga della tabella è dato alla ennupla **STATO + segnale**; se la riga esiste significa che all'avverarsi della condizione deve essere eseguito quanto indicato nel "valore" della KVP.

In questo modo si evita di dover scrivere (ed eseguire) codice di tipo "verifica di condizioni logiche" (if(condizione) esegui_a else esegui_b ...) che in caso di molti eventi concomitanti richiede piùà computazione e lo si trasforma in un lavoro di ricerca in array indicizzati della "soluzione" al caso.

Questo permette anche di modificare (a posteriori) una "Mappa logica" di regole e "rieseguire" la catena di eventi generando una nuova catena di risultati, utile in fase iniziale di setup (qualcosa potrebbe sfuggire come corner caso) ma anche a regime in caso di problemi di esecuzioni asincrone o propblemi di calcolo lato server che eprmettono di "rigenerare" la "tabella dei fatti" derivante dalla catena di eventi rilevati + regole SENZA modificare codice sorgente ma solo tabelle regole ed eseguendo query batch sul DB.


Abbiamo quindi il seguente schema logico di massima:

@startuml
PLC -> Iob: lettura segnali
Iob -> MapoIO: invio segnali
MapoIO -> Redis: seek LUT segnali
Redis -> MapoIO: Riga TabIngressi, evento
MapoIO -> DataLayer: registrazione evento
DataLayer -> DB: Registrazione Evento
DataLayer -> Redis: seek LUT eventi
Redis -> DataLayer: Riga TabStati, evento
DataLayer -> DB: Registrazione Stato
@enduml


I dati presenti sul DB sono poi utilizzati in modalità lettura dai programmi di monitoraggio (MapoMON), di analisi (MapoSIte, Mapo Stats) ed in modalità lettura/scrittura dai programmi di interazione utente (MapoAdm + Mapo TAB)

<div style="page-break-after: always;"></div>

## State machine

Le state amchine sono tabelle su SQL server codificate x definire in modo univoco il coportamento stato + nuova informazione --> azione.

Sono salvate in REDIS per permettere impiego in simultanea da parte di + agenti software (servers) con la massima velocità.

### Ingressi --> Eventi

La tabella ingressi --> eventi è costruita a partire dal sw MapoState creato dall'ing Carlo Viviani nel 2006 (..\Mapo-IOB\StateMachine\Sw MapoState) sulla abse di un file di regole (*.rul) che definisce come scrivere il file CSV che rappresenta la tabella in formato testuale.

Questa tabella viene poi importata in SQL saerver da apposito script di normalizzazione

Il file prevede un intestazione/setup (codice ID famiglia ingressi, num bit, numero micro stati gestiti, elenco eventi da inviare) e una aprte di regole gerarchiche per cui la regola più in alto è la prima che verrà eseguita nella catena realizzando quindi un elenco di righe di tipo LUT che determinano, per ogni combinazione degli eventi indicato, quale sia il NUOVO microstato + eventi da inviare

### Eventi --> Stati

Questa tabella, costruita a mano a suo tempo e gestita direttamente in SQL; determina cosa debba derivare da una xdata catena di eventi in termini di 

 * stato macchina
 * eventi di conteggio / rettifica
 * eventi / stati da trasmettere da una machcina da un altra

## IOB-PI

E' la versione HW ed iniziale del sistmea di acquisizione.

Basata su scheda custom (costruida da Claudio Baldi di CB Elettronica) su schema di Carlo Viviani, passata da una prima versione seriale x PC; a una seriale x PI a una parallela x PI a 8 ingressi fino alla versione atutale per raspberry Pi 4 a 12 ingressi.

Gli ingressi, optoisolati, leggono i segnali elettrici tipicamente a 24V (a gruppi di 3 con terra comune)

Il raspberry PI è in grado di 
  * campionare tipicamente a 10hz
  * inviare il segnale ad OGNI variazione rilevata (e comunque ogni minuto x funzionalità watchdog)
  * filtrare segnali blink (es verde lampeggiante --> verde)
  * invertire/negare segnali (Norm Aperto <--> Norm Chiuso)
  * filtrare segnali diventati "inutili" (x non inviare)
  * loggare in locale
  * accumulare in memoria i dati in caso di server NON funzionante (es x update/reboot) e ritrasmettere dopo anche a blocchi 

## IOB-MAN

E' il programma principale nella versione windows, si occupa di
  * garantire che siano eseguiti agenti di comunicazione per opgni PLC confugurato
  * tenere i pID dei processi
  * riavviare in caso di mancato aggiornamento/comunicazione da PLC e/o da server
  * gestire anomalie e blocchi dei sw di comunicazione 

## IOB-WIN

E' il vero programma di comunicazione che tramite classi specifiche per ogni tipo di PLC/modalità di comunicazione e per ogni costruttore determina come un dato sistema vada ritradotto int ermini di
  * catena di segnali/ingressi rilevati
  * log di eventi registrati (come campionamenti eventualmente filtrati/mediati)
  * inviare comandi alla machcina (es reset contapezzi, nuovo lotto, codice articolo...)
### Esempio catena segnali ed invio IOB-PI

Esempio di funzionamento in caso di segnali elettrici rilevati  ed inviati da IOB-PI

@startuml
PLC -> IobPI: B0 = 1
PLC -> IobPI: B1 = 1
PLC -> IobPI: B7 = 1
IobPI -> MapoIO: hex 83
MapoIO -> IobPI: OK!
PLC -> IobPI: B1 = 0
IobPI -> MapoIO: hex 81
MapoIO -> IobPI: OK!
@enduml



## IOB-WIN

## Schema funzionamento generale

