Skip to content

Latest commit

 

History

History
549 lines (467 loc) · 24.4 KB

README.md

File metadata and controls

549 lines (467 loc) · 24.4 KB
Raw

homebridge-smarthomeng

npm verified-by-homebridge npm npm npm npm

Currently supported accessories

This plugin currently supports the following services (and characteristics):

Type Description
ContactSensor Simple contact sensor, for example for windows
Doorbell Doorbell, sends message to devices on ring
Fan Simple on/off fan, may be extended in future
GarageDoor Garage door opener
HumiditySensor Humidity sensor
Lightbulb Everything, from simple light to dimmable, RGB and RGBW
MotionSensor Detects and reports motion
OccupancySensor Detects presence in a room
Outlet Simple on/off wall outlet
SecuritySystem Intrusion alarm system
Switch Simple on/off switch
TemperatureSensor Temperature sensor
Thermostat Thermostat with temperature sensor and heating state
WindowCovering Window covering (shutters, blinds, ...)

Requirements

Installation of plugin

Use Homebridge Config UI X or install manually using npm install -g homebridge-smarthomeng

Configuration

If you already have a working homebridge installation just add the platform section into your existing config. If you are a new homebridge user you have to create a config.json file in the .homebridge directory. You'll find that directory in your home folder.

Platform configuration

The following parameters are available to configure the plugin as platform in homebridge.

Parameter Possible values Mandatory Default Description
platform Any <string> Yes Internal name of your platform
name Any <string> Yes Visible name in HomeKit
host IP address or FQDN of your SHNG server Yes Your SHNG host
port Port <number> No 2424 Listening port of websocket module.
tls <boolean> No False Should TLS encryption be used.

Example configuration:

{
    "platform": "SmartHomeNG",
    "name": "SmartHomeNG",
    "host": "smarthome.my.domain",
    "port": 2425,
    "tls": true,
}

Common accessories characteristics

The following characteristics are valid for all accessories:

Parameter Possible values Mandatory Description
type Supported <type> of accessory Yes Type from the list of supported accessories
name Any <string> Yes Visible name in HomeKit
manufacturer Any <string> No Visible manufacturer in HomeKit
model Any <string> No Visible model in HomeKit

Example:

{
    "type": "OccupancySensor",
    "name": "Presence kitchen",
    "manufacturer": "Preussen",
    "model": "Motion 360 KNX",
}

Contact sensor

This sensor shows the open / closed state of a contact (door, window, generic ...).

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
ContactState <item> Yes SHNG item to monitor for contact

Example:

{
    "type": "ContactSensor",
    "name": "Window kitchen",
    "ContactState": "EG.Kueche.Fenster"
}

Doorbell

A doorbell is an accessory that simply sends a message to all devices enrolled in the home that someone rang the doorbell. HomeKit displays a message that "This accessory is not currently supported by the Home app.". Further investigation is needed, but for now it still works.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
SinglePress <item> Yes SHNG item to monitor for doorbell ring

Example:

{
    "type": "Doorbell",
    "name": "Main door",
    "SinglePress": "Technik.Asterisk.Klingel"
}

Fan

For now this accessory only supports turning the fan on and off. Further improvements are possible, but i don't have the needed hardware for testing.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
Active <item> Yes SHNG item to set and get the fan state.
RotationSpeed <item> No SHNG item to set and get the fan rotation speed

Example:

{
    "type": "Fan",
    "name": "Fan bathroom",
    "Active": "OG.Bad.Ventilator"
}

Garage Door

This accessory is used for opening/closing garage doors or any other automatic gate.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
CurrentDoorState <item> Yes SHNG item to monitor the current door state
TargetDoorState <item> Yes SHNG item to monitor and set the target position
ObstructionDetected <item> No SHNG item to monitor if the door is blocked

Additional comments

Valid values for 'CurrentDoorState':

  • OPEN = 0
  • CLOSED = 1
  • OPENING = 2
  • CLOSING = 3
  • STOPPED = 4

