Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision 		Previous revision
en:mervis-ide:65-webpanel:webpanel-api [2017/06/21 10:51]
m.chlupac created 		en:mervis-ide:65-webpanel:webpanel-api [2019/05/21 10:13]
m.chlupac [Request]
Line 3: Line 3:
 Communication is based on HTTP protocol. Clients send HTTP POST request and get the response depending on the request. Each request must specify the credentials in case the credentials are specified for the project. Communication is based on HTTP protocol. Clients send HTTP POST request and get the response depending on the request. Each request must specify the credentials in case the credentials are specified for the project.
  
-===== Login request =====+===== Login =====
  
-Data:+==== Request ====
  
-<font inherit/courier new;;inherit;;inherit>{</font>+**URL:** ''http://[ip-address-of-the-plc]/login.cgi''
  
-<font inherit/courier new;;inherit;;inherit>ver : 1,//version</font>+<code javascript>{ 
 +  ver : 1,//version 
 +  //optional - only for non-authenticated access 
 +  //credentials 
 +  c: {u: "karel", p: "x"}  
 +}</code>
  
-<font inherit/courier new;;inherit;;inherit>//optional - only for non-authenticated access</font>+==== Response ====
  
-<font inherit/courier new;;inherit;;inherit>//credentials</font> +<code javascript>{ 
- +  ver : 1,//version 
-<font inherit/courier new;;inherit;;inherit>c: {u: “karel”, p: “x”}</font> +  code: "ok", //return code 
- +  msg: "", //error message 
-<font inherit/courier new;;inherit;;inherit>}</font> +  c : {u: "karel", p:"x"} //must be used for further communication 
- +}</code>
-===== Login response ===== +
- +
-<font inherit/courier new;;inherit;;inherit>{</font> +
- +
-<font inherit/courier new;;inherit;;inherit>ver : 1,//version</font> +
- +
-<font inherit/courier new;;inherit;;inherit>code: “ok”, //return code</font> +
- +
-<font inherit/courier new;;inherit;;inherit>msg: “”, //error message</font> +
- +
-<font inherit/courier new;;inherit;;inherit>c : {u: “karel”, p:”x”} //must be used for further communication</font> +
- +
-<font inherit/courier new;;inherit;;inherit>}</font>+
  
 ===== Data request ===== ===== Data request =====
  
-Data:+==== Request ====
  
-<font inherit/courier new;;inherit;;inherit>{</font>+**URL:** ''http://[ip-address-of-the-plc]/values.cgi''
  
-<font inherit/courier new;;inherit;;inherit>ver : 1,//version</font>+<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>
  
-<font inherit/courier new;;inherit;;inherit>//optional - only for non-authenticated access</font>+  * variable ID is unique string - in future, may be different for different platforms/protocol versions (uPLC - int?, SharkRT - string)
  
-<font inherit/courier new;;inherit;;inherit>//credentials</font>+=== Example ===
  
-<font inherit/courier new;;inherit;;inherit>c: {u: “karel”, p: “x”},</font>+<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>
  
-<font inherit/courier new;;inherit;;inherit>//variable IDs</font> 
  
-<font inherit/courier new;;inherit;;inherit>v: [ “svc://defaultConnection/myVarId1”,</font> +=== Variable specification for Mervis RT ===
- +
-<font inherit/courier new;;inherit;;inherit>“svc://otherConnection/xxxYYYYDDD”]</font> +
- +
-<font inherit/courier new;;inherit;;inherit>}</font> +
- +
-  * variable ID is unique string - in future, may be different for different platforms/protocol versions (uPLC - int?, SharkRT - string) +
- +
-==== Variable specification for RT2 ====+
  
   * svc - protocol   * svc - protocol
   * Connection - generally, clients can request data from more sources (more or less corresponds to a connection definition of PLC). For local data (data belonging to the PLC that executes the request) it may be defaultconnection.   * Connection - generally, clients can request data from more sources (more or less corresponds to a connection definition of PLC). For local data (data belonging to the PLC that executes the request) it may be defaultconnection.
   * Variable id: it has a form of commUID[offset, lenght]. CommUID can be retrieved from a .vlist file of the IDE 2 project and specifies a variable. Variables can be of a complex and large types. In this case a user can retrieve only a small part of the variable by using the offset and length.   * Variable id: it has a form of commUID[offset, lenght]. CommUID can be retrieved from a .vlist file of the IDE 2 project and specifies a variable. Variables can be of a complex and large types. In this case a user can retrieve only a small part of the variable by using the offset and length.
-  * Example: svc://defaultConnection/8776[0,2] +  * Example: <code>svc://defaultConnection/877* 0,2]</code> 
-      * Represents a variable with the commUID 8776. 2 bytes from the offset 0 are returned.+    * Represents a variable with the commUID 8776. 2 bytes from the offset 0 are returned.
  
 the POST body can be: the POST body can be:
  
-1) JSON string (AngularJS default behaviour):+  - JSON string (AngularJS default behaviour): <code javascript>{"ver":1,"c":{"u":"karel","p":"x"},"v":["svc://defaultConnection/myVarId1","svc://otherConnection/xxxYYYYDDD"]}</code> 
 +  - converted into POST parameters (jQuery default behaviour):<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>
  
