Skip to main content
Version: 1.0

KNX

caution

Available as preview since 1.4.0-beta1. The API is subject to change.

note

Available only for Gen3 and Gen2 Pro* devices.

Overview​

KNX integration enables Shelly devices to become part of KNX installations and expose selected Shelly functionality to KNX automations. KNX enabled Shelly devices allow selected Shelly components to be controlled from the KNX installation and also provide information or control it. In the first release supported are Input, Light and Switch components. Configuration of these components is extended to include KNX specific settings which enable certain KNX functionality and there is a global KNX component responsible for common configuration and functionality.

KNXIP/Routing is used to connect to KNX installations and existence of KNXIP router connected to the network of a Shelly device network interface is assumed. The router is automatically discovered if present and is required for Shelly KNX functionality to work. KNXIP/Tunneling is not supported.

The management is accomplished through RPC methods within the KNX namespace:

Methods​

KNX.GetConfig​

Find more about the global component's config properties in its config section

KNX.SetConfig​

Parameters:

PropertyTypeDescription

config

object

General KNX configuration

Find more about the global component's config properties in its config section

KNX.GetStatus​

The global KNX component does not have status at the moment.

KNX.GetComponentConfig​

Request​

Parameters:

PropertyTypeDescription

key

string

Key of the related Shelly component. (in format <type>:<cid>, for example input:0)

Response​

This method returns KNX configuration specific for the Shelly component type, Including current KNX revision.

Find more about KNX Input configuration properties in the corresponding config section
Find more about KNX Input operation in the corresponding functionality section

Find more about KNX Light configuration properties in the corresponding config section
Find more about KNX Light operation in the corresponding functionality section

Find more about KNX Switch configuration properties in the corresponding config section
Find more about KNX Switch operation in the corresponding functionality section

KNX.SetComponentConfig​

Request​

Parameters:

PropertyTypeDescription

key

string

Key of the related Shelly component. (in format <type>:<cid>, for example input:0)

config

object

KNX configuration for the related Shelly component specific to its type

Response​

This method will validate and update correpsonding KNX configuration. It will return an error if the supplied config object fails validation or the update fails and a JSON object containing the updated KNX revision on success.

Find more about KNX Input configuration properties in the corresponding config section
Find more about KNX Input operation in the corresponding functionality section

Find more about KNX Light configuration properties in the corresponding config section
Find more about KNX Light operation in the corresponding functionality section

Find more about KNX Switch configuration properties in the corresponding config section
Find more about KNX Switch operation in the corresponding functionality section

KNX.ListComponents​

Request​

Parameters:

PropertyTypeDescription

offset

number

Starting index of the element in the paginated repsonse list. Optional, default 0

Response​

This method will return the current KNX revision and the list of available on the device KNX configurations.

note

KNX component methods are available when the KNX enable flag is set in the global configuration.

note

A global KNX revision is maintained, which is incremented on each change of KNX configuration and is included in the status of the System component, status change events are also triggered. All KNX component methods include this revision number in the response.

Configuration​

Properties:

PropertyTypeDescription

enable

boolean

Global KNX enable flag, initially false. Changing it requires restart. When enabled and after restart default KNX configuration for relevant components is created and KNX functionality becomes available.

ia

string

KNX individual address applicable to all available KNX components. Defaults to the reserved address 15.15.255 and must be changed when enabling KNX. Specified value must be unique for the KNX installation.

routing

object

KNXIP/Routing properties

PropertyTypeDescription

adrr

string

Multicast address and port specified as IP:port. Defaults to the reserved by KNX default multicast address and port (224.0.23.12:3671). Valid multicast address must be specified, set to null to restore default. Changing this property requires restart.

Status​

The global KNX component does not have status at the moment.

Examples​

KNX.GetConfig example​

http://192.168.33.1/rpc/KNX.GetConfig

Response

{
  "enable": true,
  "ia": "1.1.9",
  "routing": {
    "addr": "224.0.23.12:3671"
  }
}

