homebridge-gpio-device

Homebridge GPIO device expose several HomeKit accessories interacting with GPIO

Installation

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
4. Add rights to homebridge user if running homebridge as systemd service: sudo usermod -a -G gpio homebridge
5. Install this plugin using: sudo npm install -g homebridge-gpio-device --unsafe-perm
6. Update your configuration file. See bellow for a sample.

Wiring

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

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

Common configuration

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

Pin Configuration

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---+---+------+---------+-----+-----+

Type of accessories

DigitalInput

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

DigitalOutput

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)

ProgrammableSwitch

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

PositionOpener

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

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

LockMechanism operate a GPIO outputs plugged to an electric latch. When operating, the latch is unlocked for duration 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)