Homebridge SynTex KNX
A simple plugin to control KNX devices.
This plugin is made to cooperate with Homebridge: https://github.com/nfarina/homebridge
It connects to a KNX IP Gateway and offers some special tweaks.
Core Features
- IP Gateway Connection: Connect to your KNX IP Gateway trough your network.
- Device Control: View and control your KNX devices.
- HTTP Access: Update and read device states via HTTP calls.
- Automation: We integrated our powerful automation API for fast and complex automation.
Troubleshooting
-
Report
us yourIssues
-
Join
ourDiscord Server
Installation
- Install homebridge using:
sudo npm install -g homebridge
- Install this plugin using:
sudo npm install -g homebridge-syntex-knx
- Update your
config.json
file. See snippet below. - Restart the Homebridge Service with:
sudo systemctl restart homebridge; sudo journalctl -fau homebridge
Example Config
Info: If the baseDirectory
for the storage can't be created you have to do it by yourself and give it full write permissions!
-
sudo mkdir -p /var/homebridge/SynTex/
( create the directory ) -
sudo chmod -R 777 /var/homebridge/SynTex/
( permissions for many processes ) -
sudo chown -R homebridge /var/homebridge/SynTex/
( permissions only for homebridge )
"platforms": [
{
"platform": "SynTexKNX",
"baseDirectory": "/var/homebridge/SynTex",
"ip": "192.168.1.100",
"options": {
"port": 1714,
"language": "us",
"disablePreload": false
},
"log": {
"debug": false
},
"accessories": [
{
"id": "knx1",
"name": "Sensor Accessory",
"services": [
{
"address": {
"status": "1/0/0"
},
"type": "contact"
}
]
},
{
"id": "knx2",
"name": "Boolean Accessory",
"services": [
{
"address": {
"status": ["1/1/0", "1/1/1"],
"control": ["1/1/0", "1/1/1"]
},
"type": "switch"
}
]
},
{
"id": "knx3",
"name": "Dimmer Accessory",
"services": [
{
"address": {
"status": "1/1/2",
"control": "1/1/2"
},
"type": "dimmer"
}
]
},
{
"id": "knx4",
"name": "RGB Accessory",
"services": [
{
"address": {
"status": "1/1/3",
"control": "1/1/3"
},
"type": "rgb"
}
]
},
{
"id": "knx5",
"name": "Window Covering Accessory",
"services": [
{
"address": {
"status": "1/1/4",
"control": "1/1/4"
},
"delay": {
"up": 11000,
"down": 10000
},
"type": "blind",
"name": "Up / Down"
},
{
"address": {
"status": "1/1/5",
"control": "1/1/5"
},
"type": "switch",
"name": "Stop"
}
]
},
{
"id": "knx6",
"name": "Inverted Accessory",
"services": [
{
"datapoint": "1.001",
"address": {
"status": "1/0/0"
},
"type": "contact",
"inverted": true
}
]
},
{
"id": "knx7",
"name": "Multi Accessory",
"services": [
{
"address": {
"status": "1/0/0"
},
"type": "contact",
"name": "Contact"
},
{
"address": {
"status": "1/0/1"
},
"type": "humidity",
"name": "Humidity"
},
{
"address": {
"status": "1/0/2"
},
"type": "leak",
"name": "Leak"
},
{
"address": {
"status": "1/0/3"
},
"type": "light",
"name": "Light"
},
{
"address": {
"status": "1/0/4"
},
"type": "motion",
"name": "Motion"
},
{
"address": {
"status": "1/0/5"
},
"type": "occupancy",
"name": "Occupancy"
},
{
"address": {
"status": "1/0/6"
},
"type": "smoke",
"name": "Smoke"
},
{
"address": {
"status": "1/0/7"
},
"type": "temperature",
"name": "Temperature"
},
{
"address": {
"status": "1/1/1",
"control": "1/1/1"
},
"type": "led",
"name": "LED"
},
{
"address": {
"status": "1/1/1",
"control": "1/1/1"
},
"type": "outlet",
"name": "Outlet"
},
{
"address": {
"status": "1/1/1",
"control": "1/1/1"
},
"type": "switch",
"name": "Switch"
},
{
"address": {
"status": "1/1/2",
"control": "1/1/2"
},
"type": "dimmer",
"name": "Dimmer"
},
{
"address": {
"status": "1/1/3",
"control": "1/1/3"
},
"type": "rgb",
"name": "RGB"
},
{
"datapoint": "5.001",
"address": {
"status": "1/1/4",
"control": "1/1/4"
},
"delay": {
"up": 11000,
"down": 10000
},
"type": "blind",
"name": "Blind"
},
{
"datapoint": "1.001",
"address": {
"status": "1/1/1",
"control": "1/1/1"
},
"type": "switch",
"name": "Inverted Switch",
"inverted": true
}
]
}
]
}
]
Required Parameters
-
platform
is alwaysSynTexKNX
-
baseDirectory
The path where cache data is stored. -
ip
The IP address of your KNX gateway. -
accessories
For the accessory config.
Optional Parameters
-
port
To control your accessory over HTTP calls. -
language
You can use your country initials if you want to change it ( Currently supported:us
,en
,de
) -
disablePreload
Disable reading device states after reboot ( prevents the bus from overflow )
Log Parameters
- Disable certain log level:
error
,warn
,info
,read
,update
,success
anddebug
( for exampledebug: false
)
Accessory Config
- Every accessory needs these parameters:
id
,name
andservices
( required ) -
id
has to be either aphysical group address
or anotherrandom unique text
( no duplicates! ) -
name
could be anything. -
services
The services of your accessory.
-
name
could be anything. -
type
Define the service type (blind
,contact
,dimmer
,humidity
,leak
,led
,light
,motion
,occupancy
,outlet
,rain
,relais
,rgb
,smoke
,switch
,temperature
) -
address
can include yourstatus
and probablycontrol
group address from your knx system. - You can customize group address datapoints by adding
datapoint
( KNX datapoint types ) - For Boolean and Percentage Devices you can add
inverted
( inverts the state fromfalse
->true
/0
->100
) - For Window Coverings you can add
delay
forup
anddown
( to calibrate the time it takes to open / close the covering )
-
SynTex UI
Control and set up your devices by installing homebridge-syntex
This plugin is made for plugin management, automation system and device control.
Check out the GitHub page for more information:
https://github.com/SynTexDZN/homebridge-syntex
Update KNX Device
- Open
http://
Bridge IP/devices?id=
Device ID&value=
New Value - Insert the
Bridge IP
andDevice ID
- For the
New Value
you can type this pattern:
- For boolean devices:
true
/false
( dimmer, led, outlet, rgb, switch ) - For numeric devices:
10
/12.4
( blind ) - For dimmable lights add
&brightness=
New Brightness ( has to be a number ) - For colored lights add
&hue=
New Hue ( has to be a number ) - For colored lights add
&saturation=
New Saturation ( has to be a number ) - For accessories with multiple service types add
&type=
SERVICETYPE - For accessories with multiple services with more than one of the same service type add
&counter=
SERVICENUMBER
( First of that type = 0, second = 1 .. )
Example: http://homebridge.local:1714/devices?id=ABCDEF1234567890&type=dimmer&counter=0&value=true&brightness=100
( Updates the value and brightness of ABCDEF1234567890
to turned on, 100% brightness
for example )
Read KNX Device
- Open
http://
Bridge IP/devices?id=
Device ID - Insert the
Bridge IP
andDevice ID
- For accessories with multiple service types add
&type=
SERVICETYPE - For accessories with multiple services with more than one of the same service type add
&counter=
SERVICENUMBER
( First of that type = 0, second = 1 .. )
Example: http://homebridge.local:1714/devices?id=ABCDEF1234567890
( Reads the state of ABCDEF1234567890
for example )
Remove KNX Device
- Open
http://
Bridge IP/devices?id=
Device ID&remove=CONFIRM
- Insert the
Bridge IP
andDevice ID
- To remove a specific service add
&type=
SERVICETYPE - To remove a specific service from an accessory with more than one of the same service type add
&counter=
SERVICENUMBER
( First of that type = 0, second = 1 .. )
Example: http://homebridge.local:1714/devices?id=ABCDEF1234567890&remove=CONFIRM
( Removes ABCDEF1234567890
from the Config and Home App )
Automation
To enable the automation module you have to create a file named automation.json
in your baseDirectory >> automation
or install the homebridge-syntex
plugin to create them via UI ( only between SynTex plugins )
Example: For manual configuration update your automation.json
file. See snippet below.
{
"automation": [
{
"id": 0,
"name": "Demo Automation",
"active": true,
"trigger": {
"logic": "AND",
"groups": [
{
"logic": "OR",
"blocks": [
{
"id": "multi2",
"name": "Multi Device",
"letters": "F0",
"plugin": "SynTexWebHooks",
"operation": "<",
"state": {
"value": 1000
}
},
{
"operation": "=",
"time": "16:00",
"options": {
"stateLock": true
}
}
]
},
{
"logic": "AND",
"blocks": [
{
"id": "multi1",
"name": "Multi Switch",
"letters": "41",
"plugin": "SynTexWebHooks",
"operation": "=",
"state": {
"value": false
},
"options": {
"stateLock": true
}
},
{
"operation": "=",
"days": [
1,
2,
3,
4,
5
]
}
]
}
]
},
"result": [
{
"id": "knx5",
"name": "Multi Accessory",
"letters": "80",
"plugin": "SynTexKNX",
"operation": "=",
"state": {
"value": true
}
},
{
"id": "extern1",
"name": "Extern Accessory",
"letters": "40",
"bridge": "192.168.1.100",
"plugin": "SynTexWebHooks",
"operation": "=",
"state": {
"value": false
},
"options": {
"stateLock": false
}
},
{
"operation": "=",
"delay": 1000
},
{
"url": "http://192.168.1.100:1714/devices?id=ABCDEF1234567890&value=true"
}
]
}
]
}
Required Parameters
-
id
A unique ID of your automation. -
name
The name of the automation. -
active
Enable / disable a single automation. -
trigger
What triggers the automation?
-
logic
Define a logical operation for your groups (AND
,OR
) -
groups
Logical layer one
-
logic
Define a logical operation for your blocks (AND
,OR
) -
blocks
Logical layer two
-
-
-
result
What happens when running an automation? -
options
General automation options
-
timeLock
Set a timeout to prevent to many executions ( in milliseconds )
-
Block Configuration
Service Block ( Trigger, Result )
-
id
is the same like in your config file ( or in your log ) -
name
The name of the accessory. -
letters
See letter configuration below. -
bridge
IP of your other bridge ( optional ) -
plugin
Use the platform name of the plugin ( optional, see supported plugins below ) -
operation
Use the logical operands (>
,<
,=
) -
state
The state of your accessory.
-
value
is used for the main characteristic. -
brightness
can be used for dimmable / RGB lights. -
hue
can be used for RGB lights. -
saturation
can be used for RGB lights.
-
Time Block ( Trigger )
-
operation
Use the logical operands (>
,<
,=
) -
time
Define a time point ( e.g.16:00
)
Weekday Block ( Trigger )
-
operation
Use the logical operands (=
) -
days
Set the weekdays ( from0
to6
)
Delay Block ( Result )
-
delay
Set a timeout ( in milliseconds )
URL Block ( Result )
-
url
Fetch an URL.
Letter Configuration
The letters are split into two parts ( characters )
1. Service Type
- 0 : Occupancy
- 1 : Smoke
- 2 : Airquality
- 3 : RGB
- 4 : Switch
- 5 : Relais
- 6 : Stateless Switch
- 7 : Outlet
- 8 : LED
- 9 : Dimmer
- A : Contact
- B : Motion
- C : Temperature
- D : Humidity
- E : Rain
- F : Light
- G : Blind
2. Duplicate Counter
- If there are more services of the same type the counter indicates which is which
- Simply count from top to bottom.
Example: The first switch in your config has the letters 40
, the second 41
and so on ..
Supported Plugins
- SynTexKNX (
homebridge-syntex-knx
) - SynTexMagicHome (
homebridge-syntex-magichome
) - SynTexTuya (
homebridge-syntex-tuya
) - SynTexWebHooks (
homebridge-syntex-webhooks
)
Currently Supported
- Contact Sensor
- Humidity Sensor
- Leak / Rain Sensor
- Light Sensor
- Motion Sensor
- Occupancy Sensor
- Smoke Sensor
- Temperature Sensor
- Switch / Relais / Outlet
- LED Lights / Dimmable Lights / RGB Lights
- Blinds / Shutters / Window Coverings