Sonoff iFan03 using Tasmota and Home Assistant

On the one hand, it seems like everyone who gets one of these iFan03 modules working with Tasmota and Home Assistant puts up a blog post about how they did it. So I will, too. On the other hand, it seems like I had to pull a bunch of blog posts together to figure out how to do it. As with most home automation things, you do it at a point in time and then you leave it alone for a long time. So blog posts were current when they were written, but then technology changes and they become less relevant for someone using a more recent version.

Quick Inventory

Here’s a list of all the stuff I bought to do this project. I was starting from literally nothing. Although I had a soldering iron and some solder, my soldering iron sucked and I knew I’d never do the small soldering that I needed to do. So I bought a new one.

Resources

I didn’t figure this out on my own. I found a few blogs that all contributed in their way. This is the list of blog posts that I used, in order by how useful they were.

Method

Here’s a quick summary of the method. I wrote “quick summary” and then I realise there’s at least 14 important steps here! Start to finish, I did it in an afternoon. By far the biggest time I spent was on Home Assistant making it look right and behave properly.

  1. Buy all the things.
  2. Open up the iFan03 and get the board out
  3. Solder on some pin headers from the variety pack
  4. (For me, anyways) Install the drivers for the CP2102 adapter.
  5. Download a tool for flashing ESP8266 chips. I used espresssif/esptool.
  6. Hook up all the wires from the USB adapter to the iFan03 except the 3.3v wire. (You want to hold down the reset button on the iFan03 when you power it up)
  7. Power it up and test it out a bit. I ran a couple esptool.py commands to make sure I had communications right.
  8. Do the steps to flash the chip.
  9. Connect to the iFan03 over the wifi and configure it.
  10. Disconnect it from my laptop, and reassemble it for installation.
  11. Install it on my fan.
  12. Test it out on the fan by connecting directly to Tasmota over wifi.
  13. Configure Home Assistant
    • Add integrations that you need (e.g., MQTT, Tasmota)
    • Add cards to Lovelace to control your fan
  14. Sit back and relax

Early steps

The early steps of taking the board out of the container, soldering the pins, and flashing are all pretty well covered on Rasmus’s blog post. Do what he says. It’s all very good.

After I got the board set and I installed the drivers for the CP2102 adapter I used espresssif/esptool to talk to it.

flashing using my laptop and tasmota

A Couple Notes on Flashing

To power on the board and put it in the mode that it will talk to esptool.py, you need to press the white button, then plug in the 3.3v lead. Count to 5 seconds, and then release the white reset button.

One thing that caught me by surprise is that each time I ran a esptool.py command I had to power down, and power the board back up to run another command.

I ran esptool.py flash_id just to verify that I got connectivity right.

The process I followed is at the bottom of the Tasmota instructions, but here it is in detail:

  1. Connect the board to the adapter.
  2. esptool.py flash_id to see that I can talk to the controller.
  3. Disconnect and reconnect the board to reset it.
  4. esptool.py read_flash 0x00000 0x100000 fwbackup.bin to make a backup. In case you ever want to roll back to what you started with.
  5. Disconnect and reconnect the board to reset it.
  6. esptool.py erase_flash
  7. Disconnect and reconnect the board to reset it.
  8. esptool.py write_flash -fs 1MB -fm dout 0x0 tasmota.bin
  9. Disconnect and reconnect the board to reset it.
  10. Connect to the device over WiFi to configure it.

Configuring the iFan03 in Tasmota

While it was still running on my laptop (drawing power from the 3.3v line on the USB adapter) I connected to it on http://192.168.4.1/.

First thing I did was go into the Configure Module menu and choose Sonoff iFan03 (71) in the Module type.

tasmota module type iFan03

The information screen is super useful. It shows you a lot of details about how it is operating.

tasmota info screen

Notice the MQTT Topic and Full Topic. This is different from what you see in Rasmus’s blog. That will be important at the very end, when you’re configuring the Lovelace Dashboard.

When I had fully configured it, I disconnected it from my laptop, and reassembled it for installation.

Installing The iFan03 on my Harbor Breeze Fan

I have a “dumb” Harbor Breeze ceiling fan. That is, it doesn’t have any intelligence in it. It has 2 pull chains: one for the fan speed, one for the light. I found the wires for my fan at the top of the post, near the ceiling. You can see it in the photo below. I suppose I could have found those same wires at the bottom of the post, but I didn’t want to open up the fan motor assembly.

Photo of ceiling fan wiring

I didn’t find the wiring diagram from Sonoff particularly useful, because it didn’t include the wiring in the fan itself.

