ESP32 HomeKit Sunshade with Calibration and Weather Protection

This is a complete Apple HomeKit Window Covering accessory for the ESP32-WROOM-32D, built with ESP-IDF v5. It replaces a standard UP, DOWN and STOP switch and adds HomeKit control, capacitive touch buttons, time-based position tracking, calibration and automatic recovery after a power loss. Optional wind, rain and light sensors close the sunshade for you, and restore the position when the weather calms down.

The whole project is open source on GitHub.

High voltage warning

What it does

Hardware

Required

Optional

The BH1750 and SHT3x share one I²C bus, and each optional sensor is switched on separately in idf.py menuconfig.

Wiring

The two relay outputs switch the motor direction. The open relay (GPIO16) feeds motor terminal A, the close relay (GPIO17) feeds motor terminal B, and the common goes to the motor common. Never wire open and close to the same motor terminal at once. The software interlock already prevents both relays from being energised together, but check your wiring anyway.

The firmware drives the relays active-high by default. Many common optoisolated 2-channel modules are active-low. If both relays click on at boot and the motor runs unexpectedly, set ESP_RELAY_ACTIVE_LEVEL to 0 in menuconfig, and always test with the motor disconnected first.

Touch pads

Each capacitive button uses a TTP223 module in momentary, active-high mode between the electrode and the ESP32. The electrode is a copper ring or pad, wired to the TTP223 SIG input, and a shielded cable with the braid to GND runs between pad and module to prevent false triggers. The ESP32 reads the TTP223 output as a normal GPIO input, so its internal touch peripheral is not used.

GPIO pinout

All defaults can be changed with idf.py menuconfig under StudioPieters. Only ADC1 GPIOs (32 to 39) work for the wind sensor, because ADC2 conflicts with WiFi.

Build and flash

git clone https://github.com/AchimPieters/esp32-homekit-Sunshade.git
cd esp32-homekit-Sunshade
idf.py set-target esp32
idf.py menuconfig
idf.py build flash monitor

If idf.py set-target fails with a CMake error, remove the stale build folder first with rm -rf build and run the set-target step again. New to the toolchain? Start with ESP32 HomeKit for total beginners or ESP32 HomeKit Development with ESP-IDF.

WiFi credentials are not stored on the first boot. Use any ESP-IDF provisioning method, for example the esp-idf-prov app on iOS or Android, to set the SSID and password. The device remembers them after that.

First-time setup and calibration

1. Flash the firmware.
2. Provision WiFi.
3. Pair with HomeKit using the QR code or the setup code from menuconfig. The repository ships a default code, so change it before you use the device for real. Changing the code or setup ID needs a new QR code.
4. Calibrate, so the device learns how long your motor takes.

To calibrate, hold the STOP touch pad for 3 seconds. The LED starts blinking rapidly.

• Phase 1: the motor closes for the stored travel time multiplied by 1.5, which makes sure it reaches the end stop. The LED blinks fast.
• Phase 2: the motor opens and a timer runs. The Home app shows the sunshade opening in real time, based on the previous value. When it is fully open, tap STOP once. The elapsed time is saved to flash. The LED blinks slowly.

To update the travel time, for example after replacing the motor, run the calibration again.

Power-loss recovery

After a power loss the device does not know where the sunshade is. If it has been calibrated, it homes in the background on boot: it runs the motor closed for the calibrated time multiplied by 1.5, which ends at the physical end stop and counts as 0 %. It then waits 500 ms, loads the last saved target position and moves there. WiFi and HomeKit start in parallel, and commands are blocked while homing runs.

Every time you command a new position, from HomeKit or the touch buttons, the target is saved. If power fails while the shade is moving from 0 % to 70 %, it closes fully after the reboot and then moves to 70 %. Without calibration the device starts normally and logs a warning.

Controlling it from HomeKit

