node-red-contrib-gira-rest

Node-RED node for Gira X1/Gira HomeServer REST API

Install

To install the stable version use the Menu - Manage palette - Install option and search for node-red-contrib-gira-rest, or run the following command in your Node-RED user directory, typically ~/.node-red

npm install node-red-contrib-gira-rest

Status of the project

This project is highly beta at the moment. The basic functionality is implemented. No heavy quirks in sight and basic error checking is implemented, too. Help and description in the editor is missing at the moment, but on the list!

About Gira REST API & unique identifiers (UIDs)

Details about the Gira RESTful API are available here. For the interaction with node-red-contrib-gira-rest it's important to know that the Gira API implements the concept of unique identifiers (UIDs). UIDs are four-chars long strings representing one (or a set of) datapoints of the Gira X1/Gira HomeServer.

The API function 'GiraAPI_GetUIconfig' is used to get the whole user interface configuraton from the device. This function is implemented in the gira-host (configuration) node for the use in future versions. At the moment can get the whole UIconfiguration as a JSON-object by using the gira-get node (see below).

As an example for this documentation I use the UID a00v. The example UIconfig look like:

{
    "functions": [
        {
            "channelType": "de.gira.schema.channels.KNX.Dimmer",
            "dataPoints": [
                {
                    "canEvent": true,
                    "canRead": true,
                    "canWrite": true,
                    "name": "OnOff",
                    "uid": "a00t"
                },
                {
                    "canEvent": true,
                    "canRead": true,
                    "canWrite": true,
                    "name": "Shift",
                    "uid": "a00u"
                },
                {
                    "canEvent": true,
                    "canRead": true,
                    "canWrite": true,
                    "name": "Brightness",
                    "uid": "a00v"
                }
            ],
            "displayName": "LED Fette",
            "functionType": "de.gira.schema.functions.KNX.Light",
            "parameters": [
                {
                    "key": "ButtonTimeout",
                    "set": "Visu",
                    "value": "0.4"
                },
                {
                    "key": "DefaultShift",
                    "set": "Visu",
                    "value": "10"
                },
                {
                    "key": "OffText",
                    "set": "Visu",
                    "value": "Aus"
                },
                {
                    "key": "OnText",
                    "set": "Visu",
                    "value": "Ein"
                },
                {
                    "key": "ShowOnHomeScreen",
                    "set": "Visu",
                    "value": "False"
                },
                {
                    "key": "ShowStatus",
                    "set": "Visu",
                    "value": "True"
                },
                {
                    "key": "ShowTimer",
                    "set": "Visu",
                    "value": "True"
                }
            ],
            "uid": "a00s"
        }
    ],
    "uid": "a08k"
}

Nodes

gira-host - Configuration of the API endpoint

All nodes share a common configuration node (gira-host) with the following properties:

• Host URL - This is the https-only URL of the Gira REST API endpoint. Usualy this points to the domainname or the IP-address of the Gira X1 or Gira HomeServer.
• Callback URL - The https-only URL of the Node-Red instance, where the callback service of the node is accessible for the Gira X1 or Gira HomeServer. The callback is used for emitting events from the Gira X1 or Gira HomeServer to the node. This can be the Node-Red web server itself with an SSL certificate. However, a reverse proxy server is more preferable (nginx, Træfik, et al.). The HTTP callback is using RED.httpNode. To avoid conflicts with other nodes, it's using an URL path like /node-red-contrib-gira-rest/{ ID of the gira-host node }/service'. For security reasons the callback service expects the token issued by the Gira REST API after first registration of the client in the JSON-object in the body of the request.
• Username - The username for accessing the Gira REST API.
• Password - The password for accessing the Gira REST API.
• Name - The usual Node-Red name property.

gira-get

With the gira-get node it's possible to get a value from the API. There are two ways to tell the node which UIDs to request from the API and to emit as a message:

1. You can set the UID in the configuration dialog.

2. You can set the UID in msg.payload, if it's not set in the configuration dialog.

The node may return something like:

{
    "values":
    [
        {"uid":"a00v","value":"0"}
    ]
}

If you request UIDs with multiple datapoints (e.g. a00s in the example configuration above), the response would be populated with multiple uids and the corresponding values.

gira-set

With the gira-set node it's possible to set one or multiple values using the API. There are three ways to tell the node which UIDs to set:

1. You can set one or multiples UIDs by sending a JSON-object as msg.payload as follows:

{
    "values": 
    [
        {
            "uid": "a00v",
            "value": 0
        }
    ]
}

If you emit a JSON-object with the primary key values, the UID in the configuration dialog of the node is overruled.

2. You can set the UID as msg.topic. If it's set to a four-character long string, the UID in the configuration dialog of the node is overruled.

3. You can set the UID in the configuration dialog. In this case you can set the value in msg.payload.

gira-event

The gira-event node is simple to use. It emits all events received by the Gira REST API service callback & value callback. A usual msg.payload looks like:

{
    "events":
    [
        {
            "uid":"a05d",
            "value":"22"
        }
    ],
    "failures":0
}

There are some special events desrcibed in chapter 4.6 of the Gira REST API documentation. Most notably is the event uiConfigChanged. This event notifies the API client about a change of the internal user interface configuration of the Gira X1/Gira HomeServer. If this event gets fired, the gira-host node updates it's internal uiconfig object.

Example

Todos

• [x] ~~Add comprehensive information to the README.md~~
• [x] ~~Add node.debug and node.trace debugging~~
• [ ] Migrate from request to something other...
• [ ] Add helpful information to the configuration of the nodes in the editor
• [ ] Utilize uiconfig object for the configuration of the node (TreeView, Dropdowns, et al.)
• [ ] Considerate using information from uiconfig for the gira-event and gira-get output to msg.payload

Licensing

node-red-contrib-gira-rest is licensed under GNU General Public License v3.

Donate

I developed this set of nodes for my personal learning experience and use in my smart home. They are probably far from being perfect and probably are not even good examples of how to develop custom nodes for Node-Red. Therefore, I do not ask for money, but I hope that others will contribute and remove my mistakes. But if you absolutely want to send an attention to me, then I do like an invite for a coffee (or mostly tea at the moment)...