Chicken Coop Automation: Architecture, Safety & Recovery Runbook

The operating principle

The coop door is an animal-safety system, not merely a convenience automation. Schedules tell it when to try; independent sensors confirm what actually happened; notifications tell a human when the system needs help.

Schedule or manual request → door command → physical movement → end-state sensor → confirmation or alert

Current architecture

The coop controller is a Zigbee device exposed through Zigbee2MQTT/Home Assistant. Its relevant endpoint roles are:

Endpoint	Meaning
EP60	Door control command
EP61	Fully open indication
EP62	Fully closed indication

The Home Assistant entities are represented as DoorControl, DoorOpen, and DoorClosed. Entity IDs can vary with naming/integration migration; use Developer Tools to inspect the exact current state before editing an automation.

Timing is measured, not assumed

A prior issue showed the full-open reed state arriving just after a one-minute check. The verification window was increased to two minutes. Preserve that margin unless fresh measurement proves another value is appropriate.

Physical timing can vary with temperature, battery/power, mechanism friction, debris, and load. A schedule alone is never completion evidence.

Normal operation

Event	Expected outcome
Open schedule	Door command issued; fully-open sensor confirmed within timeout
Close schedule	Door command issued; fully-closed sensor confirmed within timeout
Manual request	Same confirmation/timeout path as schedule
Sensor confirmation	Success notification/log only where useful
Timeout/conflict	High-priority alert and manual inspection path

Safe automation pattern

# Conceptual pattern; replace entity IDs only after live inspection
actions:
  - action: switch.turn_on
    target: {entity_id: switch.coop_door_control}
  - wait_for_trigger:
      - trigger: state
        entity_id: binary_sensor.coop_door_open
        to: "on"
    timeout: "00:02:00"
    continue_on_timeout: true
  - choose:
      - conditions: "{{ wait.completed }}"
        sequence:
          - action: notify.mobile_app_iphone
            data: {message: "Coop door confirmed open."}
    default:
      - action: notify.mobile_app_iphone
        data:
          title: "Coop needs attention"
          message: "Door did not reach confirmed open state within two minutes."

The exact command action must match the controller’s documented behaviour and your current tested automation. Do not change endpoint semantics from a guide alone.

Daily/weekly checks

Daily / after unusual weather:
[ ] Door state is believable in Home Assistant.
[ ] No timeout or unavailable alert.
[ ] Mechanism is clear of obstructions.

Weekly:
[ ] Observe one full open/close cycle when safe.
[ ] Check Zigbee link quality trend and device availability.
[ ] Inspect physical door, reed sensors, cable path, and mounting.

Fault diagnosis

Door did not move

Check power, mechanical obstruction, and manual-control path.
Check Zigbee device availability and link quality.
Inspect the automation trace: did it issue the command?
Confirm the command endpoint/state using Developer Tools.
Do not repeatedly command the motor without observing the mechanism.

Door moved but not confirmed

Inspect reed/magnetic end sensor alignment and state.
Compare timestamps: was the timeout too short, or is sensor state wrong?
Check whether endpoint meaning/inversion has changed.
Test sensor state manually without moving the door if possible.

Zigbee device unavailable

Check the Zigbee2MQTT bridge and coordinator health.
Check power to the controller.
Confirm nearby Zigbee router/mesh conditions.
Avoid repeated re-pair attempts during a time-critical animal-safety event; use manual fallback first.

Manual fallback is mandatory

Keep a practical manual method for opening/closing/securing the door and ensure anyone responsible for the chickens knows it. Automations should make the normal path easier; they must never remove the ability to care for animals during a power, network, or hardware failure.

Change checklist

[ ] Backup/export current automation configuration.
[ ] Test at a safe time while physically present.
[ ] Change one variable only: timing, sensor, command, or notification.
[ ] Observe physical movement and HA trace.
[ ] Confirm both open and close behaviours.
[ ] Keep the two-minute confirmation margin unless measured data supports change.
[ ] Document outcome and any new failure mode.