Introduction: Apple HomeKit WS2812B LED Controller

By GitHub page
About: I'm developing ESP8266 and ESP32 based  HomeKit projects including software and hardware solutions!

There are a lot of projects based on WS2812B LED strips out there, but most of these are using homebridge or any other solution - mostly based on MQTT - to communicate with HomeKit.

Some projects are using effects via Apple HomeKit too, but none of them supports standalone HomeKit without needing any bridge I'm using WS2812B LEDs nearly 3-4 years now with HomeKit and they are working very well

Since the code is very complex and i've used a lot of custom libraries I've made pre-compiled firmware files. For those who interested in making native HomeKit projects, the source code for esp-homekit available here.

Basic Informations:

  • Currently only WS2812B, WS2812B ECO and WS2813 LED strips are supported!
  • Maximum number of LEDs are limited to 500 for saving RAM
  • Logic Level converter required (for 3.3V to 5V data conversion)
  • Good quality 5V power supply is necessary too
  • More information can be find on my GitHub
  • Adafruit Überguide can also help :-)


PCB Design:

I've designed a simple PCB for driving the NeoPixel LEDs the proper way described in Adafruit's NeoPixel Überguide using the latest SN74HCT125N Logic Level Converter IC and the also recommended 1000uF capacitor :-) I'm currently using this PCB with a 5V 10A power supply without any (temperature) issues :-)

Also i have an USB Type-C version too for shorter LED strips!

You can order the PCBs from here and here!

You can find more information about the PCBs here!

Features:

  • Change Color
  • Change Brightness
  • Change Color Temperature (no RGBW strip required)
  • WS2812FX Light Effects(beta!!!)
  • Setting up WS2812B LED count(on first boot from 1 to 500)
  • Power Behaviour characteristic (Default Color / Last Used on startup via Eve app)
  • Transition(Quick / Default / Moderate / Calm via Eve app)
  • Child Lock (Enable/Disable button press via Eve app)
  • Downloadable User Manual (via Eve app)
  • Power / Reset button

Supplies

For creating the custom PCB You'll need a cheap Soldering Iron, or a Soldering Station like this one or this one. Also a Hot Air Soldering Gun would be helpful too! For uploading the code you probably have to buy an USB TTL adapter too.

Necessary Parts:


PCB Parts:

Step 1: Installing the Firmware

You can download the firmware from my GitHub page!

Windows

For Windows you can use the official Firmware Download Tool by Espressif!

Setting the flash addresses (0x2000), flash size (1MB/8mbit, 4MB/32mbit) and flash mode (DIO/QIO) is very important step, but these settings may changed based on the module you're using! Also I've recommend to erase the flash before uploading the .bin files!

Settings:

  • Baud rate 115200
  • Flash size 4MB or 32mbit (depending on your module)
  • Flash Mode QIO (or DIO, depending on your module)
  • 0x0000 rboot.bin
  • 0x1000 blank_config.bin
  • 0x2000 ledstrip.bin
  • 40MHz

MacOS

For MacOS you can use this flasher tool!

Settings:

  • Erase flash - yes
  • Baud rate 115200
  • Flash size 4MB or 32mbit (depending on your module)
  • Flash Mode QIO (or DIO, depending on your module)
  • File: ledstrip.bin
  • 40MHz

Manually Flash

We have to install esptool.py on our Mac in order to be able to flash our ESP module. To work with esptool.py, you’ll need either Python 2.7, Python 3.4 or a newer Python installation on your system. We recommend using the latest Python version, so go to Python’s website and install it in your computer.

With Python installed, open a Terminal window and install the latest stable esptool.py release with pip:

pip install esptool


Note:with some Python installations that command may not work and you’ll receive an error. If that’s the case, try to install esptool.py with:

pip3 install esptool python -m pip install esptool pip2 install esptool

After installing, you will have esptool.py installed into the default Python executables directory and you should be able to run it with the command esptool.py. In your Terminal window, run the following command:

esptool.py

With esptool.py installed on your computer, you can easily flash your ESP8266 board with the firmware.

