IKON Server - Domotica Labs · • Nel caso di comando diretto dall'interfaccia del FRONTEND di...

IKON SERVER

SCRIPTING

VERSIONE SOFTWARE 1.1.3

INDICE

1 INTRODUZIONE........................................................................................................................... 6

1.1 COSA È IKON SERVER........................................................................................................ 6

1.2 COSA È QUESTO MANUALE.............................................................................................. 6

1.3 REQUISITI............................................................................................................................. 6

2 PANORAMICA GENERALE......................................................................................................... 7

2.1 SCRIPTS............................................................................................................................... 7

2.2 SCRIPT RUNNERS............................................................................................................... 7

2.3 LIBRERIE.............................................................................................................................. 8

2.4 INPUT E OUTPUT................................................................................................................. 9

2.5 DEBUG, INFO ED ERRORI................................................................................................. 11

2.6 INCLUSIONE DI SCRIPTS.................................................................................................. 12

3 SCRIPTS..................................................................................................................................... 14

3.1 INTRODUZIONE..................................................................................................................14

3.2 PAGINA DI GESTIONE DEGLI SCRIPTS........................................................................... 14

3.3 CONSULTAZIONE O MODIFICA DI UNO SCRIPT............................................................. 15

3.4 ESEMPIO............................................................................................................................ 16

4 SCRIPT RUNNERS.....................................................................................................................17

4.1 INTRODUZIONE..................................................................................................................17

4.2 CREAZIONE DI UNO SCRIPT RUNNER............................................................................ 17

4.2.1 Ingressi....................................................................................................................... 18

4.2.2 Uscite.......................................................................................................................... 19

4.3 DEBUG................................................................................................................................ 19

4.4 ESECUZIONE IN BACKGROUND...................................................................................... 21

4.5 VISUALIZZAZIONE NEL FRONTEND................................................................................ 21

5 LIBRERIA “OBJECT”................................................................................................................ 22

5.1 INTRODUZIONE..................................................................................................................22

5.2 INCLUSIONE DELLA LIBRERIA........................................................................................ 22

5.3 CARICARE UN OGGETTO................................................................................................. 22

5.4 RELAZIONI CON ALTRI OGGETTI.....................................................................................24

5.5 COMANDO DI OGGETTI.................................................................................................... 29

5.6 AGGIORNAMENTO DI OGGETTI CON IL DATABASE...................................................... 31

6 LIBRERIA “SURROUNDING”.................................................................................................... 33

6.1 INTRODUZIONE..................................................................................................................33


6.3 AMBIENTE “DI CONTORNO” DELLO SCRIPT RUNNER................................................. 33

6.4 ESEMPI............................................................................................................................... 34

7 LIBRERIA “SERIAL”.................................................................................................................. 36

7.1 INTRODUZIONE..................................................................................................................36


7.3 INIZIALIZZAZIONE DELLA PORTA....................................................................................36

7.4 SCRITTURA SULLA SERIALE........................................................................................... 37

7.5 LETTURA DALLA SERIALE............................................................................................... 37

7.6 ACCESSO DIRETTO ALLA SERIALE................................................................................ 38

8 LIBRERIA “MODBUS”............................................................................................................... 39

8.1 INTRODUZIONE..................................................................................................................39


8.3 ASSEGNAZIONE DEL DISPOSITIVO MODBUS SLAVE................................................... 39

8.4 LETTURA DI REGISTRI...................................................................................................... 40

8.5 LETTURA DI COILS............................................................................................................ 40

8.6 SCRITTURA DI REGISTRI.................................................................................................. 40

8.7 SCRITTURA DI COILS........................................................................................................ 41

8.8 LETTURA E SCRITTURA DI REGISTRI............................................................................. 42

8.9 CONVERSIONE DEI VALORI LETTI DAL DISPOSITIVO...................................................42

8.9.1 Valori su 4 byte .......................................................................................................... 42

8.9.2 Valori su 2 byte .......................................................................................................... 43

9 LIBRERIA “SONOS”.................................................................................................................. 45

9.1 INTRODUZIONE..................................................................................................................45


9.3 ASSEGNAZIONE DEL DISPOSITIVO SONOS................................................................... 45

9.4 CONTROLLO DEL DISPOSITIVO SONOS.........................................................................46

9.5 REGOLAZIONE DEL VOLUME.......................................................................................... 47

9.6 MODALITÀ DI RIPRODUZIONE......................................................................................... 47

9.7 INFORMAZIONI MULTIMEDIALI........................................................................................ 48

9.8 ESEMPIO DI CONFIGURAZIONE.......................................................................................48

9.8.1 Creazione OGGETTO COMPOSITO........................................................................... 48

9.8.2 Creazione e associazione degli script runner.......................................................... 50

10 LIBRERIA “DUNE”................................................................................................................... 53

10.1 INTRODUZIONE................................................................................................................53

10.2 INCLUSIONE DELLA LIBRERIA...................................................................................... 53

10.3 ASSEGNAZIONE DEL DISPOSITIVO DUNE....................................................................53

10.4 CHIAMATE GENERICHE AL DISPOSITIVO DUNE.......................................................... 54

10.5 CONTROLLO DEL DISPOSITIVO DUNE......................................................................... 54

10.6 EMULAZIONE TELECOMANDO...................................................................................... 55

10.7 GESTIONE DELLA RIPRODUZIONE............................................................................... 56

11 LIBRERIA “MESSAGES”......................................................................................................... 57

11.1 INTRODUZIONE................................................................................................................ 57

11.2 INCLUSIONE DELLA LIBRERIA...................................................................................... 57

11.3 INVIO DI UNA NOTIFICA A VIDEO................................................................................... 57

11.4 INVIO DI UNA NOTIFICA VIA EMAIL................................................................................58

12 ESEMPI..................................................................................................................................... 59

12.1 INTRODUZIONE................................................................................................................59

12.2 LOGIC.AND....................................................................................................................... 59

12.3 LOGIC.OR......................................................................................................................... 59

12.4 SERIAL.WRITER_GENERIC............................................................................................ 60

12.5 DEMUX.STATUSBYTE...................................................................................................... 61

12.6 MATH.SUM........................................................................................................................ 63

12.7 MATH.PRODUCT.............................................................................................................. 63

12.8 MODBUS.READCOILS..................................................................................................... 64

12.9 MODBUS.READREGISTERS........................................................................................... 67

12.10 MODBUS.WRITECOILS..................................................................................................68

12.11 SONOS.GENERIC........................................................................................................... 69

12.12 SONOS.SETVOLUME..................................................................................................... 70

12.13 SONOS.GETVOLUME.................................................................................................... 70

12.14 SONOS.PLAYPAUSE...................................................................................................... 70

12.15 SONOS.PREVNEXT........................................................................................................ 71

12.16 SONOS.SETPLAYMODE................................................................................................ 71

12.17 SONOS.GETINFO........................................................................................................... 71

12.18 DUNE.ONOFF................................................................................................................. 72

12.19 DUNE.PLAYPAUSE........................................................................................................ 72

12.20 DUNE.SETVOLUME....................................................................................................... 72

12.21 DUNE.IRCOMMAND....................................................................................................... 73

12.22 DEWPOINT..................................................................................................................... 73

13 APPENDICI............................................................................................................................... 74

13.1 TIPI FUNZIONALI DI OGGETTO...................................................................................... 74

13.2 TIPI WEB (PHPCLASS) DI OGGETTO............................................................................. 75

14 NOTE DI RILASCIO.................................................................................................................. 77

14.1 VERSIONE 1.0.2............................................................................................................... 77

14.2 VERSIONE 1.1.0............................................................................................................... 77

1 INTRODUZIONE

1.1 COSA È IKON SERVERIKON SERVER è un webserver di supervisione per impianti di home & building automation basati su tecnologia KNX, sviluppato e commercializzato da DOMOTICA LABS. Sul sito www.domoticalabs.com è possibile scaricare gratuitamente schede tecniche, brochure e manuali per l'installazione, la configurazione e l'utilizzo di IKON SERVER.

1.2 COSA È QUESTO MANUALEQuesto manuale illustra le funzionalità offerte dal motore di scripting personalizzato di IKON SERVER, mediante il quale è possibile estendere le funzioni base del webserver; attraverso gli script è possibile:

• Interagire con gli oggetti della supervisione, leggendo stati, effettuando logiche ed inviando comandi

• Inviare messaggi di notifica personalizzati

• Interagire con il sistema operativo

• Inviare e ricevere stringhe attraverso la rete LAN e la porta seriale

Il manuale guida l'installatore passo a passo nella realizzazione di uno script personalizzato ed alla sua esecuzione nell'ambiente di runtime di IKON SERVER; sono inoltre analizzati nel dettaglio gli esempi presenti sul webserver, che offrono una panoramica completa delle funzionalità offerte da questa tecnologia.

1.3 REQUISITIPer poter sfruttare appieno le potenzialità del motore di scripting di IKON SERVER, è necessario disporre di:

• IKON SERVER dotato di licenza per il modulo di scripting

• Buona conoscenza di IKON SERVER

• Buona conoscenza di ETS e della tecnologia KNX

• Conoscenza, anche a livello base, del linguaggio di scripting PHP

IKON SERVER – SCRIPTING PERSONALIZZATO – PAGINA 6

http://www.domoticalabs.com/

2 PANORAMICA GENERALE

2.1 SCRIPTSGli SCRIPTS sono files contenenti codice in linguaggio PHP che è possibile creare e memorizzare sul disco flash di IKON SERVER attraverso un'apposita sezione nell'ambiente di amministrazione di IKON SERVER. Questi files possono essere creati, modificati e cancellati attraverso un'apposita pagina grafica, mediante la quale è anche possibile esportarli ed importarli su un altro webserver.

I files rimangono memorizzati sul disco di IKON SERVER e persistono anche a seguito di un ripristino dei parametri di fabbrica; d'altro canto, essi non sono compresi nel file di backup di IKON SERVER, pertanto devono essere esportati (e, successivamente, importati) separatamente se di vuole portare il progetto su un altro webserver.

Gli SCRIPTS devono essere realizzati seguendo le indicazioni contenute in questo manuale, facendo uso delle librerie e delle funzioni messe a disposizione dal motore di scripting; qualunque codice che esuli da queste indicazioni può potenzialmente compromettere il corretto funzionamento di IKON SERVER.

IKON SERVER è già dotato di una serie di esempi che offrono una panoramica completa delle potenzialità offerte dal sistema di scripting; non è prevista la modifica o esecuzione diretta di questi esempi, ma è possibile duplicarli e lavorare sulla copia senza alcuna restrizione.

2.2 SCRIPT RUNNERSUna volta creato uno script personalizzato (ex novo oppure duplicando e modificando un esempio), è necessario associarlo ad uno o più oggetti di tipo “script runner”; questi particolari oggetti hanno il compito di eseguire il codice contenuto nello script a cui sono associati, ogni qualvolta

• vengano comandati direttamente dall'utente nel FRONTEND di IKON SERVER, interagendo con il “box” relativo nelle pagine ambiente o funzione

• cambi il valore di uno degli oggetti associati come EVENTI PASSIVI, così come accade per qualunque altra tipologia di oggetto in IKON SERVER

Gli SCRIPTS non possono essere pertanto eseguiti direttamente, ma solo attraverso uno SCRIPT RUNNER, che si comporta in modo del tutto analogo alle altre tipologie di oggetto: ha un'icona ed un valore associati, può essere inserito negli AMBIENTI, nelle FUNZIONI o nei PREFERITI, può essere associato ad altri oggetti mediante EVENTI ATTIVI o PASSIVI, far parte di uno SCENARIO etc...

Il vantaggio di avere una struttura basata su SCRIPTS e SCRIPT RUNNERS distinti è duplice:

• Possibilità di associare lo stesso SCRIPT a più di un oggetto RUNNER, a sua volta inserito in logiche, eventi, scenari etc... differenti e quindi in grado di manipolare dati differenti

• Possibilità di esportare, importare e condividere gli script a prescindere dal progetto realizzato

Lo schema seguente illustra a livello di principio le interazioni tra uno SCRIPT RUNNER e gli oggetti associati tramite EVENTI, oppure il suo comando attraverso le pagine di RUNTIME del webserver:


2.3 LIBRERIEIKON SERVER mette a disposizione una serie di librerie, che offrono strumenti già pronti per l'interazione con i principali aspetti coperti dal motore di scripting. Le librerie non sono automaticamente incluse all'interno degli scripts, ma devono essere richiamate mediante direttive del tipo

include_library(<nome della libreria>);

Esempio:

include_library(“serial”);

Giacché l'inclusione di ogni libreria comporta un tempo di elaborazione, si consiglia l'inclusione delle sole librerie strettamente necessarie al compito che deve svolgere lo script. Le librerie possono a loro volta dipendere da altre librerie; in questo caso, non è necessario includere anche le librerie correlate, in quanto l'inclusione avviene automaticamente richiamando la libreria che presenta le dipendenze.

La tabella seguente riporta un elenco delle librerie disponibili, una sintetica descrizione e le eventuali dipendenze; nei capitoli successivi saranno esaminate nel dettaglio.


<?phpinclude_library(“surrunding”);$value = $in1->value + $in2->value;output($value);?>

Script

Script Runner

Oggetti “padri” Oggetti “figli”

EventiPassivi

EventiAttivi

Pagina web runtime

Box script runner

Libreria Descrizione Dipendenze

db Permette di interagire con il database di IKON SERVER, effettuando query SQL di interrogazione oppure di modifica, inserimento o cancellazione di dati.

object Permette di interagire con gli oggetti della supervisione di IKON SERVER; è possibile leggere il valore degli oggetti, modificarne le proprietà o inviare comandi ad essi

db

surrounding Offre un insieme di oggetti per interagire comodamente con l'oggetto SCRIPT RUNNER che sta eseguendo lo script ed i relativi EVENTI ATTIVI e PASSIVI

db

object

serial Permette di leggere e scrivere stringhe attraverso la seriale RS232 di IKON SERVER, oppure attraverso un adattatore USB-SERIALE compatibile

modbus Permette di gestire uno o più dispositivi MODBUS SLAVE attraverso la rete TCP/UDP, leggendo e scrivendo valori

2.4 INPUT E OUTPUTQuando l'oggetto SCRIPT RUNNER viene eseguito, esso riceve sempre un valore di INPUT; in particolare:

• Nel caso di comando diretto dall'interfaccia del FRONTEND di IKON SERVER, il valore è dato dall'input dell'utente (es: digitando un valore in una casella di testo, oppure premendo un pulsante – dipende dall'aspetto grafico scelto per lo SCRIPT RUNNER)

• Nel caso di comando a seguito della variazione di stato di uno degli oggetti “padri” associati come EVENTI PASSIVI allo SCRIPT RUNNER, il valore di input è dato dalle proprietà dell'evento stesso, così come definito in amministrazione. In particolare, è possibile passare come valore:

◦ Il valore dell'oggetto che cambia di stato, e che determina l'esecuzione dell'evento

◦ Un valore costante