Valid values for 'TargetDoorState':

  • OPEN = 0
  • CLOSED = 1

'ObstructionDetected' may be set 'true' if there is any physical problem opening/closing the door.

Example

{
    "type": "GarageDoor",
    "name": "GarageRechts",
    "currentdoorstate": "garage.rechts.cds",
    "targetdoorstate": "garage.rechts.tds",
    "obstructiondetected": "garage.rechts.od"
}

Humidity sensor

This accessory shows the current relative humidity in %.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
CurrentHumidity <item> Yes SHNG item to monitor relative humidity in %

Example:

{
    "type": "HumiditySensor",
    "name": "Luftfeuchtigkeit Glashaus",
    "CurrentHumidity": "Glashaus.Luftfeuchtigkeit"
}

LightBulb

Lightbulb can be as simple as a generic on/off light, but can also be as complex as a full RGBW led strip.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Default Description
On <item> Yes SHNG item to switch the lightbuld on or off
Brightness <item> No SHNG item to monitor and set the brigtness for a dimmable light
BrightnessMin <number> No 0 Your device's minimum value for brightness
BrightnessMax <number> No 100 Your device's maximum value for brightness
Hue <item> No SHNG item to get and set the HUE in case of a HSB light
Saturation <item> No SHNG item to get and set the saturation in case of a HSB light
R <item> No SHNG item for the RED color in case of RGB(W) light
RMin <number> No 0 Your device's minimum value for the RED color
RMax <number> No 100 Your device's maximum value for RED color
G <item> No SHNG item for the GREEN color in case of RGB(W) light
GMin <number> No 0 Your device's minimum value for the GREEN color
GMax <number> No 100 Your device's maximum value for GREEN color
B <item> No SHNG item for the BLUE color in case of RGB(W) light
BMin <number> No 0 Your device's minimum value for the BLUE color
BMax <number> No 100 Your device's maximum value for BLUE color

Additional comments

HomeKit works with values between 0 and 100 where 0 is completely dim and 100 is maximum brightness.
My KNX installation, as example, needs values between 0 and 255.
The above optional min and max parameters allow you to specify the neede range for your device. The plugin then transposes the values in both directions.

Example (used for my KNX RGBW strip):

{
    "type": "Lightbulb",
    "name": "RGBW strip living room",
    "On": "EG.Stube.Ledleiste",
    "Brightness": "EG.Stube.Ledleiste.dimmen",
    "BrightnessMin": 0,
    "BrightnessMax": 255,
    "R": "EG.Stube.Ledleiste.R.dimmen",
    "RMin": 0,
    "RMax": 255,
    "G": "EG.Stube.Ledleiste.G.dimmen",
    "GMin": 0,
    "GMax": 255,
    "B": "EG.Stube.Ledleiste.B.dimmen",
    "BMin": 0,
    "BMax": 255,
    "W": "EG.Stube.Ledleiste.W.dimmen",
    "WMin": 0,
    "WMax": 255
}

Motion sensor

This sensor is tripped if it detects motion in a room.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
MotionDetected <item> Yes SHNG item to monitor for motion

Example:

{
    "type": "MotionSensor",
    "name": "Movement hallway",
    "MotionDetected": "EG.Flur.Bewegung"
}

Occupancy sensor

This sensor is tripped if it detects presence in a room.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
OccupancyDetected <item> Yes SHNG item to monitor for presence

Example:

{
    "type": "OccupancySensor",
    "name": "Presence bathroom",
    "manufacturer": "Preussen",
    "model": "Motion 360 KNX",
    "OccupancyDetected": "OG.Bad.Praesenz"
}

Outlet

This accessory can monitor and change the on/off state of a wall outlet. The outlet can be generic, a light, a fan, ...

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
On <item> Yes SHNG item to switch outlet on or off

Example:

{
    "type": "Outlet",
    "name": "Christmas tree",
    "On": "EG.Esszimmer.Steckdose"
}

Security system