Here’s the wiring that I did when I wired up my fan. Wiring diagram for iFan03 and ceiling fan

I don’t like the look, but I didn’t have access to the space in the ceiling above the drywall above my fan. If I could have put it inside the drywall, I would have. Instead, I ended up sticking it to the ceiling with double-sided tape. It’s uglier than I like, but it’s functional.

Configuring Home Assistant

I run Home Assistant in a Docker container. I didn’t have an MQTT broker running anywhere. So before I could set up the Tasmota fan, I installed Eclipse Mosquitto in a Docker container.

Then I could install MQTT and Tasmota in Home Assistant.

I called my Tasmota fan master-fan. Which means that I could go to the MQTT integration, and I could publish on the topic cmnd/master-fan/FanSpeed. Publishing 1, 2, 3 picks fan speeds low, medium, high. Publishing 0 turns the fan off. In Home Assistant, I went to: Configuration → Integrations → MQTT → Configure.

MQTT Example

When I published via my MQTT screen in Home Assistant, the fan did what it should do. That told me I was ready to do the Lovelace integration and make buttons in my dashboards.

Lovelace UI for iFan03

Note that the topic I use for my iFan03 is quite different from what Rasmus used in his blog. His example configuration uses a topic of ifan03-1/cmnd/FanSpeed (his fan was named ifan03-1). In my case the topic is cmnd/master-fan/FanSpeed. I’m not sure how/why this changed since he put his blog post out, but that’s what worked for me. For him, he puts his fan name first, then cmnd. For me, I put cmnd first, then my fan name. I’m new to all this and I’m just making it up as I go along. I figured this out by downloading MQTT Explorer and hooking it up to my MQTT broker on my Raspberry Pi.

I did not use Rasmus’s code in his configuration.yaml for Home Assistant. That wasn’t necessary for me.

Cards in Lovelace

Here’s the cards that I use in Lovelace. Go to Configuration → Lovelace Dashboards and find the dashboard where you want to work. I created a new dashboard called Fan while I figured this out. Later, when I had a card I liked, I copied it to my main Lovelace dashboard.

To use this code, create a new card, then choose to edit the YAML manually. Copy/Paste the code below.

Code

type: grid
cards:
  - type: button
    tap_action:
      action: call-service
      service: mqtt.publish
      service_data:
        topic: cmnd/master-fan/FanSpeed
        payload: '0'
      target: {}
    entity: fan.master_fan
    hold_action:
      action: none
    name: 'Off'
    icon: 'mdi:stop-circle-outline'
  - type: button
    tap_action:
      action: call-service
      service: mqtt.publish
      service_data:
        topic: cmnd/master-fan/FanSpeed
        payload: '1'
      target: {}
    entity: fan.master_fan
    hold_action:
      action: none
    name: Low
  - type: button
    tap_action:
      action: call-service
      service: mqtt.publish
      service_data:
        topic: cmnd/master-fan/FanSpeed
        payload: '2'
      target: {}
    entity: fan.master_fan
    hold_action:
      action: none
    name: Med
  - type: button
    tap_action:
      action: call-service
      service: mqtt.publish
      service_data:
        topic: cmnd/master-fan/FanSpeed
        payload: '3'
      target: {}
    entity: fan.master_fan
    hold_action:
      action: none
    name: High
  - type: button
    tap_action:
      action: toggle
    entity: light.master_fan
    name: Light
    hold_action:
      action: none
square: false
columns: 5

What it Looks Like

MQTT Example

Some Points

Home Assistant understands “fans” as objects, but I was confused as to how to use it with the iFan03. There are notions of “presets” and there is a notion of fan speed as a percentage, but that didn’t line up with what I was seeing. I post a 3 to the cmnd/master-fan/FanSpeed topic, the fan goes to high speed. I know that, so I made my cards post that MQTT message. This is effective, but seems wrong somehow. I’m not using Home Assistant’s fan capabilities at all, and I would like to.

The 4 buttons (Off, Low, Med, High) will all be yellow/highlighted if the fan is on, and they will all be dark if the fan is off. What I’d really like is for ‘Med’ to be highlighted if the fan is running on the medium speed. I don’t know how to do that. The iFan03 card for lovelace looks like it supports that kind of status, but I never got that card working with my setup.

Where Next?

I don’t yet have any automations built from this. I have an Aqara temperature sensor and I hope to use it to trigger the fan to turn on and off as the room gets warmer and cooler.

I haven’t built those, yet, so I can’t really talk about how to do it. I’m writing this blog post only a day after getting it all running. Once I get those running, I’ll blog about it.

Comments (via Mastodon)