Magic Home LED Controller ESPurna’d

Following the bright path (sic) of the Ai-Thinker AiLight / Noduino OpenLight I wrote about a few weeks ago, now it’s turn for one of those devices you purchase but once they arrive they are stored in the TODO box until they eventually come back to life.

The Magic Home LED Controller [Aliexpress, also available from Ebay] is an ESP8266 based single-color RGB(W) LED strip controller. It works with every 5050 LED strip [Aliexpress] out there. Just be careful since even thou some LED strips are waterproof [Aliexpress] this controller is not.

Being able to flash custom firmware in the controller lets you really own the device. Why? Because:

  1. You are not required to install a proprietary app on you phone to manage it
  2. You are not limited by the options the developers of that app have decided you will need
  3. You can make it interoperate with other devices at home
  4. You, and only you, know when you turn on your lights
  5. And if all the previous points are not enough: it’s so much fun!


Getting the hardware ready

Just like in the Ai Light, flashing any custom firmware into this controller will require you to solder some wires to small copper pads on the board. It’s not hard but it’s one of those things you learn by doing. Just to get you started let me give you some advice that work for me:

  • Use a thin tip
  • Ensure it’s hot before starting, I usually set it to 350 celsius
  • Heat the pads one by one and apply a little blob of tin
  • Remove 1-2 mm of insulator from the cables
  • Tin the cable too
  • Make contact between the pads and the cable tips and apply heat again to reflow the tin for less than one second



Connect the wires to your USB2UART programmer as in the picture above, GND to GDN, TX to RX and RX to TX. Tie IO0 to ground to enter flash mode and power the board through the original jack. If you are going to flash and test several times, remember to disconnect and connect IO0 from ground every time. Booting while IO0 is tied to ground makes it enter into flash mode, otherwise it’s normal boot mode.

Also, once you have an OTA compatible firmware loaded you might want to remove the wires (again, apply some heat) and flash new versions over the aire from then on.

Flashing ESPurna

The ESPurna firmware is released as free open software and can be checked out at my Espurna repository on GitHub.

I strongly recommend everyone to use PlatformIO to build and flash their ESP8266 projects (and their Arduino projects, and their STM32 projects,…). You can either use the command line version of PlatformIO or the PlatformIO IDE based on Atom. Either way the builder will take care of all the project dependencies (frameworks, toolkits, libraries,…). You just have to checkout the project from the link above, open the “code” folder with the IDE (or “cd” to it) and run the builder for your target board. In the PlatformIO IDE that’s done pressing F7 and selecting “PlatformIO: Upload (env:led-controller-debug)”.

Using the command line this translates into:

git clone
cd espurna/code
pio run -e led-controller-debug -t upload

Upon reboot the blue LED in the board will flash every half second and it will create an access point named something like “LED_CONTROLLER_ABCDEF”, connect to it using “fibonacci” as password and then open a browser pointing to It will ask you for authentication. Use user “admin” and pass “fibonacci” again.

The first time you will have to change the default password and login again. Then I recommend you to change the hostname (say you will call it “ledstrip”), and the wifi credentials for your home network. Then press reconnect and it will connect to your WiFi using the credentials you just provided.

When connected to a WiFi the builtin led flashes briefly every five seconds. Then you can just browse to “http://ledstrip.local” (“ledstrip” is the hostname you set in the previous step) to go back to the web interface.


Using ESPurna

The ESPurna web interface lets you control the status of the lights (on/off) and the color, but it also lets you configure the access to other services like MQTT, the REST API, Home Assistant,…

If you have a local MQTT broker you can connect ESPurna to it (check the MQTT tab in the menu) and start changing color and status remotely right away:

# turns on the light
mosquitto_pub -t /home/ledstrip/relay/0 -m 1

# turns off the light
mosquitto_pub -t /home/ledstrip/relay/0 -m 0

