homebridge-grumptechgaragedoor v1.0.6
GrumpTech Garage Door
A plug-in component for Homebridge that provides control and status of one or more garage doors using a Raspberry PI. (some assembly required)
To provide some measure of security, preventing unintended opening/closing of the doors, a software lock will prevent control of the door. The lock is enabled by default and the state of the lock is not preserved between sessions. (Refer to the Limitations and Known Issues section below)
GrumpTech Garage Door supports both a proximity switch and sonar based sensors to detect the state of the door.
Installation
This module is not intended to provide an extensible API.
npm i homebridge-grumptechgaragedoor
Configuration
The plug-in allows for user specified configuration of the digital input/output lines to use as well as the type of sensors to use for detecting the door. The config_sample.json file located in ./config shows an example of many of the user configurable settings.
Bridge(bridge)
| Key | Description | Value(s) | Default(s) | Remark(s) |
|---|---|---|---|---|
username | Identifier in the form of a globally-unique colon-delimited EUI-48 multicast MAC address. | MAC Address | Takes the form (xx:xx:xx:xx:xx:xx) |
Platforms(platforms)
Settings for the GrumpTech Garage Door platform.
| Key | Description | Value(s) | Default(s) | Remark(s) |
|---|---|---|---|---|
platform | Identifier for the name of the Homebridge platform. | Any valid non-null string | GrumpTechGarageSystemPlatform | Must match the text in the config_info/platform entry of the package.json file.Recommended to leave as-is.Rebuild required if changed. |
name | Identifier for the name of the Homebridge plug-in. | Any valid non-null string | homebridge-GrumpTechGarageSystem | Identifier for the name of the Homebridge plug-in. Must match the text in the config_info/plugin entry of the package.json file.Recommended to leave as-is.Rebuild required if changed. |
System(platforms/platform/system)
Settings used to define & configure the garage door system.
| Key | Description | Value(s) | Default(s) | Remark(s) |
|---|---|---|---|---|
gpio_mode | (Optional) Specify the pin numbering system to use for identifying & accessing the digital input/output resources on the Raspberry Pi. | BCM, RPI | BCM | Refer to the rpi-gpio node module for more documentation.Note: Most development and testing was done using BCM mode |
heartbeat | (Optional) The digital output used to toggle a heartbeat. | Any valid digital output resource on the RPi | 4 (BCM) / 7 (RPI) | Assumed to be connected to a LED or other indicator.Must be specified according to the 'gpio_mode'. |
Doors(platforms/platform/system/doors)
An array of doors in the system.
| Key | Description | Value(s) | Default(s) | Remark(s) |
|---|---|---|---|---|
name | Identifier for the door | Any valid non-null string | Door names must be unique, as they are used internally for identification. | |
state_indicator | The digital output used to show the state of the door | Any valid digital output resource on the RPi | Assumed to be connected to a LED or other indicator.Must be specified according to the 'gpio_mode'. | |
control_request | The digital output used to control a relay that is used to initiate the door open/close operation | Any valid digital output resource on the RPi | Must be specified according to the 'gpio_mode'. | |
manual_control_reqest | The digital input that is used to initiate a door open/close operation from direct hardware access. | Any valid digital input resource on the RPi | Assumed to be a push button or some other form of digital input control.Must be specified according to the 'gpio_mode'. | |
soft_locked | The initial state of the software lock. | true, false | true | (Optional)true indicates that the software lock default to the locked state.Refer to the Limitations and Known Issues section |
Detection Sensors(platforms/platform/system/doors/detect_sensors)
An array of sensors used to detect the state of the door. The plug-in only functionally supports two active sensors. One sensor to detect the door opening and another to detect closing. Additional sensors can be specified even though not active, which can be helpful during development & debug.
| Key | Description | Value(s) | Default(s) | Remark(s) |
|---|---|---|---|---|
id | Unique name identifying this sensor | Any non-null string | The id field is only used for debugging.Uniqueness of the name is not checked or enforced | |
class | Classification/Type for this sensor | SonarSensor, ProximitySwitchSensor | Case sensitive | |
function | Detection function for this sensor | OPEN, CLOSE | Only the first OPEN and CLOSE sensor will be detected. A function other than OPEN or CLOSE will be ignored. Case Insensitive. |
Sensor Configuration(platforms/platform/system/doors/detect_sensors/config)
A collection of configuration settings appropriate for the sensor classification specified.
Sonar Sensors
| Key | Description | Value(s) | Default(s) | Remark(s) |
|---|---|---|---|---|
polling_interval | (Optional) Interval, specified in seconds, over which to measure distance from the sensor | Any positive number greater than or equal to 0.25 seconds. | 5.0 seconds | The minimum bound accounts for the maximum measurement cycle of 60ms-100ms and prevents overlapping trigger requests with the resulting echo signal |
trigger_out | The digital output used to initiate a sonar distance measurement. | Any valid digital output resource on the RPi. | Must be specified according to the 'gpio_mode'. | |
echo_in | The digital input that is used read the echo signal from the sensor, which is used to determine the distance to the object being measured. | Any valid digital input resource on the RPi | Must be specified according to the 'gpio_mode'. | |
distance_threshold_change_notification | (Optional) Distance threshold, specified in meters, which must be exceeded for the sensor to raise a distance_changed event. | Any positive number greater than 0.0 | 0.08 meters | The distance_changed event is not currently used in this application |
detect_threshold_min | Minimum threshold, specified in meters, to define a measurement range for detecting the object. | Any number greater than or equal to 0.0 | Used in conjunction with detect_threshold_max. Distance measurements outside of the defined range will result in the sensor indicating that the object is not detectedMust be less than detect_threshold_max | |
detect_threshold_max | Maximum threshold, specified in meters, to define a measurement range for detecting the object. | Any number greater than 0.0 | Used in conjunction with detect_threshold_min. Distance measurements outside of the defined range will result in the sensor indicating that the object is not detectedMust be greater than detect_threshold_min |
Proximity Sensor
| Key | Description | Value(s) | Default(s) | Remark(s) |
|---|---|---|---|---|
detect_in | The digital input that is used to detect the door state, as defined by the sensor | Any valid digital input resource on the RPi | Must be specified according to the 'gpio_mode'. | |
debounce_time | (Optional) The time, in seconds, to debounce the sensor input | Any number greater than or equal to 1.0 | 1.0 second | This is the time required to see no further signal change after detecting the most recent signal state change |
mode | (Optional) Flag indicating if the switch is configured as normally closed or normally open | true, false | true | true indicates normally closed and false indicates normally open |
Limitations and Known Issues
Some applications may not properly render these accessories by limiting the accessory characteristics presented to the user. Notably, the default Apple Home application for iOS and macOS is among these. At the present time, it is recommended that the Home+ application for iOS by Matthias Hochgatterer (https://apps.apple.com/us/app/home-4/id995994352) be used to control these accessories.
- Software Lock: The Apple Home application for both iOS and macOS does not present the user with the ability to control the lock. To work around this problem, the user may configure the plugin to set the default lock state to unlocked. However, the recommended solution is to use the Home+ application to control the plugin.