Mervis SCADA API

Mervis SCADA nabízí otevřené REST-like API založené na datových formátech JSON a XML pro bezproblémovou integraci s aplikacemi třetích stran. Podrobný popis pokročilých funkcí získáte u technické podpory.

Důležité upozornění k formátům: Přestože jsou v novějších API metodách ve velké míře využívány formáty JSON, jediným oficiálně podporovaným zpětně kompatibilním formátem odpovědí v rámci celého původního API je XML.

Podporované API metody

Níže je uveden konsolidovaný seznam doporučených API metod. Jsou zde uvedeny pouze metody s kompletní dokumentací a ověřenými příklady.

Funkce	Popis
Autentizace
`api/v2/get/authenticate`	Ověří uživatele a vrátí token relace pro následná API volání.
Projekty a datová struktura
`api/get/projects`	Vrátí seznam všech projektů dostupných přihlášenému uživateli.
`api/get/projectByParts`	Vrátí strukturu Visual tree a seznam datových bodů ve vybraném projektu.
Čtení dat
`api/get/values`	Vrátí aktuální hodnoty zadaných datových bodů v reálném čase.
`api/v3/get/history`	Stáhne historická trendová data jedné nebo více časových řad v jednom stránkovaném volání.
`api/get/history/specific`	Vrátí konkrétní historické hodnoty vzhledem k zadanému referenčnímu času.
Zápis dat a provádění akcí
`api/set/values`	Zapíše nové hodnoty do zadaných datových bodů.
`api/set/executeActions`	Spustí předdefinované akce nebo tlačítka (například INIT nebo ZAP) nad datovými body.
`api/set/history`	Vloží nové historické hodnoty do databáze.
`api/replace/history`	Kompletně nahradí existující historická data ve zvoleném časovém rozsahu.

Poznámka k přihlašovacím údajům: API metody můžete testovat pomocí přihlašovacích údajů `n: demo` a `p: demo`. V produkčních aplikacích je doporučeno nejprve získat autentizační token pomocí metody `api/v2/get/authenticate` a následně jej používat (`t: [token_string]`) při dalších API voláních. Tím je zajištěn optimální výkon.

Autentizace

api/v2/get/authenticate

Požadavek:

URL: /api/v2/get/authenticate?format=json
Metoda: POST

Standardní přihlášení:

{"data":{"cred":{"n":"demo","p":"demo"}}}

Přihlášení do konkrétní domény:

{"data":{"cred":{"d":"GlobalDomain","n":"demo","p":"demo"}}}

Vlastnosti odpovědi:

token (string) – autentizační token používaný při dalších API voláních.
tokenValidFor (TimeSpan) – doba platnosti tokenu (např. „P1D“ = 1 den).
changePwdBefore (DateTime nebo null) – datum a čas, do kterého je nutné změnit aktuální heslo.

{
    "data": {
        "ChangePwdBefore": null,
        "ClientType": 2,
        "Domain": "3c73477a-6c95-4939-b047-7bbf902bcef1",
        "DomainName": "GlobalDomain",
        "FullName": "GlobalDomain\\demo",
        "Login": "demo",
        "NotifyNearingPwdExpirationIn": null,
        "Token": "3:b83d56f8-2e25-4745-a4e5-1a259c286c5f",
        "TokenValidFor": "P1D",
        "User": "48141739-5d16-4ca3-8ae1-33e27d9eb22e",
        "Username": ""
    },
    "result": { "code": 0, "codeTxt": null, "dataType": null, "desc": null }
}

Čtení dat

api/get/values

Vrací aktuální hodnoty datových bodů (vlastnost „Output“) z jednoho nebo více projektů.

Požadavek:

URL: /api/get/values?format=xml
Metoda: POST

{
 "cred": {
  "n": "demo",
  "p": "demo"
 },
 "propNamesToSerialize": ["Output"],
 "offset": 0,
 "count": 1000,
 "serverState": null,
 "dps": [{
   "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
   "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"]
  }]
}

Odpověď:

<?xml version="1.0" encoding="utf-8"?>
<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2026-07-17T10:29:17Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints">
 <vals>
  <v projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" serverTime="2026-07-17T10:29:17Z">
   <dps>
    <d id="62cf4083-31ed-4bc1-be25-044ba837a9f0" serAlr="true">
     <props>
      <p n="Output" t="2026-07-17T10:29:17Z" q="Good" r:type="b133774d-21ce-42b6-add3-57c012079c55">
       <n1:v>13851.42</n1:v>
      </p>
     </props>
    </d>
   </dps>
  </v>
 </vals>
