Generic Gateway Description File

Generic Gateway Description File

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

This static file is referred to as Generic Gateway Description File or GGDF

URL to GGDF

Here follows three examples of possible URLs to a GGDF:

1. localhost:1880/genericgateway/json
2. https://company.eu/genericgateway/json
3. http://192.168.1.1/thegatewayfile

The URL to the GGDF is set from realKNX main UI, top left icon.

If you want to store the GGDF on another system, then copy the file to that system and set the URL as in example 2 & 3. If you want to store the GGDF on this system (localhost, as in the first example), you can inject with the Inject Node in file situated in Snips flow v7 Node-RED(picture below).

IMPORTANT NOTE: After modifying the GGDF you might want to Inject any new names to Snips. If you don’t Inject, then Snips might not understand non-standard room or device names. You can initiate a Snips Inject from the realKNX Snips dialog ‘Restart Snips’ button.

Generating a GGDF

This is the format and content of GGDF(in JSON). ‘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.

To get a full exemple of the Description File, click here.

How does this description file works ?

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. It could be a URL, part of a URL or an MQTT topic.
   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.

Creating a Communication Module

In this part, we’ll explain how to implement the Gateway Communication code. There are two types of requests, hence two handlers:

1. Query – to GET a value
2. Command – to SET a value

If the Gateway communication module uses a Web API (http), you can re-use the sample flow we provide (download it here: Generic Gateway for Snips with proServ, Jung SVS and Gira X1). You will need to adapt it by changing SET URL node.

Query

This handler is called when the Snips application needs to get the current value of a device (temperature, brightness, shutters position, sensors etc.). It receives an array of device queries as input.

This input is a list of object queries from the description file you provided. The command name as well as the UID are defined by you in the GGDF. The array can contain one object or more depending on the question from the user.

For example, if the user said Hey Snips, what is the status of the ceiling in home cinema. Then, this type of input (type Object) will be received by the QUERY HOOK IN.

[{
       "name": "CurrentState",
       "uid": "386",
       "valueMin": false,
       "valueMax": true
}]

Example 2, Hey Snips, what is the status of the ceiling in home cinema, then this type of input (type Object) will be received by the QUERY HOOK IN.

[{
        "name":"CurrentState",
        "uid":"386",
        "valueMin":false,
        "valueMax":true
},{
      "name":"CurrentBrightness",
      "uid":"390",
      "valueMin":0,
      "valueMax":255
}]

Before sending out the response from the gateway server to the link out of Query, you should put it in an Object format that can be read by realKNX.

Sample output to send (type Object):

[{
     "Data": [{
         "Value": false,
         "uid": "386"
      }],
      "Result": true
}, {
      "Data": [{
          "Value": 46.3,
          "uid": "390"
      }],
      "Result": true
}]

If the server doesn’t respond correctly, you should put false in “Result” like this example:

[{
      "Result": false
      "messageError": "The server is offline"
}]

The messageError is optional. If you didn’t set the messageError, then the default message error will be

English: “The server did not answer correctly”.

French: “Le serveur n’a pas répondu correctement”.

German: “Der Server hat nicht korrekt reagiert”.

You can get the current language used in variable msg.cmd.lang.

Command

This handler is called to get the current value of the device (on, off, decrease, set etc.). The link in node of the Command is also connected to Snips application. It receives commands of devices as input. The array can contain one object or more depending on the commands from the user. If the user precisely asking to turn on the table in a room, then, only one object command will be received by the COMMAND HOOK IN. Else, if the user asking to turn on the lights in a room (imprecisely), then HOOK IN will receive turn on object command from each lights in the room.

[{
      "name":"On",
      "uid":"385",
      "value":1
   },{
      "uid":"On",      
      "name":"389",
      "value":255
      "description":"Turn on ceiling in Home Cinema"
}]

This input is a list of object command from the description list you provided.

Before send out the response from the gateway server to the link out of Command, you should put it in an Object format that can be read by realKNX.

Sample output to send (type Object):

[{
      "Result":true
}]

[{
     "Result":false
     "messageError": "The server is offline"
}]

True is when the server respond correctly, otherwise, Result is false

The messageError is optional. If you didn’t set the messageError, then the error message will be by default.

Demonstration

This demonstration shows how the communication works (we use our sample ProKNX gateway as example).