At first you need to download three bin files: rboot.bin and blank_config.bin and the latest release. The rboot.bin contains the bootloader for the ESP8266 and the blank_config.bin in just a blank config file and ledstrip.bin contains the firmware. Now connect your device to your FTDI adapter in flash-mode.

Mirror links:


rboot.bin
blank_config.bin
ledstrip.bin

Putting Device Into Flash Mode

To enable ESP8266 firmware flashing GPIO0 pin must be pulled low while powering the device. With my custom PCB theres a button, nodeMCU also has a flash button and the Wemos does it automatically using USB. Conversely, for a normal boot, GPIO0 must be pulled high or floating. Start in FLASH MODE

Go to the directory you made where you put the previously downloaded rboot.bin blank_config.bin files (e.g Downloads)

Open the Terminal app. Click the Finder icon in your dock. Click Go. Click Utilities. Double-click Terminal. Change to the downloads directory.

You'll need an USB TTL adapter for connecting to the ESP8266. If You using a Wemos D1 Mini only needed is a microUSB cable, the Wemos has TTL adapter built-in.

cd downloads

Note: If You using an another library for storing the three .bin files, navigate into that library using `cd` command:

Use esptool.py to flash your device. First we need to erase the flash:

esptool.py -p /dev/ erase_flash

Normally, your ESPPort will be something like /dev/cu.usbserial-`xxxxxx`. Then, set your device in flash-mode again, and flash the new firmware:

esptool.py -p /dev/cu.wchusbserial1420 --baud 115200 write_flash -fs 32m -fm dio -ff 40m 0x0 rboot.bin 0x1000 blank_config.bin 0x2000 ledstrip.bin

Step 2: Wi-fi and HomeKit Setup

Wi-Fi Setup

You must configure wifi network before adding the accessory to HomeKit. To configure Wi-Fi settings, device generates its own Wi-Fi in AP mode. You must connect to it in order to setup your Wi-Fi network.

Simply take your iOS device, go to Setting -> Wi-Fi, and search for an SSID called HomeKid- followed by the module's MAC address and connect to it. For security reasons the AP is password protected!

Default AP password: 12345678


Wait a few seconds until a web appears showing you all Wi-Fi networks that the device has found. Select yours, and enter password! After that you can add the exact number of LEDs in your LED strip! Enter a number from 1 to 500! Then click the Join button! The module will try to connect the selected Wi-Fi network, this will take a couple of seconds.

Note: If the given password is wrong, you can Reset the Wi-fi settings by holding the Reset button for 10sec


HomeKit Setup


In your iOS device, open Home App and follow normal steps to add a new accessory.
Pairing setup takes about 30 seconds.

Default HomeKit code is 021-82-017.


Also You can scan this HomeKit QR code:

Note: If pairing fails, you can unpower your device, repower it, and start HomeKit setup again (Wifi settings keep configured). After successful pairing the LED strip will flashing white 3 times!

Common issues:

  • Sometimes adding multiple accessories using QR code fail, if HomeKit reports "Accessory already added" simply just add the pairing code manually instead of scanning the QR code!
  • In case something went wrong you can see the log files using Arduino's serial monitor and fell free to open an issue on GitHub

Step 3: Custom Settings

Sadly the Home app doesn't support custom/3rd party characteristics so you'll need the Elgato EVE app for changing these setting and using the WS2812B effects. Also the accessory is acting like a Fake Eve Light Strip accessory when you add it via the Eve app 😄

Transitions and Power Behaviour

The original Eve Light strip supports these two characteristics. With Transitions you can change the speed of the LED strip when using WS2812FX Effects! Setting it to Quick will disable fading in/out and it will quickly turn on!

With Power Behaviour you can change default color when the LED strip turn on! By default it is set to Last Used Color, so when you turn off the LED strip it will always remember the last color you used! When set to Default White, each time you turn off the LED strip, color will go back to White!

Reset

The code has a Reset function in case of something goes wrong. Wait about 5 seconds to allow device to boot completely, and then long press the button for at least 10sec!

All configured settings has been removed and device is restarting. This removes HomeKit and Wi-Fi settings, and your device will go to Access Point mode next time in order to reconfigure Wi-Fi.

Note: Single pressing the same button will toggle the LED strip ON or OFF