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