hgd

homebridge-gpio-device

Homebridge GPIO device expose several HomeKit accessories interacting with GPIO

Showing:

Popularity

Downloads/wk

19

GitHub Stars

53

Maintenance

Last Commit

5mos ago

Contributors

10

Package

Dependencies

1

Size (min+gzip)

7.8KB

License

ISC

Type Definitions

Tree-Shakeable

No?

Categories

Readme

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

TypeNote
nameAccessory name
typeType of accessory

Accessory type could be one of the following:

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
ParameterTypeDefaultNote
pinIntegerN/Amandatory, input pin number to monitor (LOW: sensor triggered, HIGH: sensor not triggered)
invertedBooleanfalseoptional, reverse the behaviour of the GPIO input pin (HIGH: sensor triggered, LOW: sensor not triggered)
postponeInteger100optional, 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.

ParameterTypeDefaultNote
occupancy{}nulloptional, activate an occupancy sensor with a timeout after motion detection
occupancy.nameStringN/Amandatory, occupancy sensor name
occupancy.timeoutInteger (sec)60optional, ocupancy timeout in sec after motion detection

DigitalOutput

Switch, Lightbulb, Outlet, Fan, Fanv2 and Valve operates a GPIO output as ON/OFF.

Configuration
ParameterTypeDefaultNote
pinIntegerN/Amandatory, output pin number to trigger (on: HIGH, off: LOW)
invertedBooleanfalseoptional, reverse the behaviour of the GPIO output pin (on: LOW, off: HIGH)
initState0/10optional, default state of the switch at startup (0: off, 1: on)
durationInteger0optional, duration before restoring output state (0: disabled)
inputPinIntegerN/Aoptional, input pin number used as mirroring. (LOW: switch to on, HIGH: switch to off)
Valve optional configuration
ParameterTypeDefaultNote
subTypeString"generic"optional, valve widget subtype like "irrigation", "shower" or "faucet"
inputPinIntegerN/Aoptional, 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
ParameterTypeDefaultNote
pinIntegerN/Amandatory, input pin number to monitor (LOW: button pressed, HIGH: button released)
invertedBooleanfalseoptional, reverse the behaviour of the GPIO output pin (HIGH: button pressed, LOW: button released)
shortPressInteger500optional, delay (ms) of a short press (double press will be detected if done in this delay)
longPressInteger2000optional, delay (ms) of a long press
postponeInteger100optional, 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
ParameterTypeDefaultNote
pinsInteger[2]N/Amandatory, output pins numbers to trigger (pins[0]: open, pins[1]: close)
invertedBooleanfalseoptional, reverse the behaviour of the GPIO output pin(s) (pulse becomes HIGH->LOW->HIGH)
initPositionInteger (%)0optional, default shutter position at homebridge startup to compensate absence of state feedback, recommanded to ensure open/close scenarios after unexptected restart: 99%
shiftDurationInteger (sec)20optional, duration of a shift (close->open or open->close) used to compute intermediate position
pulseDurationInteger200optional, duration of the pin pulse. (0: deactivate, pin active during all shifting)
invertStopPinBooleanfalseoptional, utilize the opposite pin to stop the shutter
openSensorPinIntegerN/Aoptional, input pin number for open sensor (LOW: opened position)
closeSensorPinIntegerN/Aoptional, input pin number for close sensor (LOW: closed position)
invertedInputsBooleanfalseoptional, 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
ParameterTypeDefaultNote
pinIntegerN/Aoptional, output pin number for toggle opener (first pulse: open, second pulse: close)
pinsInteger[2]N/Aoptional, output pins numbers for open/close opener (pins[0]: open, pins[1]: close)
invertedBooleanfalseoptional, reverse the behaviour of the GPIO output pin(s) (pulse becomes HIGH->LOW->HIGH)
openingDurationInteger10optional, opening duration of the door (seconds). Emulate transition if openSensorPin not provided.
closingDurationInteger10optional, closing duration of the door (seconds). Emulate transition if closeSensorPin not provided.
waitingDurationIntegerN/Aoptional, waiting duration of the door shift before closing (seconds). If setted, emulate a cyclic door if openSensorPin not provided.
pulseDurationInteger200optional, duration of the pin pulse.
openSensorPinIntegerN/Aoptional, input pin number for open sensor (LOW: opened position)
closeSensorPinIntegerN/Aoptional, input pin number for close sensor (LOW: closed position)
invertedInputsBooleanfalseoptional, 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
ParameterTypeDefaultNote
pinIntegerN/Amandatory, output pin number to trigger (lock: LOW, unlock: HIGH)
durationInteger (sec)0optional, duration before restoring locked state (0 : disabled)
invertedBooleanfalseoptional, reverse the behaviour of the GPIO output pin (lock: HIGH, unlock: LOW)
inputPinIntegerN/Aoptional, input pin number for lock sensor (LOW: unlocked, HIGH: locked)

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100