Garage Door - WizBangCrash/esp-homekit-devices GitHub Wiki

A HomeKit Garage Door accessory. This can be used to manage your garage door driver, or be a stand-alone fully working driver.

If you don't use a sensor, or use only one, Door Working Time will be used to determine door state. If you use both sensors (for open and close: "f2" to "f5"), Door Working Time will be used as a security measure alerting when an obstruction is detected if the door does not complete operation before the working time expires. If you also define an Obstruction Detection Time then the sum of the Working Time and Obstruction Detection Time is used.

When an obstruction is detected, the door cannot be operated until the obstruction is removed.

Type Device Type
40 Garage Door

The following configuration is available for garage doors:

Section Key Description
Actions "0", "1" etc. The actions performed by the accessory
Digital Inputs "b" GPIOs that invoke specific actions
State & Status Inputs "f[n]" & "g[n]" Inputs that manage accessory state
Accessory Notifications "m" Notifications to send to another accessory
Initial State "s" State a garage door accessory enters on boot
Door Opening Time "d" Time door takes to open
Door Closing Time "c" Time door takes to close
Obstruction Detection Time "e" Time allowed to detect door obstruction

Garage Door Example

{
  "c":{"l":13,"b":[{"g":0,"t":5}]},
  "a":[{
    "t":40,
    "d":18,
    "0":{"r":[{"g":12,"v":1,"i":0.5}]},
    "1":{"a":0},
    "2":{"r":[{"g":12,"i":1.5},{"g":12,"v":1,"i":0.5},{"g":12,"v":1,"i":2}]},
    "3":{"a":2},
    "f3":[{"g":14,"t":0}],
    "f4":[{"g":14}]
  }]
}

This is an example of a device used to control a garage door ("t":40). The door takes 18 seconds to open ("d":18).

The four key actions are defined; Door is opened and receives closing order ("0"), door is closed and receives opening order ("2"), door is opening and receives closing order ("2") & door is closing and receives opening order ("3").

The door control is done using GPIO 12 and actions "1" & "3" are duplicates of actions "0" & "2" respectively (see Copy Action).

When the door is fully closed "f3" is triggered and then the door is fully open "f4" is triggered. GPIO 14 is used to indicate this state.

Actions

A garage door has a number of actions as documented below:

Key Action Description
"0" Close an open door Handle request to open a closed door
"1" Open a closed door Handle request to close an open door
"2" Close an opening door Handle changing direction of opening action
"3" Open a closing door Handle changing direction of closing action
"4" Opened door detected Handle door has opened
"5" Closed door detected Handle door has closed
"6" Opening door detected Handle door opening
"7" Closing door detected Handle door closing
"8" Obstruction removed Handle the removal of an obstruction
"9" Obstruction detected Handle the detection of an obstruction
"10" Emergency stop Handle an emergency stop

The Digital Outputs "r": [{}] for each should be configured to attain the desired state.

Door Opening Time

The door opening time is defined by the "d" key contained within the accessory object.

Key Value Description
"d" 30 Door takes 30 seconds to open (default)
1 - 65535 Integer value specifying number of seconds

This option specifies the time needed for the garage door to completely open. It is an integer (no decimals).

Door Closing Time

Door Closing Time was introduced in firmware version 1.0.0

The door closing time is defined by the "c" key contained within the accessory object. If this key is not declared, the door opening time value will be used i.e. the value from the "d" key.

Key Value Description
"c" 1 - 65535 Integer value specifying number of seconds

This option specifies the time needed for the garage door to completely close. It is an integer (no decimals).

Obstruction Detection Time

Obstruction detection time was introduced in firmware version 0.8.7

Obstruction detection time is defined by the "e" key contained within the accessory object.

Key Value Description
"e" 0 Door obstruction detection disabled (default)
1 - 65535 Integer value specifying number of seconds

This option specifies the time allowed for the garage door to detect an obstruction when door open/close sensors are used. It is an integer (no decimals).

By default this option is disabled. When enabled the timer begins once the Door Working Time has expired. The accessory then has the defined number of seconds to report an obstruction is detected.

Accessory Notifications

The list of notifications "m" supported by a garage door are as follows:

Value Notification
0 Door open (default)
1 Door close
2 Emergency stop
3 Obstruction removed
4 Obstruction detected

See the general Accessory Notifications section for details of how to configure these notifications.

Digital Inputs

Digital Inputs "b" are supported by this accessory.

See Digital Inputs for details on how to define this mandatory option.

State and Status Inputs

State inputs "f[n]" & Status Inputs "g[n]" are supported by this accessory. The supported list is:

Key Required State
"f0" Set garage door to open
"f1" Set garage door to close
"f2" Indicates that garage door is open
"f3" Indicates that garage door is closed
"f4" Indicates that garage door is opening
"f5" Indicates that garage door is closing
"f6" Indicates that there is not obstruction
"f7" Indicates that there is obstruction
"f8" Emergency stop

Refer to State Inputs for more detail and examples.

ICMP Ping Inputs

ICMP Ping inputs "p[n]" and "q[n]" are supported by this accessory. Refer to ICMP Ping Inputs for more detail.

Initial State

The Initial State key is supported by this accessory. Refer to Initial State for more details.

Key State Description
"s" 0 Open
1 Closed (default)
5 Last state before restart
6 Opposite to last state before restart