KNXController

From ago control wiki
Jump to: navigation, search

Contents

Introduction

All KNX networks need to be programmed with a Windows application called ETS. The ETS software can be downloaded from the KNX.org website. ETS is used to configure each KNX device, to program logic information into KNX devices, and to provide identification information called *group addreses*. The group address is a unique identification not to a single device, but to a single device action, a single device value etc. Everything in KNX can be accessed by using GAs. This page defines briefly how GAs are organized, and how those GAs should more easily be imported and managed in agocontrol.

ETS Group Addresses

Structure

Logical level addressing on the KNX side works with group addresses (GA). They're usually grouped by main and middle number (separated with '/'). A possible GA could look like this: 4/1/15

A possible tree in ETS could look like this:

ETS-GA-structure.png

In this example we're using the main (first) part of the GA for the room and the second part for identifying the type (lighting, shutters, sensors, ..). This is not mandatory, one can create whatever preferred structure (e.g. using the main part for the building or floor number, and so on).

Mapping to an agocontrol device

So for one light switch in KNX, we usually use two group addresses. One to turn it on and off. The switch will then send the current status to the second GA. Local changes (operating the switch manually) will also trigger telegrams to the status GA.

- 2 Office
-- 2/0 Light
--- 2/0/0 Ceiling - On/Off
--- 2/0/1 Ceiling - Status

Dimmers have two more GAs. One to set a dimming level, and one to report the dimming level back. Agocontrol needs to know which GAs to use when translating qpid commands to KNX telegrams. Hence the internal device map needs to store the relevant GAs. The internal entry for a dimmer does look like this:

   "5a1b7c2b-6c24-4442-a5bc-b6c077494d03": {
        "devicetype": "dimmer",
        "levelstatus": "4/0/3",
        "onoff": "4/0/0",
        "onoffstatus": "4/0/1",
        "setlevel": "4/0/4"
}

Wizard functionality

The KNX Wizard should allow the following:

Import ETS GA export

The ETS application can export the whole KNX project stored on the Windows machine into a XML file.

User should be able to specify a local ETS XML GA Export file. Wizard will send the file contents as qpid command to the knxcontroller device, command "parseetsexport" with the parameter "etsdata", which hold the XML file contents. The knxcontroller will deliver a map within the reply data, named "groupmap". This will hold the structure from the above picture in JSON format:

"Office":{
    "Appliance":{
        "Outlet Desktop - On/Off":"2/5/0",
        "Outlet Desktop - Status":"2/5/1"
    },
    "Light":{
        "Ceiling - On/Off":"2/0/0",
        "Ceiling - Status":"2/0/1"
    },
    "Blinds":{
        "West window - Up/Down":"2/1/0",
        "West window - Go To Position":"2/1/3",
        "West window - Position Status":"2/1/4",
        "West window - Direction Status":"2/1/2",
        "West window - Stop":"2/1/1"
    }
},
"Bathroom":{
    "Heating":{
        "Towerheater - On/Off":"7/3/0",
        "Towelheater - Status":"7/3/1"
    },
    "Light":{
        "Ceiling - On/Off":"7/0/0",
        "Ceiling - Status":"7/0/1",
        "Mirror - On/Off":"7/0/2",
        "Mirror - Status":"7/0/3"
    }
},

Create a new KNX device

The user should be able to create a new KNX device inside agocontrol by specifying the device type (light, blinds etc), and assigning the respective GAs from the ETS export to the new device. E.g. when creating a light switch, the following steps would be done:

  • Import the GA Export from ETS in the wizard, this will be shown as a collapsable tree
  • Specify to create a new device
  • Select the device type for the new device
  • Drag and drop (?) the proper GA from the tree to the new device fields, "onoff" and "onoffstatus" in this switch example
  • Save the new device (it would be great if a name - and maybe room - could be specified here already)

Delete or edit a KNX device

Existing agocontrol KNX devices should be modifiable and deleteable.

