KONNEKTING XML Device Description

KONNEKTING XML Device Description (.kdevice.xml)

After writing your arduino KONNEKTING Device sketch, you should have a list of communication objects and parameters your device will use or provide. To be able to program the device via the KNX bus, you have to provide a XML file which describes your device. This XML file can then be used by the KONNEKTING Suite, which provides a comfortable way of device programming.

Either you use a standard text editor (on windows we can recommend Notepad++), or you use an XML editor of your choice. In case of an XML Editor that can handle XML Schema Definition files (.xsd), you can use this one:

https://github.com/KONNEKTING/KonnektingXmlSchema/blob/master/src/main/xsd/KonnektingDeviceV0.xsd

Preparation

If you haven't registered a manufacturer-id yet, NOW would be the best time for it. REGISTER FOR FREE

XML Format explained (1.0.0-RC1 Format!)

  1<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  2<KonnektingDevice xmlns="http://konnekting.de/xml/KonnektingDevice/v0" 
  3    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  4    xsi:schemaLocation="http://konnekting.de/xml/KonnektingDevice/v0 http://konnekting.de/xml/KonnektingDevice/KonnektingDeviceV0.xsd">
  5
  6    <!-- 
  7        Herer you have to provide your IDs and device revision. 
  8        This MUST match the definition in your Arduino Sketch.
  9        Otherwise programming fails.
 10
 11        The IDs need to be provided as unsigned integer values.
 12
 13        Manufacturer ID = Your individual vendor ID (uint16)
 14        Device ID = An ID for your device (uint8) 
 15        Revision = typically "1" (uint8)
 16                    You might use 
 17                        0 for developing-phase, 
 18                        1 for first release and 
 19                        2...255 of every change which breaks compatibility.
 20    -->
 21    <Device ManufacturerId="12345" DeviceId="123" Revision="123">
 22        <!-- 
 23            Providing a manufacturer name and device name is optional.
 24            But without, your device will not be shown with a vendor/name in the KONNEKTING SUite
 25        -->
 26        <ManufacturerName>You Manufacturer Name</ManufacturerName>
 27        <DeviceName>Your Device Name</DeviceName>
 28        
 29        <!--
 30            If your device needs any parameters which the user should be able to configure, 
 31            you have to put them here.
 32        -->
 33        <Parameters>
 34            
 35            <!--
 36                Parameters are grouped. It's not allowed to have a parameter without a group.
 37
 38                Each group needs an ID and readable name. The first group has to have Id="0". 
 39                The ID must be provided as a readable integer and you must not have Id-gaps.
 40                The name is display in the KONNEKTING Suite.
 41
 42                You can have as much groups as you like. Okay, actually the limit is 256. 
 43                But that should be enough.
 44            -->
 45            <ParameterGroup Name="A Parameter Group" Id="0">
 46                
 47                <!--
 48                    Each parameter needs an ID. The first parameter has to have Id="0". 
 49                    The ID must be provided as a readable integer.
 50
 51                    You can distribute your parameters in any order over the groups. 
 52                    Important thing is: 
 53                        - If you have parameters, there must a parameter with Id="0", 
 54                        - There are no Id-gaps
 55
 56                    If you have an obsolete parameter: 
 57                        - change the name to "unused" or "deprecated" or whatever,
 58                        - set type to uint8,
 59                        - Default to 00,
 60                        - Min to 00 and
 61                        - Max to 00
 62
 63                    This will just waste one byte of your EEPROM memory in your sketch. 
 64
 65                    IdName is optional and can be used together with the KONNEKTING Code-Creator to
 66                    auto-create Arduino-code. Ensure that the IdName attribute has only alphabetic chars and no whitespaces, special-chars etc.
 67                -->
 68                <Parameter Id="0" IdName="aParameter">
 69                    
 70                    <!-- If course a parameter needs a name, which you can define here -->
 71                    <Description>A Parameter</Description>
 72                    
 73                    <!--
 74                        And beside a name, you have to provide the at least:
 75                        - Type: 
 76                            The variable type of your number parameter
 77
 78                            uint8: unsigned 8-bit integer: 0..255
 79                            int8: signed 8-bit integer: -128..127
 80
 81                            uint16: unsigned 16-bit integer: 0..65535
 82                            int16: signed 16-bit integer: -32768..32767
 83
 84                            uint32: unsigned 32-bit integer: 0..4294967295
 85                            int32: signed 32-bit integer: -2147483648..2147483647
 86
 87                            And there is a type for raw data, called "raw". This is f.i. useful 
 88                            if you have a parameter for IR hexcodes or 1-wire serialnumbers etc.
 89                            The Suite will let you enter the data as HEX.
 90
 91                            raw1: 1 byte raw data
 92                            raw2: 2 byte raw data
 93                            .
 94                            .
 95                            raw11: 11 byte raw data
 96
 97                            string11: max. 11 byte ISO-8859-1 encoded string/text. Unused, tailing characters are filled with 0x00
 98
 99                            This attribute is MANDATORY and there's - except for DEFAULT - no other attribute possible!
