Chicken coop board

ChickenDoors - ESP32 Kerbl Smart Coop Controller

An open-source MicroPython project for an ESP32 designed to control Kerbl automatic chicken doors and integrate them seamlessly into Home Assistant via MQTT Discovery.

Kerbl doors provide a safe mechanism that protects poultry houses from nocturnal predators like foxes and martens. This project upgrades that reliable hardware with custom limit switch feedback, and full smart home control.

Features

• Kerbl Door Compatibility: Interfaces directly with Kerbl chicken doors, which safely operate vertical sliders weighing up to 2.5 kg.
• Home Assistant Integration: Fully supports MQTT Discovery. Switches, buttons, and limit sensors auto-populate in Home Assistant.
• Custom PCB (KiCad): KiCad files are included in this repository so you can manufacture your own clean, dedicated control board.
• Hardware Watchdog & Soft Recovery: Uses the ESP32 hardware WDT and socket timeouts to automatically recover from silent network freezes or MQTT broker disconnects.
• Limit Switch Feedback: Real-time physical door state feedback published every 5 seconds.

Hardware & Pin Configuration

Components Needed

• Custom Control PCB (See the included KiCad files in this repository) or an ESP32 dev board with relay modules
• Kerbl Automatic Chicken Door hardware
• 4-Channel Relay Module (Active-Low)
• 2x Limit Switches

Custom PCB

The included KiCad files allow you to manufacture a custom PCB with the following components:

• ESP32-C6-MINI-1U chip
• PC817 optocouplers to trigger the doors
• AC input with 5V and 3.3V regulators
• Direct 5V power for the Doors including physical switches to turn of the power to the doors
• PC817 optocouplers to read power status of the doors
• UART Programming header for flashing the ESP32

You can also switch out the ESP32-C6-MINI-1U for a ESP32-C6-MINI-1 if you want an integrated antenna.

Wiring / Pinout

The ESP32 relays interface with the Kerbl door's external button inputs, which use a normally open contact each for Up and Down movements.

RTC (DS3231)

• I2C SDA: GPIO 21
• I2C SCL: GPIO 22
• SQW/INT: GPIO 14 (Configured as input with pull-up)

Relays (Active-Low)

• Door 1 Lock (Down): GPIO 32
• Door 1 Unlock (Up): GPIO 33
• Door 2 Lock (Down): GPIO 25
• Door 2 Unlock (Up): GPIO 26

Limit Switches

• Door 1 Limit: GPIO 16 (Active-low with internal pull-up)
• Door 2 Limit: GPIO 17 (Active-low with internal pull-up)

Indicators

• Beeper: GPIO 13
• Status LED: GPIO 2 (Built-in LED on most dev boards)

Installation & Setup

1. Flash MicroPython

Ensure your ESP32 is flashed with the latest standard MicroPython firmware.

2. Clone the Repository

git clone [https://github.com/yourusername/ChickenDoors.git](https://github.com/yourusername/ChickenDoors.git)
cd ChickenDoors

3. Configure Network (WiFi)

Open esp_root/boot.py and update your WiFi credentials:

WIFI_SSID = "YourWiFiSSID"
WIFI_PASSWORD = "YourWiFiPassword"

4. Configure MQTT and Home Assistant

1. Rename config.example.py to config.py.
2. Edit config.py to set your MQTT broker details and Home Assistant discovery prefix:

MQTT_BROKER = "192.168.1.100"
CLIENT_ID = "chicken_coop_1"
MQTT_USER = "your_mqtt_user"
MQTT_PASS = "your_mqtt_pass"
HA_DISCOVERY_PREFIX = "homeassistant"

5. Upload Files to ESP32

Upload the contents of the esp_root folder to the root of your ESP32.

MQTT API

Home Assistant will auto-discover all entities. However, if you wish to integrate this with Node-RED, openHAB, or a custom script, you can use the raw MQTT topics. Command Topics:

• home/chicken/lock: Payload 1 or 2 locks (closes/down) door 1 or 2.
• home/chicken/unlock: Payload 1 or 2 unlocks (opens/up) door 1 or 2.
• home/chicken/sync: Any payload triggers an NTP time sync and resets alarm timers.
• home/chicken/active/1: Payload ON or OFF activates/deactivates door 1 (software block).
• home/chicken/active/2: Payload ON or OFF activates/deactivates door 2 (software block).

State / Telemetry Topics:

• home/chicken/active_state: Publishes block states: {"door1":"ON","door2":"OFF"}
• home/chicken/limit_status: Publishes switch states every 5 seconds: {"s1":1,"s2":0} (1 = Pressed, 0 = Not Pressed)

Troubleshooting & Crash Logs

The firmware is designed for maximum uptime. If a critical failure causes the main loop to crash, the ESP32 will write the stack trace to error.log in the root filesystem before resetting itself. To debug a crashed device:

• Connect via USB/Thonny.
• Open error.log.
• Read the Python traceback to identify the failure point.