Differences

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

--- en:mervis-scada:50-api [2018/11/06 12:57]
m.chlupac
+++ en:mervis-scada:50-api [2021/04/08 13:04]
127.0.0.1 external edit
@@ Line 3: / Line 3: @@
 Mervis SCADA offers open REST-like API based on JSON and XML data formats. For full description please contact our [[:en:help:support|technical support]].
+**Important:** Only officially supported response format is XML!
 ===== List of basic API methods =====
 ^Function^Description|
 ^api/checkCredentials||
 ^api/logout||
@@ Line 32: / Line 32: @@
-===== Example =====
+===== Examples =====
+====api/checkCredentials====
+**Request**
+   * URL: /api/checkCredentials?format=xml
+   * Method: POST
+**Request**
+<code javascript>
+{"cred":{"n":"demo","p":"demo"}}
+</code>
+**Response**
+<code xml>
+<?xml version="1.0" encoding="utf-8"?>
+<checkCredentialsResult xmlns:r="http://dev.rcware.eu/serialization/references" d="GlobalDomain" l="demo" t="2:85be00d3-5875-4dec-a9b4-c98e2ff2acbe" xmlns="http://dev.rcware.eu/auth" />
+</code>
+  * You **should** use the received token **t** in subsequent API calls.
 ====api/get/history====
@@ Line 45: / Line 67: @@
    "cred":{
       "n":"demo", //username
-      "p":"demo", //password
+      "p":"demo" //password
-      "pe":0
    },
    "projId":"5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //project ID
@@ Line 64: / Line 85: @@
 <getHistoryResult xmlns:r="http://dev.rcware.eu/serialization/references" r:type="b133774d-21ce-42b6-add3-57c012079c55" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/history">
   <!--
-  Interval - ISO interval of trend values defined by the database client.
+  @Interval - ISO interval of trend values defined by the database client.
+  @historyState - to be copied into the next request
+  @nextValOfs - to be copied into the next request until value -1 is reached.
   If ts of value in not within the interval time span after the previous value's gt - some data is missing.
   -->
   <hist projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="62cf4083-31ed-4bc1-be25-044ba837a9f0" propName="Output" interval="PT3M" historyState="" nextValOfs="-1">
@@ Line 104: / Line 128: @@
         <n1:v>12761</n1:v>
       </hv>
-      <!-- value without gt - ts and gt are equeal-->
+      <!-- value without gt - ts and gt are equal-->
       <hv ts="2018-11-06T09:22:03.9461503Z">
         <n1:v>12761</n1:v>
