Difference between revisions of "KONNEKTING XML Device Description"
Jump to navigation
Jump to search
Konnekting (talk | contribs) |
Konnekting (talk | contribs) |
||
| Line 34: | Line 34: | ||
1 for first release and | 1 for first release and | ||
2...255 of every change which breaks compatibility. | 2...255 of every change which breaks compatibility. | ||
| + | SystemType = Identifies system type. See https://wiki.konnekting.de/index.php/KONNEKTING_Protocol_Specification_0x01#System_Type | ||
--> | --> | ||
| − | <Device ManufacturerId="12345" DeviceId="123" Revision="123"> | + | <Device ManufacturerId="12345" DeviceId="123" Revision="123" SystemType="1"> |
<!-- | <!-- | ||
Providing a manufacturer name and device name is optional. | Providing a manufacturer name and device name is optional. | ||
Latest revision as of 13:49, 29 March 2022
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>