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