====== Webpanel API ======

Komunikace je založena na protokolu HTTP. Klienti odesílají HTTP POST požadavky a získávají odpovědi odpovídající zaslanému požadavku. Pokud jsou pro projekt nastaveny přihlašovací údaje, musí je obsahovat každý požadavek.

===== Přihlášení =====

==== Požadavek ====

**URL:** ''http://[ip-address-of-the-plc]/login.cgi''

<code javascript>{
  ver : 1,//version
  //optional - only for non-authenticated access
  //credentials
  c: {u: "karel", p: "x"}
}</code>

==== Odpověď ====

<code javascript>{
  ver : 1,//version
  code: "ok", //return code
  msg: "", //error message
  c : {u: "karel", p:"x"} //must be used for further communication
}</code>

===== Požadavek na data =====

==== Požadavek ====

**URL:** ''http://[ip-address-of-the-plc]/values.cgi''

<code javascript>{
  ver : 1,//version
  //optional - only for non-authenticated access
  //credentials
  c: {u: "karel", p: "x"},
  //variable IDs
  v: [ "svc://defaultConnection/myVarId1",
     "svc://otherConnection/xxxYYYYDDD"]
}</code>

  * ID proměnné je jedinečný řetězec. V budoucnu se může lišit podle platformy nebo verze protokolu (uPLC – int?, SharkRT – string).

=== Příklad ===

<code javascript>{
 "ver": 1,
 "c": {
  "u": "Visitor",
  "p": "b39576d3da8eb2b0e262645e84707cdc"
 },
 "v": ["svc://DefaultConnection/9104[0,4]",
       "svc://DefaultConnection/9105[0,4]",
       "svc://DefaultConnection/9129[456,4]"]
}
</code>

=== Specifikace proměnných pro Mervis RT ===

  * svc – protokol
  * Connection – obecně mohou klienti požadovat data z více zdrojů (více či méně odpovídá definici připojení v PLC). Pro lokální data (data náležející PLC, které požadavek zpracovává) lze použít ''defaultConnection''.
  * ID proměnné má tvar ''commUID[offset,length]''. Hodnotu ''commUID'' lze získat ze souboru ''.vlist'' projektu v Mervis IDE a jednoznačně určuje proměnnou. Proměnné mohou být komplexních nebo velkých datových typů. V takovém případě lze pomocí parametrů ''offset'' a ''length'' načíst pouze požadovanou část proměnné.
  * Příklad: <code>svc://defaultConnection/8776[0,2]</code>
    * Představuje proměnnou s hodnotou ''commUID'' 8776. Vrátí se 2 bajty od offsetu 0.

Tělo POST požadavku může mít následující podobu:

  - Řetězec JSON (výchozí chování AngularJS): <code javascript>{"ver":1,"c":{"u":"karel","p":"x"},"v":["svc://defaultConnection/myVarId1","svc://otherConnection/xxxYYYYDDD"]}</code>
  - Převedené POST parametry (výchozí chování jQuery):<code>ver=1&c%5Bu%5D=karel&c%5Bp%5D=x&v%5B%5D=svc%3A%2F%2FdefaultConnection%2FmyVarId1&v%5B%5D=svc%3A%2F%2FotherConnection%2FxxxYYYYDDD</code>

==== Odpověď ====

<code javascript>{
 ver : 1,//version
 code: "ok", //return code
 msg: "", //error message
v: [{
     i: "svc://defaultConnection/myVarId1", //variable Id
     v: "ACA1", //value - binary encoded
     q: "G",//quality
     t: 654654321654 //timestamp UTC, milliseconds since 1970
     }
   ]
}</code>

=== Kódování hodnot – verze 1 ===

  * Každá hodnota je přenášena jako binární reprezentace zadané proměnné (včetně offsetu a délky) v pořadí bajtů big endian.

=== Příklad ===

<code javascript>{
 "ver": 1.0,
 "code": "ok",
 "msg": "",
 "v": [{
   "i": "svc://DefaultConnection/9104[0,4]",
   "v": "C376DC63",
   "q": "good",
   "t": 636940178310000000
  }, {
   "i": "svc://DefaultConnection/9105[0,4]",
   "v": "C0400000",
   "q": "good",
   "t": 636940178310000000
  }, {
   "i": "svc://DefaultConnection/9129[456,4]",
   "v": "C0400000",
   "q": "good",
   "t": 636940178310000000
  }
 ]
}</code>

===== Požadavek na vykonání příkazu =====

==== Požadavek ====

**URL:** ''http://[ip-address-of-the-plc]/command.cgi''

<code javascript>{
	ver : 1,//version
     //optional - only for non-authenticated access
	//credentials
	c: {u: "karel", p: "x"},
v: [{
     i: "svc://defaultConnection/myVarId1", //variable Id
     //digital setter
     time: "20.0", //digital setter has some time property...
     state: "2", //state that should be applied
     defaultValue: "6", //some default value
     //analogPlusMinusInit, TPG, ...
     set: 5,
     //set: "<?cdata....?>" //TPG
     //login - pin
     login: "1234"
     }
   ]
}</code>

  * Upozornění: Na nejmenších platformách (uPLC) se očekává pouze jedna proměnná v požadavku. Ostatní proměnné jsou ignorovány.

===== Požadavek na historická data =====

==== Požadavek ====

**URL:** ''http://[ip-address-of-the-plc]/history.cgi''

<code javascript>{
	ver : 1,//version
     //optional - only for non-authenticated access
	//credentials
	c: {u: "karel", p: "x"},
v: [ {i:"svc://defaultConnection/myVarId1",
      from: XXXX,
      to: YYYY
      },
     {i:"svc://defaultConnection/myVarId1",
      from: XXXX,
      to: YYYY
     }
   ]
}</code>

==== Odpověď ====

<code javascript>{
 "ver": 1,
 "code": "ok",
 "msg": "",
 "v": [{
  "i": "svc://DefaultConnection/15[0,1]",
  "v": [{
   "t": 636579093300049300,
   "v": "00"
  },
  {
   "t": 636579093600055900,
   "v": "00"
  }],
  "n": 10
 },
 {
  "i": "svc://DefaultConnection/16[0,1]",
  "v": [
 {
  "t": 636579093300049300,
  "v": "00"
 },
 {
  "t": 636579093600055900,
  "v": "00"
 }],"n": 10
}]
}
</code>

===== Nativní vestavěné datové typy =====

Poznámka: Kódování používá pořadí bajtů big endian (v1).

  * integer (představuje int8 až int64)
  * unsigned integer (představuje uint8 až uint64)
  * double (double64)
  * float (float32)
  * bool (boolean – 0 = false, 1 = true)
  * dt (datum a čas – počet intervalů o délce 100 ns, které uplynuly od 1. ledna 0001 00:00:00)
  * time (čas – počet intervalů o délce 100 ns)
  * Výčtové typy (enum) jsou kódovány jako 32bitové celé číslo.