A list of the existing KNX devices should be shown, with a detail button to change or view the GA assignments, and a delete button to remove the device

Information regarding possible GA assignments

The information can be found in the agocontrol schema. It is located in the "internal" section of the knxcontroller:

[...]
devicetypes:
  knxcontroller:
    name: KNX controller
    description: internal device to manage the KNX configuration
    commands: [adddevice, getdevice, deldevice, parseetsexport]
    internal:
      groupaddresstypes:
        onoff:
          name: 1 bit on/off
        onoffstatus:
          name: 1 bit status
        binary:
          name: binary
        levelstatus:
          name: level status
        setlevel:
          name: set level
        stop:
          name: stop
        temperature:
          name: temperature
        brightness:
          name: brightness
        energy:
          name: energy
      childdevices:
        switch: [onoff, onoffstatus]
        dimmer: [onoff, onoffstatus, setlevel, levelstatus]
        drapes: [onoff, onoffstatus, setlevel, levelstatus, stop]
        binarysensor: [binary]
        brightnesssensor: [brightness]
        temperaturesensor: [temperature]
        powermeter: [energy]
[...]

KNX Controller examples

Fetch map for a specific device

# /opt/agocontrol/bin/messagesend uuid=40820aa5-7d69-4541-b3eb-dcf0374e8520 command=getdevice device=3b933ba8-22d6-4894-9a02-57711d317e02
Sending message: {command:getdevice, device:3b933ba8-22d6-4894-9a02-57711d317e02, uuid:40820aa5-7d69-4541-b3eb-dcf0374e8520}
Reply: {_newresponse:True, result:{data:{device:3b933ba8-22d6-4894-9a02-57711d317e02, devicemap:{devicetype:switch, onoff:4/5/0, onoffstatus:4/5/1}}, identifier:success}}

create device

JSON-RPC command to create a devce with the command "adddevice" and the device map for a switch as parameter "devicemap":

{"method":"message","params":{"content":{"command":"adddevice","uuid":"40820aa5-7d69-4541-b3eb-dcf0374e8520","devicemap":{"devicetype":"switch","onoff":"6/6/6","onoffstatus":"6/6/7"}}},"id":2,"jsonrpc":"2.0"}

Reply:

