GDK's XML Content

Introduction

Most users of GDK need never look at the XML files. This chapter is intended as a detailed reference.

GDK uses XML data for definitions of hardware, the DMC language, and content for some tools. Users editing XML content are usually trying to do one of the following.

  • Change data handling for a command that is set to non-defaults, namely AQ or DQ.
  • Adapt to a custom firmware/hardware product by
    • Interpreting data in a special format.
    • Adapt the Editor to properly parse custom commands.
    • Update the Setup tool to backup and clone custom settings.
  • Adapt GDK to an application by interpreting data in user units. E.G. nanometers instead of encoder counts, or degrees Celsius instead of Analog input counts.
  • Create a custom tool layout appropriate to an application. E.G. a Viewer layout showing the motion axes and I/O with the exact detail needed to see the state of the application "at-a-glance".

If the reader is unfamiliar with XML, please take a moment to review the great introduction from w3schools.

The XML files are automatically created by GDK when they don't exist. The files are easily accessible from within the application.

  1. In GDK's main options menu, open the settings directory by clicking Settings... and then click the Files button.
  2. Open the xml subdirectory to view the files.

GDK's installer will automatically write over old XML files, so it is important to keep a copy of any modifications so that they can be restored after an install.

On Windows, the installer will make a backup of the XML directory present upon install. The old XML files will be in a directory called xml_backup.

To return the XML to default, delete them and restart GDK. See Restoring Defaults for instructions.

Content Filtering

In order to match the XML to a particular product, GDK uses a filtering mechanism. The attributes key and i are used to filter any XML element.

The special names discussed below can be found by connecting the Setup tool to a controller and clicking the Read from Hardware button while holding the alt key. Several extra fields will be printed in the Info tab.

The key attribute is used to filter content by the product key, e.g. DMC40_0. If the key attribute is present in an element, the controller's product key must be in the list of product keys to be included. If a controller's product key is not in the list, the element and all child elements are ignored when used by GDK. The following is an example of an XML element that would be ignored for all products except the DMC-18x6.

<shift key="DMC18_6">-4</shift>
  

The i attribute is used to filter content by special tokens which describe various hardware configurations. If the i attribute appears in an element, all of the tokens in the attribute must be present in the controller's tokens. If there are tokens in the i attribute that are not present in the controller's configuration, the element and all child elements are ignored when used by GDK. The following are some examples of i tokens.

TokenMeaning
BHardware has a B axis
THardware has a T vector plane
I2Hardware has input bank 2
O3Hardware has output bank 3
I12BHardware has 12 bit Analog inputs
O16BHardware has 16 bit Analog outputs
ENCHardware has optional encoder inputs

The following is an example of a data record field that would only occur on a controller with a B axis.

<f i="B" s="TA11"><d>Hall Error</d><o>54</o><t>2</t></f>
  

Because elements that do not meet the filtering criteria are ignored, including all child elements, it can be useful to group elements under a parent filter element. The XML element <nul> is reserved for this purpose. It means nothing itself, but GDK will parse the i and key attributes as with any other element. The following is an example of grouping elements. The Encoder Channels will only be present for hardware that has the ENC token.

<nul i="ENC">
  <f s="_QE0"><d>Encoder Channel 0</d><o>56</o><t>206</t></f>
  <f s="_QE1"><d>Encoder Channel 1</d><o>60</o><t>206</t></f>
  <f s="_QE2"><d>Encoder Channel 2</d><o>64</o><t>206</t></f>
  <f s="_QE3"><d>Encoder Channel 3</d><o>68</o><t>206</t></f>
</nul>
  

The Files

The XML content is broken up into several files.

  • record.xml

    Defines the decoding of the binary controller data record for tools like the Viewer and Scope.

  • dmc.xml

    Defines the DMC programming language for syntax highlighting and parsing.

  • viewer.xml

    Customized views of the data record for rendering in the Viewer tool.

  • setup.xml

    Defines parameters for backup in the Setup tool. Details coming soon.

  • tuner.xml

    Defines tuning layout and available tuners for the Tuner tool. Details coming soon.