In entrambi i casi, il valore di input è disponibile all'interno dello script richiamando la funzione

input()

Esempio:

$val = input();

A seconda del tipo di comando e delle proprietà dell'evento che manda in esecuzione lo SCRIPT RUNNER, il valore restituito da questa funzione può essere numerico oppure una stringa; il linguaggio PHP non prevede particolari distinzioni tra le due tipologie di dato, gestendole automaticamente quando vengono assegnate ad una variabile oppure utilizzate all'interno del codice; spetta a chi scrive lo SCRIPT effettuare eventuali controlli sul tipo di dato in base alle esigenze specifiche. Ad esempio, per verificare se l'input è una stringa, è possibile utilizzare la funzione PHP

is_string(input())


mentre per determinare se l'input è un numero intero oppure floating point rispettivamente

is_int(input())

is_float(input())

Per determinare infine se l'input è una stringa che contiene un valore numerico, è possibile utilizzare la funzione

is_numeric(input())

Per ulteriori dettagli sui tipi di dato in PHP e le relative funzioni di controllo o conversione, si rimanda alla documentazione online al seguente indirizzo:

http://www.php.net/manual/en/ref.var.php

Al termine dell'esecuzione, lo script può restituire un valore di OUTPUT all'ambiente di esecuzione; questo valore viene impostato come valore dello SCRIPT RUNNER, e può essere visualizzato nel FRONTEND oppure utilizzato in esecuzioni successive dello SCRIPT RUNNER stesso. Inoltre, se è presente almeno un EVENTO ATTIVO, questo valore viene passato come valore di ingresso agli oggetti “figli” correlati.

Per restituire un valore all'ambiente di esecuzione è sufficiente richiamare la funzione

output()

Esempio:

output(1);

La chiamata alla funzione output() determina la fine dell'esecuzione dello script; ogni eventuale riga di codice successiva viene ignorata.

Qualora non si desideri passare alcun valore all'ambiente chiamante, è sufficiente richiamare la funzione senza argomenti:

output();

In questo caso:

• Non viene impostato alcun valore allo SCRIPT RUNNER

• Non vengono eseguiti gli EVENTI ATTIVI eventualmente associati allo SCRIPT RUNNER

La mancata esecuzione degli EVENTI ATTIVI in caso di chiamata alla funzione output() senza argomenti non deve essere vista come un limite, bensì come una maggiore flessibilità. E' possibile infatti eseguire manualmente all'interno dello script gli eventi passivi, passando valori differenti ad ognuno di essi (cosa altrimenti impossibile attraverso il valore di output, uguale per tutti), prima di terminare l'esecuzione dello script; in questo caso non si desidera ovviamente che l'ambiente chiamante esegua nuovamente tali eventi. Per ulteriori dettagli si rimanda alla sezione relativa alla libreria “surrounding”.


http://www.php.net/manual/en/ref.var.php

2.5 DEBUG, INFO ED ERRORIE' possibile inserire all'interno degli script messaggi rispettivamente di DEBUG (finalizzati al monitoraggio delle attività svolte dallo script in fase di realizzazione), di INFO (utili per notificare all'ambiente di esecuzione messaggi di vario genere) e di ERRORE (necessari per segnalare e tracciare eventuali anomalie durante l'esecuzione dello script che ne compromettono il corretto completamento).

Per inserire questi messaggi è sufficiente richiamare, rispettivamente, una delle seguenti funzioni:

debug()

info()

error()

Esempio:

debug(“Questo è un messaggio di debug”);

info(“Questo è un messaggio di info”);

error(“Questo è un messaggio di errore”);

La funzione di error() prevede anche un secondo parametro, che è il CODICE DI RITORNO dello script stesso; questo codice, da non confondere con il VALORE DI OUTPUT visto nella sezione precedente, è un valore numerico che indica all'ambiente di esecuzione se lo script è stato eseguito correttamente o meno. In condizioni normali, lo script restituisce automaticamente il valore 0 (zero) all'ambiente chiamante, il che indica l'assenza di errori; in caso di interruzione programmata dello script attraverso una chiamata error(), è possibile specificare un particolare valore da restituire all'esterno diverso da 0:

error(“Questo è un messaggio di errore”,1);

IKON SERVER prevede già una serie di codici di ritorno standard, identificati con altrettante costanti; i principali sono:

CODICE DI RITORNO VALORE NUMERICO DESCRIZIONE

_DPAD_RESULT_NOERROR 0 Nessun errore

_DPAD_RESULT_DBERROR 1 Errore sul database

_DPAD_RESULT_SYSERROR 4 Errore generico di sistema

_DPAD_RESULT_CONFIGERROR 5 Errore di configurazione

_DPAD_RESULT_USERERROR 6 Errore dato dall'utente (ad esempio, frutto di un input sbagliato)

