KONNEKTING XML Device Description
Revision as of 13:47, 29 March 2022 by Konnekting (talk | contribs)
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>