Homebridge plugin exposing devices plugged on GPIO
npm install homebridge-gpio-deviceHomebridge GPIO device expose several HomeKit accessories interacting with GPIO
1. Install latest NodeJS 10.x (tested with 10.19.0)
2. Install homebridge using: npm install -g homebridge
3. Install wiringPi using: sudo apt-get install wiringpi
3. Add rights to homebridge user if running homebridge as systemd service: sudo usermod -a -G gpio homebridge
4. Install this plugin using: sudo npm install -g homebridge-gpio-device --unsafe-perm
6. Update your configuration file. See bellow for a sample.
Any inputs are configured with pull-up resistor and considered as active on low state.
Sensors must be plug as following
GND <---> SENSOR <---> PIN
Sensors are considered as _Normally Opened_ by default. If using _Normally Closed_ sensor, you can use inverted or invertedInputs parameters as explained in the next section.
Pull-up resistors can be disabled by adding parameter "pullUp": false in any accessory using inputs. If disabled, you'll have to wire pull-up or pull-down resistors by yourself.
###### Note
In the section bellow, LOW state means _sensor contact closed_. HIGH state means _sensor contact opened_.
For outputs, LOW state means 0V and HIGH state means 3.3V.
Configuration example:
``
{
"bridge": {
...
},
"description": "...",
"accessories": [
{
"accessory": "GPIODevice",
"name": "Front Door",
"type": "ContactSensor",
"pin": 4
},
{
"accessory": "GPIODevice",
"name": "Sofa Light",
"type": "Lightbulb",
"pin": 5
},
{
"accessory": "GPIODevice",
"type": "MotionSensor",
"name": "Hall Motion",
"pin": 3,
"occupancy": {
"name": "Home Occupancy",
"timeout": 3600
}
},
{
"accessory": "GPIODevice",
"name": "Kitchen Roller Shutter",
"type": "WindowCovering",
"pins": [12,13]
"shiftDuration": 23,
"initPosition": 99
},
{
"accessory": "GPIODevice",
"type": "LockMechanism",
"name": "Front Door",
"pin": 6,
"duration": 5
},
{
"accessory": "GPIODevice",
"type": "Valve",
"name": "Garden irrigation",
"subType": "irrigation",
"pin": 6
},
{
"accessory": "GPIODevice",
"type": "StatelessProgrammableSwitch",
"name": "Push Button",
"pin": 4
}
],
"platforms":[]
}
`
pin numbers must be specified as ~~wPi~~ BCM (as of v0.4.7) pin number in the Pin Configuration table below
| Type | Note |
|-----------------------|-------------------|
| name | Accessory name |type
| | Type of accessory |
Accessory type could be one of the following:
* ContactSensor
* MotionSensor
* LeakSensor
* SmokeSensor
* CarbonDioxideSensor
* Switch
* Lightbulb
* Outlet
* Valve
* Window
* WindowCovering
* Door
* GarageDoorOpener
* LockMechanism
* StatelessProgrammableSwitch
* Doorbell
wPi pin number must be used in config file
gpio readall``
+-----+-----+---------+------+---+---Pi 2---+---+------+---------+-----+-----+
| BCM | wPi | Name | Mode | V | Physical | V | Mode | Name | wPi | BCM |
+-----+-----+---------+------+---+----++----+---+------+---------+-----+-----+
| | | 3.3v | | | 1 || 2 | | | 5v | | |
| 2 | 8 | SDA.1 | OUT | 0 | 3 || 4 | | | 5V | | |
| 3 | 9 | SCL.1 | IN | 1 | 5 || 6 | | | 0v | | |
| 4 | 7 | GPIO. 7 | IN | 1 | 7 || 8 | 1 | ALT0 | TxD | 15 | 14 |
| | | 0v | | | 9 || 10 | 1 | ALT0 | RxD | 16 | 15 |
| 17 | 0 | GPIO. 0 | IN | 0 | 11 || 12 | 1 | IN | GPIO. 1 | 1 | 18 |
| 27 | 2 | GPIO. 2 | OUT | 0 | 13 || 14 | | | 0v | | |
| 22 | 3 | GPIO. 3 | IN | 0 | 15 || 16 | 0 | IN | GPIO. 4 | 4 | 23 |
| | | 3.3v | | | 17 || 18 | 0 | IN | GPIO. 5 | 5 | 24 |
| 10 | 12 | MOSI | IN | 0 | 19 || 20 | | | 0v | | |
| 9 | 13 | MISO | IN | 0 | 21 || 22 | 0 | IN | GPIO. 6 | 6 | 25 |
| 11 | 14 | SCLK | IN | 0 | 23 || 24 | 1 | IN | CE0 | 10 | 8 |
| | | 0v | | | 25 || 26 | 1 | IN | CE1 | 11 | 7 |
| 0 | 30 | SDA.0 | IN | 1 | 27 || 28 | 1 | IN | SCL.0 | 31 | 1 |
| 5 | 21 | GPIO.21 | IN | 1 | 29 || 30 | | | 0v | | |
| 6 | 22 | GPIO.22 | IN | 1 | 31 || 32 | 0 | IN | GPIO.26 | 26 | 12 |
| 13 | 23 | GPIO.23 | IN | 0 | 33 || 34 | | | 0v | | |
| 19 | 24 | GPIO.24 | IN | 0 | 35 || 36 | 0 | IN | GPIO.27 | 27 | 16 |
| 26 | 25 | GPIO.25 | IN | 0 | 37 || 38 | 0 | IN | GPIO.28 | 28 | 20 |
| | | 0v | | | 39 || 40 | 0 | IN | GPIO.29 | 29 | 21 |
+-----+-----+---------+------+---+----++----+---+------+---------+-----+-----+
| BCM | wPi | Name | Mode | V | Physical | V | Mode | Name | wPi | BCM |
+-----+-----+---------+------+---+---Pi 2---+---+------+---------+-----+-----+
ContactSensor, MotionSensor, LeakSensor, SmokeSensor, CarbonDioxideSensor and CarbonMonoxideSensor types monitor a GPIO input and report it as HomeKit Sensor.
###### Configuration
| Parameter | Type | Default | Note |
|----------------------------|------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| pin | Integer | N/A | mandatory, input pin number to monitor (LOW: sensor triggered, HIGH: sensor not triggered) |inverted
| | Boolean | false | optional, reverse the behaviour of the GPIO input pin (HIGH: sensor triggered, LOW: sensor not triggered) |postpone
| | Integer | 100 | optional, delay (ms) between 2 state change to avoid bouncing |
###### MotionSensor additional parameters
MotionSensor has optional OccupancySensor wich can be configured with a timeout.
Could be used with this PIR Sensor.
| Parameter | Type | Default | Note |
|----------------------------|------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| occupancy | {} | null | optional, activate an occupancy sensor with a timeout after motion detection |occupancy.name
| | String | N/A | mandatory, occupancy sensor name |occupancy.timeout
| | Integer (sec) | 60 | optional, ocupancy timeout in sec after motion detection |
Switch, Lightbulb, Outlet, Fan, Fanv2 and Valve operates a GPIO output as ON/OFF.
###### Configuration
| Parameter | Type | Default | Note |
|----------------------------|------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| pin | Integer | N/A | mandatory, output pin number to trigger (on: HIGH, off: LOW) |inverted
| | Boolean | false | optional, reverse the behaviour of the GPIO output pin (on: LOW, off: HIGH) |initState
| | 0/1 | 0 | optional, default state of the switch at startup (0: off, 1: on) |duration
| | Integer | 0 | optional, duration before restoring output state (0: disabled) |inputPin
| | Integer | N/A | optional, input pin number used as mirroring. (LOW: switch to on, HIGH: switch to off) |
###### Valve optional configuration
| Parameter | Type | Default | Note |
|----------------------------|------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| subType | String | "generic" | optional, valve widget subtype like "irrigation", "shower" or "faucet" |inputPin
| | Integer | N/A | optional, input pin number used as "InUse" characteristic for Valve widget. (LOW: in use, HIGH: not in use) |
StatelessProgrammableSwitch or Doorbell types monitor a GPIO input and reports it as HomeKit Stateless Programmable Switch.
###### Configuration
| Parameter | Type | Default | Note |
|----------------------------|------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| pin | Integer | N/A | mandatory, input pin number to monitor (LOW: button pressed, HIGH: button released) |inverted
| | Boolean | false | optional, reverse the behaviour of the GPIO output pin (HIGH: button pressed, LOW: button released) |shortPress
| | Integer | 500 | optional, delay (ms) of a short press (double press will be detected if done in this delay) |longPress
| | Integer | 2000 | optional, delay (ms) of a long press |postpone
| | Integer | 100 | optional, delay (ms) between 2 state change to avoid bouncing |
Window, WindowCovering or Door controls 2 GPIO outputs plugged to a remote control.
When operating, the GPIO is turned on for 200ms to simulate a button pression on the remote control.
###### Configuration
| Parameter | Type | Default | Note |
|----------------------------|------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| pins | Integer[2] | N/A | mandatory, output pins numbers to trigger (pins[0]: open, pins[1]: close) |inverted
| | Boolean | false | optional, reverse the behaviour of the GPIO output pin(s) (pulse becomes HIGH->LOW->HIGH) |initPosition
| | Integer (%) | 0 | optional, default shutter position at homebridge startup to compensate absence of state feedback, recommanded to ensure open/close scenarios after unexptected restart: 99% |shiftDuration
| | Integer (sec) | 20 | optional, duration of a shift (close->open or open->close) used to compute intermediate position |pulseDuration
| | Integer | 200 | optional, duration of the pin pulse. (0: deactivate, pin active during all shifting)invertStopPin
| | Boolean | false | optional, utilize the opposite pin to stop the shutter |openSensorPin
| | Integer | N/A | optional, input pin number for open sensor (LOW: opened position) |closeSensorPin
| | Integer | N/A | optional, input pin number for close sensor (LOW: closed position) |invertedInputs
| | Boolean | false | optional, reverse the behaviour of the GPIO input pins (detect opened/closed on HIGH state) |
GarageDoorOpener controls 1 or 2 GPIO output(s) plugged to a garage door engine.
When operating, the GPIO is turned on for 200ms.
###### Configuration
| Parameter | Type | Default | Note |
|----------------------------|------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| pin | Integer | N/A | optional, output pin number for toggle opener (first pulse: open, second pulse: close) |pins
| | Integer[2] | N/A | optional, output pins numbers for open/close opener (pins[0]: open, pins[1]: close) |inverted
| | Boolean | false | optional, reverse the behaviour of the GPIO output pin(s) (pulse becomes HIGH->LOW->HIGH) |openingDuration
| | Integer | 10 | optional, opening duration of the door (seconds). Emulate transition if openSensorPin not provided. |closingDuration
| | Integer | 10 | optional, closing duration of the door (seconds). Emulate transition if closeSensorPin not provided. |waitingDuration
| | Integer | N/A | optional, waiting duration of the door shift before closing (seconds). If setted, emulate a cyclic door if openSensorPin not provided. |pulseDuration
| | Integer | 200 | optional, duration of the pin pulse. |openSensorPin
| | Integer | N/A | optional, input pin number for open sensor (LOW: opened position) |closeSensorPin
| | Integer | N/A | optional, input pin number for close sensor (LOW: closed position) |invertedInputs
| | Boolean | false | optional, reverse the behaviour of the GPIO input pins (detect opened/closed on HIGH state) |
LockMechanism operate a GPIO outputs plugged to an electric latch.duration
When operating, the latch is unlocked for seconds (or indefinitely if duration=0)
###### Configuration
| Parameter | Type | Default | Note |
|----------------------------|------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| pin | Integer | N/A | mandatory, output pin number to trigger (lock: LOW, unlock: HIGH) |duration
| | Integer (sec) | 0 | optional, duration before restoring locked state (0 : disabled) |inverted
| | Boolean | false | optional, reverse the behaviour of the GPIO output pin (lock: HIGH, unlock: LOW) |inputPin` | Integer | N/A | optional, input pin number for lock sensor (LOW: unlocked, HIGH: locked) |
|