# toggles the light 
mosquitto_pub -t /home/ledstrip/relay/0 -m 2

# Changes color to red using #RRGGBB notation
mosquitto_pub -t /home/ledstrip/color -m "#FF0000"

# Changes color to red using R,G,B notation (only in dev branch as of this writing)
mosquitto_pub -t /home/ledstrip/color -m "255,0,0"

# Changes color using temperature (only in dev branch as of this writing)
mosquitto_pub -t /home/ledstrip/color -m "6500K"

Using the REST API is a little more involved since you have to use the APIKEY provided in the web interface for every request, but still it’s really simple and something you can test from the browser (it’s actually REST-ish since it accepts GET requests to change statuses).

# URL to turn light on

# URL to turn light off

# URL to turn toogle light

# URL to change color to RED using #RRGGBB notation (notice the '#' is encoded as '%23')

# URL to change color to RED using R,G,B notation (only in dev branch as of this writing),0,0

# URL to change color using temperature (only in dev branch as of this writing)

Finally you can also use Home Assistant to change the color and status of the light using the MQTT Light component. The plan is to support MQTT JSON Light component also, to change status, color, brightness, temperature and adding effects to the lights. Soon!


Home Assistant widget to change status and color of the LED strip

CC BY-SA 4.0 Magic Home LED Controller ESPurna’d by Tinkerman is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

