homebridge-venuevue-relay

Homebridge plugin for the VenueVue Relay Controller (ESP32). Exposes relays as HomeKit switches and drives as garage door openers.

Features

• Relays → HomeKit Switch (on/off) — only unassigned relays are exposed
• Drives → HomeKit GarageDoorOpener (open/close/stopped) — all drive modes supported
• Drive lockout → HomeKit Lock mechanism on the garage door accessory
• Auto-discovery of relays and drives from the controller
• Polling-based state sync (configurable interval)
• Automatic re-authentication on token expiry

Installation

# From the Homebridge UI: search for "venuevue-relay"
# Or install manually:
npm install -g homebridge-venuevue-relay

For local development / linking:

cd homebridge-venuevue-relay
npm link
# In your Homebridge installation:
npm link homebridge-venuevue-relay

Configuration

Add to your Homebridge config.json under platforms:

{
  "platforms": [
    {
      "platform": "VenueVueRelay",
      "name": "VenueVue Relay",
      "host": "10.23.4.227",
      "port": 80,
      "username": "admin",
      "password": "vvurelay",
      "pollInterval": 5,
      "exposeRelays": true,
      "exposeDrives": true
    }
  ]
}

| Field | Default | Description | |-------|---------|-------------| | host | required | IP or hostname of the relay controller | | port | 80 | HTTP port | | username | "admin" | Login username (leave blank if auth disabled) | | password | "" | Login password | | pollInterval | 5 | State poll interval in seconds (1–60) | | exposeRelays | true | Expose unassigned relays as switches | | exposeDrives | true | Expose drives as garage door openers |

HomeKit Mapping

Relays → Switch

| Relay State | HomeKit | |-------------|---------| | on | Switch On | | off | Switch Off |

Drives → Garage Door Opener

| Drive Position | HomeKit CurrentDoorState | |----------------|------------------------| | open | Open | | closed | Closed | | moving (target=open) | Opening | | moving (target=close) | Closing | | unknown | Stopped |

| Drive Mode | HomeKit Open/Close behavior | |------------|-----------------------------| | single_toggle | Open → relay on, Close → relay off | | single_pulse | Open/Close both send trigger | | dual_relay | Open → open relay, Close → close relay | | dual_pulse | Open → pulse open relay, Close → pulse close relay |

The drive lockout is mapped to the garage door's lock mechanism (secured = locked out).