Skip to main content

Search

Diagnostics & Commissioning

Apps that facilitate the diagnostics and the commissioning of projects

      Device Reader

      Vassilios Lourdas
      • Updated

      This article covers the following topics:

      Background information

      This app allows more in-depth diagnostics at the device level. The read out data can be also be saved, however to be able to interpret this data, one shall have deep KNX system knowledge.

      The following, basic functions are offered in this ETS App:

      • Open device data (from a file or the device).
      • Save device data to a file.

      Activation

      Follow these instructions in order to activate the app:

      Use of the Device Reader app in ETS

      1. Invoke the App within a project  (How to start an ETS App)
      2. In the ETS App window, it is possible to toggle between the 'Properties' and 'Memory' view on a tab.

      Properties view

      The 'Properties' tab deals with device properties and allows to read device properties.

      The App panel is divided into two parts. The objects (including the object number) are displayed in the left-hand part (1) and the associated properties are displayed in the right-hand part (2).

      DeviceReader_withIndexes.png

      Column Property ID Type Value
      Description Contains the plain text name of the property. Contains the numerical property ID. Indicates the property type. Property Value
      There is a title line which contains information about the origin of the data (e.g. 'Displaying properties of the device: 1.1.4' or 'Properties from C:/User/Admin/Desktop/taster.knxprop').
      Sidebar Display

      Additional properties are also stored in the Properties container.Sidebar.png

      Item Description
      Index The consecutive index of the properties relative to the selected object (0...n).
      Type ID The ID of the property type according to KNX specifications or a custom definition using a type file (see below) for the Device Editor
      Name... The actual (more intelligible) name of the Type ID (in the Sidebar) or Type (in the Panel)
      Type Text The name in text form (default PID--xyz/xyz). A custom name can be assigned in the Device Editor using Definition and a type file (see below)
      Identifier Name; identical to Property in the Panel
      Access Defines the minimum read and write access rights ("access level") required for a property. Depending on the device type (mask version), there can be up to 16 (0 = highest ...15 = lowest) different levels which can be enabled using an Access Key. The precondition for this is that the manufacturer has even defined levels in this manner for the device using a key for a corresponding level. This means that a display of 3/2 requires Level 3 for reading and Level 2 for writing. In other words, to write data, at least Level 2 must be established either by the default key or with a manufacturer-specific key. The Read/Write function can be used to input a key.

      Editing

      • Properties can be edited directly in the associated field (in-place editing), either by double clicking on the respective cell (or using F2) or in the Sidebar (Properties Container).
      • If the properties are not writable, editing is not possible and a double-click on the cell will have no effect.
      • Entire arrays can be edited in a separate dialog, which can be opened by double clicking on the property.
      • If an invalid value is entered, the entry is ignored and the original value is again displayed.

      Functions

      DeviceReaderFunctions.png

      Open from a device

      Open from file

       

      Write to a file

      Memory view

      The 'Properties' tab deals with device memory.

       

       

       

      Index: The consecutive index of the properties relative to the selected object (0...n).
      Type ID: The ID of the property type according to KNX specifications or a custom definition using a type file (see below) for the Device Editor
      Name...: The actual (more intelligible) name of the Type ID (in the Sidebar) or Type (in the Panel)
      Type Text: The name in text form (default PID--xyz/ xyz). A custom name can be assigned in the Device Editor using Definition and a type file (see below)
      Identifier: Name; identical to Property in the Panel
      Access: Defines the minimum read and write access rights ("access level") required for a property. Depending on the device type (mask version), there can be up to 16 (0 = highest ...15 = lowest) different levels which can be enabled using an Access Key. The precondition for this is that the manufacturer has even defined levels in this manner for the device using a key for a corresponding level. This means that a display of 3/2 requires Level 3 for reading and Level 2 for writing. In other words, to write data, at least Level 2 must be established either by the default key or with a manufacturer-specific key. The Read/Write function can be used to input a key.

       

      Functions

      Properties – Read from a device

      The dialog for reading out device properties allows the following input:

      •Device/ Physical Address; predefined using the address of the device last selected in ETS (or the address of the device to which the last element selected belongs).

      •Device/Access Key (also called Access Key in KNX); for procedure, see Note

      •Reading mode; complete/partial indicates whether the properties are to be read completely (time factor) or only little by little when the object is selected in the left window.

      While the properties are being read from the device, a modular "Please wait" dialog appears. The operation which is running can be canceled using this dialog. In this case, all of the data loaded up to this point are discarded. None of the data loaded up to now is displayed.

      Note

      Array-Properties with a size in excess of 64 bytes are only loaded "on demand" during editing (see above) of the property (increases the speed of the display).
      Properties – Read from file

      If properties are to be read from a file, an "Open File" dialog appears first which only allows *.knxprop files to be selected. When a file is opened, all previously displayed data is discarded.
      Properties – Write to file

      As is the case for reading from a file, the "Open File" dialog only allows *.knxprop files to be selected. If the file selected already exists, there will be a confirmation prompt about overwriting the file.

      Note

      If you are dealing with an Array- Property, which is larger than 64 bytes and has not yet been loaded "on demand", the property is saved as a blank field. There will be no subsequent loading of as yet unread fields.
      Behavior in the event that there are contradictions between the device information and the KNX administrative data (master data)

      When the properties of a device are read out, information about the type or the number of elements of the property are determined for each property online for the device. It may occur that this information does not coincide with the description of the property in the KNX master data .

      For example, the master data may indicate that a property is a single value of the type INTEGER, while the online information indicates that it is an INTEGER with nine (9) values, i.e. an array. Or that a property is writeable according to the KNX master data while the "online" information claims the opposite.

      •In these cases, the information from the KNX master data always takes priority.

      •This sort on contradiction is indicated by the type being displayed orange.

      This view allows the editing of a memory area of a device; the structure is similar to that of common hex editors.

      Display

      The width of the display is fixed at 16 bytes and is not variable. The base addresses (hexadecimal form) are listed in the left column; to the right in the header are the 16 different memory locations (hexadecimal form).

      Editing

      Modified bytes are displayed in red while read-only bytes are grayed out. Input is made in hexadecimal form.

      Functions

      Memory – Reading from a device

      The dialog for reading out the device memory allows the following input:

      •Device/ Physical Address; predefined using the address of the device last selected in ETS (or the address of the device to which the last element selected belongs).

      •Device/Access Key (also called Access Key in KNX); for procedure, see Note

      •Range; from ... to; default = 0x0100.. 0x010F

      •Address space; default = Standard Memory, others are User Memory, Line Coupler Slave, Line Coupler Routing Table)
      Memory – Read from file

      In the dialog for opening *.sxx files, the formats *.s19; *.s28 and *.s37 may be selected.

      After selection of a file, the entire contents of the file is displayed in the editor. If the format of the file is faulty or the file cannot be read out completely, a corresponding message appears and the process is ended.
      Memory – Write to file

      Writing to *.sxx files can only be done in the file formats mentioned above. If the target file already exists, there will be a confirmation prompt whether the file should be overwritten. If memory is read from a file, edited and written back to the file, any loading procedures which may exist in this file are not lost in the process.

      In addition to the Device Reader, there is also the Device Editor which, in addition to offering further functions, provides write access/data transfer to devices. The following table lists the differences (R = read access, W = write access).

      ETS App

      Device Properties

      Device Memory

      *.sxx files

      *.knxprop files

      Device Reader

      R

      R

      R / W

      R / W

      Device Editor

      R / W

      R / W

      R / W

      R / W

      Which memory areas even allow read/write access depends on the respective device model (mask version). Writing rights (W) are subject to an access encoding; a (memory) resource cannot be written to if the (Write) access rights contain the following:

      •<AccessRights Read="xyz" Write="None"/>

      •<AccessRights Read="xyz" Write="Manufacturer"/>

      The data is all stored in the ETS administrative data (master data).

      Additional Functions

      Memory – Transfer to device

      When transferring a memory area to a device, a dialog with the following options appears:

      •Device/ Physical Address; predefined using the address of the device last selected in ETS (or the address of the device to which the last element selected belongs).

      •Device/Access Key (also called Access Key in KNX); for procedure, see Note

      •Write Mode; complete/partial indicates whether the memory area should be overwritten completely, or only the modified bytes marked in red.

      If the memory area specified is larger than the number of bytes read in, an error message will appear.
      Properties – Transfer to device

      The following dialog options are available:

      •Device/ Physical Address; predefined using the address of the device last selected in ETS (or the address of the device to which the last element selected belongs).

      •Device/Access Key (called Access Key in KNX as well); predefined using a possible ETS project key which may exist

      In contrast to the Memory Mode (see above), only the changes which have currently been made are transferred to the device in this case. The option of transferring everything (again) is very time-intensive and not entirely secure (for so-called Stateless Function Properties).
      User-defined Load Type Data

      Using the Load Type Data function, users can load their own type data to display the designations of property types which, for example, are not yet contained in the KNX administrative data. If an attempt is made here to overwrite an ID which already exists, an error message will appear.

      •When user-defined data is loaded, the known data types are first reset to the status of the KNX administrative data and then the selected data is read in. All user data loaded previously is discarded in this process. This means that it is not possible to consecutively load several user-defined data files.

      •To reset the KNX administrative data to the original state, a type data file must be read in which contains only a blank element (<PropertyIdentifiers />).

      •The format of the type file is described below.

      There are three (3) file formats which KNX ETS Apps can work with and store. These are described in the following:

      •Property Files (*.knxprop);         Saves (read) data in files

      •Save Files (*.sxx);         Saves (read) memory contents in files

      •Type Files (*.xml);         Defines the interpretation of (possibly unknown) property types

      Property File format

      The format is XML based and describes objects and their associated properties as well as their values. Every object here is identified by two descriptive items:

      TypeId An ID from the KNX master data
      Index Index of the object on the device

      The following information from properties is stored:

      Id PropertyTypeId from the KNX master data; if not available, only a numeric value
      Access Byte
      Writeable Boolean
      TypeId Name of the PropertyIdentifier
      ElementCount For arrays > 1, otherwise 1
      Index Index of the property on the object
      Value Formattable value

      Formatting of values

      Except for arrays, every property type is broken down into its individual bytes and is stored this way, whereby the bytes are separated by a "-".

      By way of example, here is the value of a property of the type PDT_GENERIC_10:

      Value="16-75-C1-04-41-81-45-20-02-00"

      Formatting of arrays

      The individual elements of the array are broken down into bytes the same way as non-array values. The individual values are separated by a comma in the array. Stored arrays are enclosed in curly brackets. As an example, here is a property of the type PDT_GENERIC_01 with 12 elements:

      Value="{ 31,34,3A,34,30,3A,30,34,00,00,00,00 }"

      Example

      Here is a completeExample to further clarify the format. As can be seen, objects are also stored for which no properties have yet been read in.

      <?xml VERSION="1.0"?>
      <Objects>
        <Object TypeID="OT-0" Index="0">
          <Properties>
            <Property Id="PID--1" Access="0" Writable="false" 
                      TypeId="PDT_UNSIGNED_INT" ElementCount="1" Index="0" Value="00-00" />
            <Property Id="PID--9" Access="0" Writable="false" 
                      TypeId="PDT_UNSIGNED_CHAR" ElementCount="1" Index="1" Value="01" />
            <Property Id="PID--11" Access="0" Writable="false" 
                      TypeId="PDT_GENERIC_06" ElementCount="1" Index="2" 
                      Value="00-01-00-1F-72-F4" />
            <Property Id="PID--12" Access="0" Writable="false" 
                      TypeId="PDT_UNSIGNED_INT" ElementCount="1" Index="3" Value="00-01" />
            <Property Id="PID--14" Access="0" Writable="true" 
                      TypeId="PDT_GENERIC_01" ElementCount="1" Index="4" Value="00" />
            <Property Id="PID--15" Access="0" Writable="false" 
                      TypeId="PDT_GENERIC_10" ElementCount="1" Index="5" 
                      Value="16-75-C1-04-41-81-45-20-02-00" />
            <Property Id="207" Access="0" Writable="false" 
                      TypeId="PDT_GENERIC_04" ElementCount="1024" Index="20" Value="{  }" />
            <Property Id="208" Access="0" Writable="true"
                      TypeId="PDT_FUNCTION" ElementCount="1" Index="21" />
            <Property Id="209" Access="0" Writable="true" 
                      TypeId="PDT_FUNCTION" ElementCount="1" Index="22" />
            <Property Id="211" Access="0" Writable="false" 
                      TypeId="PDT_GENERIC_01" ElementCount="12" Index="23" 
                      Value="{ 31,34,3A,34,30,3A,30,34,00,00,00,00 }" />
            <Property Id="247" Access="0" Writable="false" 
                      TypeId="PDT_VERSION" ElementCount="1" Index="24" Value="40-00" />
          </Properties>
        </Object>
        <Object TypeId="OT-6" Index="1">
          <Properties />
        </Object>
        <Object TypeId="OT-7" Index="2">
          <Properties />
        </Object>
      </Objects>
      Memory File format

      The use of all the *.sxx formats in ETS grew historically. They are binary-oriented data formats defined by Motorola. A precise format definition can be found on the Internet. The general principle is always RECORD-TYPE COUNT ADDRESS DATA CHECK-SUM.
      Type File format

      The file format of the type data files corresponds to the format of the corresponding elements in the KNX administrative data (master data). All elements of the type Property Identifier are enclosed in pointed brackets <PropertyIdentifiers> and contain the following information as XML attributes:

      Id Property ID (plain text in the Property properties)
      Number Property ID (numerical)
      Name Property Name
      Text Property Name (plain text in the Property column)
      PDT Property Type ID (specifies the type and bit width)
      ObjectType ObjectType ID; specifies for which object types this Property Identifier is valid. If this value is not set, the Property Identifier is valid for all Object Type's.

      Example

      Here is a completeExample to further clarify the format.

      <PropertyIdentifiers>
            <PropertyIdentifier Id="PID--208" Number="208" Name="PID_CUSTOM_STATE" 
                                Text="Custom State" PDT="PDT-4"  />
            <PropertyIdentifier Id="PID--212" Number="212" Name="PID_SUPPORT_FLAG" 
                                Text="Support Flag" PDT="PDT-3"  />
            <PropertyIdentifier Id="PID--215" Number="215" ObjectType="OT-11"
                                Name="PID_CHANNEL_MODE" Text="Channel Mode" PDT="PDT-3"  />
      </PropertyIdentifiers>

      Notes

      •The Access Key is predefined using a key of the ETS project that may already exist; otherwise, the default key (0xFFFFFFFF) is used. ETS attempts to use the "higher value" level on the basis of these two keys.

      ▪Project key exists; Level from the winner project key <> default key; If the first query with the default key immediately achieves the maximum level (= 0), the second query can be omitted.

      ▪There is no project key; The level from the default key is used.

      •This KNX ETS App can be called more than once in ETS (see Call Types for ETS Apps).

      Related articles

      Didn't find what you were looking for?
      Submit a request Community