====== ComApps ======

----

====== Le Comapps ======

Le comapps sono dei programmi, in qualsiasi linguaggio, che servono per interrogare un dispositivo di misura e leggerne i dati.

Per poterlo fare bisogna innanzitutto che il dispositivo abbia apposite API per poterlo interrogare, una volta che abbiamo i dati li dobbiamo formattare in un apposito formato leggibile da MeterN, ne abbiamo parlato **__[[:metern|qui]]__** .

MeterN ha già delle comapss preconfezionate realizzate e messe a disposizione dall'autore, basta solo impostare i propri dati, altre dobbiamo realizzarle da noi, a questo scopo possiamo aiutarci studiando i vari esempi messi a disposizione dall'autore al seguente [[https://github.com/jeanmarc77/meterN_comapps/tree/main|LINK]].

<WRAP center round info 60%>\\
Le comapps devono essere tutte archiviate in una directory, meglio se fuori dalla directory che contiene MeterN cosi in caso di reinsatallazione e/o aggiornamento non verranno modificate o cancellate.\\
</WRAP>


===== Comapss standard =====

  * pool123s Se avete installato e funzionante 123solar questa comapss si intefaccia con l'altro applicativo e passa i dati necessari a MeterN
  * remotepool123s come il precedente ma legge i dati su un sito remoto dove è installato 123solar
  * houseenergy E' una comapps che legge vari meter, imposta vari Meter Id (i meter id sono fissi in quanto servono per calcolare i dati)


===== Comapss autoprodotte =====

Le comapps sono di due tipi, alla fine fanno le stesse cose, ma le fanno in modo diverso:

  * Pooler = leggono continuamente i dati direttamente dal meter (un dato alla volta)
  * Daemon = sono dei programmi che leggono tutti i dati dal meter li parcheggiano su un file di supporto da dove vengono letti mediante un pooler

per capire la differenza di funzionamento facciamo un esempio comparativo, supponiamo di dover leggere 4 dati da un meter (W prodotti, Wh prodotti, W consumati, Wh consumati). \\ Con un pooler si devono fare 4 cicli di lettura sul meter (tipicamente un SDM o uno Shelly) \\ Con un Daemon si fa un solo ciclo di lettura sul meter e poi si legge 4 volte il file di supporto.

Il primo è da preferire se si leggono uno o due dati, il secondo è molto più performante se si devono leggere molti dati inoltre è molto utile nei casi in cui si debbano leggere dati da siti web dove ci sono limiti al numero di letture orarie e/o giornaliere


===== Struttura delle comapps =====

<wrap em>Pooler</wrap>

Sono file singoli che vengono attivati direttamente da MeterN e si interfacciano direttamente col meter

^Programma^Descrizione^Esempio|
|pooler.php|programma che legge i dati dal meter e li passa a MeterN|shelly1.php|

<wrap em>Daemon</wrap>

qui la cosa si fa più strutturata, dobbiamo sempre avere:

^Programma^Descrizione^Esempio|
|com_daemon.php|Avvia il daemon_loop|shelly0_daemon.php|
|daemon_loop.php|legge i dati dal meter|shelly0_loop.php|
|daemon.php|pooler che legge i dati dal file di supporto|shelly0.php|

Ogni pooler o daemon dovrà gestire tanti parametri ( il nome con cui MeterN richiama il dato) tamti quanti sono i dati che si vogliono gestire. questo parametro verrà richiamato da MeterN e sarà inserito nella configurazione dei vari meter.


====== Creare una comapps ======

----


===== Comapps pooler =====

Dobbiamo posizionare il programma nella directory che conterrà tutte le comapps, ma lo dobbiamo fare come amministratore, tutta la procedura andrebbe fatta seguendo il flusso senza interromperla per non perdere i diritti di amministratore senza accorgersene.\\
Procedere nel seguente modo:

<code>
sudo -s
cd /var/www/comapps

</code>

Con il nostro editor preferito creiamo il file:

<code>
poolshelly.php

</code>

Al suo interno andremo a inserire il seguente codice:

<code php [enable_line_numbers="true"]>

#!/usr/bin/php
<?php

if (isset($_SERVER['REMOTE_ADDR'])) {
die('Direct access not permitted');
}

error_reporting(~E_WARNING);

// This script will output a ShellyEM counter into a meterN compatible format
// Configure, then ln -s /var/www/comapps/poolshelly.php /usr/bin/poolshelly and chmod +x poolshelly.php
// Request Main command with 'poolshelly {energy | energy1 | power | power1}'

// Shelly IP
$IP = '192.168.xxx.yyy';
// Shelly request
$url = "http://"."$IP"."/status";
$remotedata = file_get_contents($url);

// meterN config

$METERID    = 1;

// No edit is needed below

if (isset($argv[1])) {

    $GP = null;
    if (!empty($remotedata)) {
        $memarray = json_decode($remotedata, true);
        if ($argv[1] == 'power') {
            $GP = $memarray['emeters'][0]['power'];
            $GP = round($GP, 1);
            echo "$METERID($GP*W)\n";
        }
        elseif ($argv[1] == 'energy') {
            if (isset($memarray['emeters'][0]['total'])) {
                $KWHT = round($memarray['emeters'][0]['total']); // Wh
                echo "$METERID($KWHT*Wh)\n";
            } else {
                die("Abording: KWHT[0] not defined\n");
            }
        }
        elseif ($argv[1] == 'power1') {
            $GP = $memarray['emeters'][1]['power'];
            $GP = round($GP, 1);
            echo "$METERID($GP*W)\n";
        }
        elseif ($argv[1] == 'energy1') {
            if (isset($memarray['emeters'][1]['total'])) {
                $KWHT = round($memarray['emeters'][1]['total']); // Wh
                echo "$METERID($KWHT*Wh)\n";
            } else {
                die("Abording: KWHT[1] not defined\n");
            }
        }
    } else {
        die("Abording: Nessun dato presente\n");
    }
} else {
    die("Usage: poolshelly { energy | energy1 | power | power1 }\n");
}
?>


</code>

dobbiamo inoltre rendere il file eseguibile dal sistema, per far questo eseguiamo i seguenti passaggi:
<code>

cd /var/www/comapps
chown www-data:www-data poolshelly.php
chmod a+x /var/www/comapps/poolshelly.php

</code>

a questo punto dobbiamo creare un link simbolico per poter richiamare il programma

<code>
ln -s /var/www/comapps/poolshelly.php /usr/bin/poolshelly

</code>

ora siamo pronti per l'operazione più importante, testare il software creato prima di darlo in pasto a MeterN.

Dalla shell, con riga di comando lanciare tutte le opzioni previste nel software per assicurarsi che diano il risultato voluto, se avete previsto la gestione degli errori, generateli, per assicurarvi che il software li gestisca correttamente, nell'esempio precedente:

<code>
poolshelly energy
poolshelly energy1
poolshelly power
poolshelly power1
poolshelly

</code>

l'ultimo genera l'errore di nessuna opzione richiesta e visualizza le opzioni possibili.

----


===== Comapps daemon =====

Come detto in precedenza dobbiamo creare 3 programmi, per tenere in ordine i programmi, se non già fatto, creeremo una directory dove posizionare i com_daemon che in effetti non servono a manipolare i dati ma ad avviare i daemon_loop.

<code>
sudo -s
cd /var/www/comapps
mkdir -v daemon

</code>


==== Daemon_loop ====

Iniziamo ora a creare il programma di loop che andrà a leggere il nostro meter nello specifico si tratta di uno Shelly EM con una sola pinza che legge immissioni e prelievi distinguendoli con i valori positivi per i prelievi e negativi per le immissioni, il file lo chiameremo shelly_3_loop.php

shelly_3_loop.php

<code php [enable_line_numbers="true"]>

#!/usr/bin/php
<?php
if (isset($_SERVER['REMOTE_ADDR'])) {
    die('Direct access not permitted');
}
// Beware, only use a tmpfs as /dev/shm (ramfs) !

// This script will perform a loop to continuosly  request data to ShellyEM meter and put data into a Shelly_n_log.txt file
// Request the follow data {energy | power | volt | ampere | cosphi | energy1 | power1 }'
// **** Measurements performed with a single clamp that measures import + ed export - ******
// by Walter62  rev 00   on 02/07/23

$IP = '192.168.xxx.yyy'; // Shelly IP for import export energy
$CH = 0;                   // Channel "0 = import" or "1 = export" which you want use for volt-ampere-cosphi
$MID = 3;                  // meterN config

// No edit is needed below

$url = "http://"."$IP"."/status"; // Shelly request
$filelog = "shelly_" . $MID . "_log.txt"; // Temporary file for dataset exaple "selly_1_log.txt"

while (true) {
    $dataarray = array();
    $remotedata = "";

    $remotedata = file_get_contents($url);
    //print_r($remotedata);

    if (!empty($remotedata)) {
        $memarray = json_decode($remotedata, true);

        $GP   = round($memarray['emeters'][0]['power'],1); //W

        if ($GP <0){
            $GP_0 = 0;
            $GP_1 = abs($GP);
        } else {
            $GP_0 = $GP;
            $GP_1 = 0;
        }

        //channel 0 ==> Import
        //$GP_0   = round($memarray['emeters'][0]['power'],1); //W
        $KWHT_0 = round($memarray['emeters'][0]['total'],1); // Wh

        //Channel 1 ==> Export
        //$GP_1   = round($memarray['emeters'][1]['power'],1); //W
        //$KWHT_1 = round($memarray['emeters'][1]['total_returned'],1); // Wh
        $KWHT_1 = round($memarray['emeters'][0]['total_returned'],1); // Wh

        //channel $CH
        $VOLT   = round($memarray['emeters'][$CH]['voltage'],1); // V
        $AMP    = abs(round (${'GP_'.$CH}/$VOLT,1)); //A
        $PHI    = abs(round($memarray['emeters'][$CH]['pf'],2)); // cosphi

        $dataarray[0] = $MID . '_0(' . $GP_0 . '*W)';    // n_0(nnn*W)
        $dataarray[1] = $MID . '_0(' . $KWHT_0 . '*Wh)';
        $dataarray[2] = $MID . '_1(' . $GP_1 . '*W)';
        $dataarray[3] = $MID . '_1(' . $KWHT_1 . '*Wh)';
        $dataarray[4] = $MID . '_V(' . $VOLT . '*V)';
        $dataarray[5] = $MID . '_A(' . $AMP . '*A)';
        $dataarray[6] = $MID . '_PHI(' . $PHI . '*phi)';
        $str          = implode(PHP_EOL, $dataarray);
        file_put_contents('/dev/shm/' . $filelog, $str);

    } else {
        if (file_exists($filelog)) {
            $now = time();
            if ($now - filemtime($filelog)> 5) { // 5 sec
                unlink('/dev/shm/' . $filelog);
            }
        }
    }
    usleep(500000);
}
?>


</code>

Dato che con una pinza leggo sia il valore di energia importata che esportata ma con valore negativo, ho disabilitato la lettura del canale e dalla riga 34 alla 40 vado a leggere il valore di energia letto dalla pinza e in funzione che sia positivo o negativo assegno al canale appropriato il valore assoluto quindi positivo per entrambi i canali.

Ora che abbiamo il file compilato lo salviamo in:
<code>

/var/www/comapps

</code>


==== daemon ====

Ora passiamo alla stesura del programma che si occuperà di leggere i dati e renderli disponibili a MeterN, lo chiameremo shelly_3.php, il contenuto dovrà essere il seguente:

shelly_3.php

<code php [enable_line_numbers="true"]>

#!/usr/bin/php
<?php
if (isset($_SERVER['REMOTE_ADDR'])) {
    die('Direct access not permitted');
}
// This script will read output file of the ShellyEM counter and will expos the data to MeterN
// Configure, then ln -s /var/www/comapps/shelly_n.php /usr/bin/shelly_n and chmod +x shelly_n.php
// Request Main command with 'shelly_1 {energy | power | volt | ampere | cosphi | energy1 | power1 }'
// by Walter62  rev 00   on 02/07/23

$MID = 3;  // meter to call - shelly_n = shelly_3
$filelog = "shelly_" . $MID . "_log.txt"; // Temporary file for dataset exaple "selly_2_log.txt"

// No edit is needed

$help = "Usage: shelly_3 { energy | power | volt | ampere | cosphi | energy1 | power1 }\n";

if (!isset($argv[1])) {
    die($help);
}

if ($argv[1] == 'power'){
    $outstr =  exec('cat /dev/shm/'.$filelog .' | egrep "^'. $MID .'_0\(" | grep "*W)"');
}elseif ($argv[1] == 'energy'){
    $outstr =  exec('cat /dev/shm/'.$filelog .' | egrep "^'. $MID .'_0\(" | grep "*Wh)"');
}elseif ($argv[1] == 'power1'){
    $outstr =  exec('cat /dev/shm/'.$filelog .' | egrep "^'. $MID .'_1\(" | grep "*W)"');
}elseif ($argv[1] == 'energy1'){
    $outstr =  exec('cat /dev/shm/'.$filelog .' | egrep "^'. $MID .'_1\(" | grep "*Wh)"');
}elseif ($argv[1] == 'volt'){
    $outstr =  exec('cat /dev/shm/'.$filelog .' | egrep "^'. $MID .'_V\(" | grep "*V)"');
}elseif ($argv[1] == 'ampere'){
    $outstr =  exec('cat /dev/shm/'.$filelog .' | egrep "^'. $MID .'_A\(" | grep "*A)"');
}elseif ($argv[1] == 'cosphi'){
    $outstr =  exec('cat /dev/shm/'.$filelog .' | egrep "^'. $MID .'_PHI\(" | grep "*phi)"');
} else{
    die($help);
}

echo "$outstr";
?>


</code>


==== Com_daemon ====

Adesso abbiamo i due programmi che che leggono i dati dal contattore e li trasmettono a meter su richiesta, dobbiamo però assicurarci che ad ogni avvio del sistema, o meglio, ad ogni avvio di MeterN si avvii anche il programma daemon_loop (il daemon lo avvia MeterN quando gli serve il dato).

Dato che è più pulito avviare il programma quando MeterN è in esecuzione ci appoggiamo al com_daemon e quindi creiamo il software necessario:

shelly_3_daemon.php

<code php [enable_line_numbers="true"]>

#!/usr/bin/php
<?php
/*
Check shelly_3_loop.php path bellow
Then ln -s  /path to/shelly_3_daemon.php /usr/bin/shelly_3_daemon
Start and stop the daemon via metern/config/config_daemon.php
And request values with shelly_3 command
*/

if (isset($_SERVER['REMOTE_ADDR'])) {
    die('Direct access not permitted');
}

if (file_exists('/dev/shm/shelly_3_daemon.pid')) {
    $cdpid = (int) file_get_contents('/dev/shm/shelly_3_daemon.pid');
    exec("ps -ef | grep $cdpid | grep shelly_3_daemon", $ret);
    if (!isset($ret[1])) {
        $cdpid = null;
        unlink('/dev/shm/shelly_3_daemon.pid');
    }
} else {
    $cdpid = null;
}

if (isset($argv[1])) {
    if (($argv[1] == 'start' || $argv[1] == 'stop') && file_exists('/dev/shm/shelly_3_log.txt')) {
        unlink('/dev/shm/shelly_3_log.txt');
    }
    if ($argv[1] == 'start') {
        if (is_null($cdpid)) {
            $command = 'php /var/www/comapps/shelly_3_loop.php' . '> /dev/null 2>&1 & echo $!;';
            $cdpid     = exec($command);
            file_put_contents('/dev/shm/shelly_3_daemon.pid', $cdpid);
        } else {
            echo "shelly_3_daemon seem to be running as $cdpid";
        }
    } else if ($argv[1] == 'stop') {
        if (!is_null($cdpid)) {
            $command = exec("kill $cdpid> /dev/null 2>&1 &");
        unlink('/dev/shm/shelly_3_daemon.pid');
        }
    } else {
        echo "Usage : shelly_3_daemon {start | stop}\n";
    }
} else {
    echo "Usage : shelly_3_daemon {start | stop}\n";
}
?>


</code>

come per il pooler rendiamo i files eseguibili dal sistema, per far questo eseguiamo i seguenti passaggi:
<code>

sudo -s
cd /var/www/comapps
chown www-data:www-data shelly_3.php
chown www-data:www-data shelly_3_loop.php
chown www-data:www-data daemon/shelly_3_daemon.php
chmod a+x /var/www/comapps/shelly_3.php
chmod a+x /var/www/comapps/shelly_3_loop.php
chmod a+x /var/www/comapps/daemon/shelly_3_daemon.php

</code>

creiamo i link simbolici per poter richiamare i programmi

<code>
ln -s /var/www/comapps/shelly_3.php /usr/bin/shelly_3
ln -s /var/www/comapps/shelly_3_loop.php /usr/bin/shelly_3_loop
ln -s /var/www/comapps/daemon/shelly_3_daemon.php /usr/bin/shelly_3_daemon

</code>

ora siamo pronti per testare il software creato prima di darlo in pasto a MeterN.

Dalla shell, con riga di comando lanciare tutte le opzioni previste nel software per assicurarsi che diano il risultato voluto, se avete previsto la gestione degli errori, generateli, per assicurarvi che il software li gestisca correttamente, nell'esempio precedente:

<code>
poolshelly energy
poolshelly energy1
poolshelly power
poolshelly power1
poolshelly

</code>

l'ultimo genera l'errore di nessuna opzione richiesta e visualizza le opzioni possibili.


====== Configurazione ComApps in MeterN ======

Quando tutto funziona possiamo abilitare i vari programmi in MeterN, per far ciò dobbiamo modificare un file di sistema (sistema di MeterN) in questo modo:

<code>
cd /var/www/metern/config
nano allowed_comapps.php

</code>

alle voci esistenti aggiungere altre voci all'array dopo l'ultima esistente

<code>
$ALLWDCMD[n] = 'poolshelly energy';
$ALLWDCMD[n] = 'poolshelly power';
......
......
$ALLWDCMD[n] = 'shelly_3 energy';
$ALLWDCMD[n] = 'shelly_3 power';
$ALLWDCMD[n] = 'shelly_3 volt';
$ALLWDCMD[n] = 'shelly_3 ampere';
$ALLWDCMD[n] = 'shelly_3 cosphi';
......
......
$ALLWDCMD[n] = 'shelly_3_daemon start';
$ALLWDCMD[n] = 'shelly_3_daemon stop';

</code>

la struttura è la seguente:

  - [//n//] = il numero tra parentesi quadre deve essere un numero progressivo che segue quelle già presenti
  - poolshelly = link simbolico che richiama il nostro programma
  - energy = opzione da richiamare

inserire tante voci quante sono le opzioni che MeterN dovrà richiamare.

Bene, ora che tutte le ComApps sono utilizzabili da MeterN ci occuppiamo di istruire MeterN ad avviare tutte le com_daemon ad ogni avvio, per far questo basta inserirle nel file di configurazione di MeterN che si chiama "config_daemon.php", procediamo come segue:

<code>
cd /var/www/metern/config
nano config_daemon.php

</code>

si aprirà il file in modifica, se non è mai stato usato prima troveremo al suo interno due righe commentate che danno un esempio di come inserire il comando, nell'esempio sotto sono le righe 5 e 9.

<code php [enable_line_numbers="true", start_line_numbers_at=""]>

<?php
if(!defined('checkaccess')){die('Direct access not permitted');}
// Manage com. apps daemon as 'http' user if needed
if (is_null($PID)) { // Stop Daemon
        //$out = exec("com_daemon stop");
        $out0 = exec("shelly_3_daemon stop");
        $out1 = exec("solax_daemon stop");
} else { //Start
        //$out = exec("com_daemon start");
        $out0 = exec("shelly_3_daemon start");
        $out1 = exec("solax_daemon start");
}
?>


</code>

come mostrato nell'esempio, dove si vuole far avviare due com_daemon, si dovranno inserire per ogni com_daemon una riga nella sezione "stop" e una nella sezione "start", nellesempio sono le rige 6 e 7 per lo stop e 10 e 11 per lo start