-<font inherit/inherit;;inherit;;inherit>{"ver":1,"c":{"u":"karel","p":"x"},"v":["svc://defaultConnection/myVarId1","svc://otherConnection/xxxYYYYDDD"]}</font> 
  
-2) converted into POST parameters (jQuery default behaviour):+==== Response ====
  
-<font inherit/courier new;;inherit;;inherit>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</font>+<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>
  
-The best solution would be to support both versions. Easier is now the JSON string.+=== Encoding of values - version 1 ===
  
-===== Data response =====+  * Each value is transmitted as a big endian binary representation of the specified variable (and its offset and length).
  
-<font inherit/courier new;;inherit;;inherit>{</font>+=== Example ===
  
-<font inherit/courier new;;inherit;;inherit>ver : 1,//version</font>+<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>
  
-<font inherit/courier new;;inherit;;inherit>code: “ok”, //return code</font> 
- 
-<font inherit/courier new;;inherit;;inherit>msg: “”, //error message</font> 
- 
-<font inherit/courier new;;inherit;;inherit>v: [{</font> 
- 
-<font inherit/courier new;;inherit;;inherit>i: “svc://defaultConnection/myVarId1”, //variable Id</font> 
- 
-<font inherit/courier new;;inherit;;inherit>v: ”ACA1”, //value - binary encoded</font> 
- 
-<font inherit/courier new;;inherit;;inherit>q: “G”,//quality</font> 
- 
-<font inherit/courier new;;inherit;;inherit>t: 654654321654 //timestamp UTC, milliseconds since 1970</font> 
- 
-<font inherit/courier new;;inherit;;inherit>}</font> 
- 
-<font inherit/courier new;;inherit;;inherit>]</font> 
- 
-<font inherit/courier new;;inherit;;inherit>}</font> 
- 
-==== Encoding of values - version 1 ==== 
- 
-  * Each value is transmitted as a big endian binary representation of the specified variable (and its offset and length). 
  
 ===== Command Request ===== ===== Command Request =====
  
-<font inherit/courier new;;inherit;;inherit>{</font>+==== Request ====
  
-<font inherit/courier new;;inherit;;inherit>ver : 1,//version</font>+**URL:** ''http://[ip-address-of-the-plc]/command.cgi''
  
-<font inherit/courier new;;inherit;;inherit>//optional - only for non-authenticated access</font>+<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>
  
-<font inherit/courier new;;inherit;;inherit>//credentials</font> +  * Warning : only one variable is expected in the request for the tiniest (uPLC) platforms - other variables are ignored
- +
-<font inherit/courier new;;inherit;;inherit>c: {u: “karel”, p: “x”},</font> +
- +
-<font inherit/courier new;;inherit;;inherit>v: [{</font> +
- +
-<font inherit/courier new;;inherit;;inherit>i: “svc://defaultConnection/myVarId1”, //variable Id</font> +
- +
-<font inherit/courier new;;inherit;;inherit>//digital setter</font> +
- +
-<font inherit/courier new;;inherit;;inherit>time: ”20.0”, //digital setter has some time property...</font> +
- +
-<font inherit/courier new;;inherit;;inherit>state: “2”, //state that should be applied</font> +
- +
-<font inherit/courier new;;inherit;;inherit>defaultValue: “6”, //some default value</font> +
- +
-<font inherit/courier new;;inherit;;inherit>//analogPlusMinusInit, TPG, ...</font> +
- +
-<font inherit/courier new;;inherit;;inherit>set: 5,</font> +
- +
-<font inherit/courier new;;inherit;;inherit>//set: “<?cdata....?>” //TPG</font> +
- +
-<font inherit/courier new;;inherit;;inherit>//login - pin</font> +
- +
-<font inherit/courier new;;inherit;;inherit>login: “1234”</font> +
- +
-<font inherit/courier new;;inherit;;inherit>}</font> +
- +
-<font inherit/courier new;;inherit;;inherit>]</font> +
- +
-<font inherit/courier new;;inherit;;inherit>}</font> +
- +
-<font inherit/courier new;;red;;inherit>uPLC Warning : only one variable is expected in the request - other variables are ignored</font>+
  
 ===== Historical Data Request ===== ===== Historical Data Request =====
  