This accessory can pilote your intrusion security system. That system can be a physical one operated via SHNG, or a SHNG native logic.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
CurrentState <item> Yes SHNG item to monitor for the current alarm state
TargetState <item> Yes SHNG item to set or get the target state

Additional comments

Valid values for 'CurrentState':

  • STAY_ARM = 0
  • AWAY_ARM = 1
  • NIGHT_ARM = 2
  • DISARMED = 3
  • ALARM_TRIGGERED = 4

Valid values for 'TargetState':

  • STAY_ARM = 0
  • AWAY_ARM = 1
  • NIGHT_ARM = 2
  • DISARMED = 3

Example:

{
    "type": "SecuritySystem",
    "name": "Intrusion alarm",
    "currentState": "Technik.Alarmanlage.Status.Ist",
    "targetState": "Technik.Alarmanlage.Status.Soll"
}

Switch

This accessory can monitor and change the on/off state of something. It is very similar to an outlet.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
On <item> Yes SHNG item to switch something on or off

Example:

{
    "type": "Switch",
    "name": "Music living-room",
    "On": "EG.Stube.Radio"
}

Temperature sensor

This sensor shows the actual temperature.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
CurrentTemperature <item> Yes SHNG item to monitor for temperature

Example:

{
    "type": "TemperatureSensor",
    "name": "Temperature WC",
    "CurrentTemperature": "EG.WC.Temperatur"
}

Thermostat

This sensor shows and sets the actual temperature. In addition it can show the actual heating / cooling state.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Description
CurrentTemperature <item> Yes SHNG item to monitor for temperature
TargetTemperature <item> Yes SHNG item to set target temperature
CurrentHeatingCoolingState <item> Yes SHNG item to monitor for current heating / cooling state

Additional comments

CurrentHeatingCoolingState = 0 for OFF, 1 for HEAT and 2 for COOL

Example:

{
    "type": "Thermostat",
    "name": "Temperature badroom",
    "CurrentTemperature": "OG.SZSS.Temperatur",
    "TargetTemperature": "OG.SZSS.Temperatur.Sollwert",
    "CurrentHeatingCoolingState": "OG.SZSS.Temperatur.Status"
}

Window covering

This accessory type can be used for shutters or blinds. Because the differnce between HomeKit and the controlling technology, for example KNX, can be significant this accessory has a lot of parameters. Luckily most are optional.

Characteristics in addition to common characteristics

Parameter Possible values Mandatory Default Description
CurrentPosition <item> Yes SHNG item to monitor thecurrent position
TargetPosition <item> Yes SHNG item to monitor and set the target position
CurrentPositionMin <number> No 0 Your device's minimum value for current position
CurrentPositionMax <number> No 100 Your device's maximum value for current position
CurrentPositionDecimals <number> No 0 Number of decimals to round to
CurrentPositionInverted <boolean> No false Should the values be inverted, ex: 0 for Homekit = 100 for device
TargetPositionMin <number> No 0 Your device's minimum value for target position
TargetPositionMax <number> No 100 Your device's maximum value for target position
TargetPositionDecimals <number> No 0 Number of decimals to round to
TargetPositionInverted <boolean> No false Should the values be inverted, ex: 0 for Homekit = 100 for device
CurrentHorizontalTiltAngle <item> No SHNG item to monitor current horizontal tilt angle
TargetHorizontalTiltAngle <item> No SHNG item to monitor and set the target horizontal tilt angle
CurrentVerticalTiltAngle <item> No SHNG item to monitor current vertical tilt angle
TargetVerticalTiltAngle <item> No SHNG item to monitor and set the target vertical tilt angle

Additional comments

HomeKit works with values between 0 and 100 where 0 is completely closed and 100 is open.
My KNX installation, as example, needs values between 0 and 255 where 255 is completely closed and 0 is open.
The above optional parameters allow you to specify the neede range for your device. If needed the values can be inverted at the same time. The plugin then transposes the values in both directions.

Example (for use with most KNX shutters):

