Webpanel API

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.

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

• variable ID is unique string - in future, may be different for different platforms/protocol versions (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 - 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:

  svc://defaultConnection/877* 0,2]

  • Represents a variable with the commUID 8776. 2 bytes from the offset 0 are returned.

the POST body can be:

1. JSON string (AngularJS default behaviour):

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

2. converted into POST parameters (jQuery default behaviour):

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

• Each value is transmitted as a big endian binary representation of the specified variable (and its offset and length).

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

• Warning : only one variable is expected in the request for the tiniest (uPLC) platforms - other variables are ignored

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]", //variable ID
  "v": [
 {
  "t": 636579093300049300,                //timestamp (UTC)
  "v": "00"                               //value
 },
 {
  "t": 636579093600055900,
  "v": "00"
 },"n": 10                                //offset for the following request. -1 = reading finished
}]
}

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