{"cred":{"n":"demo","p":"demo"}}
**Response**
* You **should** use the received token **t** in subsequent API calls.
==== api/v3/get/history ====
**Request**
* URL: /api/v3/get/history?format=json
* Method: POST
* Downloading of one or multiple trends with single API call
* You should always use "token" instead of simple "name" a "password". Non-token call is slower.
* "seriesParameters" [optional] - use only if you request different parameters than "commonSeriesParameters"
* "clientReference" [optional] - use for your own identification of the series
* Items: "segmenation", "requestState" and "serverState" should always copy the values from the last server response. First call should use empty "segmentation".
{
"credentials": {
"token":"guid" //string
},
"request": {
"commonSeriesParameters": {
"from": "2018-12-01T00:00:00Z", //UTC dateTime
"to": "2018-12-01T10:00:00Z"//UTC dateTime
},
"series": [
{
"seriesParameters": {
"from": "2017-11-28T14:26:16.5029619Z",//UTC dateTime
"to": "2018-11-28T14:26:16.5029619Z" //UTC dateTime
},
"clientReference": "myId2a", //string
"provider": {
"parameters": {
"projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //guid
"dataPointId": "2a9c26c9-2ce3-49c4-909d-9ac1143121f1" //guid
}
}
},
{
"clientReference": "myId1a",
"provider": {
"parameters": {
"projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
"dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
}
}
}
]
},
"dataSpecification": {
"limits": {
"count": 1000 //int
}
},
"segmentation": {
"requestState": ";;2;;0", //string
"serverState": "xyz" //string
}
}
**Response**
* Empty "segmentation" ("requestState") marks response containing last data of the requested series
* "requestState" and "serverState" must be copied to the next API call
* Values
* v - value
* ts - timestamp - start of the value validity period
* gt - goodthrough - end of the value validity period
* i - interval, only present if it differs from the interval in Meta section
* Meta
* type - value type - double, string, datetime
* unit - unit
* interval - expected interval between the stored records. Useful to identify missing data.
{
"result": {
"code": 0, //int
"subCode": 0, //int
"message": "" //string
},
"data": {
"count": 3, //int
"historyData": [
{
"clientReference": "myId2a", //string
"provider": {
"id": "689e32fa-24a2-448e-9374-6158e6e6cb15", //guid
"parameters": {
"projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //guid
"dataPointId": "2a9c26c9-2ce3-49c4-909d-9ac1143121f1" //guid
}
},
"meta": {
"type": "string", //string
"unit": "", //string
"interval": "PT3M" //string - ISO8601 Timespan
},
"values": [
{
"v": "AUT", //string
"ts": "2018-11-26T12:22:15.25795Z", //dateTime
"gt": "2018-11-26T13:22:15.5784067Z" //dateTime
}
]
},
{
"clientReference": "myId1a",
"provider": {
"parameters": {
"projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
"dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
}
},
"meta": {
"type": "double",
"unit": "hod",
"interval": "PT3M"
},
"values": [
{
"v": 12939,//double
"ts": "2018-11-30T23:58:15.2394603Z",
"gt": "2018-12-01T01:37:15.4869553Z"
},
{
"v": 12946,
"ts": "2018-12-01T09:22:16.2049051Z",
"gt": "2018-12-01T10:37:15.4023519Z",
"i": "PT4M"
}
]
}
]
},
"segmentation": {
"requestState": "xyz", //string
"serverState": "xyz" //string
}
}
**Demo**
{
"credentials": {
"name": "demo",
"password": "demo"
},
"request": {
"commonSeriesParameters": {
"from": "2018-12-01T00:00:00Z",
"to": "2018-12-01T00:11:00Z"
},
"series": [
{
"clientReference": "myId1",
"provider": {
"parameters": {
"projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
"dataPointId": "acad79f3-3358-42dd-9b74-98733e63d771"
}
}
},
{
"clientReference": "myId2",
"provider": {
"parameters": {
"projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
"dataPointId": "14cf0dbb-b050-43aa-a6f0-22886c33ed8e"
}
}
}
]
},
"dataSpecification": {
"limits": {
"count": 1000
}
}
}
==== api/get/history/specific ====
**Request**
* URL: /api/get/history/specific?format=json
* Method: POST
* You should always use token ("t") instead of simple name and password ("n" and "p"). Non-token call is slower.
* "dataSpec" - data specification
* MinTimestamp = 0,
* MaxTimestamp = 1,
* FirstLessThanReferenceDateTime = 2,
* FirstLessThanOrEqualThanReferenceTime = 3,
* FirstGreaterThanReferenceDateTime = 4,
* FirstGreaterThanOrEqualThanReferenceTime = 5,
* MaxGoodThroughTime = 6
* "refTime" [optional] - reference time for dataSpec values 2 to 5
{
"cred":
{
"n":"test",
"p":"test"
},
"projId":"b4d96a6d-2b3d-48eb-af30-d11e875ba7ed",
"offset":0,
"count":1000,
"dataSpec":2,
"refTime":"\/Date(1692788459000)\/",
"dpIds":["58426e69-46ba-4925-9a5c-d7d65efb9886","f4501a2e-62ed-430e-9346-5e155e730fe3","28e7d087-917a-456a-9d02-96882f572286"]
}
**Response**
* Values
* v - value
* ts - timestamp - start of the value validity period
* gt - goodthrough - end of the value validity period
* i - interval
{
"ns": {
"r": "http://dev.rcware.eu/serialization/references",
"n1": "http://dev.rcware.eu/scada/history",
"n2": "http://dev.rcware.eu/scada/datapoints",
"n3": "http://dev.rcware.eu/scada/basic-props"
},
"doc": {
"n1:getHistorySpecificResult": {
"n2:pl": [
{
"n2:p": {
"n1:hist": {
"@": {
"n1:projId": "b4d96a6d-2b3d-48eb-af30-d11e875ba7ed",
"n1:dpId": "58426e69-46ba-4925-9a5c-d7d65efb9886",
"n1:propName": "Output",
"n1:interval": "00:00:00",
"n1:historyState": "",
"n1:nextValOfs": 0
},
"n1:errMsg": "",
"n1:vals": [
{
"n1:hv": {
"@": {
"n1:ts": "2023-08-23T11:00:57.7010708Z",
"n1:i": "1.00:00:00"
},
"n3:v": 12.48
}
}
]
},
"@": {
"r:type": "b133774d-21ce-42b6-add3-57c012079c55"
}
}
},
{
"n2:p": {
"n1:hist": {
"@": {
"n1:projId": "b4d96a6d-2b3d-48eb-af30-d11e875ba7ed",
"n1:dpId": "f4501a2e-62ed-430e-9346-5e155e730fe3",
"n1:propName": "Output",
"n1:interval": "00:00:00",
"n1:historyState": "",
"n1:nextValOfs": 0
},
"n1:errMsg": "",
"n1:vals": [
{
"n1:hv": {
"@": {
"n1:ts": "2023-08-23T10:38:43.784Z",
"n1:gt": "2023-08-23T11:18:00.207Z",
"n1:i": "00:00:30"
},
"n3:v": 5.0
}
}
]
},
"@": {
"r:type": "b133774d-21ce-42b6-add3-57c012079c55"
}
}
},
{
"n2:p": {
"n1:hist": {
"@": {
"n1:projId": "b4d96a6d-2b3d-48eb-af30-d11e875ba7ed",
"n1:dpId": "28e7d087-917a-456a-9d02-96882f572286",
"n1:propName": "Output",
"n1:interval": "00:00:00",
"n1:historyState": "",
"n1:nextValOfs": 0
},
"n1:errMsg": "",
"n1:vals": [
{
"n1:hv": {
"@": {
"n1:ts": "2023-08-23T10:38:43.786Z",
"n1:gt": "2023-08-23T11:18:00.207Z",
"n1:i": "00:00:30"
},
"n3:v": "ZAP"
}
}
]
},
"@": {
"r:type": "177e726a-3180-4152-bef2-6254e7055e1f"
}
}
}
],
"@": {
"r:type": "1c4c1ddc-463f-443d-883a-19489cd2e53a"
}
}
}
}
==== [Depricated] api/get/history====
**Request**
* URL: /api/get/history?format=xml
* Method: POST
{
"cred":{
"n":"demo", //username
"p":"demo" //password
},
"projId":"5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0", //project ID
"dpId":"62cf4083-31ed-4bc1-be25-044ba837a9f0", //single datapoint ID
"from":"/Date(1541199600000)/", //UTC in ms
"to":"/Date(1541496190357)/", //UTC in ms
"offset":0,
"count":5000,
"historyState":"" //client has to send historyState value from the last response with the following request
}
**Response**
12754
12754
12754
12755
12756
12757
12758
12759
12760
12761
12761
12761
====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.
2.7
3.0
2.0
2.3
**Response**
* 200 OK
====api/replace/history====
**Request**
* URL: /api/replace/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.
2.7
3.0
2.0
2.3
**Response**
* 200 OK
====api/set/executeActions====
**Request**
* URL: /api/set/executeActions?format=xml
* Method: POST
* Content-Type: text/xml
16
**Response**
====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
{
"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"]
}
]
}
**Response**
ON
0
====api/get/projectByParts====
To get the list of datapoints.
**Request**
* URL: /api/get/projectByParts?format=xml
* Method: POST
{
"cred": {
"t": "xxxxxx"
},
"projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
"treeId": "Visual tree",
"partType": 0,
"offset": 0,
"count": 250
}
**Response**
1
OK
Output
OK
0
ALARM
1
0
OK
Output
OK
0
ALARM
1
===== 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 ====
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;
==== ScadaClient ====
ScadaClient(url, username, password)
Constructor of Mervis API wrapper.
==== findAllDPsWithReqTags ====
findAllDPsWithReqTags(projIds, tags)
Returns list of datapoints based on tags query. Example of tags definition: {'label','indoor_air_temperature';'room_type','office'}
==== saveData====
saveData(projID, dpID, time, data)
Saves data into the Mervis database.
==== deleteVariable ====
deleteVariable(projGuid, dpGuid, from, to)
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 ====
setDataPointValue(projGuid, dpGuid, value, buttonName)
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:**
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)
==== getData====
[data, time, dataInCell, info] = getData(projID,dpsIds,from,to,span,zone,doublesInterpolationMethod, interpolate_gaps_shorter_than)
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====
getDpTags(projectId, DpId)
Returns tags of the particular datapoint.
==== getAllProjectDPs====
getAllProjectDPs(projectGuid)
Returns project IDs and names that are accessible to logged user.