# Functions

Questa pagina è dedicata all'automazione vera e propria del sistema: mette a disposizione un meccanismo di scrittura e creazione di una o più funzioni (script PHP), ognuna contenente del codice da eseguire definito dagli utenti.

Functions

# Side panel

Le funzioni si classificano in due categorie, in base a come vengono gestite dal sistema PlexusLAB:

Static constants e Static functions (le prime nell'elenco a sinistra) sono funzioni eseguite solo una volta in fase di inizializzazione del sistema, in questo preciso ordine;
Tutte le altre funzioni sono invece eseguite ciclicamente e sono gli utenti a deciderne quantità, nome e in quale ordine eseguirle (dall'alto al basso nell'elenco sulla sinistra)

La lista delle funzioni è mostrata a sinistra, ognuna identificata con il proprio nome. L'icona e l'etichetta possono avere colore:

blu, per identificare la funzione che è correntemente visualizzata;
grigio, tutte le altre funzioni

L'icona può essere di due tipi, e identifica un'eventuale differenza tra la versione salvata e la versione uploadata (ulteriori dettagli sotto):

quando la funzione che sta eseguendo il sistema è esattamente quella mostrata nell'editor o, per usare altre parole, quando non ne esiste una versione in bozza su cui si sta lavorando;
quando la funzione che sta eseguendo il sistema differisce da quella mostrata nell'editor. Questo avviene quando si effettua una modifica alla funzione, si effettua un salvataggio, e non è ancora stato effettuato l'upload

# Attivare/Disattivare una funzione

Un interruttore alla destra del nome indica se la funzione corrispondente è attualmente attiva o disattiva nel flusso di esecuzione ciclico.

Quando una funzione è attiva, lo stato può essere Running, se la funzione è eseguita come previsto, oppure Error se l'esecuzione è andata in errore per qualche motivo (eccezione in fase di esecuzione dello script, ad esempio);
Quando invece una funzione è disattivata, il codice che contiene sarà del tutto ignorato. Il suo stato sarà sempre indicato come Not active

# Aggiungere una funzione

Aggiungere una nuova funzione è possibile grazie al pulsante "ADD FUNCTION": al click si apre una finestra per l'inserimento del nome della funzione, che deve rispettare i criteri di nomenclatura Plexus

# Riordinare le funzioni

È possibile riordinare le funzioni tramite il pulsante "Edit Order" in fondo alla lista delle funzioni: al click si apre una finestra che mostra la lista delle funzioni nell'ordine attuale. Trascinandole con il puntatore sarà possibile riordinarle a piacimento, per cambiarne l'ordine di esecuzione.

TIP

Il pulsante "Edit Order" viene visualizzato solo quando sono presenti 2 o più Functions.

Esempio di esecuzione Ladder Logic: la variabile FOO è sovrascritta dalla functionTwo per diventare 1 invece che 100, poichè la functionOne viene prima di functionTwo nell'ordine

# Static constants

L'uso della Static constants è consigliato per la definizione di costanti e variabili enumerative globali, in modo che possano essere richiamate all'interno di altre functions.

Static constants

# Static functions

La Static functions permette di dichiarare eventuali custom API definite a livello globale che possono essere richiamate all'interno delle altre functions. Alcuni esempi sono mostrati nelle Appendici. Le funzioni globali sono create dallo sviluppatore di codice per adempiere a task specifici e personalizzati qualora questi debbano essere svolti frequentemente e richiedano diverse righe di istruzioni. Aiutano inoltre a mantenere ordinato e comprensibile l'intero programma.

Static function

# Aspetto

# Top Bar

Sopra il codice di ogni funzione appare una "top bar" che raccoglie pulsanti di diverse utility:

Function Top bar

Icon	Name	Information
	Cerca in Functions	Permette all'utente di ricercare un termine nelle functions; non-case-sensitive
	Cerca in Devices/Sections	Permette all'utente di ricercare un termine nelle Sections/nei Devices; non-case-sensitive
	Fold / Unfold Code	Permette di minimizzare il codice visualizzato, seguendo il flusso di ramificazione del linguaggio PHP
	Allineamento	Allinea il codice
	Messaggi di Debug	Permette di visualizzare i messaggi di debug impostati. L'icona si colora di giallo quando è presente almeno un messaggio
	API List	Libreria delle funzioni API da usare
	Salva	Salva le modifiche apportate al codice, l'icona diventa verde solo se sono state apportate modifiche. Ricorda di effettuare l'upload della funzione dopo averla salvata, altrimenti il sistema eseguirà il codice precedente
	Upload	Permette di fare l'upload della funzione dopo averla modificata e salvata. L'icona si colora di blu quando è presente una versione salvata che non corrisponde a quella attualmente in esecuzione
	Info	Permette di modificare il nome della function e di eliminarla

# Scrivere ed eseguire le funzione

Partendo da zero, il flusso generale per iniziare ad automatizzare un sistema è:

Creare una funzione;
Scrivere il codice (è possibile far riferimento alla nostra API List per conoscere le funzioni di default offerte da PlexusLAB, per il resto valgono le funzioni offerte da PHP, versione 7 o 8 a seconda dell'installazione effettuata);
Salvare la funzione;
Upload della funzione;
Attivare la funzione

# Autocompletamento

All'interno dell'editor di sviluppo del codice è disponibile un meccanismo di auto-completamento, che aiuta a rintracciare nomi di variabili, canali, funzioni e costanti definite nelle Static.

Autocomplete

# Regole e reminders

Attenzione

Il codice deve rispettare la sintassi PHP, versione 7 o 8 a seconda dell'installazione effettuata;
Le funzioni sono eseguite dal'alto verso il basso (Ladder Logic), dalla prima all'ultima, in ordine. Le funzioni eseguite a valle possono sovrascrivere i valori impostati da quelle a monte;
Evitare di utilizzare cicli 'while' per non interrompere il flusso di programma, o assicurati di avere delle condizioni di uscita e di non effettuare cicli troppo lunghi;
Disattivare le funzioni non ripristinerà i valori che sono stati già scritti!
Per leggere e scrivere uno specifico channel di un device, quel device deve essere acceso

# Functions Library API

General APIs

if / Read
if / Read / Write
Comment Title
Comment Small
debug_message('message')
info_message('message', 'INFO')
function_active('function_id')

Variable APIs

read_val('var_name')
read_future_val('var_name', $seconds_future)
write_val('var_name', $value)
write_val_delay('var_name', $value, $msDelay)
reset_val_delay('var_name')
write_val_period('var_name', $value1, $value2, $ms1, $ms2)
reset_val_period('var_name')
write_val_ramp('var_name', $rampValueStart, $rampValueEnd, $msRampDuration)
reset_val_ramp('var_name')
write_val_at_time('var_name', $value, '16:20')
write_val_at_time_range('var_name', $value, '16:20', '16:30')
disable('var_name')
enable('var_name')
get_bounded_value($input_value, $min_value, $max_value)
is_value_inside_target_range($input_value, $target_value, $offset = null)
is_value_inside_target_range_mod($input_value, $input_min, $input_max, $target_value, $offset = null)
scale_value($input_value, $input_1, $input_2, $output_1, $output_2, $round = true)
to_bitmap($values, $lsb_first = true, $signed = false)
from_bitmap($bitmap, $length = 16)
increment_cycling_variable($var_name, $max_value_before_reset, $var_reset_value = 0)
watchdog_on_bit_inversion($watchdog_timer_name, $watchdog_timeout_var, $watchdog_actual_value)
moving_average('var_name', $window_in_samples)
reset_moving_average('var_name', $window_in_samples)
fixed_average('var_name', $window_in_seconds)
reset_fixed_average('var_name', $window_in_seconds)
moving_max('var_name', $window_in_seconds)
reset_moving_max('var_name', $window_in_seconds)
moving_min('var_name', $window_in_seconds)
reset_moving_min('var_name', $window_in_seconds)

Timers APIs

start_timer('timer_name')
reset_timer('timer_name')
pause_timer('timer_name',1)
timer_running('timer_name')
read_timer('timer_name')
set_timer_duration('timer_name', $duration)

Alert APIs

set_alert('alert_name', 'message', ['subordinated_alert_name_1', ...])
set_alert_delay('alert_name', 'message', $msDelay, ['subordinated_alert_name_1', ...])
reset_alert('alert_name')
alert_active('alert_name')
any_alert_active()

Stepper APIs

start_step('step_name')
read_step('step_name')
set_step('step_name', $value)

PID control APIs

PID_controller('PID_name', $PID_params)
reset_PID_controller('PID_name')
PWM_controller('var_name', $duty, $msPeriod)
reset_PWM_controller('var_name')

Una lista di ogni Funzione API nel dettaglio è disponibile qui.

← Sections Alerts →