homebridge-smarthomeng v2.0.7

homebridge-smarthomeng

Version v2 is a complete rewrite from scratch and a breaking update.
You need to adapt your config.json !

Currently supported accessories

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

Requirements

• SmartHomeNG
• Node.js >=14.18.1
• Homebridge

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.

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

}