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.

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

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

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

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

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

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

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

• 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:

  svc://defaultConnection/8776[0,2]

  • 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:

1. Řetězec JSON (výchozí chování AngularJS):

   {"ver":1,"c":{"u":"karel","p":"x"},"v":["svc://defaultConnection/myVarId1","svc://otherConnection/xxxYYYYDDD"]}

2. Převedené POST parametry (výchozí chování jQuery):

   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

{
 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
     }
   ]
}

• 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.

{
 "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
  }
 ]
}

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

{
	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"
     }
   ]
}

• 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.

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

{
	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
     }
   ]
}

{
 "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
}]
}

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.