Differences

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

--- en:mervis-ide:65-webpanel:webpanel-api [2017/06/21 11:01]
m.chlupac
+++ en:mervis-ide:65-webpanel:webpanel-api [2019/05/21 11:13] (current)
@@ Line 7: / Line 7: @@
 ==== Request ====
-Data:
+**URL:** ''http://[ip-address-of-the-plc]/login.cgi''
-<code js>{
+<code javascript>{
+  ver : 1,//version
+  //optional - only for non-authenticated access
+  //credentials
+  c: {u: "karel", p: "x"}
+}</code>
+==== Response ====
+<code javascript>{
+  ver : 1,//version
+  code: "ok", //return code
+  msg: "", //error message
+  c : {u: "karel", p:"x"} //must be used for further communication
+}</code>
+===== Data request =====
+==== Request ====
+**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>
+  * variable ID is unique string - in future, may be different for different platforms/protocol versions (uPLC - int?, SharkRT - string)
+=== Example ===
+<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>
+=== Variable specification for Mervis RT ===
+  * 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.
+  * 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: <code>svc://defaultConnection/877* 0,2]</code>
+    * Represents a variable with the commUID 8776. 2 bytes from the offset 0 are returned.
+the POST body can be:
+  - 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>
+==== Response ====
+<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>
+=== Encoding of values - version 1 ===
+  * Each value is transmitted as a big endian binary representation of the specified variable (and its offset and length).
+=== Example ===
+<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>
+===== Command Request =====
+==== Request ====
+**URL:** ''http://[ip-address-of-the-plc]/command.cgi''
+<code javascript>{
 	ver : 1,//version
-	//optional - only for non-authenticated access
+     //optional - only for non-authenticated access
 	//credentials
-	c: {u: “karel”, p: “x”}
+	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>
-==== Response ====
+  * Warning : only one variable is expected in the request for the tiniest (uPLC) platforms - other variables are ignored
-{
+===== Historical Data Request =====
+==== Request ====
+**URL:** ''http://[ip-address-of-the-plc]/history.cgi''
+<code javascript>{
 	ver : 1,//version
-	code: “ok”, //return code
+     //optional - only for non-authenticated access
-	msg: “”, //error message
+	//credentials
-c : {u: “karel”, p:”x”} //must be used for further communication
+	c: {u: "karel", p: "x"},
+v: [ {i:"svc://defaultConnection/myVarId1",
+      from: XXXX,
+      to: YYYY
+      },
+     {i:"svc://defaultConnection/myVarId1",
+      from: XXXX,
+      to: YYYY
+     }
+   ]
+}</code>
+==== Response ====
+<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>
+===== Native/built-in data types =====
+Note: big endian encoding (v1)
+  * integer (represents int8-int64)
+  * unsigned integer (represents uint8-uint64)
+  * double (double64)
+  * float (float32)
+  * bool (boolean - 0 ~ false, 1 ~ true)
+  * 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)
+  * Enums are encoded into 32-bit int