search

mjuhanne / fyrtur-esp

ESP32 / ESP8266 based IKEA Fyrtur wireless blinds controller
MIT License
61 stars 7 forks source link

readme

IKEA Fyrtur roller blind WiFi module firmware

Introduction

This is a firmware for custom ESP32 / ESP8266 based WiFi module that can be used to control IKEA Fyrtur and Kadrilj roller blinds.

First, why would one want to re-invent the wheel and replace the Ikea wireless module?

There also exists a custom firmware for the Fyrtur motor module that makes it possible to have more finer control of the motor unit along with several enhancements:

For more information about the custom firmware and the motor board itself (including reverse engineered schematics), please see the motor module page.

Wiring

There are many ways one can install the module. Probably the easiest way is to modify the original main board:

Custom PCB

There is also a custom PCB that replaces the original Fyrtur main board. It's been designed to hold ESP12F (ESP8266 SMT module) along with the usual reset paraphernalia. Alternatively one can use it as an interface board. In the latter case a separate ESP32 or ESP8266 module (DevkitC for example) can be connected to the motor, LED and buttons via the interface board.

Fyrtur custom PCB

Installation

In the current state it is recommended to use ESP32 since ESP8266 might not have enough memory to handle all the operation scenarios (especially when WiFi/MQTT manager Access Point is up) and its behaviour can be thus erratic at times. This might change in the future if the memory usage can be optimized significantly.

SDK

Install the ESP32 SDK (esp-idf) by following the steps on the installation page. Make sure you can build and deploy an example project before continuing further.

Compiling and deployment

Install the fyrtur-esp main program and its dependencies. The required components are shared by other home automation/ESP projects as well, so please create a directory layout as describe below:

mkdir iot
cd iot
git clone https://github.com/mjuhanne/fyrtur-esp.git
mkdir components
cd components
git clone https://github.com/mjuhanne/node-framework.git
git clone https://github.com/mjuhanne/esp-wifi-manager.git
git clone https://github.com/mjuhanne/esp-si7021.git
git clone https://github.com/mjuhanne/idf-stm-flash.git

Chdir to fyrtur-esp directory and build the application (use default menuconfig settings). Then deploy the application while monitoring the debug console for any possible errors.

idf.py menuconfig
idf.py app
idf.py -p /dev/tty.SLAB_USBtoUART flash monitor

The port may vary depending on the operating system and the ESP32 variant you have.

Configuration

Fyrtur module will create an Access Point with a custom web portal which can be used to configure the home network WiFi AP well as the MQTT server. The AP name is "Fyrtur-xxxxxx", where xxxxxx is the last 6 digits of ESP32 WiFi module MAC address. This variation is done because we want to distinguish one Fyrtur node from another. Password to the AP is by default 'esp32pwd' but that can be configured via menuconfig. Connect to the AP and access http server at 10.10.0.1. Use the interface to first connect to the target Access Point and then configure the MQTT server. The Fyrtur Access Point will shutdown after 1 minute of successful configuration. AP can be restarted via MQTT interface, pressing UP and DOWN buttons for > 2 seconds, or by doing factory reset (see below).

Usage

When first powered, the motor module does not know the current curtain position, so curtains are calibrated by rolling them up until motor starts stalling. Fyrtur blinds can then be controlled manually by using the buttons or via MQTT protocol. Button interface is usable even when the module is not yet configured and/or the wireless link to home automation system is down.

Button interface

LED signaling

MQTT interface

(In the examples below "fyrtur-e975c1" is just a sample node name)

Curtain position

Fyrtur-esp will publish curtain position with an outgoing MQTT topic:

/home/cover/fyrtur-e975c1/position

Remote control

Fyrtur-esp supports controlling the curtain with following incoming MQTT topics:

For more information about the maximum/full curtain lenghts and curtain position calibration, the best source is currently the custom Fyrtur motor module firmware documentation

Other MQTT remote control topics:

Node configuration via MQTT

Fyrtur-esp supports also configuring additional settings. These will be stored into the non-volatile EEPROM/FLASH of either ESP32/8266 or the STM32 based motor module.

Temperature and humidity sensor

If Fyrtur-esp detects the external SI7021 / HTU21D temperature and humidity sensor, it will broadcast its measurements with following topics:

The default broadcast interval is 10 seconds. This can be configured with MQTT:

MQTT Discovery