</values>

api/v3/get/history

Stažení jednoho nebo více trendů jedním API voláním.

Pravidla:

Položky segmentation, requestState a serverState musí při stránkování vždy obsahovat hodnoty z poslední odpovědi serveru. Při prvním volání použijte prázdnou hodnotu segmentation.

Požadavek:

URL: /api/v3/get/history?format=json
Metoda: POST

{
    "credentials": {
        "name": "demo",
        "password": "demo"
    },
    "request": {
        "commonSeriesParameters": {
            "from": "2026-06-20T00:00:00Z",
            "to": "2026-07-17T00:00:00Z"
        },
        "series": [
            {
                "clientReference": "test1",
                "provider": {
                    "parameters": {
                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
                    }
                }
            }
        ]
    },
    "dataSpecification": {
        "limits": { "count": 1000 }
    },
    "segmentation": {
        "requestState": "",
        "serverState": ""
    }
}

Popis odpovědi:

v – hodnota
ts – časová známka (začátek období platnosti)
gt – goodthrough (konec období platnosti)
meta.interval – očekávaný interval mezi uloženými záznamy. Lze využít k identifikaci chybějících dat.

{
    "result": { "code": 0, "subCode": 0, "message": "" },
    "data": {
        "count": 1,
        "historyData": [
            {
                "clientReference": "test1",
                "provider": {
                    "id": "689e32fa-24a2-448e-9374-6158e6e6cb15",
                    "parameters": {
                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
                    }
                },
                "meta": { "type": "double", "unit": "h", "interval": "PT3M" },
                "values": [
                    { "v": 13851.4, "ts": "2026-06-25T12:00:00.000Z" }
                ]
            }
        ]
    },
    "segmentation": { "requestState": "", "serverState": "" }
}

api/get/history/specific

Požadavek:

URL: /api/get/history/specific?format=json
Metoda: POST
dataSpec: Definuje požadovaný bod historie (například 2 = první hodnota menší než referenční čas).
refTime: Referenční čas použitý při vyhledávání.

{
 "cred": {
  "n": "demo",
  "p": "demo"
 },
 "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
 "offset": 0,
 "count": 1000,
 "dataSpec": 2,
 "refTime": "\/Date(1692788459000)\/",
 "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"]
}

Zápis dat a provádění akcí

api/set/values

Požadavek:

URL: /api/set/values?format=xml
Metoda: POST

<?xml version="1.0" encoding="UTF-8"?>
<setValuesRequest xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="http://dev.rcware.eu/scada/datapoints" xmlns:n2="http://dev.rcware.eu/auth" xmlns:n1="http://dev.rcware.eu/scada/comm-props" >
   <n2:cred n="demo" p="demo"/>
        <values projId="1b2623be-eaa4-4e29-8596-c66dd85d5643">
            <dps>
                <d id="07d538d9-9f4b-46ca-ba4d-13b13b5302ff">
                    <props>
                        <p n="Source" t="2024-02-23T09:58:00Z" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09">
                            <n1:v>23</n1:v>
                        </p>
                    </props>
                </d>
            </dps>
        </values>
</setValuesRequest>

api/set/executeActions

Požadavek:

URL: /api/set/executeActions?format=xml
Metoda: POST

<?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 n="demo" p="demo"/>
  <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>

api/set/history & api/replace/history

Atribut i určuje interval (ISO 8601), ve kterém je očekávána následující hodnota. Všechny datumové a časové údaje musí být uvedeny v UTC.

Příklad požadavku Replace History:

URL: /api/replace/history?format=xml
Metoda: POST

<?xml version="1.0" encoding="UTF-8"?>
<replaceHistoryRequest 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" from="2020-03-15T11:00:00+00:00" to="2020-03-18T11:00:00+00:00">
  <n2:cred n="demo" p="demo"/>
  <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>
  </vals>
</replaceHistoryRequest>

Správa projektů

api/get/projects

Požadavek:

URL: /api/get/projects?format=xml
Metoda: POST

{
 "cred": {
  "n": "demo",
  "p": "demo"
 },
 "offset": 0,
 "count": 250
}

