hlc

homebridge-loxone-connect

Websocket based homebridge plugin for controlling Loxone.

Showing:

Popularity

Downloads/wk

35

GitHub Stars

9

Maintenance

Last Commit

1mo ago

Contributors

2

Package

Dependencies

4

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

homebridge-loxone-connect

Homebridge plugin for controlling Loxone.

❤️ One-time donation

There are a few variants from the original loxone homebridge plugin, but they all have the same problem. Most of them are abandoned and they don't work completely. Those are the two main reason that i made this plugin, i also added a lot of fun and useful stuff.

Feature requests are always welcome!

The plugin will be able to communicate with the following items from your Loxone setup:

  • Lights (Switches, Dimmers and RGB/ Smart-actor RGBW leds)
  • Sensors (Temperature, Humidty, Light, Motion, Contact, Leak and Smoke)*
  • Switches (On/Off, Pushbutton, Stairwell)
  • Doorbell notification*
  • Valve, Sprinklers*
  • HomeKit trigger*
  • Window blinds
  • Alarm system
  • Outlet*
  • Gate
  • Lock*
  • Fan*

*Needs additional configuration, check assumptions. The only configuration required is the credentials to your Loxone miniserver.

Prerequisites

Homebridge Follow all the installation steps there.

Installation

Install the plugin through npm or download the files from here.

$ sudo npm install -g homebridge-loxone-connect

Or update to latest version when already installed:

$ sudo npm update -g homebridge-loxone-connect

Configuration

See config-sample.json for an example configuration.

Platform configuration

ParameterNote
hostIP of your loxone miniserver
portoptional, port of your miniserver (default: 80)
usernameloxone username
passwordloxone password
optionsoptional, check options
aliasoptional, check assumption aliases

Options

ParameterNote
roomsoptional, specify an array of interested rooms to filter on. If empty or not given, all elements are used.
Example: specifying "rooms" : ["Kitchen", "Bedroom"] will limit your bridge to only elements from those 2 rooms.
StairwellSwitchoptional, choose the switch behavior of the Stairwell Light Switch, default: "pulse".

Has 2 possible values:
pulse : Normal operation, light will stay on for fixed amount of time. This is the default in case not given.
on : Light will stay on as long as the switch is enabled.
moodSwitchesoptional, displays Loxone moods (wich are part of LightControllerV2 elements) as seperate buttons, default: "none".

Has 3 possible values:
none : does not include moods. This is the default in case not given.
all : include moods as actionable item.
* only : only include moods and filter out any other element.
alarmSystemoptional, choose between instant and delayed activation of the alarm, default: "delayedon".

Has 2 possible values
delayedon : Alarm will be delayed. Default.
on : Alarm will be instantly on.
alarmTrigerLeveloptional, choose at what level the alarm notification will be send to HomeKit, default: "5".

Has 6 possible values:
1 : Silent.
2 : Acustic.
3 : Optical.
4 : Internal.
5 : External.
6 : Remote.
autoLockoptional, whether the lock should automatically lock after being opened, default: "1".
autoLockDelayoptional, time (in seconds) until the lock will auto lock if enabled, default: "5".

Assumption aliases

ParameterNote
OutletOutlet alias.
LightingLighting alias.
DoorbellContact sensor alias.
TriggerTrigger alias.
ContactContact sensor alias.
MotionMotion sensor alias.
BrightnessLight sensor alias.
TemperatureTemperature sensor alias.
HumidityHumidity sensor alias.
LeakLeak sensor alias.
Smokesmoke sensor alias.
ValveValve alias.
SprinklersSprinklers alias.
FanFan alias.
LockLock alias.

For more information check assumptions.

Assumptions

To create the correct accessory type from Loxone items, some attribute parsing is required inside Loxone config.
The prefixes can be changed in assumption aliases.
Currently these assumptions are made:

Lightbulb

To make a lightbulb accessory you have to give a switch the prefix "Lighting" or you can give it the lightning category. *You can use a different category name as long as the category has the lightning icon.

Outlet

To make a lightbulb accessory you have to give a switch the prefix "Outlet" or you can give it the power category. *You can use a different category name as long as the category has the power icon.

Fan

To make a fan accessory you have to give a switch the prefix "Fan".

Lock

To make a lock accessory you have to give a switch the prefix "Lock". *automatic locking can be configured.

Valve, Sprinklers

To make a valve or sprinkler accessory you have to give a switch the prefix "Valve" or "Sprinklers".

Sensors, Doorbell, Trigger

For the following accessory's you will have to use a "Virtual Status block" inside Loxone config to make the following sensors.

AccessoryNote
DoorbellHas to have prefix "Doorbell".
The Doorbell will show 'Not compatible' but it will still send the notification.
TriggerHas to have prefix "Trigger".
This can be used for Homekit automation like triggering a scene to become active.
Contact sensorHas to have prefix "Contact".
Motion sensorHas to have prefix "Motion".
Light sensorHas to have prefix "Brightness".
Temperature sensorHas to have prefix "Temperature".
Humidity sensorHas to have prefix "Humidity".
Leak sensorHas to have prefix "Leak".
Smoke sensorHas to have prefix "Smoke".

The controls will be named like you named them in Loxone Config. Rename them through the iOS Home app to make it more intuitive for using with Siri. Eg LIGHT_KITCHEN can be renamed to 'main light' and added to room Kitchen. Then you can ask Siri to 'turn on the main light in the kitchen'.

Limitations

Rooms

The Homebridge/HAP protocol does currently not allow attaching the Loxone rooms to the accessories. That is a manual action to be done once using the IOS Home app (or the Eve app which is much more user-friendly).

Special note: organizing into rooms can be done from Eve, but renaming the items should (unfortunately) be done from the IOS Home app. Name changes in Eve are not reflected in Home and thus not known by Siri.

100 items

HomeKit has a limit of 100 accessories per bridge. If you have a large Loxone setup, try to filter unneeded items out either through a dedicated Loxone usergroup or in the checkCustomAttrs function.

Visualization password

Currently node-lox-ws-api does not support Loxone blocks with a visualization password on it. We are looking into solving this issue.

pushbuttons

Since Homekit has no pushbutton concept, I implemented pushbuttons as switches in Homekit. Telling Siri to put them On will send a pulse to the pushbutton. In Homekit, they will appear to be On for a second.

Problem solving

If you have troubles getting the states on your iOS device, try removing the files in your 'persists' folder (usually in ~/.homebridge/persist) and restarting homebridge.

License

The plugin is released under MIT license, which means you can do whatever you want with it as long as you give credit.

Credits

The original Loxone WS work was done by Sroose

Attribution goes towards Tommaso Marchionni. The structure of this code is based on his openHAB plugin.

The original HomeKit API work was done by Khaos Tian in his HAP-NodeJS project.

The homebridge component on which this plugin is built was created by Nick Farina.

I've made use of the NodeJS Loxone websocket API created by Ladislav Dokulil

Thanks to all contributors!

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100