ETAtouch RESTful Webservces Verson 1.1 November 8, 2012
Contents 1 Introducton 3 2 The resource /user/ap 6 2.1 HTTP GET................................... 6 2.2 HTTP POST.................................. 6 2.3 HTTP PUT................................... 6 2.4 HTTP DELETE................................ 6 3 The resource /user/menu 6 3.1 HTTP GET................................... 6 3.2 HTTP POST.................................. 7 3.3 HTTP PUT................................... 7 3.4 HTTP DELETE................................ 7 4 The resource /user/var 7 4.1 HTTP GET................................... 8 4.2 HTTP POST.................................. 8 4.3 HTTP PUT................................... 10 4.4 HTTP DELETE................................ 10 5 The resource /user/vars 10 5.1 HTTP GET................................... 10 5.2 HTTP POST.................................. 11 5.3 HTTP PUT................................... 11 5.4 HTTP DELETE................................ 12 6 The resource /user/errors 13 6.1 HTTP GET................................... 13 6.2 HTTP POST.................................. 15 6.3 HTTP PUT................................... 16 6.4 HTTP DELETE................................ 16 2
1 Introducton The ETAtouch devce offers several web servces to get access to the nternal CAN subsystem. The webservces are mplemented usng the REST archtectural style 1. Ths allows the user to retreve nformatons n a network-compatble, platform ndependent and programmng language ndependent way. You can access the webservces of your ETAtouch devce by sendng your requests to port 8080 usng the HTTP protocol: http://etatouch-ip:8080/resource In order to use the ETAtouch webservces you must have ensured the followng precondtons (take care of the sequence): 1. You must have nstalled system software verson 1.20.0 or hgher on your ETAtouch devce. 2. You must have regstered your ETAtouch devce at http://www.meneta.at. 3. You must have appled for LAN access at http://www.meneta.at for your ETAtouch devce. 4. You must have actvated LAN access on your ETAtouch devce n the system settngs. Fgure 1 shows a use case dagram of the ETAtouch RESTful webservces. Fgure 2 shows a typcal sequence of requestng the menu tree whch can be seen n the tree vew on your ETAtouch devce. 1 http://en.wkpeda.org/wk/representatonal_state_transfer 3
ETAtouch Read menu tree «extends» Read varable Varable operatons «extends» Set varable User Read actve errors Create varable set «extends» «extends» Read varable set Varable set operatons «extends» Delete varable set «extends» «extends» Add varable Remove varable Fgure 1: Use cases of ETAtouch RESTful webservces. 4
sd ETAtouch REST c:httpclent s:etatouch GET http://{ip}:8080/user/menu HTTP/1.1 xmlresponse: XmlResponse Content-Type: applcaton/xml <menu> <fub ur="/112/10021" name="kessel"> <object ur="/112/10021/0/0/12010" name="counters"> <object ur="/112/10021/0/0/12153" name="full load hours"/>... </fub> </menu> new :XmlParser parse(xmlresponse) Fgure 2: Typcal sequence of gettng the menu tree. After requestng the menu resource, the web servce responses wth the menu tree n XML format whch can be processed by the clent. 5
2 The resource /user/ap Ths resource returns the verson of the API. 2.1 HTTP GET Usng HTTP GET you can read the current API verson. Example 1 Read the API verson number. GET /user/ap HTTP/1.1 Content-Type: applcaton/xml <ap verson="1.1" /> 2.2 HTTP POST Ths method s not supported by ths ressource. 2.3 HTTP PUT Ths method s not supported by ths ressource. 2.4 HTTP DELETE Ths method s not supported by ths ressource. 3 The resource /user/menu Ths resource dentfes the menu tree whch you can see on the touch dsplay n the tree vew. 3.1 HTTP GET Usng HTTP GET you can read the menu tree as you can see t on the touch screen. Grouped by the varous functonal blocks you can fnd the partcular objects n a herarchcal order. 6
Example 1 Retreve the menu tree. GET /user/menu HTTP/1.1 Content-Type: applcaton/xml <menu> <fub ur="/112/10021" name="kessel"> <object ur="/112/10021/0/0/12010" name="counters"> <object ur="/112/10021/0/0/12153" name="full load hours"/>... </object> <object ur="/112/10021/0/0/12182" name="mscellaneous"> <object ur="/112/10021/0/0/12080" name="i/o key"/> <object ur="/112/10021/0/0/12112" name="ash removal key"/> <object ur="/112/10021/0/0/12115" name="emsson Measurement"/> <object ur="/112/10021/0/0/12152" name="feedng tme"/> </object> </fub> </menu> 3.2 HTTP POST Ths method s not supported by ths ressource. 3.3 HTTP PUT Ths method s not supported by ths ressource. 3.4 HTTP DELETE Ths method s not supported by ths ressource. 4 The resource /user/var Ths resource dentfes a varable n the CAN system. 7
4.1 HTTP GET Usng HTTP GET you can read a varable s value. Each varable s defned by a unque address n the CAN system. Ths address can be determned by evaluatng the menu tree. Followng you can see a snppet from the menu tree. 1 <o b j e c t u r = /112/10021/0/0/12182 name= Mscellaneous > 2... 3 <o b j e c t u r = /112/10021/0/0/12112 name= Ash removal key /> 4... 5 </ o b j e c t> Based on the XML snppet above, you can fnd the address 112/10021/0/0/12112 whch dentfes the ash removal key. Example 1 Read the state of the ash removal key on CAN node 112 and Fub-ID 10021. GET /user/var/112/10021/0/0/12112 HTTP/1.1 Content-Type: applcaton/xml <value ur="/user/var/112/10021/0/0/12112" strvalue="off" unt="" decplaces="0" scalefactor="1" advtextoffset="1802">1802</value> As you can see, the resultng XML document contans an element named <value>. The content of ths element s the varable s raw value. Please refer to table 1 for a descrpton of the attrbutes. 4.2 HTTP POST Usng HTTP POST you can set a varable to a certan value. Note, that you have to provde the the varable s raw value (wthout scalng)! If a varable wth tme nterval datatype should be set, value, begn and end parameters must be provded. The begn and end tme are ntegral multples of 15 mnutes snce mdnght. Ths mples a vald range of [0, 96] for begn and end. Note: The feature of settng the tme slots requres an API verson of 1.1 or hgher (avalable snce system software verson 1.25.0/2.25.0 or hgher). 8
Attrbute ur strvalue unt decplaces scalefactor advtextoffset Descrpton Ths s the requested URI. The varable s value as formatted strng. The varable s unt as strng. The number of decmal places. The scale factor for processng the raw value. The offset of text varables. If you read a text varable (e.g. the ash removal key) you can subtract ths value from the varable s raw value n order to get a value from [0, max] for e.g. boolean evaluatons. Table 1: Descrpton of XML attrbutes of element <value>. Example 1 Set the deash key to On. POST /user/var/112/10021/0/0/12112 HTTP/1.1 Content-Type: applcaton/x-www-form-urlencoded value=1803 Content-Type: applcaton/xml <success ur="/user/var/112/10021/0/0/12112"/> Example 2 Set monday s tme slot 1 of the hot water tank s chargng tmes to 00:00-12:00, 40 degrees: POST /user/var/112/10111/12130/0/1082 HTTP/1.1 Content-Type: applcaton/x-www-form-urlencoded value=400&begn=0&end=48 9
Content-Type: applcaton/xml <success ur="/user/var/112/10111/12130/0/1082"/> 4.3 HTTP PUT Ths method s not supported by ths ressource. 4.4 HTTP DELETE Ths method s not supported by ths ressource. 5 The resource /user/vars Ths resource dentfes a set of varables. It allows you to defne your own named varable set whch acts as a contaner for dfferent sngle varables. Havng once created a varable set you can add or remove arbtrary varables from the CAN system to ths set. The name of a varable set must match the followng regular expresson: 5.1 HTTP GET [a za Z0 9] + Usng HTTP GET you can request two resources. (see table 2). Resource /user/vars /user/vars/{varset} Descrpton Get a lst of all defned varable sets. Read all varables from the specfed varable set Varset. Table 2: Descrpton of resources under /user/vars. Example 1 Get a lst of defned varable sets. GET /user/vars HTTP/1.1 10
Content-Type: applcaton/xml <vars ur="/user/vars/myset1"/> Example 2 Read varable set myset1. GET /user/vars/myset1 HTTP/1.1 Content-Type: applcaton/xml <vars ur="/user/vars/myset1"> <varable ur="112/10021/0/0/12112" strvalue="off" unt="" decplaces="0" scalefactor="1" advtextoffset="1802">1802</varable> </vars> 5.2 HTTP POST Ths method s not supported by ths ressource. 5.3 HTTP PUT HTTP PUT s used to create resources on the server. The semantcs of HTTP PUT depends on your requested URI (see table 3). Example 1 Create a new varable set named myset1. PUT /user/vars/myset1 HTTP/1.1 HTTP/1.1 201 Created 11
Resource /user/vars/{varset} /user/vars/{varset}/{node-id}/{fub- ID}/{Fkt-ID}/{Io-ID}/{Var-ID} Descrpton Create a new varable set named Varset. Add the varable specfed by the address Node-ID/Fub-ID/Fkt-ID/Io-ID/Var- ID to the varable set named Varset. Table 3: Descrpton of resources under /user/vars. Content-Type: applcaton/xml <success ur="/user/vars/myset1"/> Example 2 Add the varable 112/10021/0/0/12112 to the varable set myset1. PUT /user/vars/myset1/112/10021/0/0/12112 HTTP/1.1 HTTP/1.1 201 Created Content-Type: applcaton/xml <success ur="/user/vars/myset1/112/10021/0/0/12112"/> 5.4 HTTP DELETE HTTP DELETE s used to delete resources on the server. The semantcs of HTTP DELETE depends on your requested URI (see table 4). If you do not need a varable set any more your clent software should ensure, that all created varable sets are deleted n order to avod resource conflcts. Example 1 Remove the varable 112/10021/0/0/12112 from the varable set myset1. DELETE /user/vars/myset1/112/10021/0/0/12112 HTTP/1.1 12
Resource /user/vars/{varset} /user/vars/{varset}/{node-id}/{fub- ID}/{Fkt-ID}/{Io-ID}/{Var-ID} Descrpton Delete the varable set named Varset. Remove the varable specfed by the address Node-ID/Fub-ID/Fkt-ID/Io-ID/Var- ID from the varable set named Varset. Table 4: Descrpton of resources under /user/vars. Content-Type: applcaton/xml <success ur="/user/vars/myset1/112/10021/0/0/12112"/> Example 2 Delete the varable set myset1. DELETE /user/vars/myset1 HTTP/1.1 Content-Type: applcaton/xml <success ur="/user/vars/myset1"/> 6 The resource /user/errors Ths resource dentfes the actve errors n the CAN system. 6.1 HTTP GET Usng HTTP GET you can read the actve errors. A descrpton of the resources can be found n table 5. 13
Resource /user/errors /user/errors/{node-id} /user/errors/{node-id}/{fub-id} Descrpton Retreve all actve errors from the CAN system. Retreve all actve errors from the CAN node wth node number Node-ID. Retreve all actve errors from functonal block Fub-ID on the CAN node wth node number Node-ID. Table 5: Descrpton of resources under /user/errors. Example 1 Retreve all actve errors from the system. GET /user/errors HTTP/1.1 Content-Type: applcaton/xml <errors ur="/user/errors"> <fub ur="/112/10021" name="kessel"> <error msg="flue gas sensor Interrupted" prorty="error" tme="2011-06-29 12:47:50">Sensor or Cable broken or badly connected </error> <error msg="water pressure too low 0,00 bar" prorty="error" tme="2011-06-29 12:48:12">Top up heatng water! If ths warnng occurs more than once a year, please contact plumber. </error> </fub> <fub ur="/112/10101" name="hk1"/> </errors> Example 2 Retreve all actve errors from CAN node 112. GET /user/errors/112 HTTP/1.1 14
<errors ur="/user/errors/112"> <fub ur="/112/10021" name="kessel"> <error msg="flue gas sensor Interrupted" prorty="error" tme="2011-06-29 12:47:50">Sensor or Cable broken or badly connected </error> <error msg="water pressure too low 0,00 bar" prorty="error" tme="2011-06-29 12:48:12">Top up heatng water! If ths warnng occurs more than once a year, please contact plumber. </error> </fub> <fub ur="/112/10101" name="hk1"/> </errors> Example 3 Retreve all actve errors from functonal block 10021 on CAN node 112. GET /user/errors/112/10021 HTTP/1.1 Content-Type: applcaton/xml <errors ur="/user/errors"> <fub ur="/112/10021" name="kessel"> <error msg="flue gas sensor Interrupted" prorty="error" tme="2011-06-29 12:47:50">Sensor or Cable broken or badly connected </error> <error msg="water pressure too low 0,00 bar" prorty="error" tme="2011-06-29 12:48:12">Top up heatng water! If ths warnng occurs more than once a year, please contact plumber. </error> </fub> </errors> 6.2 HTTP POST Ths method s not supported by ths ressource. 15
6.3 HTTP PUT Ths method s not supported by ths ressource. 6.4 HTTP DELETE Ths method s not supported by ths ressource. 16