Tiedonsiirtorajapinnat
Tässä ohjeessa on esitelty protokollat, joita tuetaan
suoraan pisteiden dataSource ja dataTarget -kentissä.
Yleistä:
dataSource ja dataTarget kenttiin annetaan URL muotoinen kuvaus siitä,
millä tavalla pisteen arvo halutaan lukea jostakin ulkoisesta
tietolähteestä, tai millä tavoin pisteen arvo halutaan kirjoittaa
johonkin ulkoiseen kohteeseen. Edellä mainittu ulkoinen kohde voi olla
jokin kenttäväylä, web-sivusto tai tiedosto.
Suurin osa dataSource ja dataTarget protokollista tukee seuraavia yleisiä
URL parametreja.
YLEISIÄ DATASOURCE JA DATATARGET URL PARAMETREJA:
?scale=0.1 skaalaa luetun raw arvon annetulla kertoimella.
?offset= Tekee skaalattuun arvoon suuntaissiirtoa
?invert=1 Tällä parametrilla käännetään tavallisimmin DI tai DO pisteen polariteetti,
mutta sillä voidaan tehdä myös muuta.
Invert parametri toimii niin, että väylältä luettu arvo vähennetään
invert parametrin arvosta.
Digitaali pisteen polariteetin saa käännettyä antamalla "invert=1"
?bitmask= Tällä parametrilla voi antaa maskin, jonka avulla valitaan
vain halutut bitit raw arvosta. Käytännössä suorittaa
binäärisen AND operaation RAW datan ja tämän maskin välillä.
?datatype= Määrittää missä muodossa luettu RAW arvo tulee tulkita.
Mahdollisia tyyppejä: int16, uint16, int32, uint32, float32
?x1=0&y1=0..x32=100&y32=100 Inline muunnostaulukko joka voidaan antaa
dataSource tai dataTarget URL:ssa. Käyrän taittopisteet
annetaan koordinaatteina URL parametreissa, jotak ovat
nimeltään muotoa "x1", "y1", x2 ja "y2". Pisteitä voi olla
enimmillään 32 kpl, ja ne on nimettävä juoskevasti 1:stä
lähtien. Raakadatan arvo on annettu X akselissa, ja vastaava
skaalattu arvo y akselilla. Ero on tärkeätä huomata
dataTargetissa, jolloin taulukkoa käytetään tavallaan
takaperin - eli pisteen pv sijoitetaan x akselille, ja väylään
lähetettävä data luetaan y akselilta. Tällöin samaa taulukkoa
voidaan käyttää sekä sourcessa että targetissa.
?rejecthi Raja-arvo, jota suuremmat (skaalatut) arvot hylätään,
eli pisteen pv ei muutu.
?rejectlo Raja-arvo jota pienemmät (skaalatut) arvot hylätään,
eli pisteen pv ei muutu.
?hilimit Ylin arvo jonka skaalattu arvo voi saada - eli rajoittaa pv:n
maksimia. Arvoa ei hylätä, mutta se rajoitetaan.
?lolimit Alin arvo jonka skaalattu arvo voi saada - eli rajoittaa pv:n
minimiä. Arvoa ei hylätä, mutta se rajoitetaan.
?damping Luo pisteen pv arvoon vaimennusta, eli käytönnössä tässä parametrissa voi antaa
vaimennuksen aikavakion (lambda), aikayksikkönä funktiokutsut - jos kutsutaan kerran
sekunnissa, aikavakion yksikkö on sekunti.
?precision Pisteen tarkkuus. Arvo 0.001 tarkoittaa että piste näytetään 3 desimaalin tarkkuudella,
ja tarkkuun 10 että arvo pyöristetään lähimpään kymmeneen.
?curve Pisteen skaalaukseen voi käyttää tällä parametrilla hvac kirjaston hvacCurve tyyppisiä pisteitä.
Käyttö tapahtuu niin, että halutun hvacCurve pisteen nimi annetaan URL:ssä ?curve=hvacCurvePisteenNimi
HUOM! Toimii VAIN dataSource URL:issa (ei dataTarget).
HUOM, Muutos! Tämä toimii myös luomalla pisteeseen "curve" niminen kenttä, ja antamalla sen arvoksi haluttu
skaalaus taulukko.
?select Jos RAW data on "table" muotoinen, tällä parametrilla voi
valita taulukosta haluamansa solun, antamalla select parametrilla
oikean muotoisen polun haluttuun arvoon.
Polussa voi käyttää . ja [] syntaksia.
Esim. RAW data on {status="OK", data=
{pv={10, 20, 30, 40, 50}, description="My data"}
}
voi pv kentän kolmannen rivin osoittaa select parametrilla:
?select=data.pv[3]
HUOM! Vain toimii vain dataSource kentissä
PROTOKOLLAT:
slc:// Lukee ja kirjoittaa tietoa toisiin SLC pohjaisiin laitteisiin.
Mikäli IP osoitteeksi annetaan "local" (tai 127.0.0.1) data luetaan
tai kirjoitetaan paikallisesti laitteen omassa pistetietokannassa.
Verkon ylitse lukemiseen käytetään TCP porttia 30001
Muoto:
slc://local/dbPoint.field
Esimerkki:
slc://local/sys/settings/bacnetIP.instance
slc://192.168.0.130/ioPoints/TK01/TE10.pv
mbus:// Lukee dataa mbus väylästä. Tukee tällä hetkellä vain mbus-serial
väylää.
Huomaa että URL alkaa %-koodatulla mbus -portti tietokantapisteellä
joka osoittaa siis sen portin jota väyläkommunikaatioon käytetään.
mbus protokolla tulee URL parametreja:
interval MBus laitteen luentaväli sekunteina. Eli
?interval=3600 tarkoittaa, että mittari luetaan vain tunnin välein
Muoto:
mbus://[mbusPortPointId]/[slaveAddress]/datarecords/[dataIndex]/value
Esimerkki (dataSource):
mbus://ioPorts%2FmbusSerial%2FP1/12016562/datarecords/5/value
wmb:// Lukee dataa, joka on vastaanotettu wireless M-Bus protokollalla.
VAIN LUKEMINEN TUETTU
Muoto:
wmb://[wmbusReceiveFile]/[dataKey]
Esimerkki (dataSource):
wmb://MC603_heatMeter/temp_in
modbusrtu:// Lukee ja kirjoittaa dataa modbus RTU väylään.
Tukee ylimääräisiä URL parametreja:
order sanajärjestys kun käytetään 32 bittisiä rekistereitä
arvot: "MSW" (enemmän merkitsevä sana ensin),
"LSW" (vähemmän merkistevä sana ensiksi).
Oletus: "MSW"
multistate Tällä parametrilla voidaan tulkita peräkkäiset rekisterit
arvoiksi esim. tasoa kuvaavaksi arvoksi. Eli RAW arvoksi
tulkitaankin rekisterin sisällön sijasta tieto siitä, kuinka
mones rekisteri ketjussa on arvoltaan suurempi kuin nolla.
onvalue Kun kirjoitetaan multistate rekistereihin,
kirjoitetaan tämä arvo niin monenteen rekisteriin, kuin
(skaalattu) PV määrittää.
VAIN dataTarget!
forcewrite Normaalisti modbus rekisterit kirjoitetaan vain silloin,
kun PV arvo muuttu. Tällä voidaan kirjoitus pakottaa
tapahtuvaksi jokaisella luku/kirjoitus kierroksella.
VAIN dataTarget.
leap in multistate sources, with this paramter, it is possible
to define non-consecutive registers to behave like
multistate input.
NOTE! Use with caution! This can cause huge amount of bus traffic (meanning
latecy will creep up).
forcesinglewrite Käyttää holding rekisterin kirjoittamiseen funktionkoodia 0x06 (write single holding) eikä
normaalia 0x10, eli koodia 16 (Write multiple holding)
Muoto:
modbusrtu://[modbusPortPointId]/[slaveAddress]/regType/[regAddr]
Esimerkki (dataSource):
modbusrtu://ioPorts%2FmodbusRTU%2FP3/50/input/1?scale=0.1&datatype=int16
modbustcp:// Lukee ja kirjoittaa dataa modbusTCP -protokollalla.
Tukee ylimääräisiä URL parametreja:
order sanajärjestys kun käytetään 32 bittisiä rekistereitä
arvot: "MSW" (enemmän merkitsevä sana ensin),
"LSW" (vähemmän merkistevä sana ensiksi).
Oletus: "MSW"
forcewrite Normaalisti modbus rekisterit kirjoitetaan vain silloin,
kun PV arvo muuttu. Tällä voidaan kirjoitus pakottaa
tapahtuvaksi jokaisella luku/kirjoitus kierroksella.
VAIN dataTarget.
Muoto:
modbustcp://[modbusPortPointId]/[deviceID]/regType/[regAddr]
Esimerkki (dataSource):
modbustcp://ioPorts%2FmodbusTCP%2FM2/1/holding/1?scale=0.1&datatype=int32
bacnetip:// lukee ja/tai kirjoittaa dataa bacnet IP väylään.
Tuetut objekti muodot (objectTypeStr):
analog-input, analog-output, analog-value,
binary-input, binary-output, binary-value,
multistate-input, multistate-output, multistate-value
property voi olla joko propertyn enumeroitu numero. bacnetDefines
tiedostossa määritellään joillekin ominaisuuksille alias, joita ovat mm.
PV = 85
NAME = 77
DESCRIPTION = 28
OOS = 81
RELIABILITY = 103
STATE_TEXTS = 110
ACTIVE_TEXT = 4
INACTIVE_TEXT = 46
Muoto:
bacnetip://[deviceId]/[objectTypeStr]/[objectNo]/[property]
Esimerkiksi:
bacnetip://421001/analog-input/2/PV
bacnetip://421001/analog-output/2/77
file:// Lukee tai kirjoittaa dataa paikallisiin tiedostoihin.
Muoto:
file://localhost/full/file/path
Huomaa! localhost tarvitaan aina semantiikan vuoksi, vaikka se
jätetäänkin huomiotta - eli nykyiset versiot eivät
huomioi host-nimen kirjoitusasusta. Tulevaisuudessa on
mahdollista että file -protokolla laajenee tukemaan myös remote -hosteja,
jolloin taaksepäin yhteensopivuuden vuoksi olisi hyvä että localhost
on kirjoitettu pisteisiin jo valmiiksi oikein.
Esimerkki (dataSource tai dataTarget):
file://localhost/tmp/munIoPiste.txt
file://localhost/tmp/munMittausData.txt?scale=10
http://
https:// Toimii tällä dataSource kentässä, ja vain webService objektissa
Hakee dataa HTTP tai HTTPS protokollan ylitse. Voi lukea esimerkiksi
kokonaisen web sivuston, tai jonkin REST pohjaisen rajapinnan tarjoaman
tiedon.
Muoto:
http://is.fi
Tarkempi kuvaus webservice dokumentissa!
DATAN LUKEMINEN JÄRJESTELMÄSTÄ - SLC JÄRJESTELMÄN RAJAPINNAT
Järjestelmä toteuttaa joitakin rajapintoja joiden kautta tieto-
kannan pisteitä pääsee lukemaan muista järjestelmistä.
RAJAPINTA: BACnet IP
Kaikki AI, AO, AV, BI, BO, BV, MSI ja MSV tyyppiset pisteet tietokannassa tulevat
automaattisesti näkyviin BACnet/IP väylään, mikäli "BACnetIP" prosessi
on käynnissä.
RAJAPINTA: WebService/REST
Data pisteitä on mahdollista lukea järjestelmästä myös REST tyyppisen
rajapinnan ylitse. Kuvattu esillisessä dokumentissa.
RAJAPINTA: SLC konsoli
Dataa voi kysellä myös suoraan SLC palvelimesta. Tämä menetelmä on
itseasiassa huomattavan tehokas, sillä sen kautta saa yhteyden suoraan
SLC enginen Lua rajapintaan, ja tätä kautta on mahdollista vaikkapa
telnet ohjelmalla, tai shell skriptistä netcat komennolla lähettää lua
kielisiä komentojonoja SLC järjestelmälle. Komennot tulee päättää \0 eli
eli niin "null" merkkiin. Tämä tarkoittaa yksinkertaisesti tavua nolla.
Telnet ohjelmassa se saadaan usein tehtyä ^@ merkillä; Suomenkieliseltä
näppäimistöltä [ctrl]-[alrGr]-[2].
Bash komentorivillä voi hyödyntää netcat komentoa,
ja testata sitä esimerkiksi näin:
>> printf "return 'Hello SLC!'\0" | nc 192.168.0.128 30001
huomaa, että printf komennon merkkijonossa annetaa null merkki \0 muodossa.
Hyödyllisempi esimerkki:
>> printf "return Data.getReal ('ioPoints/TK01/TE10_AI.pv')\0" | nc 192.168.0.128 30001
Jolloin komento palauttaa laitteen 192.168.0.130 tietokannasta pisteen
ioPoints/TK01/TE10_AI.pv -kentän pv arvon, ja tulostaa sen näytölle
Saman voi tehdä myös telnet ohjelmassa, ottamalla yhteyden esimerkin tapauksessa
osoitteseen 192.168.0.128, porttiin 30001, ja kirjoittamalla:
return Data.getReal ('ioPoints/TK01/TE10_AI.pv')^@
ja painamalla enter. Lopussa oleva merkki ^@ on edellä jo mainittu "null"
merkki.
Vastaukset joita SLC konsoli antaa, ovat aina JSON muodossa, joten voit
kysellä rajapinnan ylitse ,yös taulukoita tai muita monimutkaisempia
data-rakenteita.
RAJAPINTA: fdxServer
Datapisteitä voidaan lukea tietokannasta myös fdx-rajapinnan ylitse.
Tämän rajapinnan kautta pääsee käsiksi pisteisiin, jotka on luotu
/fdx/.. hakemistoon tietokannassa.
Esimerkiksi pisteen /fdx/TK01_TE10_M oloarvo on mahdollista kysellä fdx
rajapinnan ylitse nimellä TK01_TE10_M.
