Gateway Description File for KNX all-compatible

The following information is relevant for the Aragon Base /realKNX Air & O-two with the “KNX all-compatible” communication module.

Introduction

As opposed to the Dynamic Gateways (proServ, Jung, Gira etc) the KNX-all Gateway is defined by a static file. The ‘Dynamic’ Gateways supports reading metadata (rooms, devices etc). The ‘Static’ KNX-all Gateway doesn’t support metadata, instead a static file is used.

This static file is referred to as Gateway Description File or GDF.

We suggest you use a credible text editor for developers and programmers. If you’re working from Windows, Notepad++ is a good choice.

As an alternative, to a text editor you can use the Visual Editor for the GDF (Beta), see below.

Getting started

Open Automation / Node-RED. In the flow, you’ll find a few nodes for the KNX Description file. Double click your language to edit the content.

IMPORTANT NOTE: After modifying the GDF you might need to inject any new non-standard names to Snips. If you don’t inject, then the non-standard words will not be understood. You can initiate the inject operation from the realKNX Snips dialog ‘Restart Snips’ button.

The format of the GDF

The format of the GDF is JSON. The single top-level object ‘functions’ is an array of objects. All properties and values in red are MANDATORY, blue are RECOMMENDED, black are EDITABLE VALUE and green is OPTIONAL.

Here follows a generic example:

To get a full example of a GDF for KNX all-compatible, click here.

What are the elements of the GDF?

1. displayName: This is a required field, the value is the name of the device that the user mentioned when giving the command.
2. functionType: This is a mandatory, the value must be one of these types only

   • Type	Description
     lights	Light with only two values on and off.
     dimmers	Dimmer light. Input from the voice command will be 0 to 100. While, valueMin and valueMax will scale it proportionally.
     blinds	Roller shutters. Input from the voice command will be 0 to 100. While, valueMin and valueMax will scale it proportionally.
     heating	Thermostat, monitors the temperature in the room
     scenes	Create the scene in the room. Example: Cozy and romantic.
     sensors	Detect and return a value.
     aux	Other types of objects. Can’t get the value, can only set value.

3. zone: This is also a required field, contain the name of the room that user mentioned.
4. commands: This is an array of objects of the device commands.
   1. name of the commands is mandatory and must not be modified.
   2. value is mandatory IF it’s not defined by the voice command, it is the value that will be sent to the gateway.
   3. Uid is recommended. It is a unique reference to the device. You can call it anything
   4. description or other properties are optional. If needed, you can add more than one.
5. currentState: This is an array of objects of the device state (usually they have only one state. For type heating, there are two current states)
   1. name of the current state is mandatory and must not be modified
   2. valueMax and valueMin are mandatory. These values are required to determine the current state of the device (On, off and percentage).
      1. In type lights, minValue = off value and maxValue = on value
      2. In type blinds, minValue = open blinds and maxValue = close blinds
   3. description or other properties are optional. If needed, you can add more than one.

This table shows the name of the mandatory objects in commands and currentStates array according to type of device.

Visual Editor for GDF (Beta)

Instead of using a text editor, you can use the Visual Editor for GDF. Note that it is still in Beta and some features are missing.

Follow these steps:

1. Open Definition File for Visual GDF Editor (opens in a new window)
2. Save the page as a JSON file (default: visual-editor-gdf.json)
3. Navigate to : https://pmk65.github.io/jedemov2/dist/demo.html
4. Select Reset Form
5. Select Upload and import the JSON file
6. In the output tab, you will have an empty GDF
7. If you already have a GDF that you wish to modify:
   • clear the Output tab and copy & paste the content of the GDF into the Output tab
   • Switch to the Form tab to see the content in Visual presentation
8. If you don’t have a GDF, then either copy the sample KNX all-compatible or simply start from scratch, visually in the Form tab and by text int he Output tab.
9. At any time, switch between the Output and Form tabs.
10. Copy the content of the Output tab and save as your Gateway Description File. Copy and Paste to the Node-RED node.

Known limitations in Beta Version (2020-03-21)

• Restrict the possible command and states for each function – feature missing
• dpt type should be suggested – feature missing
• in the non-collapsed view, the room and command names should be visible- feature missing
• scene number not possible to edit – bug