At 0 % and 100 % the motor runs for the full calibrated time, and the motor’s own end stop gives the final accuracy. Intermediate positions are reached by running a fraction of the calibrated time, so their accuracy depends on how well the calibration matches the real travel time.

Touch pads and physical button

The relays are switched off before any reset or reboot. Inputs are polled every 25 ms by default and debounced over 60 ms, both configurable.

The identify LED is not a HomeKit service. It blinks three times in pairs when HomeKit sends an Identify request, for example while adding the accessory.

Weather protection and sensors

Wind, rain and light protection share one override mechanism: whichever triggers saves the current HomeKit target and restores it when the condition clears. Each sensor is enabled separately in menuconfig.

Wind sensor

The HWFS-1 output reaches 3.3 V at full scale, but the ESP32 ADC is only accurate up to about 2450 mV with 11 dB attenuation. The README therefore uses a voltage divider of 10 kΩ and 22 kΩ, which gives 2.27 V at 14 m/s. The signal wire goes to GPIO34, the ground wire to GND, and no supply voltage is connected. The firmware averages 16 samples per reading, and a 10 kΩ plus 10 µF RC filter on the signal wire is recommended against the ripple of the sensor’s DC generator. Readings at or below 30 mV are reported as 0 m/s.

The README also describes a field calibration: compare the log output with a reference anemometer in steady wind, and adjust WIND_SENSOR_MAX_SPEED_DS until they match.

Rain sensor

VCC goes to 3.3 V, GND to GND, and DO to GPIO35. The analog output is not used, and the sensitivity is set with the potentiometer on the module. Mount the sensing pad under a sheltered overhang so only falling rain reaches it, which extends its life and reduces false triggers.

Light and climate sensors

The BH1750 and the SHT3x (address 0x44 or 0x45) share SDA on GPIO21 and SCL on GPIO22. The GY-302 breakout has pull-ups, and the firmware also enables the ESP32 internal ones. The SHT3x readings appear as HomeKit temperature and humidity tiles only, and do not move the sunshade. Each sample is CRC-8 validated.

Sunrise and sunset automations

No firmware changes are needed. The Home app has built-in sunrise and sunset automations that use the location of your home hub, which needs a HomePod mini, HomePod or Apple TV 4K running continuously and location services on for the Home app. Without a home hub, time-based automations do not run.

Create an automation in the Home app with A time of day occurs, choose Sunrise (optionally with an offset), select the sunshade tile and set the position. Do the same for Sunset with 0 %. The README suggests opening to 80 % at sunrise, to 100 % two hours later, and closing to 0 % half an hour before sunset.

The weather protection in the firmware overrides HomeKit commands while it is active. When it clears, the sunshade goes back to the last position HomeKit commanded, not to an earlier sunrise position.

How position tracking works

There are no limit switches or encoders, so the position is estimated from time. Every 500 ms the movement task adds or subtracts 100 % times 500 ms divided by the calibrated time. HomeKit is notified only when the whole-number position changes, and always when the target is reached.

The mechanical end stop corrects the accumulated error each time the shade reaches 0 % or 100 %. For intermediate positions the README expects an error of 2 to 5 % over many cycles without recalibration. A new command during a move re-syncs the position and immediately changes direction, with the relay interlock making sure the opposite relay is off first.

Troubleshooting

Get the code

The firmware needs ESP-IDF 5.0 up to but not including 7.0, the achimpieters/esp32-homekit component (3.0.0 or newer), achimpieters/esp32-button (1.2.3 or newer) and espressif/mdns (1.8.0 or newer).

Every push runs host unit tests for the pure logic (relay polarity, position maths, sensor conversions, SHT3x CRC and hysteresis), then builds the firmware for the ESP32 on ESP-IDF 5.3.2 and 5.4.1, with and without all optional sensors enabled. The repository has releases up to 0.0.7 with a signed main.bin.

Everything is in the esp32-homekit-Sunshade repository on GitHub.