{"jsonrpc": "2.0", "result": {"data":{"device":"40820aa5-7d69-4541-b3eb-dcf0374e8520"},"identifier":"success"}, "_temp_newstyle_response":true, "id": 2

Delete device

Deleting a device via messagesend. Command "deldevice" with device uuid as parameter "device" (agoknx uses the global uuid as internal id)

~# /opt/agocontrol/bin/messagesend uuid=40820aa5-7d69-4541-b3eb-dcf0374e8520 command=deldevice device=3b933ba8-22d6-4894-9a02-57711d317e02
Sending message: {command:deldevice, device:3b933ba8-22d6-4894-9a02-57711d317e02, uuid:40820aa5-7d69-4541-b3eb-dcf0374e8520}
Reply: {_newresponse:True, result:{identifier:success}}

Complete agoknx internal map, for reference

This shows how agoknx stores the internal device map:

# cat /etc/opt/agocontrol/maps/knx.json | python -m json.tool
{
    "084ecee8-a60c-4ec0-8347-2e7fc3ec15b8": {
        "devicetype": "binarysensor",
        "levelstatus": "4/4/0"
    },
    "0962f27e-99ce-43a4-872b-97d75d61f464": {
        "devicetype": "dimmer",
        "levelstatus": "1/0/6",
        "onoff": "1/0/0",
        "onoffstatus": "1/0/1",
        "setlevel": "1/0/7"
    },
    "0d69e759-d459-4431-87fb-be068bb0cc16": {
        "devicetype": "drapes",
        "levelstatus": "5/1/4",
        "onoff": "5/1/0",
        "setlevel": "5/1/3",
        "stop": "5/1/1"
    },
    "11743e6e-ed1e-4a3b-8a92-ba5873c716b0": {
        "devicetype": "switch",
        "onoff": "1/0/19"
    },
    "17c4f855-7c6a-46d5-acf6-1e5c9ae367e7": {
        "devicetype": "switch",
        "onoff": "6/0/0",
        "onoffstatus": "6/0/1"
    },
    "22bf1714-fb33-4bd6-a79a-736898e4eb82": {
        "devicetype": "switch",
        "onoff": "2/5/0",
        "onoffstatus": "2/5/1"
    },
    "26e1cb96-8585-4f43-aec4-d0935a32c188": {
        "binary": "1/4/2",
        "devicetype": "binarysensor"
    },
    "2db31059-43f2-4687-8730-ca2591892cbd": {
        "devicetype": "temperaturesensor",
        "temperature": "1/4/14"
    },
    "349289c5-b254-4480-af90-4548cbcdda9d": {
        "devicetype": "switch",
        "onoff": "7/0/0",
        "onoffstatus": "7/0/1"
    },
    "3887ac29-8f58-43dd-8c5f-36c0b3507f4e": {
        "devicetype": "switch",
        "onoff": "1/0/15"
    },
    "3b933ba8-22d6-4894-9a02-57711d317e02": {
        "devicetype": "switch",
        "onoff": "4/5/0",
        "onoffstatus": "4/5/1"
    },
    "47ad756e-c5f6-4c9f-acca-cc4d9148e538": {
        "devicetype": "drapes",
        "levelstatus": "3/1/4",
        "onoff": "3/1/0",
        "setlevel": "3/1/3",
        "stop": "3/1/1"
    },
    "4b4a46f6-993f-49b6-868d-0b2b77b1af2a": {
        "devicetype": "switch",
        "onoff": "1/0/20"
    },
    "4fe0477e-0732-4080-8595-a6a4b68a7aa9": {
        "devicetype": "binarysensor",
        "levelstatus": "1/4/17"
    },
    "54539af0-a871-4883-bf8f-eb3fa24d63ab": {
        "devicetype": "binarysensor",
        "levelstatus": "5/4/0"
    },
    "5a1b7c2b-6c24-4442-a5bc-b6c077494d03": {
        "devicetype": "dimmer",
        "levelstatus": "4/0/3",
        "onoff": "4/0/0",
        "onoffstatus": "4/0/1",
        "setlevel": "4/0/4"
    },
    "5bb6e858-aeec-47bb-8144-61293467cfb6": {
        "devicetype": "binarysensor",
        "levelstatus": "1/4/20"
    },
    "5e4c10c2-05ab-46eb-ad9d-4dc39f4d4913": {
        "devicetype": "switch",
        "onoff": "0/5/0",
        "onoffstatus": "0/5/1"
    },
    "5e4c1ac2-55ab-46eb-dd9d-4dc39f4d4914": {
        "devicetype": "switch",
        "onoff": "0/5/4",
        "onoffstatus": "0/5/5"
    },
    "6a46bea3-3325-4ea3-8168-65b357572b5c": {
        "devicetype": "switch",
        "onoff": "9/0/0",
        "onoffstatus": "9/0/1"
    },
    "730dd18b-15f2-4997-a033-e16ed08f40d2": {
        "devicetype": "switch",
        "onoff": "7/0/2",
        "onoffstatus": "7/0/3"
    },
    "76a633b2-0f2b-426b-91a9-860ecb1e5d20": {
        "devicetype": "switch",
        "onoff": "1/0/18"
    },
    "7b51fae3-b872-4f03-82c4-d96f6a27a560": {
        "devicetype": "switch",
        "onoff": "8/0/0",
        "onoffstatus": "8/0/1"
    },
    "86edff75-5e0a-4618-b9e7-294c9b21f7df": {
        "devicetype": "switch",
        "onoff": "1/0/21"
    },
    "88313953-f3e9-4e15-8d1d-e7533ba324df": {
        "binary": "1/4/3",
        "devicetype": "binarysensor"
    },
    "8892b260-0aff-444d-8a80-a2fd42c941ee": {
        "devicetype": "drapes",
        "levelstatus": "4/1/4",
        "onoff": "4/1/0",
        "setlevel": "4/1/3",
        "stop": "4/1/1"
    },
    "8a042031-785b-4336-827c-ab192be8fdff": {
        "devicetype": "powermeter",
        "energy": "0/4/0"
    },
    "99044e96-cce3-4d03-af70-3e0ea7a0c652": {
        "devicetype": "switch",
        "onoff": "2/0/0",
        "onoffstatus": "2/0/1"
    },
    "995104a1-11ba-4116-bd75-957e4dbaf628": {
        "devicetype": "switch",
        "onoff": "1/0/4"
    },
    "a8d8a6da-097d-40f1-a655-9bb917e7d491": {
        "binary": "1/4/0",
        "devicetype": "binarysensor"
    },
    "aa489957-a0dd-4862-9ed5-8d713a24f766": {
        "devicetype": "dimmer",
        "levelstatus": "5/0/3",
        "onoff": "5/0/0",
        "onoffstatus": "5/0/1",
        "setlevel": "5/0/4"
    },
    "b3eec103-ba9f-4ae1-965f-14c1e988b738": {
        "devicetype": "drapes",
        "levelstatus": "2/1/4",
        "onoff": "2/1/0",
        "setlevel": "2/1/3",
        "stop": "2/1/1"
    },
    "becc82e2-2738-4c43-bdaf-d61cc74782d1": {
        "devicetype": "switch",
        "onoff": "4/0/5",
        "onoffstatus": "4/0/6"
    },
    "c29f2099-589b-4ff9-bdea-71ea94c3e9df": {
        "devicetype": "switch",
        "onoff": "3/0/0",
        "onoffstatus": "3/0/1"
    },
    "c81a868e-e3da-418a-9f4e-fbfa30dfdcb9": {
        "devicetype": "switch",
        "onoff": "1/0/2",
        "onoffstatus": "1/0/3"
    },
    "c81e979c-46e6-4b14-ac06-b53f912193c3": {
        "devicetype": "binarysensor",
        "levelstatus": "1/4/19"
    },
    "ce76f3ef-7158-4cd0-b700-b82f91cab0ea": {
        "binary": "1/4/10",
        "devicetype": "binarysensor"
    },
    "d125dd30-2272-442f-9d9a-17d3ef4d8e7c": {
        "brightness": "1/4/9",
        "devicetype": "brightnesssensor"
    },
    "de2db24c-88de-448d-9798-11966c8c1cdc": {
        "devicetype": "drapes",
        "levelstatus": "4/1/14",
        "onoff": "4/1/10",
        "setlevel": "4/1/13",
        "stop": "4/1/11"
    },
    "ef6a6b73-4422-42bc-9e4d-82936ef045fe": {
        "devicetype": "binarysensor",
        "levelstatus": "1/4/19"
    },
    "efe76637-256d-4ca3-acff-0c082518660b": {
        "binary": "1/4/8",
        "devicetype": "binarysensor"
    },
    "f047fdc7-e4ce-4384-ab7d-bfd6447858e0": {
        "binary": "0/4/3",
        "devicetype": "binarysensor"
    },
    "f0b9aa64-bcac-4000-a379-5832a00db81b": {
        "devicetype": "switch",
        "onoff": "7/3/0",
        "onoffstatus": "7/3/1"
    },
    "f8792db5-a046-4bb4-8355-7afc4ad977f2": {
        "devicetype": "switch",
        "onoff": "4/5/4",
        "onoffstatus": "4/5/5"
    },
    "fb21788d-6da3-4fc7-a348-a47508b24b6c": {
        "devicetype": "switch",
        "onoff": "0/6/16"
    }
}
Personal tools