{
    "type": "WindowCovering",
    "name": "Shutters office",
    "CurrentPosition": "EG.Buero.Rolladen.Position",
    "CurrentPositionMin": 0,
    "CurrentPositionMax": 255,
    "CurrentPositionInverted": true,
    "TargetPosition": "EG.Buero.Rolladen.ZielPosition",
    "TargetPositionMin": 0,
    "TargetPositionMax": 255,
    "TargetPositionInverted": true
}

Example configuration file

This is an example config file which just uses this plugin and some example SmartHomeNG items.

{
    "bridge": {
        "name": "SmartHomeNG",
        "username": "CC:22:3D:E3:DE:37",
        "port": 51138,
        "pin": "655-59-9284"
    },

    "platforms": [
        {
            "platform": "SmartHomeNG",
            "name": "SmartHomeNG",
            "host": "smarthome.iot.wagener.family",
            "port": 2425,
            "tls": true,
            "accessories": [
                {
                    "type": "Outlet",
                    "name": "Steckdose Esszimmer",
                    "On": "EG.Esszimmer.Steckdose"
                },
                {
                    "type": "OccupancySensor",
                    "name": "Präsenz Büro",
                    "manufacturer": "Preussen",
                    "model": "Motion 360 KNX",
                    "OccupancyDetected": "EG.Buero.Praesenz"
                },
                {
                    "type": "MotionSensor",
                    "name": "Bewegung Flur",
                    "manufacturer": "Preussen",
                    "model": "Motion 360 KNX",
                    "MotionDetected": "EG.Flur.Praesenz"
                },
                {
                    "type": "ContactSensor",
                    "name": "Fenster Büro",
                    "ContactState": "EG.Buero.Fenster"
                },
                {
                    "type": "Doorbell",
                    "name": "Haustür",
                    "SinglePress": "Technik.Asterisk.Klingel"
                },
                {
                    "type": "Lightbulb",
                    "name": "Licht Büro",
                    "On": "EG.Buero.Deckenspots",
                    "Brightness": "EG.Buero.Deckenspots.dimmen",
                    "BrightnessMin": 0,
                    "BrightnessMax": 255
                }
                {
                    "type": "Lightbulb",
                    "name": "RGB Leiste Stube",
                    "On": "EG.Stube.Ledleiste",
                    "Brightness": "EG.Stube.Ledleiste.dimmen",
                    "BrightnessMin": 0,
                    "BrightnessMax": 255,
                    "R": "EG.Stube.Ledleiste.R.dimmen",
                    "RMin": 0,
                    "RMax": 255,
                    "G": "EG.Stube.Ledleiste.G.dimmen",
                    "GMin": 0,
                    "GMax": 255,
                    "B": "EG.Stube.Ledleiste.B.dimmen",
                    "BMin": 0,
                    "BMax": 255,
                    "W": "EG.Stube.Ledleiste.W.dimmen",
                    "WMin": 0,
                    "WMax": 255
                },
                {
                    "type": "Fan",
                    "name": "Ventilator Bad",
                    "Active": "OG.Bad.Ventilator"
                },
                {
                    "type": "Thermostat",
                    "name": "Temperatur Büro",
                    "CurrentTemperature": "EG.Buero.Temperatur",
                    "TargetTemperature": "EG.Buero.Temperatur.Sollwert",
                    "CurrentHeatingCoolingState": "EG.Buero.Temperatur.Modus"
                },
                {
                    "type": "WindowCovering",
                    "name": "Shutters office",
                    "CurrentPosition": "EG.Buero.Rolladen.Position",
                    "CurrentPositionMin": 0,
                    "CurrentPositionMax": 255,
                    "CurrentPositionInverted": true,
                    "TargetPosition": "EG.Buero.Rolladen.ZielPosition",
                    "TargetPositionMin": 0,
                    "TargetPositionMax": 255,
                    "TargetPositionInverted": true
                }
            ]
        }
    ],

    "description": "This is my development config file."

}