homebridge-garage-door-wsensor

A Homebridge plugin for controlling a garage door opener via a Raspberry Pi GPIO relay, with optional door state sensor support.

Compatible with Homebridge 1.x and Homebridge 2.0.

Requirements

• Raspberry Pi (any model with GPIO, including Pi 5)
• Node.js >= 18
• Homebridge >= 1.1.7 (including 2.0)
• gpiod system package — install with: sudo apt install gpiod
  • Provides gpioget and gpioset which this plugin uses for GPIO access
  • Works on all Pi models including Pi 5 (uses /dev/gpiochip* character device, not legacy sysfs)
  • Raspberry Pi 5 note: gpiod is pre-installed on Raspberry Pi OS Bookworm — no extra install step needed
• A relay module wired to a GPIO output pin
• (Optional) A magnetic reed sensor or similar wired to a GPIO input pin

Installation

Option 1: Homebridge UI (recommended)

Search for homebridge-garage-door-wsensor in the Homebridge UI plugin tab and click Install.

Option 2: Command line

npm install -g homebridge-garage-door-wsensor

Option 3: Install directly from GitHub (recommended for this fork)

cd /var/lib/homebridge/node_modules
sudo git clone https://github.com/skirkpatrickMSFT/homebridge-garage-door-wsensor.git
cd homebridge-garage-door-wsensor
sudo npm install
sudo hb-service restart

To update to the latest version from GitHub later:

cd /var/lib/homebridge/node_modules/homebridge-garage-door-wsensor
sudo git pull
sudo npm install
sudo hb-service restart

Option 4: Install from a local copy

cd /path/to/this/folder
npm install
npm link

Homebridge Configuration

Add the following to the accessories array in your Homebridge config.json (usually located at /var/lib/homebridge/config.json):

{
    "accessory": "Garage Door Opener",
    "name": "Garage Door",
    "doorRelayPin": 8,
    "doorSensorPin": 23,
    "duration_ms": 500,
    "invertDoorState": false,
    "invertSensorState": false,
    "input_pull": "up"
}

Note: doorRelayPin and doorSensorPin use BCM GPIO numbers — not physical board pin numbers. See the GPIO Pin Map section below to find your BCM number.

Example of where it fits inside config.json:

{
    "bridge": { ... },
    "accessories": [
        {
            "accessory": "Garage Door Opener",
            "name": "Garage Door",
            "doorRelayPin": 8,
            "doorSensorPin": 23,
            "duration_ms": 500,
            "invertDoorState": false,
            "invertSensorState": false,
            "input_pull": "up"
        }
    ],
    "platforms": []
}

Configuration Options

| Option | Type | Required | Default | Description | |--------------------|---------|----------|---------|-------------| | name | string | Yes | — | Name of the accessory as it appears in HomeKit | | doorRelayPin | integer | Yes | — | BCM GPIO number connected to the relay (see pin map below) | | doorSensorPin | integer | Yes | — | BCM GPIO number connected to the door sensor (see pin map below) | | duration_ms | integer | No | 200 | How long (in milliseconds) to pulse the relay. 200–500 ms works for most garage openers | | invertDoorState | boolean | No | false | Invert the relay output logic (HIGH/LOW) for the door | | invertSensorState| boolean | No | false | Invert the sensor reading logic | | input_pull | string | No | "none"| Pull resistor for sensor pin: "up", "down", or "none" (configured via pinctrl) | | gpiochip | string | No | auto | GPIO chip device. Auto-detected at startup by scanning gpiodetect output for pinctrl. Override only if auto-detection fails |

Raspberry Pi 5 Notes

The Pi 5 uses the RP1 I/O controller which breaks compatibility with older GPIO libraries (e.g. rpio, pigpio, onoff). This plugin works correctly on Pi 5 because it uses the gpiod command-line tools which support the modern /dev/gpiochip* interface.

Key differences on Pi 5:

| | Pi 4 | Pi 5 | |---|---|---| | GPIO chip | gpiochip0 | gpiochip0 | | GPIO interface | /sys/class/gpio or /dev/gpiochip0 | /dev/gpiochip0 only (sysfs removed) | | gpiod version | v1 (Bullseye) or v2 (Bookworm) | v2 (Bookworm) | | Pull resistors | raspi-gpio or pigpio | pinctrl |

This plugin auto-detects all of the above at startup. You'll see log lines like:

[Garage Door] Auto-detected GPIO chip: gpiochip0
[Garage Door] gpiod syntax: v2 (default)  chip: gpiochip0  sensor cmd: gpioget -c gpiochip0 23

If auto-detection picks the wrong chip, add "gpiochip": "gpiochip0" (or the correct chip name) to your config to force it.

Wiring

Relay (door trigger)

• Connect the relay signal wire to the GPIO pin specified by doorRelayPin.
• Connect relay COM/NO terminals in parallel with the garage door button.

Door Sensor (optional but recommended)

• Connect one leg of the sensor to the GPIO pin specified by doorSensorPin.
• Connect the other leg to ground (if using input_pull: "up") or to 3.3V (if using input_pull: "down").

Important: This plugin uses BCM GPIO numbers — NOT physical board pin numbers. Use the table below to find the correct value for your config. GPIO is accessed via the gpiod system tools (gpioget/gpioset), which work on all Pi models including Pi 5.

Migrating from rpio (old plugin version)?

If you were previously using this plugin with rpio, your config used physical board pin numbers. You must convert them to BCM numbers:

| Old rpio config value (physical pin) | New BCM config value | |:---:|:---:| | 11 | 17 | | 12 | 18 | | 13 | 27 | | 15 | 22 | | 16 | 23 | | 18 | 24 | | 19 | 10 | | 21 | 9 | | 22 | 25 | | 23 | 11 | | 24 | 8 | | 26 | 7 |

For any pin not listed, use the full GPIO Pin Map below.

GPIO Pin Map: Physical Board vs BCM

The Raspberry Pi header has 40 physical pins. Only the GPIO pins are usable — use the BCM column in your config.json.

Physical  BCM  |  Physical  BCM
Pin   1   3.3V |  Pin   2   5V
Pin   3     2  |  Pin   4   5V
Pin   5     3  |  Pin   6   GND
Pin   7     4  |  Pin   8   14
Pin   9   GND  |  Pin  10   15
Pin  11    17  |  Pin  12   18
Pin  13    27  |  Pin  14   GND
Pin  15    22  |  Pin  16   23
Pin  17   3.3V |  Pin  18   24
Pin  19    10  |  Pin  20   GND
Pin  21     9  |  Pin  22   25
Pin  23    11  |  Pin  24    8
Pin  25   GND  |  Pin  26    7
Pin  27     0  |  Pin  28    1
Pin  29     5  |  Pin  30   GND
Pin  31     6  |  Pin  32   12
Pin  33    13  |  Pin  34   GND
Pin  35    19  |  Pin  36   16
Pin  37    26  |  Pin  38   20
Pin  39   GND  |  Pin  40   21

Common examples:

| Physical Pin | BCM GPIO | Use in config | |:---:|:---:|:---| | 11 | 17 | "doorRelayPin": 17 | | 13 | 27 | "doorSensorPin": 27 | | 15 | 22 | "doorRelayPin": 22 | | 16 | 23 | "doorSensorPin": 23 | | 18 | 24 | "doorRelayPin": 24 | | 22 | 25 | "doorSensorPin": 25 |

Tip: You can also run pinout on the Raspberry Pi terminal for a live visual diagram of your board.

Running Homebridge

Start Homebridge normally — the plugin will be loaded automatically:

homebridge

Or with the service manager (if configured as a service):

sudo systemctl start homebridge

To view logs:

sudo journalctl -fu homebridge

Troubleshooting

• "You must provide a config value for 'doorRelayPin'" — Ensure doorRelayPin is set in your config.json.
• "You must provide a config value for 'doorSensorPin'" — Ensure doorSensorPin is set in your config.json.
• Relay fires but door doesn't move — Check your wiring and try toggling invertDoorState.
• Sensor always shows wrong state — Try toggling invertSensorState or changing input_pull.
• Permission denied on GPIO — Run Homebridge as root or add the user to the gpio and dialout groups: sudo usermod -aG gpio,dialout $USER. The gpiod tools typically require either root or membership in the gpio group.
• Wrong chip number — Run gpiodetect on the Pi to list available chips. Pi 5 with Bookworm reports gpiochip0 [pinctrl-rp1]. Force it with "gpiochip": "gpiochip0" in your config.
• gpioget: command not found — Install the gpiod tools: sudo apt install gpiod (usually pre-installed on Bookworm/Pi 5).
• Pin numbering — Always use BCM numbers, not physical board pin numbers. Physical pin 16 = BCM 23, physical pin 24 = BCM 8.

License

ISC

Author

@skirkpatrick88