68 thoughts on “Magic Home LED Controller ESPurna’d

    1. Xose Pérez Post author

      Sure, a minor change is required to drive the W line together with the RGB lines. Right now the code uses the W only when red, green and blue values are the same.

      1. E

        good to know. To say it in other words, the moment I select “white” on an RGB module (with the magic home app), the RGB channels switch off

    1. Xose Pérez Post author

      In the dev branch you can provide a single 8 bit value as color (via MQTT or REST API) this value will control the PWM GPIO defined for the W line.

    1. Xose Pérez Post author

      I know the product and I guess it won’t be hard to use it with ESPurna. If you happen to have one you might try to find out what GPIOs drive the power mosfet for the RGBW lines.

        1. Xose Pérez Post author

          A first approach with only one white channel (add these lines to the code/espurna/config/hardware.h file just before the “Unknown hardware” section and build the project with -DH801 or adding “#define H801” int eh arduino.h file.

          // -----------------------------------------------------------------------------
          // HUACANXING H801
          // -----------------------------------------------------------------------------
          #elif defined(H801)
              #define MANUFACTURER        "HUACANXING"
              #define DEVICE              "H801"
              #define LED1_PIN            5
              #define LED1_PIN_INVERSE    1
              #define LED2_PIN            2
              #define LED2_PIN_INVERSE    1
              #define RELAY_PROVIDER      RELAY_PROVIDER_LIGHT
              #define LIGHT_PROVIDER      LIGHT_PROVIDER_RGBW
              #undef RGBW_INVERSE_LOGIC
              #undef RGBW_RED_PIN
              #undef RGBW_GREEN_PIN
              #undef RGBW_BLUE_PIN
              #undef RGBW_WHITE_PIN
              #define RGBW_INVERSE_LOGIC      0
              #define RGBW_RED_PIN            15
              #define RGBW_GREEN_PIN          13
              #define RGBW_BLUE_PIN           12
              #define RGBW_WHITE_PIN          14
              //#define RGBW_WHITE_PIN          4 <= warm white
          1. Bryan Mayland

            I see that the H801 support is in git now, however looking at hardware.h I see setSetting(“lightProvider”, LIGHT_PROVIDER_RGB2W), but there is no provider define named LIGHT_PROVIDER_RGB2W.

            And now it is in 1.8.0 release. It compiles but I am not sure it will work properly.

          2. Xose Pérez Post author

            There is a LIGHT_PROVIDER_RGB2W defined in the general.h file. But I reckon there are still some features missing, specially dimming (or one channel dimming). If you use an RGB strip with the H801 my suggestion is to change the provider to LIGHT_PROVIDER_RGB, otherwise it won’t handle whites correctly.

  1. Pingback: A closer look at the H801 LED WiFi Controller - Tinkerman

  2. Zeph

    Is it possible to decode the IR input (for the IR remote versions)?

    Optimal would be to do both:
    1) allow the IR to modify the light output (option to disable this)
    2) report the IR code via MQTT (if enabled)
    So it could have local control (good for speed) and/or allow the central controller to decide what to do with IR codes. Of course, if local IR control is allowed, it would be good to have a way that the central controller could know the current mode/levels so it could update any home control displays.

    1. Xose Pérez Post author

      It should be possible. The version I have does not have and IR receiver so I could implement that functionality. Help is welcome.

  3. Sheldon Williamson

    Hello is there any way to change the output voltage with the firmware…. right now it puts out 12v… could you male it put out 3.7v?

    1. Xose Pérez Post author

      The output voltage will be the input voltage you provide since the four channels are driven by power mosfets. But, there is a minimum for the microcontroller to work. Assuming the regulator is an ASM1117-3.3 with a typical voltage dropout of 1.1V you will need around 4.4V to power it…

    1. Xose Pérez Post author

      Once you get ESPurna in it you can control it from your Echo or Dot. But atm, it won’t work with a DIY device and the Alexa SDK.

    1. Xose Pérez Post author

      But I’m not sure about the pitch issue. They are 100mil. Most of the 5050 strips I’ve used have this same pitch…

      1. Louis Christodoulou (islou)

        I realized soon after i posted this that I actually have an extra pin to you for a cool / warm white. My model is a “ARILUX® AL-LC08 RGB+Warm White+Pure White”. Some how they have a strange ~2mm pitch. The only thing I can think (i don’t have any to test) is that there is some cold warm and RGB strip with this strange pitch ?

        Mine go C-W-B-R-G-+. This also results in some pins being switched (I quickly noticed this when i made up a custom cable to connect the whole RGB strip and the colours were all wrong. Switched some of the pins in your code to get it working but will spend some time to add the extra channel and set it up as an RGBWW eventually 🙂 .

        1. Xose Pérez Post author

          I see, certaintly a weird connector. Don’t know of any 2mm pitch led strips…

          Adding support on ESPurna 1.9.1 for this controller should be as easy as adding a LIGHT_CH5_PIN and a LIGHT_CH5_INVERSE values in the hardware.h file. Of course the GPIOs should be mapped to the right values for this board.

  4. Lazar Obradovic

    Just to double-check – during flashing, you use standard 12V input of the device, which in turn, powers ESP-12S with 3.3v. You are not supplying that voltage from your USD FTDI, right?

    1. Xose Pérez Post author

      You can do that or you can flash it wiring th 3V3 pad in the board without providing the 12V. If you want to debug with the lights on your option is better.

  5. Bob


    I cannot get this to connect to my local network. Am I missing something really dumb?

    I connect to the AP.
    I change the hostname
    I go to network and add my SSID and password
    I click the Reconnect button
    It drops the connection but then the AP comes back.

    I don’t see anything on my network, I cannot resolve it.
    The AP is still active (should it disable?) and if I look at the details if says it’s IP is still

    Am I missing a step or being dumb? I am using the latest downloaded. 1.9 IIRC

  6. Mario

    Hi. I just bought mine from AliExpress. When I opened it the hardware is different. I have ESP8285.
    Can you make a tutorial how to flash it?
    The whole board is different so I don’t even know where to connect wires for flashing.

    Best Regards.

    1. Xose Pérez Post author

      The ESP8285 is a ESP8266 with a 1Mb embedded flash memory. The code should be the same using a generic 1Mb board with DOUT flash mode.
      Are there no pads on the board? Maybe you can add a pic of it…

  7. pokemon81

    Not Controllable with Domoticz…
    Not changing Color but only can switch on or off via RGS Switch.

    Anyone get H801 work with Domoticz ?

    1. Xose Pérez Post author

      You are right. At the moment the Domoticz integration only supports switches or sensors, not lights. But you can do a PR 🙂

  8. Bob


    I have some of these:

    I had them working woth the magic-home fw but they only showed blue.
    I then flashed them again with the espurna-1.9.9-arilux-e27.bin and the espurna-1.9.9-arilux-al-lc06.bin firmware.with the first nothing happened – you could not turn them on, with the second they worked but the colours were not as per the interface.

    Do I have an unsupported version? How can I work out the pins used?

    Thanks for the hard work!

    1. Xose Pérez Post author

      I’m not sure any of the two would work. I haven’t tested the AL-LC02 but it looks like a lot to the MagicHome LED Controller. Maybe you can try the espurna-1.9.9-magichome-led-controller-20.bin .

      1. Bob

        With both of those I get an ERROR 4 after it uploads. What might that be? I can reflash it with the Arilux again. Just not change type.

        1. Xose Pérez Post author

          Binaries from 1.9.X were built against Core version 2.4.0 RC2. Unfortunately (and unaware for me at the moment) that meant ~40kb more in size making them too big for OTA.
          What you can do is to get the latest version 1.10.0 and try with it. If it’s still gives error 4 (not enough space) use the smallest binary in the repo (the one the the sonoff-basic) for instance. Flash it and then try flashing the one for the Magic Home again.

          1. Bob


            So got the firmware reflashed with the MagicHome one. 🙂

            The ones I mention above, although they are shows as Arilux also have the MagicHome sticker on the back and did work with the magichome app.

            After flashing with the magic-home version they work again. However, the reg and green pins are swapped.

            Is there a way you could have a version to configure the pins manually?



          2. Xose Pérez Post author

            Right now ESPurna does not support GPIO configuration at run time, you will have to change them at build time in the hardware.h file.

  9. Mat Smith

    Hi! Greetings from London…

    1/ you say “ESP8266 based single-color RGB(W) LED strip controller” What do you mean by “single-color”?

    2/ Have you seen the RGBWW (RGB + Warm White) strips? Also I have seen RGBWW meaning RGB and dual white (cold and warm). I guess this is 5 channels? Does ESPurna support that?

    (Sorry if I missed these topics in the comments above – there were so many to read!)

    1. Xose Pérez Post author

      By single-color I meant all the LEDs in the strip will have the same color. This is different from WS8012 strips where each LED has a small microcontroller and it’s addressable so you can set the color per LED. On regular 5050-based strips you set the channels (3, 4 or 5) for all the LEDs the same. ESPurna supports several 5-channels devices like the Huacanxing H801 or Arilux LC-06.

  10. S0und

    Do you think it’s possible to create an API for the wifi controller without flashing a custom firmware? So reverse engineering the communication between the mobile app and the controller, intercept it with Wireshark (exp.)?

  11. Newwolf

    Hee, just checking out you firmware.
    I really like it and that easy to control.
    There’s only one thing….
    It’s on “espurna-1.12.1-magichome-led-controller-20.bin” and the GPIO color assignment isn’t working.
    On the version without -20 it’s also wrong.
    Maybe it’s new version of the board I have?!?!?
    The PCB is telling a version v2.3
    The problem is that on the website red is good when pushing the ir-remote but it’s turns green.
    And when I push green it turns red.
    Is it possible to create a different version? Or make it more easy to re-assign GPIO ports?

    1. Xose Pérez Post author

      Version 2 of the firmware will allow to change GPIOs from the web UI. In the meantime you can change the configuration in hardware.h file build and reflash. If you find the right mapping for your version please report and I will add it for every one to have it.

      1. Newwolf

        Thanks for the reply.
        Would try to change hardware.h but for some reason my arduino ide isn’t working on the project.
        But on tasmota they had the same issue and made the correct mappings 🙂

        PWM1 -> GPIO12 (Red)
        PWM2 -> GPIO05 (Green)
        PWM3 -> GPIO13 (Blue)
        PWM4 -> GPIO15 (White)

        Would be very nice if you could make a Magic Home v2.3 for us.
        Keep up the good work.

        1. Xose Pérez Post author

          I have just pushed the definitions to the dev branch, will probably release it in a few days.

  12. Aleix Albanell

    Just recived my magic home v2.3 and installed Espurna 1.12.3 with the LED_CONTROLLER_23 configuration. I figured out that the Newwolf GPIOs color assignment isn’t not working properly on my device so I had to change hardware.h with the same GPIOs assignament as v2.0.
    Now the colours is working properly.

    1. Xose Pérez Post author

      Good to know. I hope all this GPIO-mess will be solved when you could configure the GPIO via the web UI. Soon.

  13. Markus Rudolf

    I just also flashed espurna-1.12.4-magichome-led-controller.bin on my Magiclight Controller. My Version uses a Radio Remote Control (433 MHz I guess), and there is an additional 8 Pin SOIC (SYN480R) doing the reception stuff. Data output of the chip is fed to GPIO4 on the ESP8266 (they used a ESP12F with the metal can removed and the board cut short by 2mm, really strange).

    On the console I get flooded with a lot of IR decode errors even in idle state, so I guess the RF protocol is different.

    [926577] [IR] Received 0x491A55D5
    [926577] [IR] Ignoring code
    [926630] [IR] Received 0x6F1F07BD
    [926631] [IR] Ignoring code
    [926673] [IR] Received 0x4986DD8A
    [926673] [IR] Ignoring code
    [926727] [IR] Received 0x37849CC
    [926727] [IR] Ignoring code
    [926770] [IR] Received 0x1B369BD7
    [926770] [IR] Ignoring code
    [926812] [IR] Received 0x3C40F415
    [926813] [IR] Ignoring code
    [926896] [IR] Received 0xDAD55EB
    [926896] [IR] Ignoring code

    Are you aware of anyone working on the RF decoding part? Otherwise I may dig out my scope and try to figure out the Protocol.

  14. Dirk

    i also have a MagicHome with RF Controll. In the debug interface i got the same and the color change without doing something. I disabled IR support in hardware.h (#define IR_SUPPORT 0) and all Problems are gone.

    Is there a hope to implement the RF Controll in Espurna? Then my LEDautomation will be perfekt.

    1. Xose Pérez Post author

      There is an RF module in ESPurna but it need direct communication between the ESP8266 and the encoder/decoder.

  15. jammo


    I am just starting to learn about this.

    Which USB2UART programmer should i get? to get started.

    Thank you.

    1. Xose Pérez Post author

      Any USB2UART will work but depending on your OS you will need different drivers. I have read people complaining about CH340 but I have had no problems so far. But, TBH, Linux has pretty good support for them.

  16. Andy W

    RE: Colour mapping

    I’ve just edited hardware.h to fix the colour mapping on my V1.4 Magichome LED controller, the mapping that worked for me was…

    #define LIGHT_CH1_PIN 5 // RED was 14
    #define LIGHT_CH2_PIN 14 // GREEN was 5
    #define LIGHT_CH3_PIN 12 // BLUE
    #define LIGHT_CH4_PIN 13 // WHITE

    It should be noted my PCB was marked different to the more conventional LED strip…

    PCB > GRBW
    LED > RGBW

  17. Ed

    In fact it is also possible to control an unreflashed controller with your own automation software, at least, when you are using openhab. In openhab there is a wifiLED binding that controls this device. . You still need the app to setup the WiFi credentials, but then it can be used both with the app and openhab and e.g. googleHome


Leave a Reply (all comments are moderated, be patient)

This site uses Akismet to reduce spam. Learn how your comment data is processed.