Odpověď:

<?xml version="1.0" encoding="utf-8"?>
<getProjectsResult xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="http://dev.rcware.eu/scada/projects">
    <projects>
        <project id="2a7f1615-..." name="Weather" />
        <project id="1b2623be-eaa4-4e29-8596-c66dd85d5643" name="SIMPLE_DEMO" />
        <project id="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" name="PLYNOVA_KOTELNA" />
        <project id="b9ad5380-..." name="CVUT_HERBERTOV" />
        <project id="843855a2-..." name="PRVNI_KROKY" />
    </projects>
</getProjectsResult>

api/get/projectByParts

Vrací strukturu Visual tree a seznam datových bodů.

Požadavek:

URL: /api/get/projectByParts?format=xml
Metoda: POST

{
 "cred": {
  "n": "demo",
  "p": "demo"
 },
 "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
 "treeId": "Visual tree",
 "partType": 0,
 "offset": 0,
 "count": 250
}

Matlab Client

Obecné poznámky

Názvy parametrů ID a Guid jsou v klientovi Matlab používány zaměnitelně. Vždy se jedná o globálně jedinečný identifikátor projektu nebo datového bodu.
Pokud je parametr uveden v množném čísle, očekává se pole GUID (např. {'guid1', 'guid2'}), jinak pouze jeden GUID.

ScadaClient

ScadaClient(url, username, password)

Konstruktor obalové třídy Mervis API.

findAllDPsWithReqTags

findAllDPsWithReqTags(projIds, tags)

Vrátí seznam datových bodů podle zadaných tagů. Příklad definice tagů: {'label','indoor_air_temperature';'room_type','office'}

getDpTags

getDpTags(projectId, DpId)

Vrátí tagy konkrétního datového bodu.

getAllProjectDPs

getAllProjectDPs(projectGuid)

Vrátí ID a názvy projektů dostupných přihlášenému uživateli.

getData

[data, time, dataInCell, info] = getData(projID, dpsIds, from, to, span, zone, doublesInterpolationMethod, interpolate_gaps_shorter_than)

Stáhne data.

span: interval vzorkování v sekundách, výchozí hodnota je 300 s.
zone: časové pásmo ('local' nebo 'utc') použité pro vstupní parametry i výstup, výchozí hodnota je 'local'.
Vrací: data (pro chybějící hodnoty se používá NaN), time, dataInCell (užitečné pro textové hodnoty) a info.

Příklad stažení dat:

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 = {'Temp UT1','Temp UT1 Return','Valve Position'};
from = now - 4;
to = now;
timeSpan = 300;
 
[data, time] = scada.getData(projectId, dataPointIDs, from, to, timeSpan);
 
plot(time,data);
legend(chartLegend);
datetick;

saveData

saveData(projID, dpID, time, data)

Uloží data do databáze Mervis.

setDataPointValue

setDataPointValue(projGuid, dpGuid, value, buttonName)

Nastaví hodnotu datového bodu pomocí tlačítka. Jsou podporovány pouze číselné hodnoty. Parametr buttonName není povinný. Pokud není zadán, použije se INIT.

Příklad:

dpGuid = 'ccaacb77-295b-48a8-a712-3fb272aa9b6f';
projectId = '6b65447e-8622-4a0d-b3b9-42f1d905fdaa';
buttonName = 'INIT';
newValue = 1;
 
scada = ScadaClient('https://scada.mervis.info/','demo','demo');
scada.setDataPointValue(projectId, dpGuid, newValue, buttonName)

deleteVariable

deleteVariable(projGuid, dpGuid, from, to)

Upozornění: Odstraní data jednoho datového bodu v zadaném intervalu from-to. Pokud interval není zadán, budou odstraněna všechna data. Tuto operaci používejte s maximální opatrností – odstranění dat nelze vrátit zpět.

Obsah

Mervis SCADA API

Podporované API metody

Autentizace

api/v2/get/authenticate

Čtení dat

api/get/values

api/v3/get/history

api/get/history/specific

Zápis dat a provádění akcí

api/set/values

api/set/executeActions

api/set/history & api/replace/history

Správa projektů

api/get/projects

api/get/projectByParts

Matlab Client

Obecné poznámky

ScadaClient

findAllDPsWithReqTags

getDpTags

getAllProjectDPs

getData

saveData

setDataPointValue

deleteVariable