@@ Line 116: / Line 140: @@
+====api/set/history====
+**Request**
+   * URL: /api/set/history?format=xml
+   * Method: POST
+   * Content-Type: text/xml
+Attribute **i** sets **interval** ([[https://en.wikipedia.org/wiki/ISO_8601#Time_intervals|ISO 8601]]) in which the next value should be expected to be saved into a database.
+Even though there could be used name and password in **cred** - you should always use **token** to get the best performance.
+All date and time values are supposed to be in UTC.
+<code xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<setHistoryRequest xmlns="http://dev.rcware.eu/scada/history"
+xmlns:n2="http://dev.rcware.eu/auth"
+xmlns:n1="http://dev.rcware.eu/scada/basic-props"
+projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0"
+dpId="e86dba6d-1250-4e7f-aafb-84fd28324710">
+  <n2:cred t="xxxxx"/><!-- token should be used here -->
+  <vals>
+    <hv ts="2020-03-15T11:00:00+00:00" i="P1D">
+      <n1:v>2.7</n1:v>
+    </hv>
+    <hv ts="2020-03-16T11:00:00+00:00" i="P1D">
+      <n1:v>3.0</n1:v>
+    </hv>
+    <hv ts="2020-03-17T11:00:00+00:00" i="P1D">
+      <n1:v>2.0</n1:v>
+    </hv>
+    <hv ts="2020-03-18T11:00:00+00:00" i="P1D">
+      <n1:v>2.3</n1:v>
+    </hv>
+  </vals>
+</setHistoryRequest></code>
+**Response**
+   * 200 OK
+====api/set/executeActions====
+**Request**
+   * URL: /api/set/executeActions?format=xml
+   * Method: POST
+   * Content-Type: text/xml
+<code xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<executeActionsRequest xmlns="http://dev.rcware.eu/scada/action-defs"
+xmlns:n2="http://dev.rcware.eu/scada/basic-props"
+xmlns:n1="http://dev.rcware.eu/auth"
+xmlns:r="http://dev.rcware.eu/serialization/references">
+  <n1:cred t="xxxxxx"/>
+  <actionDefs projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0">
+    <actions>
+      <actionDefItem propName="INIT" dpId="afc22e18-f8e4-4e08-899c-fb9e4759df3d">
+        <execParam r:type="495c9644-eed1-4b94-933b-3fae702a9aca">
+          <n2:value>16</n2:value>
+        </execParam>
+      </actionDefItem>
+      <actionDefItem propName="ZAP" dpId="34306c80-73f1-4465-ab51-2b2c1e85ab70">
+      </actionDefItem>
+    </actions>
+  </actionDefs>
+</executeActionsRequest></code>
+**Response**
+<code xml><?xml version="1.0" encoding="utf-8"?>
+<executeActionsResponse xmlns:r="http://dev.rcware.eu/serialization/references" code="Ok" message="OK" xmlns="http://dev.rcware.eu/scada/error-reporting" /></code>
+====api/get/values====
+The right way how to retrieve current values of data points (property "Output" which is usually what you want) from one or multiple projects.
+**Request**
+   * URL: /api/get/values?format=xml
+   * Method: POST
+<code javascript>
+{
+ "cred": {
+  "t": "xxxxxx" //token
+ },
+ "propNamesToSerialize": ["Output"],
+ "offset": 0,
+ "count": 1000,
+ "serverState": null,
+ "dps": [{
+   "projId": "ba1a92f7-f213-4a72-90e4-f7142b50274b",
+   "dpIds": ["e089dde2-a097-4e0d-8012-c8cf3dc62694", "1089dde2-a097-4e0d-8012-c8cf3dc62696"]
+  }
+ ]
+}
+</code>
+**Response**
+<code xml><?xml version="1.0" encoding="utf-8"?>
+<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2020-04-07T07:46:34.850422Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints">
+ <vals>
+  <v projId="ba1a92f7-f213-4a72-90e4-f7142b50274b" dataVersion="637217783110000000" serverTime="2020-04-07T07:46:34.850422Z">
+   <dps>
+    <d id="e089dde2-a097-4e0d-8012-c8cf3dc62694" serAlr="true">
+     <props>
+      <p n="Output" t="2020-04-07T07:43:42.1000676Z" q="Bad" r:type="177e726a-3180-4152-bef2-6254e7055e1f">
+       <n1:v>ON</n1:v>
+      </p>
+     </props>
+    </d>
+    <d id="1089dde2-a097-4e0d-8012-c8cf3dc62696" serAlr="true">
+     <props>
+      <p n="Output" t="2020-04-07T07:45:00.2408399Z" q="Good" r:type="b133774d-21ce-42b6-add3-57c012079c55">
+       <n1:v>0</n1:v>
+      </p>
+     </props>
+    </d>
+   </dps>
+  </v>
+ </vals>
+</values></code>
+====api/get/projectByParts====
+To get the list of datapoints.
+**Request**
+   * URL: /api/get/projectByParts?format=xml
+   * Method: POST
+<code javascript>
+{
+ "cred": {
+  "t": "xxxxxx"
+ },
+ "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
+ "treeId": "Visual tree",
+ "partType": 0,
+ "offset": 0,
+ "count": 250
+}
+</code>
+**Response**
+<code xml><?xml version="1.0" encoding="utf-8"?>
+<getProjectByPartsResult xmlns:r="http://dev.rcware.eu/serialization/references" projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dataVersion="637305748282414171" totalCount="79" nextOffset="-1" xmlns:n1="http://dev.rcware.eu/scada/comm-props" xmlns:n2="http://dev.rcware.eu/rt2com" xmlns:n3="http://dev.rcware.eu/scada/basic-props" xmlns:n4="http://dev.rcware.eu/scada/legacy-props" xmlns="http://dev.rcware.eu/scada/datapoints">
+ <dps>
+  <dp id="393df7b4-bb8d-4e8f-92a7-bf785508894a" n="Provozni podminky OK" canAct="true" canAlr="true">
+   <v>
+    <props>
+     <p n="Source" t="2020-10-05T07:17:11.601879Z" q="Good" n1:dateTimeKind="UTC" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09">
+      <n1:r n2:rp="PT0S" r:type="7b047602-40da-4095-9093-062ba30fd15e">
+       <n2:a id="3b1e3b8b-2186-4dcf-b157-8032c768d1e1" n="SW.Provozni podminky OK"/>
+      </n1:r>
+      <n1:w r:type="5ddc9dbf-a6bd-458b-a6ab-f661db0e3a64">
+       <n2:a id="3b1e3b8b-2186-4dcf-b157-8032c768d1e1" n="SW.Provozni podminky OK"/>
+      </n1:w>
+      <n1:v>1</n1:v>
+     </p>
+     <p n="Output" t="2020-10-05T07:16:58.751431Z" q="Good" r:type="177e726a-3180-4152-bef2-6254e7055e1f">
+      <n3:v>OK</n3:v>
+     </p>
+     <p n="StdVis_V1" t="2015-06-03T13:17:13.5190205Z" q="Good" r:type="b0db7bd7-0375-4830-90f2-6d918bac41ee">
+      <n3:v>
+       <n3:props>
+        <n3:p>
+         <n3:pn>Output</n3:pn>
+         <n3:props>
+          <n3:p r:type="256a44f6-32e4-4a75-b7c2-08eed38f151d">
+           <n3:ordMap>
+            <n3:grOrd>
+             <n3:t>OK</n3:t>
+             <n3:o>0</n3:o>
+            </n3:grOrd>
+            <n3:grOrd>
+             <n3:t>ALARM</n3:t>
+             <n3:o>1</n3:o>
+            </n3:grOrd>
+           </n3:ordMap>
+          </n3:p>
+         </n3:props>
+        </n3:p>
+       </n3:props>
+      </n3:v>
+     </p>
+    </props>
+   </v>
+   <core r:type="2f04d90c-ee95-4cb6-b945-146e33021945"/>
+  </dp>
+  <dp id="3e5c0b88-45fd-4e3f-b1b2-1a365327ec90" n="Zaplavení" canAct="true" canAlr="true">
+   <v>
+    <props>
+     <p n="Source" t="2020-08-17T10:21:46.470472Z" q="Good" n1:dateTimeKind="UTC" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09">
+      <n1:r n2:rp="PT0S" r:type="7b047602-40da-4095-9093-062ba30fd15e">
+       <n2:a id="45c31fe4-00b0-4498-b9f6-adfe6a2fe34b" n="SW.Zaplavení mem"/>
+      </n1:r>
+      <n1:w r:type="5ddc9dbf-a6bd-458b-a6ab-f661db0e3a64">
+       <n2:a id="45c31fe4-00b0-4498-b9f6-adfe6a2fe34b" n="SW.Zaplavení mem"/>
+      </n1:w>
+      <n1:v>0</n1:v>
+     </p>
+     <p n="Output" t="2020-08-17T10:21:46.470472Z" q="Good" r:type="177e726a-3180-4152-bef2-6254e7055e1f">
+      <n3:v>OK</n3:v>
+     </p>
+     <p n="StdVis_V1" t="2015-06-03T13:17:13.5190205Z" q="Good" r:type="b0db7bd7-0375-4830-90f2-6d918bac41ee">
+      <n3:v>
+       <n3:props>
+        <n3:p>
+         <n3:pn>Output</n3:pn>
+         <n3:props>
+          <n3:p r:type="256a44f6-32e4-4a75-b7c2-08eed38f151d">
+           <n3:ordMap>
+            <n3:grOrd>
+             <n3:t>OK</n3:t>
+             <n3:o>0</n3:o>
+            </n3:grOrd>
+            <n3:grOrd>
+             <n3:t>ALARM</n3:t>
+             <n3:o>1</n3:o>
+            </n3:grOrd>
+           </n3:ordMap>
+          </n3:p>
+         </n3:props>
+        </n3:p>
+       </n3:props>
+      </n3:v>
+     </p>
+    </props>
+   </v>
+   <core r:type="2f04d90c-ee95-4cb6-b945-146e33021945"/>
+   <alr>
+    <def enabled="true" delay="PT1M"/>
+    <galrs/>
+    <status user="SYSTEM" incidentId="88ba7198-de57-4854-8130-60c240a09522" lastChangeTime="2020-08-11T12:37:04.8002341Z"/>
+   </alr>
+  </dp>
+ </dps>
+</getProjectByPartsResult></code>
+===== Matlab Client =====
+==== General notes client function parameters ====
+  * parameter names ID and Guid are used interchangeably in the Matlab client, it is always a universally unique identifier referring to project or a particular datapoint
+  * when plural is used, array of guids is expected (ie. {'guid1', 'guid2'}), otherwise just one guid is expected (ie. 'guid1')
+==== Data download example ====
+<code matlab>scada = ScadaClient('https://scada.mervis.info/','demo','demo');
+dataPointIDs = {'acad79f3-3358-42dd-9b74-98733e63d771','1afa7d9b-1183-4ab1-a6b1-18e464ae2d4d','e496bb8c-14ce-4c2c-b53b-3b71daeabca6'};
+projectId = '5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0';
+chartLegend = {'/Plynová kotelna/ÚT1 - SEVER/TEPLOTA UT1','/Plynová kotelna/ÚT1 - SEVER/TEPLOTA UT1 zpátečka','/Plynová kotelna/ÚT1 - SEVER/Poloha ventilu'};
+from = now - 4;
+to = now;
+timeSpan = 300; %sec
+[data, time] = scada.getData(projectId, dataPointIDs, from, to, timeSpan);
+plot(time,data);
+legend(chartLegend);
+datetick;</code>
+==== ScadaClient ====
+<code matlab>ScadaClient(url, username, password)</code>
+Constructor of Mervis API wrapper.
+==== findAllDPsWithReqTags ====
+<code matlab>findAllDPsWithReqTags(projIds, tags)</code>
+Returns list of datapoints based on tags query. Example of tags definition: {'label','indoor_air_temperature';'room_type','office'}
+==== saveData====
+<code matlab>saveData(projID, dpID, time, data)</code>
+Saves data into the Mervis database.
+==== deleteVariable ====
+<code matlab>deleteVariable(projGuid, dpGuid, from, to)</code>
+Deletes data of one variable based on from - to interval. If from - to is not defined, all data are deleted. Use carefully, there is no undo!
+==== setDataPointValue ====
+<code matlab>setDataPointValue(projGuid, dpGuid, value, buttonName)</code>
+Sets data point value using a button (primary the INIT button). Only numerical values are supported. Parameter buttonName is not mandatory. Value 'INIT' is used if buttonName is not defined.
+{{ :en:mervis-scada:init.png?direct&800 |}}
+**Example:**
+<code matlab>
+dpGuid = 'ccaacb77-295b-48a8-a712-3fb272aa9b6f';
+projectId = '6b65447e-8622-4a0d-b3b9-42f1d905fdaa';
+buttonName = 'INIT' %see action ("button") name in Mervis SCADA GUI
+newValue = 1;
+scada = ScadaClient('https://scada.mervis.info/','username','password');
+scada.setDataPointValue(projectId, dpGuid, newValue, buttonName)
+</code>
+==== getData====
+<code matlab>[data, time, dataInCell, info] = getData(projID,dpsIds,from,to,span,zone,doublesInterpolationMethod, interpolate_gaps_shorter_than)</code>
+Downloads data. Span is a sampling interval in seconds, default is 300 sec. Zone is time zone 'local' or 'utc' is applied to from/to parameters as well as to output time, default is 'local'. DoubleInterpolationMethod is same as e.g. interp1, applied to double values only the other types use method 'previous'. Interpolate_gaps_shorter_than - interpolates missing values periodes that are not shorer than this parameter (in seconds). Return parameters: data - downloaded data resampled, NaN is used for missing values; time - datenum time axis according to selected zone; dataInCell - usefull for strings; info - summary info about the request.
+==== getDpTags====
+<code matlab>getDpTags(projectId, DpId) </code>
+Returns tags of the particular datapoint.
+==== getAllProjectDPs====
+<code matlab>getAllProjectDPs(projectGuid)</code>
+Returns project IDs and names that are accessible to logged user.