Home Assistant supports MQTT Discovery, which facilitates the detection of the Fyrtur curtains without explicit configuration of each individual Fyrtur node. Note that MQTT Discovery has to be enabled first in Home Assistant configuration. When connection to MQTT server is made, an announcement message is published that declares the node and its affiliated command and status MQTT topics. In the case of Fyrtur curtains, the Home Assistant integration we are using is MQTT Cover with a device class (a component subtype) "blind".

Example with a node name "fyrtur-e975c1":

/home/cover/fyrtur-e975c1/config

with JSON payload:

{    
    "name": "fyrtur-e975c1",
    "unique_id": "fyrtur-e975c1",
    "device_class": "blind",     
    "command_topic": "/home/control/fyrtur-e975c1/command",
    "position_topic": "/home/cover/fyrtur-e975c1/position",
    "set_position_topic": "/home/control/fyrtur-e975c1/set_position",
    "position_open": 1000
}

If SI7021 / HTU21D temperature and humidity sensor is detected it will be announced as well:

/home/sensor/fyrtur-e975c1/temperature/config

with JSON payload:

{    
    "name": "fyrtur-e975c1 temperature",
    "device_class": "temperature",
    "state_topic": "/home/sensor/fyrtur-e975c1/temperature"
}

and

/home/sensor/fyrtur-e975c1/humidity/config

with JSON payload:

{    
    "name": "fyrtur-e975c1 humidity",
    "device_class": "humidity",
    "state_topic": "/home/sensor/fyrtur-e975c1/humidity"
}

Using Ikea Fyrtur remotes

Since ESP32/8266 doesn't have support Zigbee protocol the original remotes cannot be used to control the blinds directly. However they can be still utilized using Zigbee2MQTT with a suitable Zigbee adapter or Samsung SmartThings Hub via SmartThings MQTT Bridge. The latter is pretty complicated and cannot be forced into local use without cloud / internet access.

Pair the Ikea remotes (or other remotes if you wish) with the Zigbee hub/router and configure them to send MQTT messages as below to simulate the original remote functionality:

/home/control/[node name]/button/[button number]/state  (payload: pushed/held/released)

Another method is to setup a custom MQTT topic that the module with subscribe to:

/home/control/[node name]/set/button_topic  (payload: MQTT topic)

e.g.

/home/control/fyrtur-kitchen-1/set/button_topic  (payload: /home/zigbee2mqtt/ikea_remote_1/state)

Module will then subscribe to /home/zigbee2mqtt/ikea_remote_1/state and will scan for "open", "close" and "stop" keywords in the payload and act accordingly.

Currently double-click or long-press are not yet supported so (re)setting lower limit or slow movement commands are to be achieved with physical buttons on the blinds (or the related MQTT messages).

ESP32 module OTA update

The node-framework supports OTA updates via HTTP. The process is initiated with a MQTT topic:

When process is started, LED will stay on until OTA update is complete. The module is rebooted automatically after successful update. If OTA update failed, LED will blink 5 times quickly, repeated by 3 times.

Note that the OTA update procedure currently supports only non-secure HTTP! HTTPS support would require providing the Fyrtur module with at least a root certificate of a root certificate authority (a public one or one that you created yourself). Uploading the certificate could be done via Access point in configuration stage (this would need additional changes to the esp-wifi-manager). This same certificate could be used to enable SSL support for MQTT server as well.

STM32 module OTA update

Starting from motor module firmware version 0.80 it's possible to update its firmare using only the existing UART wiring. However if the motor module contains earlier version (or the original Ikea firmware), one must disassemble the motor unit anyway and use ST-Link via Serial-Wire Debug interface to flash the newest firmware. Only after that are subsequent OTA updates possible.

Updates are done by downloading the firmware file from HTTP server and then checking the file integrity with MD5 checksum. Updating is initiated with MQTT topic:

OTA process can be following from topic /home/node/[node-name]/stm32ota and more detailed log from /home/node/[node-name]/stm32ota_log

When process is started the LED will stay on until OTA update is complete. If OTA update failed, LED will blink 5 times quickly, repeated by 3 times.

Warning! It's possible to brick your motor module if the OTA update is interrupted half-way. The only way to recover from this is then to re-flash the firmware using SWD interface. For this reason it is recommended that when you are taking the time to disassemble the motor unit for the first time to flash the custom firmware, you also should route the SWD wires outside the motor unit enclosure in order to avoid dismantling the whole Fyrtur setup again :)