KNX.SetConfig example​

http://192.168.33.1/rpc/KNX.SetConfig?config={"enable":true}

Response

{
  "restart_required": true
}

KNX.GetStatus example​

http://192.168.33.1/rpc/KNX.GetStatus

Response

{}

KNX.GetComponentConfig example​

http://192.168.33.1/rpc/KNX.GetComponentConfig?key="switch:0"

Response

{
  "rev": 36,
  "config": {
    "key": "switch:0",
    "cmd": {
      "control": [
        "1/1/4"
      ]
    },
    "fb": {
      "status": [
        "1/2/4"
      ],
      "apower": [
        "1/6/10"
      ],
      "current": [
        "1/6/11"
      ],
      "voltage": [
        "1/6/12"
      ],
      "ret_energy": [
        "1/6/13"
      ],
      "aenergy": [
        "1/6/14"
      ]
    }
  }
}

KNX.SetComponentConfig example​

http://192.168.33.1/rpc/KNX.SetComponentConfig?key="switch:0"&config={}

Response

{
  "rev": 13,
  "restart_required": false
}

KNX.ListComponents example​

http://192.168.33.1/rpc/KNX.ListComponents?

Response

{
  "rev": 11,
  "offset": 0,
  "total": 3,
  "components": [
    {
      "key": "input:0",
      "mode": "btn_single_dim",
      "sw_toggle": {
        "fb_status": null
      },
      "btn_dual_dim": {
        "fb_state": null,
        "fb_dim": null,
        "dir": "down",
        "step": 1
      },
      "btn_single_dim": {
        "fb_state": null,
        "fb_dim": null,
        "cmd_state": null,
        "step": 1
      },
      "btn_normal": {
        "command": "toggle",
        "fb_state": null,
        "cmd_state": null
      },
      "btn_extended": {
        "cmd_state": null,
        "single_push": {
          "fb": null,
          "type": "command",
          "command": "none",
          "percent": 0,
          "ratio": 0,
          "scene": 0
        },
        "double_push": {
          "fb": null,
          "type": "command",
          "command": "none",
          "percent": 0,
          "ratio": 0,
          "scene": 0
        },
        "triple_push": {
          "fb": null,
          "type": "command",
          "command": "none",
          "percent": 0,
          "ratio": 0,
          "scene": 0
        },
        "long_push": {
          "fb": null,
          "type": "command",
          "command": "none",
          "percent": 0,
          "ratio": 0,
          "scene": 0
        }
      }
    },
    {
      "key": "input:1",
      "mode": "btn_normal",
      "sw_toggle": {
        "fb_status": null
      },
      "btn_dual_dim": {
        "fb_state": null,
        "fb_dim": null,
        "dir": "down",
        "step": 1
      },
      "btn_single_dim": {
        "fb_state": null,
        "fb_dim": null,
        "cmd_state": null,
        "step": 1
      },
      "btn_normal": {
        "command": "on",
        "fb_state": [
          "1/1/6"
        ],
        "cmd_state": null
      },
      "btn_extended": {
        "cmd_state": null,
        "single_push": {
          "fb": null,
          "type": "command",
          "command": "toggle",
          "percent": 0,
          "ratio": 0,
          "scene": 0
        },
        "double_push": {
          "fb": null,
          "type": "command",
          "command": "toggle",
          "percent": 0,
          "ratio": 0,
          "scene": 0
        },
        "triple_push": {
          "fb": null,
          "type": "command",
          "command": "toggle",
          "percent": 0,
          "ratio": 0,
          "scene": 0
        },
        "long_push": {
          "fb": null,
          "type": "command",
          "command": "toggle",
          "percent": 0,
          "ratio": 0,
          "scene": 0
        }
      }
    },
    {
      "key": "switch:0",
      "cmd": {
        "control": [
          "1/1/0"
        ]
      },
      "fb": {
        "status": [
          "1/2/0"
        ]
      }
    }
  ]
}