homebridge-smarthomeng

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."

}

Name		Name	Last commit message	Last commit date
Latest commit History 112 Commits
.github		.github
.vscode		.vscode
src		src
.eslintrc		.eslintrc
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
config.schema.json		config.schema.json
nodemon.json		nodemon.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

Foxi352/homebridge-smarthomeng

Folders and files

Latest commit

History

Repository files navigation

homebridge-smarthomeng

Currently supported accessories

Requirements

Installation of plugin

Configuration

Platform configuration

Example configuration:

Common accessories characteristics

Example:

Contact sensor

Characteristics in addition to common characteristics

Example:

Doorbell

Characteristics in addition to common characteristics

Example:

Fan

Characteristics in addition to common characteristics

Example:

Garage Door

Characteristics in addition to common characteristics

Additional comments

Example

Humidity sensor

Characteristics in addition to common characteristics

Example:

LightBulb

Characteristics in addition to common characteristics

Additional comments

Example (used for my KNX RGBW strip):

Motion sensor

Characteristics in addition to common characteristics

Example:

Occupancy sensor

Characteristics in addition to common characteristics

Example:

Outlet

Characteristics in addition to common characteristics

Example:

Security system

Characteristics in addition to common characteristics

Additional comments

Example:

Switch

Characteristics in addition to common characteristics

Example:

Temperature sensor

Characteristics in addition to common characteristics

Example:

Thermostat

Characteristics in addition to common characteristics

Additional comments

Example:

Window covering

Characteristics in addition to common characteristics

Additional comments

Example (for use with most KNX shutters):

Example configuration file

About

Resources

License

Stars

Watchers

Forks

Releases 7

Packages 0

Contributors 4

Languages

Packages