====== PHP MicroLog ======

===== Popis =====

**PHP MicroLog** je příkaz do příkazové řádky a také knihovna určená pro začlenění do dalších projektů. 

{{:schema.png?350 |}} Projekt je vyvíjen ve scriptovacím jazyce PHP jako software k volnému užití s otevřeným zdrojovým kódem. 

Je určen pro dlouhodobé odesílání dat z měření fotovoltaických elektráren a jiných podobných zařízení prostřednictvím speciálního protokolu, který standardně užívá projekt [[start|MyPower MicroLog]]. 

Projekt je tedy plně kompatibilní se současným měřením, kde je možné se online [[http://mypower.cz/ulogadmin-register|registrovat]], získat FVEID a logovat data na server MyPower.CZ s možností jejich následné vizualizace a realizace dalších výpočtů, dostupných na serveru.

Data z měření je díky tomu možno odesílat z libovolného zařízení s podporou jazyka PHP, například Raspbian pro Raspberry PI, atd. Projekt MicroLog tak získává nezávislost na platformě Arduino s níž však zachovává plnou zpětnou kompatibilitu. 

===== Syntax =====

<code bash>$ php microlog.php [-data AX:valueX[,AY:valueY[,AZ:valueZ[...]]]]</code>

===== Download =====

{{::php-microlog-2-04-01.tgz|}}
===== Instalace =====

Pro instalaci postačí rozbalit stažený archiv.

<code bash>$ tar xzf php-microlog-2-04-01.tgz</code>

Archiv obsahuje následující strukturu souborů:

<code>
.
└── php-microlog
    ├── index.php
    ├── lib-mpw-microlog.php
    └── microlog.php
</code>

PHP MicroLog se po rozbalení nachází v adresáři //./php-microlog//

<code bash>$ cd php-microlog</code>

===== Nastavení =====

==== FVEID ====

Po instalaci je potřeba nakonfigurovat vaše FVEID, které bylo získáno registrací nového měření. V ukázkovém scriptu //microlog.php// je FVEID definováno v proměnné **$fveid**.
<code php>$fveid="mojefve123456";</code>

Řetězec //mojefve123456// nahraďte vašim FVEID.

==== Konfigurace pinů ====

Nastavení pinů je definováno jako asociativní PHP pole v ukázkovém scriptu //microlog.php//. Klíč jednotlivých položek pole je název pinu ve tvaru známém z Arduina, tedy A0 - A15.

**Příklad definice pinu A0 a A6:**

<code php>
$pinconfig=array(
  "A0"  => array (
     "name" => "Panely FV1",
     "unit" => "V",
     "min"  => 0,
     "max"  => 150,
     "opt"  => ["enabled","smp","group0"],
     ),
// ...
  "A6"  => array (
     "name" => "Proud AC L1",
     "unit" => "A",
     "min"  => 0,
     "max"  => 32,
     "opt"  => ["enabled","rms","group2"],
     ),
  );
</code>

{{ ::schema3.png?400|}}**Parametry pinu**

  * **name** - Název pinu
  * **unit** - Jednotka měřených hodnot na tomto pinu
  * **min** - Minimální hodnota 
  * **max** - Maximální hodnota
  * **opt** - Nastavení pinu

Pole **min** a **max** jsou typu //float//, je tedy možno použít desetinnou tečku.

Nastavení pinu v poli **opt** se skládá z pole 3 položek typu //string//.

První položka specifikuje stav pinu a může nabývat hodnot **enabled** nebo **disabled**. Jedná se o signalizaci pro server, zdali je pin aktivní nebo neaktivní. Bez ohledu na toto nastavení jsou data daného pinu odesílána.

Druhá určuje typ hodnoty pinu. Význam hodnot je následující:
  * **smp** - Vzorek z měření
  * **avg** - Průměrná hodnota
  * **rms** - Efektivní hodnota
  * **min** - Minimální hodnota
  * **max** - Maximální hodnota
  * **res1** - Rezerva pro speciální účely
  * **res2** - Rezerva pro speciální účely
  * **def** - Výchozí hodnota

Typ pinu je možno využít v případě, že v rámci jednoho měření pořizujeme více vzorků, tedy stejně jako [[mod:sampler|sampler]] projektu MyPower MicroLog. Z těchto vzorků jsme schopni spočítat průměrnou hodnotu, efektivní hodnotu, minimální a maximální hodnotu v daném měření a nebo použít jednotlivý vzorek. Poslední varianta může vzhledem k rušení vést k nepřesným výsledkům. U střídavých průběhů (například střídavý proud) je možno použít typ pinu **rms** a zasíláme vypočtenou efektivní hodnotu. Zároveň tím serveru dáváme najevo, že posíláme efektivní hodnotu.

Třetí hodnota určuje skupinu, do které měřený PIN patří. Je možno použít jednu ze čtyř skupin, **group0**, **group1**, **group2**, **group3**. Nastavení není povinné a je určeno pro informativní účely, pokud na toto nastavení není například navázána nějaká speciální funkce na straně serveru.



===== Použití =====

Script lze použít jako příkaz příkazové řádky. V takovém případě lze data předávat v parametru //-data//.

==== Logování hodnot z příkazové řádky ====

<code bash>$ php microlog.php -data A0:25.68,A6:231,A15:2.7</code>

==== Integrace do vlastního projektu ====

Knihovnu PHP MicroLog, konkrétně //lib-mpw-microlog.php// je možné pomocí příkazu //include// vložit do vašeho projektu, je-li také psán v PHP. Pro odeslání dat je určena funkce

<code php>Microlog_SendDataToMyPower($fveid,$pinconfig,$data)</code>

Parametry funkce jsou:
  * **$fveid** (string) - obsahuje přidělené FVEID
  * **$pinconfig** (array) - obsahuje datovou strukturu konfigurace pinů, která je popsána výše v [[#konfigurace-pinu|nastavení]].
  * **$data** (array) - obsahuje datovou strukturu s naměřenými hodnotami jednotlivých pinů

Pro odesílání dat slouží datová struktura typu asociativní pole, kdy klíčem je číslo pinu (A0-A15) a hodnotou je buď přímá hodnota, nebo asociativní pole se všemi typy hodnot. 

Příklad definice datové struktury pro pin A0 a A6:

<code php>
  $data=array(

    "A0"  =>  25.722322566,

    "A6"  =>  array(
      "smp"  =>  2.2116,
      "rms"  =>  6.52,
      "avg"  =>  5.321,
      "min"  =>  0,
      "max"  =>  7.1235,
      ),
    );
</code>

Z podstaty jazyka PHP jsou pochopitelně možné i následující zápisy:

<code php>
   "A11" =>  (0b1011001110),
</code>
<code php>
   "A11" =>  0x3ff,
</code>
<code php>
   "A11" =>  1023,
</code>

{{ :schema2.png?400 |}} 

Pokud se odeslání dat podaří, funkce vrací pole hodnot jako výsledek odesílání dat. 

Je-li definován index pole s názvem //"message"//, pak toto obsahuje zprávu ze serveru, například o použití neplatného FVEID atd. Pokud je index s názvem //"finalresult"// roven hodnotě //"OK"//, pak odeslání proběhlo v pořádku. Ukázkové použití je ve scriptu //microlog.php//.

Funkce je vybavena **ukládáním dat do bufferu v případě výpadku internetového spojení**, nebo selhání odeslání dat na server. Je tedy schopna výpadky spojení překlenout. Záznamy dat z měření, které nebyly odeslány při předchozím pokusu o odeslání budou odeslány prioritně dle času, ke kterému byl daný vzorek pořízen. 


===== Konfigurační proměnné =====

V kódu knihovny //lib-mpw-microlog.php// jsou v úvodu 3 konfigurační proměnné.

<code php>
$_microlog_storage_dir       = "/tmp/microlog";

$_microlog_true_values       = "yes";     // yes / no

$_microlog_failover_buffer   = "yes";     // yes / no
</code>

Proměnná **$_microlog_storage_dir** určuje adresář, který je potřebný pro ukládání nezbytných persistentních dat. Zejména je zde ukládán hash konfigurace pinů. Pokud je konfigurace změněna, je proveden přístup na server v režimu //login// a je přenesena i konfigurace pinů. Adresář slouží zároveň jako úložiště pro ukládání dat při nemožnosti se spojit se serverem log.mypower.cz (failover buffer).

Proměnná **$_microlog_true_values** může mít hodnotu //"yes"// nebo //"no"//. V případě zapnuté volby (//"yes"//) je využito rozšíření protokolu MicroLog pro přenos dat a jsou zasílány pravé hodnoty a nikoliv původní 10 bitový rozsah, který je dán omezením analogových pinů Arduina. Je-li volba vypnuta (//"no"//), je použit rozsah 0-1023 a naměřená hodnota je přepočítána dle nastavení daného pinu a jeho maxima a minima, kdy minimum reprezentuje hodnotu 0 a maximum hodnotu 1023.

Proměnná **$_microlog_failover_buffer** má opět možné hodnoty //"yes"// nebo //"no"//. Je-li volba zapnuta, je použit buffer v případě výpadku spojení nebo selhání odesílání dat. Pokud je volba vypnuta, v případě selhání jsou naměřená data zahozena.

===== Diskuze o projektu =====

Téma k tomuto projektu na fóru MyPower.CZ naleznete na adrese http://forum.mypower.cz/viewtopic.php?f=95&t=5199