100
101                        - Default
102                            the hexadecimal representation of the default-value, 
103                            according to the given type, incl. leading/tailing zeros, f.i.
104                            a 16-bit type needs four hex-characters: 00FF
105                            a 32-bit type needs eight hex-characters: 000000FF
106                            a 11-byte-string: 666F6F2062617200000000 ("foo bar")
107                            This attribute is MANDATORY.
108
109                        Optional:
110                        - Options
111                            If you want to present a prset of options for a parameter, 
112                            you can use the "Options" attribute. The value for this 
113                            attribute is a set of "pipe" separated value-key-pairs:
114
115                            Options="value=key_1|value=key_2|value=key_n"
116
117                            The "key" is what the user will see in the dropdown box in 
118                            KONNEKTING Suite, als "value" is what interally will be chosen 
119                            as the value for the parameter if selected.
120
121                            Example: You want to preset a preset of "startup delay values" to the user:
122                            10ms, 30ms, 60ms, 120ms, no delay
123
124                            Then the options could look like this:
125
126                            Options="00=10ms|01=30ms|02=60ms|04=120ms|FF=no delay"
127
128                            Your arduino sketch needs to know how to interpret the values and that 
129                            the 02hex value actually means 60ms and FFhex means no delay.
130
131                        - Min/Max
132                            Can only be used when no Options attribute is set and with a number type. This will limit the 
133                            value the user is allowed to enter between Min and Max. The provided
134                            value needs to be hex again with leading zeros according to the type.
135                    -->
136                    <Value Type="uint8" Default="01" Options="" Min="00" Max="0A"/>
137
138                </Parameter>
139
140                <Parameter Id="1" IdName="anotherParameter">
141                    <Description>Another Parameter</Description>
142                    <Value Type="int16" Default="0001" Options=""/>
143                </Parameter>
144
145                <Parameter Id="2" IdName="yetAnotherParameter">
146                    <Description>Yet Another Parameter</Description>
147                    <Value Type="uint8" Default="00" Options="00=10ms|01=30ms|02=60ms|04=120ms|FF=no delay"/>
148                </Parameter>
149
150                <Parameter Id="3" IdName="activate1">
151                    <Description>Activate 'Another Parameter'</Description>
152                    <Value Type="uint8" Default="01" Options="00=disabled|01=enabled"/>
153                </Parameter>
154
155                <Parameter Id="4" IdName="activate2">
156                    <Description>Activate 'Another Parameter Group'</Description>
157                    <Value Type="uint8" Default="01" Options="00=disabled|01=enabled"/>
158                </Parameter>
159
160                <Parameter Id="5" IdName="activate3">
161                    <Description>Activate 'My Second Com Object'</Description>
162                    <Value Type="uint8" Default="01" Options="00=disabled|01=enabled"/>
163                </Parameter>                
164            </ParameterGroup>
165
166            <ParameterGroup Id="1" Name="Another Parameter Group">
167                <Parameter Id="6">
168                    <Description>Another parameter in another parametergroup</Description>
169                    <Value Type="uint8" Default="02" Options="00=Aus|01=An|02=letzter Wert|04=Helligkeitswert"/>
170                </Parameter>
171            </ParameterGroup>
172
173        </Parameters>
174
175        <CommObjects>
176            <!-- 
177                A normal KNX device should have at least one communication object.
178                As with the parameters, IDs must start at 0 and there must be no ID gaps. 
179                The maximum number of comm objects is 256. The Id must be provided as a readable integer.
180            -->
181            <CommObject Id="0">
182                <!-- You should provide a reasinaly name -->
183                <Name>My First Com Object</Name>
184                <!-- and a description of the functiono of this comm object-->
185                <Function>Test-Function #1</Function>
186                <!-- 
187                    Here you have to provide the Datapoint Type for this CommObject
188                    Format:
189                        x.yyy
190                    where x = main type number, without leading zeros
191                    and yyy = sub type number, with leading zeros to pad up to 3 characters for values [0..999].
192                -->
193                <DataPointType>1.001</DataPointType>
194
195                <!-- 
196                    ComObj communication flags. 
197
198                    The "Flags" is a single byte (integer value), 
199                    that indicates the set communication flags of the ComObj by setting/unsetting single bits of that byte.
200
201                    Flags are:
202                        C   Communication
203                        R   Read
204                        W   Write
205                        T   Transmit
206                        U   Update
207                        I   Init
208
209                    (for more details about the flags, read: http://www.knx.org/fileadmin/template/documents/downloads_support_menu/KNX_tutor_seminar_page/Advanced_documentation/02_Flags_E1008a.pdf)
210
211                     B7  B6  B5  B4  B3  B2  B1  B0 (Bit number)
212                    128  64  32  16   8   4   2   1 (integer value)
213                     xx  xx   C   R   W   T   U   I (Flag) 
214
215                    Bit B6 and B7 are unused.
216
217                    Common flag-combinations:
218                        * "Sensor Profile" -> C+R+T -> 32+16+4 = 52 (integer value)
219                        * "Logical Input Profile" -> C+W+U -> 32+8+2 = 42 (integer value)
220                -->
221                <Flags>52</Flags>
222            </CommObject>
223
224            <CommObject Id="1">
225                <Name>My Second Com Object</Name>
226                <Function>Test-Function #2</Function>
227                <DataPointType>1.001</DataPointType>
228                <Flags>42</Flags>
229            </CommObject>
230        </CommObjects>
231
232        <!--
233            If you want to hide CommObjects, Parametergroups or Parameters depending on parameter values,
234            you can define dependencies here.
235
236            ParameterDependency:
237                The visibility of a parameter depends on the value of another parameter
238                * ParamId references the affected Parameter
239
240            ParameterGroupDependency:   
241                The visibility of a parameter group depends on the value of another parameter
242                * ParamGroupId references the affected ParameterGroup
243
244            CommObjectDependency:       
245                The visibility of a CommObject depends on the value of a parameter
246                * CommObjId references the affected CommObject
247
248            All three depedency types have three common attributes:
249
250                * Test: one of
251                    eq = equals
252                    ne = not equals
253                    gt = greater than
254                    lt = less than
255                    ge = greater or equals than
256                    le = less or equals than
257                    IN/NOTIN/BETWEEN/NOTBETWEEN = test against a list of values, see TestList
258                * TestParamId: the parameter which's value is been tested for setting visibility
259                * TestValue: the value the parameter is tested for (used when not testing with IN/NOTIN/BETWEEN/NOTBETWEEN)
260                * TestList: the list the parameter is tested for (used for IN/NOTIN/BETWEEN/NOTBETWEEN). Values are separated by "|" character. f.i. "01|02|03"
261
262            There's one limitation: The parameters that is used as a dependency (=referenced by TestParamId) needs
263            the parameter type "uint8". Other types are not supported.
264        -->
265        <Dependencies>
266            <ParameterDependency ParamId="1" Test="eq" TestParamId="3" TestValue="01" TestList=""/>
267            <ParameterDependency ParamId="2" Test="in" TestParamId="3" TestValue="01" TestList="02|03"/>
268            <ParameterGroupDependency ParamGroupId="1" Test="eq" TestParamId="4" TestValue="01" TestList=""/>
269            <CommObjectDependency CommObjId="1" Test="eq" TestParamId="5" TestValue="01" TestList=""/>
270        </Dependencies>
271    </Device>
272</KonnektingDevice>