-<font inherit/courier new;;inherit;;inherit>{</font>+==== Request ====
  
-<font inherit/courier new;;inherit;;inherit>ver : 1,//version</font>+**URL:** ''http://[ip-address-of-the-plc]/history.cgi''
  
-<font inherit/courier new;;inherit;;inherit>//optional - only for non-authenticated access</font>+<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>
  
-<font inherit/courier new;;inherit;;inherit>//credentials</font>+==== Response ====
  
-<font inherit/courier new;;inherit;;inherit>c: {u: “karel”, p: “x”},</font>+<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]", //variable ID 
 +  "v": [ 
 + { 
 +  "t": 636579093300049300,                //timestamp (UTC) 
 +  "v": "00"                               //value 
 + }, 
 + { 
 +  "t": 636579093600055900, 
 +  "v": "00" 
 + },"n": 10                                //offset for the following request. -1 = reading finished 
 +}] 
 +} 
 +</code>
  
-<font inherit/courier new;;inherit;;inherit>v: [ {i:“svc://defaultConnection/myVarId1”,</font> 
- 
-<font inherit/courier new;;inherit;;inherit>from: XXXX,</font> 
- 
-<font inherit/courier new;;inherit;;inherit>to: YYYY</font> 
- 
-<font inherit/courier new;;inherit;;inherit>},</font> 
- 
-<font inherit/courier new;;inherit;;inherit>{i:“svc://defaultConnection/myVarId1”,</font> 
- 
-<font inherit/courier new;;inherit;;inherit>from: XXXX,</font> 
- 
-<font inherit/courier new;;inherit;;inherit>to: YYYY</font> 
- 
-<font inherit/courier new;;inherit;;inherit>}</font> 
- 
-<font inherit/courier new;;inherit;;inherit>]</font> 
- 
-<font inherit/courier new;;inherit;;inherit>}</font> 
- 
-===== Configuration Response ===== 
- 
-<font inherit/courier new;;inherit;;inherit>{</font> 
- 
-<font inherit/courier new;;inherit;;inherit>ver : 1,//version</font> 
- 
-<font inherit/courier new;;inherit;;inherit>platform: “uPLC”,</font> 
- 
-<font inherit/courier new;;inherit;;inherit>maxVariablesInRequest: 5,</font> 
- 
-<font inherit/courier new;;inherit;;inherit>maxRequestSize: 1500, //http body size in bytes</font> 
- 
-<font inherit/courier new;;inherit;;inherit>preferedLanguage: “en-US”</font> 
- 
-<font inherit/courier new;;inherit;;inherit>}</font> 
  
 ===== Native/built-in data types ===== ===== Native/built-in data types =====
  
 Note: big endian encoding (v1) Note: big endian encoding (v1)
- 
   * integer (represents int8-int64)   * integer (represents int8-int64)
   * unsigned integer (represents uint8-uint64)   * unsigned integer (represents uint8-uint64)
Line 208: Line 212:
   * dt (date time - the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001)   * dt (date time - the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001)
   * time (time - the number of 100-nanosecond intervals)   * time (time - the number of 100-nanosecond intervals)
-  * Enums are encoded into 32-bit int +  * Enums are encoded into 32-bit int 
  
  • © Energocentrum Plus, s.r.o. 2017 - 2024