_DPAD_RESULT_IOERROR 7 Errore dato dal file system (memoria flash) di IKON SERVER (es: errore durante il salvataggio o l'apertura di un file)

_DPAD_RESULT_TIMEOUT 12 Errore dovuto ad eccessivo tempo di esecuzione

Per utilizzare tali costanti è sufficiente passarle direttamente alla funzione, senza apici o virgolette:

error(“Questo è un messaggio di errore”,_DPAD_RESULT_USERERROR);


I messaggi possono essere visualizzati durante il test dello script, come meglio evidenziato nel capitolo dedicato al debug; durante l'esecuzione a “runtime” dello script (o meglio, dello SCRIPT RUNNER) i messaggi non sono visualizzati, ma vengono tracciati nel log interno e possono essere successivamente consultati.

2.6 INCLUSIONE DI SCRIPTSA partire dalla versione 1.0.2 è possibile includere altri SCRIPT all'interno di uno SCRIPT; questa funzionalità permette di utilizzare SCRIPT realizzati in precedenza come una sorta di “libreria” personalizzata.

Per includere uno SCRIPT è sufficiente richiamare la seguente funzione:

include_script($nomeScript);

Dove $nomeScript è il nome dello SCRIPT da eseguire; ad esempio:

include_script(“prova”);

E' possibile passare allo script un VALORE DI INGRESSO differente da quello ricevuto dall'ambiente di esecuzione; in tal caso, è sufficiente indicare tale valore come secondo parametro della funzione:

include_script(“prova”,”nuovo valore di ingresso”);

La funzione restituisce il VALORE DI OUTPUT generato dallo SCRIPT incluso; questo valore può essere “raccolto” in una variabile e gestito opportunamente all'interno dello SCRIPT:

$value = include_script(“prova”);

Si consideri ad esempio lo SCRIPT “raddoppia” che moltiplica per due il valore ricevuto come ingresso:

$double = input() * 2;

output($double);

SCRIPT “raddoppia”

Volendo utilizzare questo SCRIPT come una funzione di libreria all'interno di un altro script, passando anche valori differenti da quello ricevuto dall'esterno, è sufficiente scrivere:

$double1 = include_script(“raddoppia”); //Calcola il doppio del VALORE DI INGRESSO

$double2 = include_script(“raddoppia”,2); //Calcola il doppio di 2, ovvero 4

$double3 = include_script(“raddoppia”,5); //Calcola il doppio di 5, ovvero 10

[...]

I valori di ingresso ed uscita di uno SCRIPT incluso mediante la funzione include_script() non influenzano il VALORE DI INGRESSO ed il VALORE DI USCITA dello SCRIPT che li include.

Per includere un esempio, al posto di uno SCRIPT, utilizzare la funzione

include_sample(“prova”);


il cui funzionamento è assolutamente analogo alla include_script().


3 SCRIPTS

3.1 INTRODUZIONEQuesto capitolo illustra come creare, modificare, cancellare ed esportare gli script personalizzati su IKON SERVER.

3.2 PAGINA DI GESTIONE DEGLI SCRIPTSPer accedere alla pagina di gestione degli scripts è sufficiente:

• Effettuare l'accesso ad IKON SERVER con un utente dotato dei permessi amministrativi

• Accedere all'ambiente di CONFIGURAZIONE

• Selezionare “FUNZIONI AVANZATE” e quindi “SCRIPTING” dal MENU LATERALE

• Selezionare “SCRIPTS”

Viene mostrata una pagina simile all'esempio seguente:

La parte in alto della pagina contiene una serie di script di esempio precaricati in IKON SERVER; essi non possono essere cancellati o modificati, ma solo consultati o duplicati (per realizzare, a partire da essi, un proprio script).

La parte in basso mostra invece gli script personalizzati presenti sul disco di IKON SERVER. Per creare un nuovo script è sufficiente premere il pulsante “NUOVO” al fondo della pagina: viene chiesto di indicare il nome da assegnare al nuovo script...


… e, dopo alcuni secondi, data conferma dell'avvenuta creazione del nuovo file:

Volendo creare uno script partendo da un esempio esistente, viceversa, è sufficiente premere il corrispondente pulsante “DUPLICA” (grigio); anche in questo caso viene chiesto di specificare un nome da assegnare al nuovo script.

Per eliminare uno script è sufficiente premere il corrispondente pulsante “ELIMINA” (rosso); una volta data conferma, il file viene rimosso dal disco di IKON SERVER (in modo irreversibile).

Infine, per accedere alla scheda di consultazione e/o modifica di uno script (o di un esempio), utilizzare il pulsante “MODIFICA” (verde).

3.3 CONSULTAZIONE O MODIFICA DI UNO SCRIPTSelezionando il pulsante di MODIFICA di uno script o di uno esempio, viene mostrata una pagina contenente il codice PHP che costituisce lo script stesso; nel caso degli esempi, il codice non può essere modificato. Nel caso di uno script nuovo, il codice presenta alcuni commenti (identificati dal prefisso “//”) che forniscono alcune iniziali indicazioni su come realizzare lo script, come più dettagliatamente riportato in questo manuale.

La figura seguente mostra la pagina di modifica di uno script nuovo:


Come si può notare, il tag identificativo di apertura dello script PHP...

<?php

… e quello di chiusura...

?>

… non vanno inseriti nel codice, in quanto già presenti (ed evidenziati nella pagina al di fuori dell'area utile in cui scrivere). Per ulteriori informazioni su come realizzare uno script, sfruttando in particolare le librerie a disposizione, si rimanda ai capitoli successivi.

Una volta terminate le modifiche al codice, premere il pulsante “SALVA” per renderle persistenti; premendo viceversa il pulsante “CHIUDI” prima di aver salvato, ogni eventuale modifica andrà persa.

3.4 ESEMPIOA titolo di esempio, nel proseguo di questo manuale, salvo diversamente indicato, si utilizzerà il seguente codice di esempio, che semplicemente restituisce in uscita il valore ricevuto come VALORE DI INGRESSO, dopo aver riportato il valore stesso in un messaggio di DEBUG (visualizzabile solo durante la simulazione di esecuzione, come evidenziato in seguito).

$value = input();

debug(“Ricevuto come ingresso il valore ” . $value);

output($value);


4 SCRIPT RUNNERS

4.1 INTRODUZIONEQuesto capitolo illustra come creare e gestire oggetti di tipo SCRIPT RUNNER, che permettono di eseguire SCRIPTS all'interno della supervisione di IKON SERVER.

4.2 CREAZIONE DI UNO SCRIPT RUNNERPer creare un nuovo SCRIPT RUNNER è sufficiente:

• Effettuare l'accesso ad IKON SERVER con un utente amministrativo, ed accedere alla sezione di configurazione

• Identificare la voce “SCRIPTING” all'interno di “FUNZIONI AVANZATE”, quindi selezionare “SCRIPT RUNNERS”

• Premere il pulsante “AGGIUNGI” nella toolbar in basso

• Evidenziare il nuovo oggetto creato e premere i “puntini” a lato, oppure – in alternativa – il pulsante “MODIFICA” nella toolbar in basso, per accedere alla sua scheda

Oltre ad assegnare un nome allo SCRIPT RUNNER, è necessario selezionare anche quale script sarà messo in esecuzione, scegliendolo nell'apposito menu a tendina. Inoltre, è possibile personalizzare l'aspetto grafico con cui lo SCRIPT RUNNER, se inserito in una pagina grafica del FRONTEND, viene visualizzato e permette all'utente di interagire con lo SCRIPT associato.


A partire dalla versione 1.0.1, è possibile inoltre specificare le seguenti opzioni per lo SCRIPT RUNNER:

ESEGUI ALL'AVVIO Selezionando questo flag, lo SCRIPT RUNNER viene eseguito automaticamente all'avvio della supervisione

ESEGUI IN LOOP Selezionando questo flag, lo SCRIPT RUNNER viene eseguito iterativamente per un numero indefinito di volte, fintanto che non viene arrestato manualmente oppure mediante un EVENTO. Per ulteriori dettagli, si rimanda alla apposita sezione “esecuzione in background”

TEMPO DI LOOP Nel caso di esecuzione in loop, specificare la durata in millisecondi di ogni iterazione.

E' possibile inoltre (a partire dalla versione software 1.1.0) mettere in esecuzione o arrestare uno SCRIPT RUNNER attraverso gli appositi pulsanti “AVVIA” e “ARRESTA”.

4.2.1 INGRESSI

La sezione INGRESSI (o “EVENTI PASSIVI”) permette di trascinare uno o più oggetti che, al cambio di stato, determinano l'esecuzione dello SCRIPT RUNNER; utilizzando una nomenclatura adottata in altri punti del software, questi sono gli “EVENTI PASSIVI” che determinano l'esecuzione dello SCRIPT RUNNER (e quindi, attraverso di esso, dello SCRIPT associato).

Una volta trascinato un oggetto all'interno di questo elenco, è necessario stabilire quale valore debba essere passato allo SCRIPT RUNNER ogni qualvolta l'oggetto stesso cambia di stato. A differenza di altri punti del software in cui questa scelta è guidata attraverso appositi menu a tendina, in questo caso il valore deve essere specificato manualmente; per mantenere infatti la massima flessibilità nella costruzione della catena di esecuzione degli SCRIPT RUNNER, non è stato possibile restringere il campo delle opzioni. Questo campo può contenere i seguenti valori:

$VAL Il valore corrente dell'oggetto viene passato allo SCRIPT RUNNER come valore di ingresso

$NVAL Il valore negato dell'oggetto viene passato allo SCRIPT RUNNER come valore di ingresso

Un qualunque valore numerico o stringa

Il valore viene passato allo SCRIPT RUNNER come valore di ingresso, a prescindere dallo stato dell'oggetto stesso

In ogni caso, il valore è disponibile all'interno dello script attraverso la chiamata

input()

già descritta in precedenza.

Il valore indicato in questo campo non è l'unico modo per accedere, all'interno dello SCRIPT, al valore dell'oggetto relazionato come ingresso. Attraverso la libreria surrounding, infatti, come meglio descritto in seguito, è possibile conoscere lo stato di tutti gli ingressi ed effettuare operazioni su di essi; questo campo è importante solo ai fini della corretta valorizzazione del cosiddetto “VALORE DI INGRESSO”, accessibile con l'apposita chiamata input() vista in precedenza.

A partire dalla versione 1.1.3, è possibile associare ad ogni oggetto un identificativo (che deve essere una stringa priva di spazi o caratteri speciali) che ne agevoli l'identificazione all'interno dello


SCRIPT, quando si fa uso della libreria SURROUNDING. Come meglio evidenziato nel capitolo successivo, per richiamare all'interno di uno SCRIPT l'oggetto INGRESSO associato ad un certo identificato, è sufficiente scrivere

$me->getParentByIdentifier(“identificativo”)

La colonna variabile mostra il nome della variabile con cui l'INGRESSO è disponibile, sempre previa caricamento della libreria SURROUNDING, all'interno dello SCRIPT.

Non tutte le operazioni di aggiunta, trascinamento o ordinamento degli oggetti nella lista determina un corretto aggiornamento automatico della colonna “variabile”. Premere il pulsante “AGGIORNA” per aggiornare l'intero set delle variabili dopo aver effettuato questo tipo di operazioni.

4.2.2 USCITE

Analogamente, trascinando oggetti all'interno della sezione uscite è possibile determinarne l'esecuzione al termine dello SCRIPT. Per ogni oggetto è necessario specificare quale azione eseguire e (se l'oggetto lo prevede) quale valore passare al termine dell'esecuzione dello SCRIPT RUNNER; in quest'ultimo caso, scegliere “VALORE DELLO SCRIPT RUNNER” per passare all'oggetto il valore restituito in uscita dallo SCRIPT con il comando

output(...)

Come già evidenziato in precedenza, è possibile inibire l'esecuzione automatica degli oggetti associati come uscite al termine dello SCRIPT, non passando alcun valore alla funzione output(). In questo caso, viene affidato al codice dello SCRIPT stesso l'eventuale comando degli oggetti associati come uscite, come meglio dettagliato nel capitolo dedicato alla libreria “surrounding”.

Anche per le uscite, a partire dalla versione 1.1.3 è possibile associare un identificativo e visualizzare il nome della variabile con cui fare riferimento all'uscita nello SCRIPT.

4.3 DEBUGUna volta associati gli oggetti come ingressi ed uscite dello SCRIPT RUNNER1 , è possibile simularne l'esecuzione attraverso la funzione “DEBUG”; questa funzione esegue a tutti gli effetti lo SCRIPT (determinando quindi, ad esempio, la scrittura su una porta seriale o via rete, o il comando di oggetti se previsto all'interno del codice) ma non determina l'esecuzione delle relazioni di uscita (il che viene solo simulato a video, popolando il campo “TEST” corrispondente).

1 Non è necessario associare oggetti ad uno SCRIPT RUNNER per poterlo eseguire; in questo caso, la simulazione può essere effettuata agendo sul campo “VALORE DI INGRESSO”.


Per simulare il comportamento dello script al cambio di uno degli ingressi, è sufficiente selezionare un valore tra quelli disponibili nel corrispondente menu a tendina “TEST”; il valore scelto viene scritto automaticamente nel campo “VALORE DI INGRESSO” e passato come input allo SCRIPT.

Se il codice prevede messaggi di debug o di errore, essi vengono mostrati nella finestra “DEBUG”; più in generale, questa finestra mostra tutto l'output dello script PHP, anche quello eventualmente previsto nel codice con le usuali funzioni PHP (es: print(), echo(), print_r() etc...). Il valore restituito dalla funzione output() viene mostrato nel campo “VALORE DI USCITA”; inoltre, in base alle opzioni scelte, vengono popolati i campi “TEST” degli oggetti di uscita.

In alternativa, è possibile passare manualmente un valore di input scrivendolo nel campo “VALORE DI INGRESSO” e premendo il tasto “TAB” della tastiera (o, in alternativa, il tasto “INVIO” oppure, ancora, facendo click fuori dal campo di inserimento).

Qualora il VALORE DI INGRESSO non rispecchi il valore scelto come TEST di un ingresso oppure, viceversa, il valore TEST di un'uscita non rispecchi il valore di uscita dello SCRIPT, controllare la correttezza dei rispettivi campi “VALORE”.

Questa simulazione è utile per capire non solo l'interazione tra lo SCRIPT RUNNER e gli altri oggetti associati come ingressi, ma la correttezza del codice stesso; in tal senso sono particolarmente utili i messaggi di debug inseriti all'interno dello SCRIPT.


4.4 ESECUZIONE IN BACKGROUNDCome accennato in precedenza, a partire dalla versione 1.0.1 è possibile eseguire gli SCRIPT RUNNER in “background”, permettendo di eseguire operazioni anche ripetitive (ad esempio, interrogare un dispositivo periodicamente e, al cambio di stato, generare EVENTI) senza una diretta interazione con l'utente.

E' possibile innanzitutto avviare l'esecuzione di uno SCRIPT RUNNER automaticamente all'avvio del software; ogni qualvolta la supervisione viene avviata (ad esempio, dopo un reboot di IKON SERVER) lo SCRIPT RUNNER viene eseguito.

Attivando l'opzione “ESEGUI IN LOOP”, inoltre, è possibile ripetere il codice dello SCRIPT associato in modo iterativo, fintanto che l'esecuzione non venga arrestata manualmente oppure attraverso un apposito EVENTO. Abbinando questa opzione con la precedente, è possibile lanciare processi in background sin dall'avvio della supervisione, che compiono periodicamente operazioni senza l'intervento dell'utente o di EVENTI specifici.

Nel caso di esecuzione in LOOP, è necessario specificare anche il tempo di ogni singola iterazione, in millisecondi; in questo caso, il motore di scripting calcola automaticamente il tempo necessario per l'esecuzione di ogni ciclo, e sottrae questo tempo all'attesa specificata in modo da garantire (con una minima tolleranza) che ogni ciclo venga lanciato esattamente dopo il tempo richiesto.

Nel caso di esecuzione in LOOP, il VALORE DI USCITA dello SCRIPT (generato con la chiamata alla funzione output() ) diventa il VALORE DI INGRESSO per la successiva iterazione. In questo modo è possibile passare tra un ciclo e l'altro un valore incrementale; se non si desidera usufruire di questa funzionalità, si consiglia di non inserire all'interno dello SCRIPT chiamate alle funzioni input() e output()

4.5 VISUALIZZAZIONE NEL FRONTENDInserendo uno SCRIPT RUNNER all'interno di una pagina di supervisione, viene mostrato un box grafico simile al seguente:

Premendo il pulsante “PLAY” viene mandato in esecuzione lo SCRIPT RUNNER; l'icona cambia corrispondentemente per tutta la durata dello SCRIPT. Se lo script è predisposto per l'esecuzione in loop, esso rimane in esecuzione fintanto che non viene premuto il pulsante “STOP” oppure viene arrestato il sistema.

L'arresto di uno SCRIPT RUNNER in esecuzione in loop avviene solo al termine del codice dello SCRIPT, durante l'attesa per il ciclo successivo. E' possibile quindi che lo SCRIPT RUNNER rimanga in esecuzione ancora per un certo tempo prima dell'effettivo arresto, in base al timer ed alla durata delle operazioni eseguite dal codice specifico.


5 LIBRERIA “OBJECT”

5.1 INTRODUZIONELa libreria “object” permette di gestire all'interno di uno SCRIPT uno o più OGGETTI della supervisione di IKON, sotto forma di variabili; queste variabili sono a tutti gli effetti oggetti per il linguaggio PHP, e mettono a disposizione attributi e metodi per interagire con il software. Attraverso di esse è possibile quindi conoscere lo stato in tempo reale di qualunque OGGETTO della supervisione, oppure eseguire su di essi operazioni, come, ad esempio, il comando di una funzione KNX, l'esecuzione di uno scenario etc...

5.2 INCLUSIONE DELLA LIBRERIAPer includere la libreria all'interno di uno SCRIPT è sufficiente inserire all'inizio la seguente riga:

include_library(“object”);

A partire dalla riga immediatamente successiva, risulta disponibile allo SCRIPT la seguente classe:

objM

Questa classe (“object manager” o “gestore degli oggetti”) mette a disposizione una serie di funzioni (o “metodi”) per caricare oggetti della supervisione ed effettuare operazioni su di essi. La classe objM è pensata per essere utilizzata attraverso “chiamate statiche”, come ad esempio

objM::objGet(...);

Come evidenziato, le chiamate statiche si effettuano facendo seguire al nome della classe (senza il simbolo identificativo delle variabili “$”) i “doppi due punti” ed il nome della funzione da chiamare; queste chiamate si differenziano dalle chiamate agli oggetti (il cui nome è invece sempre preceduto da “$”) che prevedono il separatore “->” prima del nome della funzione.

5.3 CARICARE UN OGGETTOPer caricare un oggetto come variabile all'interno dello SCRIPT è necessario utilizzare la seguente chiamata:

$nomevarabile = objM::objGet(XXX);

XXX è l'ID univoco numerico che identifica l'oggetto all'interno della supervisione; è possibile ricavare l'ID di un oggetto dai risultati della ricerca in amministrazione, come evidenziato nella figura seguente:


Nell'esempio dello “scenario film” della figura, quindi, la chiamata all'interno dello SCRIPT potrebbe essere

$scenarioFilm = objM::objGet(644);

La variabile contenente l'oggetto della supervisione presenta le seguenti proprietà, che possono essere utilizzate nello SCRIPT:

Proprietà Descrizione Esempio

id ID univoco dell'oggetto $obj->id

name Nome dell'oggetto all'interno della supervisione $obj->name

state Stato corrente dell'oggetto.

NOTA: questa proprietà ha significato solo per gli scenari; in questo caso:

1 → scenario fermo

2 → scenario in esecuzione

$obj->state

value Valore corrente dell'oggetto

NOTA: questa proprietà ha significato per tutte le tipologie di oggetto che hanno uno stato, scenari esclusi

$obj->value

enabled Stabilisce se l'oggetto è o meno abilitato. Possibili valori: 0,1

$obj->enabled

msp Parametro più significativo dell'oggetto, in base alla sua tipologia. Alcuni esempi:

• Oggetti KNX: indirizzo di gruppo ETS

$obj->msp


• Logiche: espressione logica

• Scenari: numero di ripetizioni

type Tipo “funzionale” di oggetto, utilizzato dai servizi di comunicazione. Alcuni esempi:

• Oggetti KNX: “EIBOBJECT”

• Variabili: “VIRTUALOBJECT”

• Scenari: “SCENARIO”

• Logiche: “LOGIC”

• Condizioni: “CONDITION”

• Script runners: “CSCMD”

NOTA: per un elenco completo dei tipi, si rimanda all'appendice 13.1

$obj->type

phpclass Tipologia grafica di oggetto, utilizzata dall'interfaccia web. Alcuni esempi:

• Oggetti KNX: “dpadEibObject”

• Variabili: “dpadVirtualObject”

• Scenari: “dpadScenario”

• Logiche: “dpadLogic”

• Condizioni: “dpadCondition”

• Script runners: “dpadScriptRunner”

NOTA: non sempre esiste una corrispondenza univoca tra “type” e “phpclass”: in alcuni casi, più “phpclass” condividono il medesimo “type”. Per un elenco completo, si rimanda all'appendice 13.2

$obj->phpclass

values_type Tipo di dato o di codifica.

NOTA: dipende dal tipo di oggetto

$obj->values_type

options Array di valori opzionali.

NOTA: dipende dal tipo di oggetto

$obj->options

$obj->options[“...”]

5.4 RELAZIONI CON ALTRI OGGETTIPer determinare le relazioni tra un oggetto ed altri oggetti, rispettivamente come “padri” (“EVENTI PASSIVI” per l'oggetto in questione) e come “figli” (“EVENTI ATTIVI” per l'oggetto in questione), sono disponibili rispettivamente i seguenti metodi, da richiamare direttamente sulla variabile che identifica un oggetto (non quindi su “objM”):

$object->loadParents();

$object->loadChilds();

Le due funzioni “popolano” rispettivamente i seguenti array:

$object->parentRelations[];

$object->childRelations[];


Questi array contengono, per ognuna delle relazioni con altri oggetti della supervisione (rispettivamente di tipo “padre” o “figlio”), un oggetto PHP di tipo “relation” caratterizzato dalle seguenti proprietà:

Proprietà Descrizione Esempio

id ID univoco della relazione all'interno del database

NOTA: non confondere questo ID, che identifica la relazione, con gli ID degli oggetti che la caratterizzano (“padre” e “figlio”, vedi sotto)

$relation->id

parent

child

Riferimento agli oggetti che fungono rispettivamente da “padre” e da “figlio” nella relazione

NOTA: queste variabili sono oggetti PHP strutturato nello stesso modo di quanto visto nel paragrafo 5.3

$relation->parent

$relation->child

condition Nel caso di relazioni di tipo EVENTO (attivo o passivo), filtro sullo stato dell'oggetto “padre” che, se soddisfatto, determina l'esecuzione dell'evento.

Nel caso di relazioni di tipo “statico” o “strutturale” (es: relazioni che legano un oggetto ad un ambiente), questo campo non viene utilizzato, e contiene solitamente l'indicazione “NO-CONDITION”

$relation->condition

action Nel caso di relazioni di tipo EVENTO (attivo o passivo), stabilire l'azione da compiere sull'oggetto “figlio”.

Nel caso di relazioni di tipo “statico” o “strutturale” (es: relazioni che legano un oggetto ad un ambiente), questo campo non viene utilizzato, e contiene solitamente l'indicazione “NO-ACTION”

$relation->action

value Nel caso di relazioni di tipo EVENTO (attivo o passivo), stabilire il valore da passare all'oggetto “figlio” (laddove previsto).

Nel caso di relazioni di tipo “statico” o “strutturale” (es: relazioni che legano un oggetto ad un ambiente), questo campo non viene utilizzato, e contiene solitamente l'indicazione “NO-VALUE”

$relation->value

enabled Stabilisce se la relazione è abilitata o meno $relation->enabled

options Elenco di impostazioni opzionali della relazione; queste impostazioni, se presenti, sono riportate nella forma

param1='value1'|param2='value2'|...

ovvero concatenate con il carattere “|”. Eventuali valori numerici possono non essere inclusi tra apici.

$relation->options


Le proprietà sopra elencate ricalcano le informazioni presenti all'interno del database nella tabella DPADD_OBJECT_RELATION, utilizzata dal software per gestire le relazioni tra oggetti.

Le funzioni loadChilds() e loadParents() per impostazioni predefinite caricano solo le relazioni di tipo EVENTO, che solitamente sono le più utilizzate all'interno degli SCRIPT. Per caricare tutte le relazioni, passare true come primo parametro alle chiamate:

$object->loadChilds(true);

$object->loadParents(true);

Per caricare viceversa solo alcuni tipi specifici di relazione, passare false come primo parametro, e un array contenente le tipologie di relazione interessate come secondo parametro:

$object->loadChilds(false,[“GENERIC_RELATION”,”ACTION_RELATION”]);

$object->loadParents(false,[“GENERIC_RELATION”,”ACTION_RELATION”]);

Si osservi come gli attributi “parent” e “child” della relazione siano essi stessi oggetti PHP, ognuno dotato di una struttura analoga all'oggetto di partenza; per accedere al valore corrente del primo figlio dell'oggetto di partenza, ad esempio, occorre scrivere

$firstChildValue = $object->childRelations[0]->child->value;

in quanto:

$object->childRelations[0] Prima relazione con i figli (indice 0)

$object->childRelations[0]->child Riferimento all'oggetto figlio della relazione2

$object->childRelations[0]->child->value Valore dell'oggetto figlio

Per capire come è strutturato un oggetto e la sua alberatura di relazioni con padri e figli, può essere utile inserire all'interno del proprio SCRIPT quanto segue (sempre immaginando che $object sia l'oggetto precedentemente caricato, su cui si vuole lavorare):

echo “<pre>”; print_r($object); echo “</pre>”;

Il comando print_r (preceduto e seguito dai TAG HTML “<pre>” e “</pre>”, che impaginano in modo indentato i risultati a video), eseguendo lo SCRIPT nella finestra di DEBUG (attraverso uno SCRIPT RUNNER, come illustrato nel capitolo 4.3), riporta infatti tutta la struttura dell'oggetto passato come argomento. Segue un esempio di output di questa chiamata, effettuata su un oggetto di tipo “scenario”:

obj Object( [id] => 644 [name] => Scenario Film [state] => 1 [value] => [enabled] => 1 [options] => Array ( )

2 In questo caso, il riferimento “parent” della relazione è l'oggetto di partenza...


[relations] => Array ( )

[childRelations] => Array ( [0] => relation Object ( [id] => 872 [parent] => obj Object *RECURSION* [child] => obj Object ( [id] => 487 [name] => Salotto - Faretti [state] => -1 [value] => 0 [enabled] => 1 [options] => Array ( [category] => climate )


[childRelations] => Array ( )

[childsLoaded] => [parentRelations] => Array ( )

[parentsLoaded] => [msp] => 0/0/4 )

[condition] => NO-CONDITION [action] => NO-ACTION [value] => 0 [enabled] => 1 [options] => Array ( )

)

[1] => relation Object ( [id] => 873 [parent] => obj Object *RECURSION* [child] => obj Object ( [id] => 491 [name] => Corridodio - Luci [state] => -1 [value] => 1 [enabled] => 1 [options] => Array ( [category] => lighting )




[parentsLoaded] => [msp] => 0/0/6


)


)

[2] => relation Object ( [id] => 875 [parent] => obj Object *RECURSION* [child] => obj Object ( [id] => 503 [name] => Luce salone Dimmer Valore [state] => -1 [value] => 75 [enabled] => 1 [options] => Array ( [category] => lighting )




[parentsLoaded] => [msp] => 0/0/15 )


)

)

[childsLoaded] => 1 [parentRelations] => Array ( )

[parentsLoaded] => 1)

Come si può dedurre, lo scenario di esempio contiene 3 relazioni con altrettanti “figli” (identificate nell'array childRelations, rispettivamente, con l'indice 0,1 e 2); ognuna di queste relazioni contiene, oltre alle proprietà intrinseche, i riferimenti agli oggetti “figli”, a loro volta caratterizzati da una struttura di proprietà.

Si noti come le relazioni contengono anche il riferimento all'oggetto “padre”; in questo caso, tuttavia, trattasi dell'oggetto di partenza; l'output della funzione print_r evidenzia questo “riferimento circolare” con la dicitura

*RECURSION*


Il comando print_r, molto utile in fase di realizzazione e debug dello SCRIPT per capire come è strutturato un oggetto o, più un generale, una struttura dati complessa, è completamente inutile in fase di runtime (come del resto qualunque altra funzione di output a video), e determina un inutile appesantimento dell'elaborazione dello SCRIPT stesso. Si suggerisce quindi di rimuovere questa funzione una volta terminata la sua utilità.

A partire dalla versione 1.1.3 è possibile ottenere l'array degli oggetti – rispettivamente con INGRESSI ed USCITE – caratterizzati da un particolare attributo della relazione con un dato oggetto ($object negli esempi sottostanti), attraverso le funzioni

$object->getParentsByRelationField($fieldName,$fieldValue);

$object->getChildsByRelationField($fieldName,$fieldValue);

Dove

$fieldName Nome del campo della relazione che si utilizza come filtro

$fieldValue Valore del filtro

Qualora si fosse interessati ad operare sulle relazioni invece che sugli oggetti, si può fare ricorso alle seguenti funzioni:

$object->getParentRelationsByField($fieldName,$fieldValue);

$object->getChildRelationsByField($fieldName,$fieldValue);

I parametri in ingresso sono gli stessi visti prima.

E' possibile reperire l'oggetto (rispettivamente INGRESSO o USCITA) in base al suo identificativo assegnato nella scheda dello SCRIPT RUNNER attraverso le funzioni

$object->getParentByIdentifier($identifier);

$object->getChildByIdentifier($identifier);

5.5 COMANDO DI OGGETTIIl gestore di oggetti objM rende possibile eseguire comandi su un qualunque oggetto della supervisione, in modo del tutto analogo a quanto accade attraverso le pagine web di IKON oppure attraverso scenari, logiche, eventi etc...

La seguente funzione rappresenta il modo generico per eseguire una qualunque operazione su un oggetto:

objM::objPerformOperation(ID,OPERATION,VALUE);

dove


ID ID univoco che identifica l'oggetto su cui effettuare l'operazione

OPERATION Operazione da eseguire

VALUE Qualora previsto, valore da passare all'oggetto

A titolo di esempio, per accendere un'utenza KNX di tipo ON/OFF (caratterizzata, a titolo di esempio, all'interno del progetto di IKON SERVER, dall'ID “123”) è necessario scrivere

objM::objPerformOperation(123,”SETVALUE”,1);

mentre, per eseguire lo scenario di esempio visto in precedenza (ID 644), è sufficiente scrivere

objM::objPerformOperation(644,”EXECUTE”);

senza passare alcun valore, in quanto, come meglio evidenziato tra poco, il comando di esecuzione di uno scenario non lo prevede.

Le operazioni previste, e gli eventuali valori, per le principali tipologie di oggetto sono riportate nella tabella seguente:

TIPO OPERAZIONE DESCRIZIONE VALORE

Oggetto KNX SETVALUE Invia un comando al gruppo KNX corrispondente

Dipende dal tipo di oggetto KNX

Es:

0 → spento

1 → acceso

50 → imposta al 50%

GETVALUE Invia una richiesta di ritrasmissione stato

Nessun valore

Scenario EXECUTE Esegue lo scenario Nessun valore

STOPEXECUTION Arresta lo scenario (se in esecuzione)

Nessun valore

Logica EVALUATE Valuta la logica ed esegue le uscite corrispondenti

Nessun valore

Condizione CALCULATE Calcola la condizione ed esegue le uscite corrispondenti

Nessun valore

Notifica a video INSERT Inserisce il messaggio nella tabella di log, in modo che venga visualizzato nel centro messaggi

Nessun valore

Notifica via email SENDMAIL Invia il messaggio via posta elettronica

Nessun valore

Integratore INTEGRATE Ricalcola il valore aggiornato dell'integratore

Nessun valore

RESET Riporta a 0 il valore Nessun valore


dell'integratore

Variabile SETVALUE Imposta il valore della variabile

In base al tipo di variabile creata

Per agevolare il comando degli oggetti di più comune utilizzo (ovvero gli oggetti KNX, gli scenari e le variabili) sono state predisposte le seguenti “scorciatoie”, ovvero funzioni che possono essere richiamate direttamente sulla variabile PHP che rappresenta, all'interno dello SCRIPT, l'oggetto stesso:

$object->set(...); //Imposta il valore passato come argomento (operazione SEVALUE)

$object->run(); //Esegue lo scenario

$object->stop(); //Arresta lo scenario

Volendo quindi eseguire lo scenario di esempio, già citato in precedenza, è sufficiente scrivere all'interno del proprio SCRIPT il seguente codice:

$scenarioFilm = objM::objGet(664);

$scenarioFilm->run();

5.6 AGGIORNAMENTO DI OGGETTI CON IL DATABASEA partire dalla versione 1.0.1 è disponibile la seguente funzione:

objM::objUpdateToDb($objectId,$field,$value);

che prevede i seguenti parametri:

$objectId ID dell'oggetto da aggiornare

$field Nome della colonna nel database da aggiornare

$value Valore da impostare

Questa funzione provvede ad effettuare una query SQL di aggiornamento nella tabella del database contenente gli oggetti, cambiando l'attributo dell'oggetto specificato con il nuovo valore.

Questa operazione permette ad esempio di modificare il nome di un OGGETTO:

objM::objUpdateToDb(XXX,”name”,”nuovo nome”);

dove ovviamente XXX è l'ID numerico dell'oggetto da aggiornare. E' possibile chiamare la stessa funzione anche direttamente su un oggetto; in questo caso la sintassi è la seguente:

$object->updateToDb($field,$value);

A partire dalla versione 1.1.3 è possibile inoltre forzare l'aggiornamento di un attributo di un oggetto leggendolo dal database durante l'esecuzione di uno SCRIPT attraverso la funzione


$object->refreshFromDb($field);

Per aggiornare il valore di un oggetto, ad esempio:

$object->refreshFromDb(“value”);


6 LIBRERIA “SURROUNDING”

6.1 INTRODUZIONELa libreria “surrounding” mette a disposizione di chi scrive uno SCRIPT un ambiente di oggetti e funzioni che permettono di interagire con l'oggetto SCRIPT RUNNER che esegue lo SCRIPT, e delle sue relazioni con gli oggetti associati come INGRESSI ed USCITE.

Questa libreria si basa sulla libreria “OBJECT” vista in precedenza; la struttura di oggetti e di relazioni creata automaticamente da questa libreria si basa quindi sui concetti del capitolo 5 a cui si rimanda per qualunque dettaglio.

Se si utilizza la libreria “surrounding” all'interno di uno SCRIPT, non è più necessario includere la libreria “object” in quanto implicitamente richiamata dalla prima.


include_library(“surrounding”);

6.3 AMBIENTE “DI CONTORNO” DELLO SCRIPT RUNNERA partire dalla riga immediatamente successiva all'inclusione della libreria, risulta disponibile allo SCRIPT il seguente oggetto:

$me

Questo oggetto, strutturato come gli oggetti visti nel capitolo 5, rappresenta lo SCRIPT RUNNER che sta eseguendo lo SCRIPT, e permette di interagire con esso all'interno dello SCRIPT. L'oggetto mette a disposizione anche le proprie eventuali relazioni con gli INGRESSI (“padri”) e le USCITE (“figli”) configurati nella scheda dello SCRIPT RUNNER (vv. capitolo 4.2) attraverso i rispettivi array

$me->parentRelations[]; //Relazioni con gli INGRESSI

$me->childRelations[]; //Relazioni con le USCITE

Inoltre, per maggiore comodità, gli ingressi dello SCRIPT RUNNER (“padri”) sono resi disponibili attraverso le seguenti variabili:

$in1; //Primo ingresso dello SCRIPT RUNNER

$in2; //Secondo ingresso dello SCRIPT RUNNER

…


Analogamente, le uscite dello SCRIPT RUNNER (“figli”) sono accessibili direttamente tramite le seguenti variabili:

$out1; //Prima uscita dello SCRIPT RUNNER

$out2; //Seconda uscita dello SCRIPT RUNNER

…

Come già suggerito al punto 5.4 è possibile, in fase di debug dello script, visualizzare l'intera struttura di contorno dello SCRIPT RUNNER scrivendo

echo “</pre>”; print_r($me); echo “<pre>”;

6.4 ESEMPIVolendo realizzare uno script che restituisce come VALORE DI USCITA la somma del valore di 2 INGRESSI, è sufficiente (oltre a collegare, nella scheda dello SCRIPT RUNNER che esegue lo SCRIPT, gli oggetti in ingresso ed in uscita) scrivere il seguente SCRIPT:

include_library("surrounding"); //Inclusione libreria

$sum = $in1->value + $in2->value; //Somma del valore dei primi due ingressi

output($sum); //Valore calcolato restituito all'esterno

Se si desidera impostare il valore della prima uscita dello SCRIPT RUNNER al valore di tale somma direttamente all'interno dello SCRIPT, senza che lo faccia l'ambiente di esecuzione una volta terminata la sua esecuzione, bisogna invece scrivere


$sum = $in1->value + $in2->value; //Somma del valore dei primi due ingressi

$out1->set($sum); //Valore impostato alla prima uscita

output(); //Uscita dallo script senza restituire valore

In quest'ultimo caso è importante chiamare la funzione output() senza passare alcun valore, in modo che l'ambiente di esecuzione dello SCRIPT RUNNER non esegua gli eventi attivi con le uscite (avendo già infatti impostato il valore all'interno dello script). In caso contrario, l'uscita verrebbe comandata due volte, la prima dallo SCRIPT stesso e la seconda dall'ambiente di runtime.

Volendo invece realizzare uno script che, in modo del tutto generico, calcoli la somma del valore di tutti gli oggetti associati come ingresso - a prescindere dal loro numero – si può scrivere il seguente codice:


$sum = 0; //Inizializzazione somma a 0

foreach($me->parentRelations as $parentRelation) //Scansione relazioni con ingressi

{

$parent = $parentRelation->parent; //Identificazione oggetto ingresso

$sum = $sum + $parent->value; //Somma valore ingresso al precedente

}


output($sum); //Restituzione valore all'esterno

In modo analogo sono realizzati gli esempi di funzioni AND e OR presenti in IKON SERVER; per ulteriori dettagli si rimanda al capitolo dedicato agli esempi precaricati


7 LIBRERIA “SERIAL”

7.1 INTRODUZIONELa libreria “serial” permette di leggere e scrivere dati attraverso la porta seriale RS232 di IKON SERVER oppure, tramite apposito adattatore USB-SERIALE, attraverso una delle porte USB in dotazione.



La libreria mette a disposizione la classe

$serialM

che può essere chiamata3 per effettuare operazioni sulla seriale, come meglio dettagliato a seguire.

7.3 INIZIALIZZAZIONE DELLA PORTALa classe serialM permette di impostare i principali parametri di comunicazione con la porta seriale; la tabella seguente riporta questi parametri, la funzione da chiamare per impostarli, il valore predefinito ed i possibili valori alternativi.

PARAMETRO CHIAMATA DEFAULT VALORI POSSIBILI

Porta di comunicazione

$serialM->deviceSet(...); “/dev/ttyS4”

NOTA: seriale RS232 di IKON SERVER

“/dev/ttyS4” (RS232)

“/dev/dlabusb1” (USB1)

“/dev/dlabusb2” (USB2)

Baud rate $serialM->confBaudRate(...); 19200 110, 150, 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200

Parità $serialM->confParity(...); “none” “none”, “odd”, “even”

Lunghezza carattere

$serialM->confCharacterLength(...);

8 8, 7

Stop bit $serialM->confStopBits(); 1 1, 1.5, 2

Controllo di flusso

$serialM->confFlowControl(); “none” “none”, “rts/cts”, “xon/xoff”

3 A differenza delle classi viste in precedenza, che devono essere chiamate “staticamente”, la classe $serialM deve essere chiamata come un oggetto, con le funzioni precedute da “->” e non da “::” - Vedi esempi riportati nel manuale


Se non è necessario modificare questi parametri, è possibile ignorare questo passaggio, altrimenti è necessario richiamare una o più tra le funzioni precedentemente elencate, prima di aprire la porta per le operazioni di lettura / scrittura.

Esempio:


$serialM->confBaudRate(9600);

$serialM->confParity(“odd”);

$serialM->confFlowControl(“rts/cts”);

...

7.4 SCRITTURA SULLA SERIALEPer scrivere un messaggio sulla porta seriale è necessario innanzitutto aprirla attraverso il comando

$serialM->deviceOpen();

A questo punto è possibile scrivere un messaggio attraverso il comando

$serialM->sendMessage(...);

a cui va passata la stringa da inviare alla porta, eventualmente seguita da un carattere di terminazione se previsto dal dispositivo ricevente. Esempi:

$serialM->sendMessage(“prova”); //Scrittura di “prova” senza terminatore

$serialM->sendMessage(“prova\n”); //Scrittura di “prova” seguito da nuova linea

$serialM->sendMessage(“prova”.chr(13)); //Scrittura di “prova” seguito da INVIO

La chiamata prevede un secondo parametro opzionale, contenente il tempo (in secondi, o frazioni di secondo) di attesa prima di leggere una eventuale risposta (per i dettagli sulla lettura dalla seriale, si rimanda alla sezione successiva):

$serialM->sendMessage(“prova\n”,2); //Scrittura ed attesa di 2 secondi

$serialM->sendMessage(“prova\n”,0.1); //Scrittura ed attesa di 100 millisecondi

Al termine della scrittura, chiudere la porta seriale attraverso il comando

$serialM->deviceClose();

7.5 LETTURA DALLA SERIALEE' possibile leggere dati dalla porta seriale, dopo averla opportunamente aperta mediante il comando



eventualmente dopo una scrittura con attesa, come visto in precedenza. Per leggere dati dalla seriale è necessario usare una delle seguenti varianti del comando di lettura:

$value = $serialM->readPort(); //Legge dati finché disponibili sulla seriale

$value = $serialM->readPort(512); //Legge un numero specifico di bytes

Al termine delle operazioni sulla porta seriale, chiuderla con il comando


come già visto in precedenza.

7.6 ACCESSO DIRETTO ALLA SERIALEQualora per esigenze specifiche si volesse accedere direttamente alla porta seriale senza passare attraverso la libreria per le operazioni di scrittura, è possibile utilizzare i seguenti comandi nativi di PHP:

$fp = fopen('/dev/ttyS4','r+b'); //Apertura seriale in scrittura

$msg = “...”; //Inizializzazione messaggio

fwrite($fp,$msg . Chr(13)); //Scrittura messaggio seguito da INVIO

fclose($fp); //Chiusura della porta

Se si effettuano questi comandi dopo le eventuali chiamate di inizializzazione della porta (vv. punto 7.3) si è sicuri di operare con le corrette impostazioni di comunicazione.


8 LIBRERIA “MODBUS”

8.1 INTRODUZIONELa libreria “modbus” permette di gestire all'interno di uno SCRIPT uno o più dispositivi MODBUS SLAVE attraverso la rete, mediante il protocollo MODBUS TCP o UDP.


include_library(“modbus”);


modbusM

Questa classe (“MODBUS manager” o “gestore MODBUS”) mette a disposizione una serie di funzioni (o “metodi”) per caricare oggetti della supervisione ed effettuare operazioni su di essi. La classe modbusM, come già altre viste in precedenza, è pensata per essere utilizzata attraverso “chiamate statiche”, come ad esempio

modbusM::bind(...);


8.3 ASSEGNAZIONE DEL DISPOSITIVO MODBUS SLAVEPrima di effettuare operazioni di lettura/scrittura è necessario assegnare alla classe modbusM il dispositivo MODBUS SLAVE con cui dialogare, attraverso la funzione

modbusM::bind($host,$protocol);

Dove

$host Indirizzo IP del dispositivo

$protocol Protocollo da utilizzare; specificare “TCP” (default) oppure “UDP”

Finché non viene nuovamente chiamata questa funzione, ogni successiva operazione viene effettuata sul dispositivo MODBUS SLAVE selezionato.


8.4 LETTURA DI REGISTRIPer leggere uno o più registri sul dispositivo MODBUS SLAVE è necessario chiamare la seguente funzione:

$data = modbusM::readRegisters($unitID, $reference, $quantity);

Dove

$unitID Identificativo del dispositivo da interrogare. Salvo diversamente specificato dal costruttore, specificare 0 (zero)

$reference Registro iniziale da interrogare.

NOTA: il numero da utilizzare tiene conto dell'offset interno al dispositivo, rispetto alla sua numerazione interna. Tipicamente, specificando “0” viene interrogato il registro 40001.

$quantity Numero di registri da interrogare. Specificare 1 se si desidera interrogare un solo registro per volta.

I risultati vengono restituiti dalla funzione sotto forma di array di byte (o, in altri termini, una stringa); per ulteriori dettagli sulla conversione dei dati ricevuti, si rimanda al capitolo 8.9 di questo manuale.

8.5 LETTURA DI COILSPer leggere uno o più coils sul dispositivo MODBUS SLAVE è necessario chiamare la seguente funzione:

$data = modbusM::readCoils($unitID, $reference, $quantity);

Dove


$reference Coil iniziale da interrogare.

NOTA: il numero da utilizzare tiene conto dell'offset interno al dispositivo, rispetto alla sua numerazione interna.

$quantity Numero di coil da interrogare. Specificare 1 se si desidera interrogare un solo coil per volta.

I risultati vengono restituiti dalla funzione sotto forma di array di valori booleani, uno per ogni coil interrogato.

8.6 SCRITTURA DI REGISTRIPer scrivere uno o più registri sul dispositivo MODBUS SLAVE è necessario chiamare la seguente funzione:

$data = modbusM::writeRegisters($unitID, $reference, $data, $dataTypes);


Dove


$reference Riferimento del registro iniziale da scrivere.


$data Array di valori da assegnare ai registri, uno per ognuno dei registri da scrivere. Il numero di elementi determina il numero di registri scritti nel dispositivo.

$dataTypes Array di formati relativi ai valori per ogni registro (contenuti in $data). Valori possibili:

• “WORD”

• “INT”

• “DINT”

• “REAL”

La funzione restituisce un codice di risultato, pari a _SCRIPT_RESULT_NOERROR (0) se l'operazione è avvenuta con successo, oppure con un codice di errore. Per ulteriori informazioni sui codici di risultato, si rimanda alla sezione 2.5 di questo manuale.

Il codice seguente mostra un esempio di utilizzo della funzione:

$data = array(10,-1000,2000,3.0);

$dataTypes = array(“WORD”,”INT”,”DINT”,”REAL”);

$result = modbusM::writeRegisters(0, 12288, $data, $dataTypes);

8.7 SCRITTURA DI COILSPer scrivere uno o più coils sul dispositivo MODBUS SLAVE è necessario chiamare la seguente funzione:

$data = modbusM::writeCoils($unitID, $reference, $data);

Dove


$reference Riferimento del registro iniziale da scrivere.


$data Array di valori booleani da assegnare ai coils. Il numero di elementi determina il numero di coils scritti nel dispositivo.

La funzione restituisce un codice di risultato, pari a _SCRIPT_RESULT_NOERROR (0) se l'operazione è avvenuta con successo, oppure con un codice di errore. Per ulteriori informazioni sui codici di risultato, si rimanda alla sezione 2.5 di questo manuale.

Il codice seguente mostra un esempio di utilizzo della funzione:


$data = array(TRUE, FALSE, TRUE, TRUE, FALSE, TRUE, TRUE, TRUE,

TRUE, TRUE, TRUE, TRUE, FALSE, FALSE, FALSE, FALSE,

FALSE, FALSE, FALSE, FALSE, TRUE, TRUE, TRUE, TRUE,

TRUE, TRUE, TRUE, TRUE, TRUE, TRUE, TRUE, TRUE);

$result = modbusM::writeCoils(0, 12288, $data);

8.8 LETTURA E SCRITTURA DI REGISTRIPer scrivere uno o più registri sul dispositivo MODBUS SLAVE, e contestualmente leggere uno o più registri con una unica connessione di rete, è necessario chiamare la seguente funzione:

$data = modbusM::readWriteRegisters($unitID, $referenceRead, $quantity, $referenceWrite, $data, $dataTypes);

Dove


$referenceRead Riferimento del registro iniziale da leggere.

$quantity Numero di registri da leggere

$referenceWrite Riferimento del registro iniziale da scrivere

$data Array di valori da assegnare ai registri, uno per ognuno dei registri da scrivere. Il numero di elementi determina il numero di registri scritti nel dispositivo.

$dataTypes Array di formati relativi ai valori per ogni registro (contenuti in $data). Valori possibili:

• “WORD”

• “INT”

• “DINT”

• “REAL”

La funzione restituisce i dati letti nel medesimo formato illustrato nel capitolo 8.4 di questo manuale; il significato degli argomenti da passare alla funzione è analogo a quanto illustrato nei punti 8.4 e 8.6.

8.9 CONVERSIONE DEI VALORI LETTI DAL DISPOSITIVOI valori ricevuti attraverso le funzioni di lettura dei registri possono essere convertiti nei formati PHP per una successiva elaborazione, in base al formato originale ed al contenuto (vedere documentazione del dispositivo MODBUS specifico). Seguono alcuni esempi, nei quali $data è sempre l'array di bytes letto (di lunghezza pari al numero di registri specificato come argomento della funzione di lettura).

8.9.1 VALORI SU 4 BYTE

Se i valori contenuti nei registri del dispositivo sono organizzati su 4 bytes (2 registri per ogni valore), è possibile separarli in un array di valori con la funzione


$values = array_chunk($data, 4);

A questo punto, su ognuno dei valori di questo array è possibile applicare una delle seguenti funzioni di conversione, in base al formato originario nel dispositivo MODBUS. Seguono alcuni esempi...

Conversione dei valori da REAL a valori FLOAT in PHP

foreach($values as $bytes)

{

$value = PhpType::bytes2float($bytes);

[...]

}

Conversione dei valori precedenti da DINT a valori INTEGER in PHP


{

$value = PhpType::bytes2signedInt($bytes);

[...]

}

Conversione dei valori precedenti da DWORD a valori INTEGER in PHP


{

$value = PhpType::bytes2unsignedInt($bytes);

[...]

}

8.9.2 VALORI SU 2 BYTE

Se i valori contenuti nei registri del dispositivo sono organizzati su 2 bytes (1 registro per valore), è possibile separarli in un array di valori con la funzione

$values = array_chunk($data, 2);

A questo punto, su ognuno dei valori di questo array è possibile applicare una delle seguenti funzioni di conversione, in base al formato originario nel dispositivo MODBUS. Seguono alcuni esempi...

Conversione dei valori da INT a valori INTEGER in PHP


{

$value = PhpType::bytes2signedInt($bytes);

[...]

}

Conversione dei valori da WORD a valori INTEGER in PHP


{

$value = PhpType::bytes2unsignedInt($bytes);

[...]


}

Se invece si desidera una corretta formattazione in formato stringa di tutta la sequenza di registri interrogati, è sufficiente chiamare la funzione

PhpType::bytes2string($data);


9 LIBRERIA “SONOS”

9.1 INTRODUZIONELa libreria “sonos” permette di gestire all'interno di uno SCRIPT uno o più dispositivi di un sistema di diffusione audio SONOS. Per ulteriori dettagli sul sistema SONOS, si rimanda al sito www.sonos.com.

Questa libreria è disponibile a partire dalla versione software 1.1.0. Se si dispone di una versione antecedente, aggiornare IKON SERVER prima di proseguire.


include_library(“sonos”);


sonosM

Questa classe (“SONOS manager” o “gestore SONOS”) mette a disposizione una serie di funzioni (o “metodi”) per caricare oggetti della supervisione ed effettuare operazioni su di essi. La classe sonosM, come già altre viste in precedenza, è pensata per essere utilizzata attraverso “chiamate statiche”, come ad esempio

sonosM::bind(...);


9.3 ASSEGNAZIONE DEL DISPOSITIVO SONOSPrima di effettuare operazioni di lettura/scrittura è necessario assegnare alla classe sonosM il dispositivo SONOS con cui dialogare, attraverso la funzione

sonosM::bind($host);

Dove


Finché non viene nuovamente chiamata questa funzione, ogni successiva operazione viene effettuata sul dispositivo SONOS selezionato.


http://www.sonos.com/

Per conoscere l'indirizzo IP di un dispositivo SONOS, è necessario aver installato sul proprio PC/MAC il software di gestione SONOS, quindi aprire la finestra “INFORMAZIONI SU SONOS” e identificare il dispositivo interessato, come ad esempio nella figura seguente:

9.4 CONTROLLO DEL DISPOSITIVO SONOSUna volta effettuato il “bind” della libreria con il dispositivo SONOS, è possibile controllarne lo stato attraverso i seguenti comandi:

sonosM::stop(); //Arresta la riproduzione dei contenuti multimediali

sonosM::play(); //Avvia la riproduzione dei contenuti multimediali

sonosM::pause(); //Sospende la riproduzione dei contenuti multimediali

La selezione dei contenuti multimediali da riprodurre deve essere effettuata tramite il software di gestione SONOS.

E' possibile spostarsi tra le tracce della lista di riproduzione attraverso i seguenti comandi:

sonosM::next(); //Passa alla traccia successiva

sonosM::previous(); //Passa alla traccia precedente

sonosM::setTrack($number); //Passa alla traccia identificata dal numero $number

E' possibile inoltre spostarsi ad un determinato tempo (in secondi) dall'inizio della traccia corrente con il seguente comando:

sonosM::setTime($time);

Infine, è possibile tornare all'inizio della traccia corrente con il comando

sonosM::rewind();


che equivale a impostare “0” come tempo dall'inizio della traccia.

E' possibile conoscere lo stato corrente del dispositivo attraverso il comando

$state = sonosM::getState();

che restituisce lo stato secondo la seguente convenzione:

• 1 → Riproduzione in corso (PLAY)

• 2 → Riproduzione sospesa (PAUSE)

• 3 → Riproduzione arrestata (STOP)

9.5 REGOLAZIONE DEL VOLUMEE' possibile impostare il volume del dispositivo SONOS attraverso il comando

sonosM::setVolume($volume);

passando alla funzione un numero compreso tra 0 e 100; è possibile anche sapere il volume attuale del dispositivo attraverso il comando

$volume = sonosM::getVolume();

che restituisce il valore, sempre compreso tra 0 e 100.

E' possibile impostare temporaneamente il volume a zero attraverso il comando di “MUTE”, che può essere impostato e letto rispettivamente con le funzioni

sonosM::setMute(); //Imposta lo stato di “MUTE”

$mute = sonosM::getMute(); //Legge lo stato di “MUTE”

9.6 MODALITÀ DI RIPRODUZIONEE' possibile modificare la modalità di riproduzione della lista corrente di contenuti multimediali attraverso il comando

sonosM::setPlayMode($mode); //Imposta la modalità di riproduzione

che si aspetta come argomento uno dei seguenti valori:

• 0 → normale (la riproduzione termina con l'ultima traccia)

• 1 → ripetizione (dopo l'ultima traccia viene riprodotta nuovamente la prima)

• 2 → casuale (le tracce vengono riprodotte in modo casuale, all'infinito)


9.7 INFORMAZIONI MULTIMEDIALIE' possibile chiedere al dispositivo le informazioni relative al contenuto multimediale che è in riproduzione in un certo momento attraverso il comando

$info = sonosM::getMediaInfo(); //Recupera le informazioni multimediali

che restituisce un array di informazioni; i più comunemente utilizzati sono:

artist Artista

title Titolo della traccia

album Nome dell'album o raccolta

Track Numero della traccia

position Posizione corrente (in secondi) dall'inizio della traccia

duration Durata (in secondi) della traccia corrente

Per utilizzare una specifica informazione all'interno dell'array ricevuto dal dispositivo, è sufficiente scrivere ad esempio

$info = sonosM::getMediaInfo(); //Recupera le informazioni multimediali

$title = $info[“title”]; //Assegna il titolo alla variabile $title

$album = $info[“album”]; //Assegna l'album alla variabile $album

...

9.8 ESEMPIO DI CONFIGURAZIONEIKON SERVER contiene (a partire dalla versione 1.1, con cui è stata introdotta la libreria SONOS) una serie di esempi che mostrano come utilizzare le principali funzioni viste in questo capitolo.

Questi esempi, documentati in dettaglio nel capitolo 12, possono essere utilizzati per costruire nel FRONTEND un controllo di zona SONOS; vediamo insieme in sintesi i passaggi da compiere...

9.8.1 CREAZIONE OGGETTO COMPOSITO

Come primo passo, deve essere creato un oggetto composito per ogni dispositivo SONOS che si intende gestire, utilizzando il template “ZONA AUDIO MULTIROOM”, come illustrato nell'apposito capitolo del MANUALE DI INSTALLAZIONE.

Una volta creato l'oggetto composito e selezionato il template corretto, premere ripetutamente il pulsante “AGGIUNGI” nella lista “SOTTO-OGGETTI ASSOCIATI ALL'OGGETTO COMPOSITO” per creare tante variabili quante sono le funzioni che si desidera gestire; il template prevede le seguenti funzioni (“IDENTIFICATIVO”):

• Controllo di stato (PLAY / PAUSE)• Arresto riproduzione (STOP)• Traccia precedente / successiva• Modo riproduzione (NORMALE / RIPETIZIONE / CASUALE)• Volume


Se si desidera gestire altre funzioni, è necessario utilizzare il template “GENERICO”, come meglio dettagliato nel MANUALE DI INSTALLAZIONE.

Una volta creati i sotto-oggetti, è necessario assegnare a ciascuno il corrispondente “IDENTIFICATIVO” ed un nome che permetta, successivamente, di identificarli. Se lo si desidera, è possibile specificare una “ETICHETTA” che viene visualizzata sopra i pulsanti del popup nel FRONTEND.

La figura seguente esemplifica quanto visto:

Una volta inserito l'oggetto composito in un ambiente, il risultato finale è simile alla figura seguente:


9.8.2 CREAZIONE E ASSOCIAZIONE DEGLI SCRIPT RUNNER

Arrivati a questo punto, si dispone degli oggetti necessari per il FRONTEND, i quali tuttavia non svolgono alcuna funzione attiva di controllo del sistema SONOS. A tale scopo, per ognuna delle funzioni gestite nell'oggetto composito, è necessario creare uno SCRIPT RUNNER il quale:

• Sia associato ad uno script che richiama la funzione della libreria SONOS desiderata• Sia relazionato con il corrispondente oggetto “VARIABILE” appartenente all'oggetto

composito, come INGRESSO, in modo che comandando nel FRONTEND il relativo comando venga passato allo SCRIPT e, di qui, al dispositivo SONOS

Tra gli esempi presenti in IKON SERVER sono già presenti tutti gli SCRIPT necessari per il richiamo delle funzioni della libreria SONOS previste nel template del controllo di zona multiroom viste in precedenza; per ulteriori dettagli su questi esempi, si rimanda al capitolo 12 di questo manuale.

A titolo di esempio, vediamo come costruire lo SCRIPT RUNNER per il controllo volume: si crea innanzitutto uno SCRIPT RUNNER nuovo e si sceglie, dal menu a tendina “SCRIPT”, l'esempio “SONOS.SETVOLUME”. Lo SCRIPT non deve essere eseguito all'avvio, né in modalità “loop”, quindi le relative opzioni devono essere lasciate invariate.


A questo punto, si cerca con il motore di ricerca l'oggetto “VARIABILE” creato in precedenza per il controllo del volume (è importante a tale scopo il nome assegnato nella fase precedente, durante la creazione all'interno dell'oggetto composito), e lo si trascina tra gli INGRESSI dello SCRIPT RUNNER, scegliendo “VALORE DI...” come valore da passare allo SCRIPT RUNNER:


A questo punto, l'oggetto nel FRONTEND passa il valore selezionato dall'utente – in questo caso, il volume – allo SCRIPT RUNNER, il quale lo passa a sua volta allo SCRIPT e, da qui, viene comandato il dispositivo SONOS con l'apposita funzione (setVolume() in questo caso).


10 LIBRERIA “DUNE”

10.1 INTRODUZIONELa libreria “dune” permette di gestire all'interno di uno SCRIPT uno o più dispositivi di un sistema di diffusione audio DUNE-HD. Per ulteriori dettagli sul sistema SONOS, si rimanda al sito http://dune-hd.com/eng/ .

Questa libreria è disponibile a partire dalla versione software 1.1.0. Se si dispone di una versione antecedente, aggiornare IKON SERVER prima di proseguire.


include_library(“dune”);


duneM

Questa classe (“DUNE manager” o “gestore DUNE”) mette a disposizione una serie di funzioni (o “metodi”) per caricare oggetti della supervisione ed effettuare operazioni su di essi. La classe sonosM, come già altre viste in precedenza, è pensata per essere utilizzata attraverso “chiamate statiche”, come ad esempio

duneM::bind(...);


10.3 ASSEGNAZIONE DEL DISPOSITIVO DUNEPrima di effettuare operazioni di lettura/scrittura è necessario assegnare alla classe duneM il dispositivo DUNE-HD con cui dialogare, attraverso la funzione

duneM::bind($host);

Dove


Finché non viene nuovamente chiamata questa funzione, ogni successiva operazione viene effettuata sul dispositivo DUNE selezionato.


http://dune-hd.com/eng/

http://dune-hd.com/eng/

10.4 CHIAMATE GENERICHE AL DISPOSITIVO DUNELa comunicazione con il dispositivo DUNE avviene attraverso chiamate di rete che rispondono alle specifiche di protocollo riportate nel documento

http://dune-hd.com/support/ip_control/dune_ip_control_overview.txt

in base alla versione firmware del proprio dispositivo. La libreria DUNE per IKON SERVER mette a disposizione la funzione generica

$result = duneM::call($cmdString);

che si aspetta come argomento ($cmdString) la stringa di comando così come riportata nella documentazione ufficiale, dopo il carattere “?” successivo al comando “do”; ad esempio, per effettuare la chiamata riportata nella documentazione

http://10.0.0.1/cgi-bin/do?

cmd=start_file_playback&media_url=nfs://10.0.0.1:/VideoStorage:/SomeFolder/file.mkv

bisogna chiamare la libreria con il seguente comando:

duneM::call(“cmd=start_file_playback&media_url=nfs://10.0.0.1:/VideoStorage:/SomeFolder/file.mkv”);

La funzione restituisce il codice di ritorno _SCRIPT_RESULT_NOERROR se il comando è andato a buon fine, _SCRIPT_RESULT_USERERROR in caso contrario.

I risultati restituiti dal dispositivo a fronte dell'ultima chiamata effettuata – così come documentato nelle specifiche di protocollo – sono resi disponibili dalla libreria nella variabile globale

$_duneLastResponse

che è un oggetto contenente, sotto forma di attributi, tutte le informazioni restituite dal dispositivo; tra queste, il messaggio di esito dell'operazione dato dal dispositivo (“ok” se ha avuto buon fine, un messaggio di errore in caso contrario) è disponibile digitando

$_duneLastResponse->command_status

all'interno dello SCRIPT.

10.5 CONTROLLO DEL DISPOSITIVO DUNEPer agevolare il compito di scrittura degli SCRIPT di controllo del sistema DUNE, la libreria mette a disposizione una serie di funzioni che includono già le chiamate di più comune utilizzo, le quali consentono di effettuare i principali controlli sul sistema multimediale.


http://dune-hd.com/support/ip_control/dune_ip_control_overview.txt

Per riprodurre un determinato contenuto multimediale, ad esempio, è possibile – in base al tipo di contenuto – richiamare una delle seguenti funzioni:

duneM::playFile($url); //Riproduce un generico file multimediale

duneM::playDVD($url); //Riproduce un DVD o un file in formato DVD

duneM::playBluRay($url); //Riproduce un BLU-RAY o un file informato BLU-RAY

duneM::playList($url,$track); //Riproduce una playlist, eventualmente partendo

(se specificato) da un certo numero di traccia

Il parametro $url deve contenere il percorso al dispositivo (CD, DVD, BLU-RAY) o al file, o ancora alla playlist, seguendo le convenzioni riportate nella documentazione DUNE vista in precedenza.

Esempi:

duneM::playFile(“nfs://10.0.0.1:/VideoStorage:/SomeFolder/file.mkv”);

duneM::playDVD(“smb://10.0.0.1/VideoStorage/SomeFolder/DVDFolder”);

duneM::playDVD(“storage_name://MyHDD1/SomeFolder/dvd_image.iso”);

duneM::playBluRay(“nfs://10.0.0.1:/VideoStorage:/SomeFolder/BlurayFolder”);

duneM::playBluRay(“nfs://10.0.0.1:/VideoStorage:/SomeFolder/bluray_image.iso”);

E' possibile riportare il dispositivo DUNE rispettivamente allo “schermo nero” ed alla schermata principale con i comandi

duneM::blackScreen();

duneM::mainScreen();

mentre per spegnere il dispositivo è necessario chiamare la funzione

duneM::standby();

10.6 EMULAZIONE TELECOMANDOE' possibile emulare il telecomando IR del dispositivo DUNE attraverso la funzione generica

duneM::irCode($code);

Che prevede come argomento il codice della funzione IR, secondo la convenzione riportata nella documentazione online

http://dune-hd.com/support/rc

Ad esempio, per emulare il tasto “1” del telecomando è necessario scrivere

duneM::irCode(“F40BBF00”);

Per agevolare l'utilizzo all'interno degli SCRIPT, la libreria mette a disposizione (per i pulsanti di più comune utilizzo) una seconda funzione, a cui passare una stringa contenente il descrittivo del pulsante da emulare:

duneM::irButton($button);

Il che rende possibile emulare il medesimo tasto “1” tramite la più agevole chiamata


http://dune-hd.com/support/rc

duneM::irButton(“1”);

La tabella seguente riporta un elenco dei pulsanti gestiti da quest'ultima funzione; si presti particolare attenzione alla corretta digitazione, rispettando maiuscole/minuscole (ed inserendo, ovviamente, le diciture tra gli apici per passarle come stringa, anche nel caso dei pulsanti numerici):

EJECT MUTE MODE POWER A B C D

1 2 3 4 5 6 7 8

9 0 CLEAR SELECT V+ V- P+ P-

SETUP UP DOWN LEFT RIGHT ENTER RETURN INFO

PLAY PAUSE PREV NEXT STOP REW FWD REC

Per ulteriori informazioni sulla funzione e compatibilità dei pulsanti con le diverse versioni del sistema DUNE, si rimanda alla documentazione online.

10.7 GESTIONE DELLA RIPRODUZIONEIl volume del sistema DUNE può essere impostato attraverso la funzione

duneM::setVolume($volume);

che si aspetta un valore da 0 a 100; è possibile viceversa mettere il dispositivo in MUTE (o, viceversa, disattivare il NUTE) passando rispettivamente i valori 1 o 0 alla funzione

duneM::setMute($mute);

Infine, è possibile mettere in PLAY o in PAUSE la riproduzione del contenuto multimediale precedentemente selezionato attraverso i comandi

duneM::play();

duneM::pause();


11 LIBRERIA “MESSAGES”

11.1 INTRODUZIONELa libreria “messages” permette di inviare notifiche a video e via email direttamente all'interno di uno SCRIPT, senza dover necessariamente creare oggetti all'interno del progetto di supervisione.


include_library(“messages”);


msgM

Questa classe (“manager dei messaggi”) mette a disposizione una serie di funzioni (o “metodi”) per caricare oggetti della supervisione ed effettuare operazioni su di essi. La classe msgM, come già altre viste in precedenza, è pensata per essere utilizzata attraverso “chiamate statiche”, come ad esempio

msgM::sendVideoMsg(...);


11.3 INVIO DI UNA NOTIFICA A VIDEOPer inviare una nuova notifica a video “on the fly” durante l'esecuzione di uno script è sufficiente richiamare la funzione

msgM::sendVideoMsg($msg,$level);

Dove

$msg Messaggio da inviare

$level Livello di priorità del messaggio. Valori possibili:

0 Allarme (predefinito)

1 Avvertimento

2 Informazione

Esempio:


msgM::sendVideoMsg(“Ricevuto valore ” . input() . “ in ingresso”,2);

La funzione restituisce _SCRIPT_RESULT_NOERROR in caso di successo, un codice di errore in caso contrario.

11.4 INVIO DI UNA NOTIFICA VIA EMAILAnalogamente è possibile inviare “on the fly” un messaggio di posta elettronica attraverso la chiamata

msgM::sendEMailMsg($msg,$to,$subject,$cc,$bcc);

Dove

$msg Messaggio da inviare

$to Indirizzo/i email a cui inviare il messaggio

Nel caso di indirizzo multipli, separarli con “;”

$subject Oggetto del messaggio [Facoltativo]

$cc Indirizzo/i email in copia [Facoltativo]

$bcc Indirizzo/i email in copia nascosta [Facoltativo]

La funzione restituisce _SCRIPT_RESULT_NOERROR in caso di successo, un codice di errore in caso contrario.


12 ESEMPI

12.1 INTRODUZIONEQuesto capitolo riporta e commenta gli esempi precaricati all'interno di IKON SERVER, che possono essere usati come base di partenza per la realizzazione dei propri SCRIPT personalizzati.

12.2 LOGIC.ANDQuesto script di esempio calcola una logica AND tra tutti gli ingressi associati all'oggetto SCRIPT RUNNER che esegue lo SCRIPT stesso. Il codice dell'esempio è il seguente (alcuni commenti sono stati omessi per brevità):

include_library("surrounding");

//Initializing logic result

$result = true;

//Scanning parent relations

foreach($me->parentRelations as $parentRelation)

{

$parent = $parentRelation->parent;

$parent_value = $parent->value;

//Calculating new logic result by putting parent value in AND with previous result

$result = $result && (!empty($parent_value));

//If result is no longer true, skipping: no need for further calculation, it won't never be true again!

if(!$result) break;

}

//Sending result to output - In this way, runner will pass it to child (active event)

output($result);

Questo esempio è molto simile a quello presente nel capitolo 6.4 di questo manuale: viene effettuata una “scansione” di tutte le relazioni di tipo “padre” (quindi, con gli INGRESSI dello SCRIPT RUNNER) e, di ognuna, identificato il valore corrente dell'oggetto di riferimento; questo viene usato per calcolare la AND con il valore calcolato all'iterazione precedente.

Qualora il risultato non sia più vero, il ciclo viene terminato anticipatamente, in quanto non sarà più possibile rendere nuovamente vera l'espressione AND.

Il valore così calcolato viene passato all'ambiente chiamante con la funzione output().

12.3 LOGIC.ORIn modo del tutto analogo all'esempio precedente, questo script calcola una logica OR tra tutti gli ingressi; per comodità, sono evidenziate in rosso le differenze rispetto al precedente:



//Initializing logic result

$result = false;


{



//Calculating new logic result by putting parent value in OR with previous result

$result = $result || (!empty($parent_value));

//If result is true, skipping: no need for further calculation, it won't never be false again!

if($result) break;

}

//Sending result to output - In this way, runner will pass it to child (active event)

output($result);

In questo caso, il ciclo viene interrotto non appena uno degli INGRESSI ha valore non nullo: la logica OR infatti non potrà mai più diventare falsa, ed è quindi inutile proseguire con le iterazioni.

12.4 SERIAL.WRITER_GENERICQuesto script rappresenta un generico scrittore sulla seriale, a partire dal valore ricevuto come VALORE DI INGRESSO. Il codice è il seguente (anche in questo caso, alcuni commenti sono stati omessi per brevità):

include_library("serial");

//Uncomment following lines if you need to change default serial settings

//$serialM->deviceSet("/dev/ttyS4"); //ATTENTION: change it at your own risk! This is default RS232 webserver port

//$serialM->confBaudRate(19200); //Change baudrate - Allowed values: 110,150,300,600,1200,2400,4800,9600,19200,38400,57600,115200

//$serialM->confParity("none"); //Change parity - Allowed values: "none","odd","even"

//$serialM->confCharacterLength(8); //Change character length

//$serialM->confStopBits(1); //Change stop bits

//$serialM->confFlowControl("none"); //Change flow control - Allowed values: "none","rts/cts","xon/xoff"

//Opening serial port


//Initializing message as input value

$msg = input();

//Sending message to serial port, by adding a trailing return at the end (new line)

$serialM->sendMessage($msg . "\n");

//Closing serial port



//Sending input value to output - In this way, value is passed to any eventual runner's child and set as its value

output(input());

Come si può vedere, prima del comando di apertura della porta seriale sono riportati per comodità tutti i possibili comandi da effettuare per cambiare le impostazioni standard della comunicazione seriale (è sufficiente de-commentarli e impostare il valore desiderato, come meglio dettagliato nel capitolo 7.3 di questo manuale).

Il valore scritto sulla seriale è quello ricevuto in ingresso tramite la funzione input(), seguito dal terminatore di riga standard (da modificare eventualmente in base alle proprie esigenze).

Al termine della scrittura, una volta chiusa la seriale, lo SCRIPT imposta la stessa stringa scritta sulla porta di comunicazione come valore dello SCRIPT RUNNER stesso, in modo che – qualora inserito nelle pagine di supervisione – esso presenti a video lo stesso valore. Questa impostazione è ovviamente opzionale e ininfluente ai fini della scrittura sulla seriale, e va eventualmente modificata in base alle proprie esigenze.

12.5 DEMUX.STATUSBYTEQuesto script effettua una operazione di “demultiplexing” sul valore ricevuto come VALORE DI INGRESSO, supponendo che si tratti di un valore numerico su 1 byte (compreso quindi, in rappresentazione decimale, tra 0 e 255), separandolo negli 8 valori ad 1bit qualora interpretato come numero binario.

Questa operazione può avere una ricaduta pratica volendo trattare i cosiddetti “status byte” che alcuni dispositivi KNX utilizzano per inviare sul bus il proprio stato (da cui il nome dell'esempio stesso). Lo script permette di “spacchettare” questo valore ed assegnare ad 8 oggetti di uscita dello SCRIPT RUNNER i corrispondenti valori binari, che tipicamente contengono uno specifico significato di stato.

Lo SCRIPT presuppone che lo SCRIPT RUNNER che lo esegue abbia al più 8 USCITE, ed imposta ad ognuna di esse – nell'ordine con cui sono state associate allo SCRIPT RUNNER stesso – il valore binario via via ricavato dal “demultiplexing” del valore ad 1 byte.


//Converting input value to binary

$statusByte = str_pad(decbin(input()),8,'0',STR_PAD_LEFT);

//Scanning childs up to 8th, setting corresponding demuxed value

for($i=0;$i<8;$i++)

{

//Initializing output name into a temporary variable

$outName = "out" . ($i+1);

//It variable is not set, exiting loop - It means we don't have enought childs associated to script runner

if(!isSet($$outName)) break;

//Setting value to child


$$outName->set($statusByte[$i] ? 1 : 0);

}

//Returning an empty string - In such a way, environment won't call childs again (since we already did it!)

output();

In particolare, la riga di codice

$statusByte = str_pad(decbin(input()),8,'0',STR_PAD_LEFT);

converte in binario il valore decimale ricevuto in ingresso, e aggiunge all'inizio eventualmente caratteri “0” per portarla ad una lunghezza fissa di 8. Il successivo ciclo, con un contatore da 1 ad 8, assegna innanzitutto ad una variabile “di appoggio” il nome della variabile che identifica l'uscita dello SCRIPT RUNNER corrispondente al contatore...

$outName = "out" . ($i+1);

… e successivamente verifica se la variabile con quel nome esiste: se non è valorizzata (e quindi lo SCRIPT RUNNER non ha tante uscite quanto è il valore corrente del contatore) si esce dal ciclo:

if(!isSet($$outName)) break;

In caso contrario (quindi l'uscita corrispondente esiste) viene effettuato un comando di “set” sull'uscita, passando il valore 1 o 0 in base al valore binario della originaria conversione da decimale dello status byte:

$$outName->set($statusByte[$i] ? 1 : 0);

Il linguaggio PHP permette di utilizzare come nome di una variabile il valore di un'altra variabile; è questo il caso dell'espressione

$$outName

dell'esempio, che – in base al valore di $outName (che può essere “out1”, “out2” etc...) - equivale, di volta in volta, a scrivere

$out1, $out2 etc...

e quindi accedere, ad ogni iterazione del ciclo, ad una delle variabili predefinite che danno accesso alle uscite dello SCRIPT RUNNER (vv. capitolo 6.3 di questo manuale)

Infine, lo script termina con il comando

output();

che, non restituendo alcun valore all'ambiente chiamante, evita che vengano eseguiti gli “eventi attivi” con le uscite, essendo esse già state comandate dallo SCRIPT stesso (ognuna con il valore “prelevato” dallo status byte).


12.6 MATH.SUMQuesto script di esempio calcola la somma algebrica tra tutti gli ingressi associati all'oggetto SCRIPT RUNNER che esegue lo SCRIPT stesso. Il codice dell'esempio è il seguente (i commenti sono stati omessi per brevità):


$sum = 0;


{



$sum = $sum + floatval($parent_value);

}

output($sum);

Questo esempio è molto simile a quello presente nel capitolo 6.4 di questo manuale: viene effettuata una “scansione” di tutte le relazioni di tipo “padre” (quindi, con gli INGRESSI dello SCRIPT RUNNER) e, di ognuna, identificato il valore corrente dell'oggetto di riferimento; questo viene usato per calcolare la somma con il valore calcolato all'iterazione precedente.

Il valore così calcolato viene passato all'ambiente chiamante con la funzione output().

12.7 MATH.PRODUCTQuesto script di esempio calcola il prodotto algebrico tra tutti gli ingressi associati all'oggetto SCRIPT RUNNER che esegue lo SCRIPT stesso. Il codice dell'esempio è il seguente (i commenti sono stati omessi per brevità):


$product = 1;


{



$product = $product * floatval($parent_value);

}

output($product);

Lo SCRIPT è concettualmente identico al precedente esempio, con l'unica differenza che, nel caso del prodotto algebrico, il risultato deve essere inizializzato ad 1 invece che a 0.

Anche in questo caso, il valore così calcolato viene passato all'ambiente chiamante con la funzione output().


12.8 MODBUS.READCOILSQuesto script di esempio legge un insieme di COILS (ingressi digitali) da un dispositivo MODBUS SLAVE e, su variazione, comanda il corrispondente oggetto della supervisione associato come USCITA dello SCRIPT RUNNER:


$host = "192.168.0.71"; //Change this according with MODBUS SLAVE IP address

$protocol = "TCP"; //Same as above

$start = 0; //First coil to read

$number = count($me->childRelations);

if($number>0)

{

include_library("modbus");


$values = modbusM::readCoils(0, $start, $number);

for($i=0;$i<count($values);$i++)

{

$value = !empty($values[$i]) ? 1 : 0;

debug("Coil " . ($start + $i) . " has value $value",true);

$childName = "out" . ($i+1);

if(is_object($$childName))

{

if($$childName->value == $value) continue;

$$childName->set($value);

debug("Object " . $$childName->name . " set to $value",true);

}

}

}

output();

Come si può facilmente intuire, la prima parte dello SCRIPT inizializza una serie di parametri necessari per la comunicazione con il dispositivo MODBUS SLAVE:




Oltre all'indirizzo IP ed al protocollo, è importante specificare anche l'indirizzo MODBUS del primo COIL da leggere; fare riferimento alla documentazione del dispositivo MODBUS per sapere quale indirizzo specificare (tenendo presente che il comando di lettura dei COILS introduce già automaticamente l'offset predefinito per la lettura dei coils, ovvero “10000”).

Lo SCRIPT è pensato per essere eseguito da uno SCRIPT RUNNER a cui associare tanti oggetti in USCITA quanti sono i COILS (ingressi digitali) da leggere sul dispositivo MODBUS SLAVE:


Lo SCRIPT, una volta lanciato, legge il numero di oggetti associati in USCITA allo SCRIPT RUNNER...


… e (dopo aver controllato che ci sia almeno un oggetto, ed aver incluso la libreria di comunicazione MODBUS) legge altrettanti COILS dal dispositivo MODBUS SLAVE:

$values = modbusM::readCoils(0, $start, $number);

A questo punto, viene scorso l'array di risultati (che contiene un numero di elementi corrispondente al numero di oggetti in USCITA), viene identificato il valore ed assegnato ad una variabile (che può valere “1” o “0” in base allo stato letto dal MODBUS)...

$value = !empty($values[$i]) ? 1 : 0;

... e viene identificato l'oggetto in USCITA corrispondente


La variabile contiene il nome dell'oggetto di uscita (es: “out1”) quindi l'oggetto è accessibile tramite l'espressione

$$childName

A questo punto, dopo aver controllato che l'oggetto effettivamente esista...



lo SCRIPT verifica che l'oggetto non sia già nello stesso stato del valore letto dal MODBUS ($value), nel qual caso non fa nulla e passa all'oggetto successivo:

if($$childName->value == $value) continue;

Se gli stati sono differenti, l'oggetto di USCITA viene comandato con il nuovo valore letto dal dispositivo MODBUS:


Al termine, lo SCRIPT restituisce una stringa vuota all'ambiente chiamante:

Output();

Questo passaggio è importante perchè, in questo modo, le USCITE non vengono comandate al termine dello SCRIPT, essendo esse già state comandate (se necessario) durante l'esecuzione.

Tipicamente, uno SCRIPT RUNNER associato ad uno SCRIPT di questo tipo viene eseguito in background sin dall'avvio del sistema:

Il tempo di loop determina con quale frequenza vengano letti (in “polling”) i COILS del dispositivo MODBUS SLAVE, e quindi con quale “reattività” un eventuale cambio di stato venga recepito da IKON SERVER e inviato al corrispondente oggetto di USCITA.

Tempi di interrogazione troppo bassi (inferiori al secondo) possono determinare un sovraccarico di lavoro su IKON SERVER, soprattutto se sono numerosi i COILS (o i REGISTRI, con altri script simili in parallelo) da interrogare.


12.9 MODBUS.READREGISTERSQuesto script è concettualmente identico al precedente, con l'unica differenza che legge REGISTRI e non COILS sul dispositivo MODBUS SLAVE; per agevolare il confronto, sono messe in evidenza le differenze salienti tra i due esempi:




$start = 0; //First register to read

$dataLength = 2; //Bytes for each data - Tipically 2 or 4 bytes


if($number>0)

{



$data = modbusM::readRegisters(0, $start, $number);

$values = array_chunk($data, $dataLength);

for($i=0;$i<count($values);$i++)

{

$value = PhpType::bytes2signedInt($values[$i]);

debug("Register " . ($start + $i) . " has value $value",true);



{


debug("Object " . $$childName->name . " set to $value",true);

}

}

}

output();

In questo caso è necessario anche specificare su quanti bytes siano organizzati i singoli dati da leggere dal dispositivo MODBUS, e di conseguenza assegnare agli oggetti in USCITA:

$dataLength = 2; //Bytes for each data - Tipically 2 or 4 bytes

In questo modo l'array di bytes letto via rete può essere separato in base al numero di bytes di ogni singolo valore...

$values = array_chunk($data, $dataLength);

… e successivamente utilizzato per la scrittura, valore per valore, sugli oggetti in USCITA. In base alla formattazione dei valori letti via MODBUS è necessario utilizzare l'apposita funzione di conversione, come ad esempio (ipotizzando che i valori siano numeri interi):

$value = PhpType::bytes2signedInt($values[$i]);


Per ulteriori dettagli sulla conversione dei valori si rimanda alla sezione 8.9 di questo manuale.

Per semplicità, questo esempio non effettua un controllo sul valore di ogni oggetto di USCITA prima di scrivere il valore ricevuto via MODBUS; sarebbe tuttavia opportuno fare questo controllo – come viene fatto invece nell'esempio di lettura dei COILS – soprattutto in casi di elevata frequenza di polling, per evitare di innescare continuamente comandi sugli oggetti della supervisione inutilmente (se il valore cioè non è cambiato).

Anche in questo caso, tipicamente la lettura deve avvenire periodicamente, quindi lo SCRIPT RUNNER va eseguito in loop con una certa frequenza di aggiornamento, e – tipicamente – impostato per essere eseguito sin dall'avvio del sistema.

12.10 MODBUS.WRITECOILSQuesto script di esempio scrive un insieme di COILS (uscite digitali) su un dispositivo MODBUS SLAVE ogni qualvolta uno degli oggetti specificati in INGRESSO allo SCRIPT RUNNER cambia di stato:





$number = count($me->parentRelations);

if($number>0)

{



$values = array();


{


$value = $parent->value;

$values[] = (!empty($value) ? TRUE : FALSE);

}

$result = modbusM::writeCoils(0, $start, $values);

debug("Written coils to modbus slave: " . implode(",",$values));

}

output();

In modo analogo a quanto visto nell'esempio precedente, la prima sezione imposta i parametri di comunicazione con il dispositivo MODBUS SLAVE...



$start = 0; //First coil to write


… ivi compreso il primo COIL da scrivere ($start). In questo caso il numero di COILS da scrivere è determinato dal numero di oggetti di INGRESSO associati allo SCRIPT RUNNER:

$number = count($me->parentRelations);

A questo punto lo SCRIPT, dopo aver controllato la presenza di almeno un oggetto e incluso la libreria MODBUS, compila un array di valori scorrendo l'elenco degli oggetti di INGRESSO...


{


$value = $parent->value;

$values[] = (!empty($value) ? TRUE : FALSE);

}

… per poi scrivere l'array via MODBUS:

$result = modbusM::writeCoils(0, $start, $values);

Anche in questo caso, lo SCRIPT non restituisce nulla all'ambiente chiamante, e termina dopo aver completato la scrittura via rete.

12.11 SONOS.GENERICQuesto script contiene un esempio di possibile gestione di un dispositivo SONOS:

include_library("sonos");

sonosM::bind("192.168.0.150");

sonosM::play();

debug("Now SONOS is playing...",true);

sleep(5);

sonosM::setVolume(50);

debug("Now SONOS volume is 50%...",true);

sleep(5);

sonosM::next();

debug("Skipped to next SONOS track...",true);

sleep(5);

sonosM::pause();

debug("Now SONOS is in pause...",true);

output();


Dopo aver fatto la connessione al dispositivo SONOS con l'indirizzo IP desiderato, vengono inviati alcuni comandi, intervallati da un'attesa di 5 secondi.

12.12 SONOS.SETVOLUMEQuesto script imposta il volume di un dispositivo SONOS ricevendolo come parametro di ingresso (tipicamente, da un oggetto collegato come INGRESSO allo SCRIPT RUNNER che mette in esecuzione questo SCRIPT):


sonosM::bind("192.168.0.150");

$volume = input();

sonosM::setVolume($volume);

output();

Questo SCRIPT è compatibile con il rendering grafico “VOLUME” disponibile per gli oggetti semplici, e con la sotto-funzione “VOLUME” del template “ZONA AUDIO MULTIROOM” per oggetti compositi

12.13 SONOS.GETVOLUMEQuesto script richiede il volume ad un dispositivo SONOS e lo restituisce in uscita (passandolo tipicamente ad un oggetto collegato come USCITA allo SCRIPT RUNNER che esegue lo SCRIPT):


configuration!

sonosM::bind("192.168.0.150");

$volume = sonosM::getVolume();

output($volume);

12.14 SONOS.PLAYPAUSEQuesto script mette in PLAY o in PAUSE un dispositivo SONOS in base al fatto che riceva come parametro di ingresso 1 o 0:


sonosM::bind("192.168.0.150");

$cmd = input();

if(intval($cmd)==1)

sonosM::play();

else

sonosM::pause();

output();

Questo SCRIPT è compatibile con il rendering grafico “PLAY / PAUSE” disponibile per gli oggetti semplici, e con la sotto-funzione “PLAY / PAUSE” del template “ZONA AUDIO MULTIROOM” per oggetti compositi


12.15 SONOS.PREVNEXTQuesto script passa alla traccia successiva o precedente di un dispositivo SONOS in base al fatto che riceva come parametro di ingresso 1 o 0:

include_library("sonos");sonosM::bind("192.168.0.150");

$cmd = input();

if(intval($cmd)==1)

sonosM::next();

else

sonosM::previous();

output();

Questo SCRIPT è compatibile con il rendering grafico “PREV / NEXT” disponibile per gli oggetti semplici, e con la sotto-funzione “TRACCIA PRECENTE / SUCCESSIVA” del template “ZONA AUDIO MULTIROOM” per oggetti compositi

12.16 SONOS.SETPLAYMODEQuesto script imposta la modalità di riproduzione di un dispositivo SONOS, in base al valore ricevuto in ingresso:


sonosM::bind("192.168.0.150");

$mode = input();

sonosM::setPlayMode($mode);

output();

Questo SCRIPT è compatibile con il rendering grafico “MODALITA' DI RIPRODUZIONE” disponibile per gli oggetti semplici, e con la sotto-funzione “MODALITA' DI RIPRODUZIONE” del template “ZONA AUDIO MULTIROOM” per oggetti compositi

12.17 SONOS.GETINFOQuesto script interroga un dispositivo SONOS per chiedere informazioni sul contenuto multimediale attualmente in riproduzione, e restituisce alcune tra queste informazioni passandole agli oggetti associati come USCITE dello SCRIPT RUNNER, se esistono (secondo un ordine arbitrario all'interno dello SCRIPT, che deve ovviamente essere rispettato nell'associazione delle USCITE):



sonosM::bind("192.168.0.150");

$info = sonosM::getMediaInfo();

if(isSet($out1) && ($out1->value != $info["artist"])) $out1->set($info["artist"]);

if(isSet($out2) && ($out2->value != $info["title"])) $out2->set($info["title"]);

if(isSet($out3) && ($out3->value != $info["album"])) $out3->set($info["album"]);

if(isSet($out4) && ($out4->value != $info["Track"])) $out4->set($info["Track"]);

if(isSet($out5) && ($out5->value != $info["position"])) $out5->set($info["position"]);

if(isSet($out6) && ($out6->value != $info["duration"])) $out6->set($info["duration"]);


output();

12.18 DUNE.ONOFFQuesto SCRIPT accende o spegne un dispositivo DUNE in base al fatto che riceva rispettivamente il valore 1 o 0 come parametro di ingresso:

include_library("dune");

duneM::bind("192.168.0.150");

$cmd = input();

if(intval($cmd)==1)

duneM::mainScreen();

else

duneM::standby();

output();

12.19 DUNE.PLAYPAUSEQuesto SCRIPT mette in PLAY o in PAUSE un dispositivo DUNE in base al fatto che riceva come parametro di ingresso rispettivamente 1 o 0:


duneM::bind("192.168.0.150");

$cmd = input();

if(intval($cmd)==1)

duneM::play();

else

duneM::pause();

output();

Questo SCRIPT è compatibile con il rendering grafico “PLAY / PAUSE” disponibile per gli oggetti semplici, e con la sotto-funzione “PLAY / PAUSE” del template “ZONA AUDIO MULTIROOM” per oggetti compositi

12.20 DUNE.SETVOLUMEQuesto SCRIPT imposta il volume di un dispositivo DUNE in base al valore ricevuto come ingresso:


duneM::bind("192.168.0.150");

$volume = input();

duneM::setVolume($volume);

output();


Questo SCRIPT è compatibile con il rendering grafico “VOLUME” disponibile per gli oggetti semplici, e con la sotto-funzione “VOLUME” del template “ZONA AUDIO MULTIROOM” per oggetti compositi

12.21 DUNE.IRCOMMANDQuesto SCRIPT emula la pressione di un tasto del telecomando di un sistema DUNE in base al valore passato come ingresso:


duneM::bind("192.168.0.150");

$button = input();

duneM::irButton($button);

output();

12.22 DEWPOINTQuesto SCRIPT calcola il punto di rugiada a partire da un valore di TEMPERATURA ed uno di UMIDITA' RELATIVA, associati come oggetti di INGRESSO allo SCRIPT RUNNER. In particolare, si suppone in questo esempio che il primo ingresso sia la TEMPERATURA e il secondo l'UMIDITA'.


$T = floatval($in1->value);

$H = floatval($in2->value);

$D = round(pow(($H/100),(1/8)) * (112 + (0.9 * $T)) + (0.1 * $T) - 112,1);

output($D);

Il calcolo è basato sulla formula approssimata disponibile al seguente indirizzo internet:

http://it.wikipedia.org/wiki/Punto_di_rugiada


http://it.wikipedia.org/wiki/Punto_di_rugiada

13 APPENDICI

13.1 TIPI FUNZIONALI DI OGGETTOLa tabella seguente riporta un elenco completo di tutti i tipi funzionali di oggetto previsti da IKON SERVER, utilizzati dai servizi di comunicazione per lo svolgimento delle operazioni “in background” del webserver. Solitamente si fa riferimento a questo tipo di oggetto come “TYPE”.

Per ognuno di essi è riportato, oltre al tipo e la descrizione, le azioni possibili; queste ultime possono essere richiamate con il metodo

objM::objPerformOperation(ID,OPERATION,VALUE);

come dettagliato nella sezione 5.5 di questo manuale.

TIPO (TYPE) DESCRIZIONE AZIONI

VIRTUALOBJECT Variabile SETVALUE → Imposta un valore all'oggetto

SCENARIO Scenario EXECUTE → Esegue lo scenario

STOPEXECUTION → Arresta l'esecuzione

LOGIC Logica EVALUATE → Valuta la logica

CONDITION Condizione CALCULATE → Calcola il confronto di valori

CLIENTBROWSER Client REDIRECT → Effettua un salto pagina sul client

VOIPCALL → Effettua una chiamata VOIP all'indirizzo IP del client

NOTIFY_VIDEO Notifica a video INSERT → Crea un messaggio a video

NOTIFY_EMAIL Notifica via email SENDMAIL → Invia un messaggio email

INTEGRATOR Integratore INTEGRATE → Aggiorna il calcolo dell'integratore

RESET → Riporta a 0 il valore dell'integratore

EIBOBJECT Oggetto KNX SETVALUE → Imposta un valore sul corrispondente indirizzo di gruppo KNX

GETVALUE → Emette una richiesta sul bus KNX di lettura stato aggiornato

CSCMD Script runner RUN → Esegue lo script

QUIT → Termina l'esecuzione dello script

USER Utente REDIRECT → Effettua un salto pagina su tutti i client in cui è connesso l'utente

VOIPCALL → Effettua una chiamata VOIP a tutti i clienti in cui è connesso l'utente

USERGROUP Gruppo utenti

USERPERMISSION Permesso

CONTAINER Oggetto composito

CAMERA Telecamera IP


PBXELEMENT Telefono IP

Videocitofono IP

Gruppo di chiamata VOIP

VOIPCALL → Effettua una chiamata VOIP destinata all'oggetto

13.2 TIPI WEB (PHPCLASS) DI OGGETTOLa tabella seguente riporta un elenco completo di tutti i tipi di oggetto previsti da IKON SERVER per quanto riguarda l'interfaccia web. Solitamente, si fa riferimento a questo tipo di oggetto come “PHPCLASS”.

Per ognuno di essi è riportato – laddove presente - il tipo funzionale (o “TYPE”) corrispondente; è possibile che più di una PHPCLASS facciano riferimento al medesimo TYPE. Se non è presente, la PHPCLASS non ha una controparte funzionale per i servizi di comunicazione; questo accade tipicamente per tutte le tipologie web che hanno una funzione puramente grafica (ambienti, collegamenti etc...)

TIPO (PHPCLASS) DESCRIZIONE TYPE DI RIFERIMENTO

dpadObject Oggetto generico *

dpadGroup Ambiente (o “cartella” in senso generale)

dpadUrl Collegamento

dpadSysCmd Comando di sistema * SYSCMD

dpadSysCmdWait Comando di attesa di uno scenario SYSCMD

dpadUser Utente USER

dpadUserGroup Gruppo utenti USERGROUP

dpadUserPermission Permesso di accesso per gruppi utente USERPERMISSION

dpadTriggerObject Trigger di sistema su cambiamento DB * TRIGGEROBJECT

dpadContainer Oggetto composito CONTAINER

dpadVirtualObject Variabile VIRTUALOBJECT

dpadScenario Scenario SCENARIO

dpadPbxExtension Telefono IP PBXELEMENT

dpadPbxTrunk Linea telefonica VOIP

dpadPbxQueue Gruppo di chiamata VOIP

dpadPbxDoorOpener Videocitofono IP

dpadLogic Logica LOGIC

dpadCondition Condizione CONDITION

dpadClientBrowser Client CLIENTBROWSER

dpadNotifyVideo Notifica a video NOTIFY_VIDEO

dpadNotifyEmail Notifica via email NOTIFY_EMAIL

dpadIntegrator Integratore INTEGRATOR


dpadEibObject Oggetto KNX EIBOBJECT

dpadCamera Telecamera IP CAMERA

dpadScriptRunner Script runner CSCMD

dpadLoadControl Controllo carichi CSCMD

* : tipologie di oggetto solitamente non utilizzate o disponibili in interfaccia web


14 NOTE DI RILASCIO

14.1 VERSIONE 1.0.2

CHANGELOG:

TIPOLOGIA LIVELLO DESCRIZIONE

Enhancement Importante Aggiunta possibilità di eseguire uno SCRIPT RUNNER in automatico all'avvio della supervisione

Enhancement Importante Aggiunta possibilità di eseguire uno SCRIPT RUNNER iterativamente in backgrund (modalità “loop”)

Enhancement Importante Aggiunta possibilità di includere altri SCRIPT all'interno di uno SCRIPT

Enhancement Importante Aggiunta libreria di gestione protocollo MODBUS via rete (TCP/UDP)

Enhancement Medio Aggiunta funzione nella libreria “object” per salvare un attributo di un oggetto all'interno del database

Enhancement Medio Modificato aspetto grafico degli SCRIPT RUNNER nel FRONTEND per gestire i comandi di ESECUZIONE ed ARRESTO

Enhancement Medio Ora gli SCRIPT RUNNER possono eseguire anche ESEMPI e non più solo SCRIPT personalizzati. Inoltre, è possibile includere ESEMPI all'interno dei propri SCRIPT.

Enhancement Medio Inseriti nuovi esempi

KNOWN ISSUES:

14.2 VERSIONE 1.1.0

CHANGELOG:

TIPOLOGIA LIVELLO DESCRIZIONE

Enhancement Importante Aggiunta attributi oggetti alla libreria “OBJECT”

Enhancement Importante Aggiunta libreria SONOS

Enhancement Importante Aggiunta libreria DUNE

Enhancement Medio Inseriti nuovi esempi


IKON Server - Domotica Labs · • Nel caso di comando diretto dall'interfaccia del FRONTEND di...

Documents

Transcript of IKON Server - Domotica Labs · • Nel caso di comando diretto dall'interfaccia del FRONTEND di...