Flashing ESPHome on White Label Smart Plugs

You may remember that I bought a smart plug a few years ago, for our Christmas tree, and had been wondering what the heck do you use a smart plug for. Well, a few months ago I found out another use case for it that I had not thought about to that point: the subwoofer.

When I moved to Dublin, nearly eight years ago now, I bought a new TV, and an AV receiver, and a set of speakers — and with these last one, came a subwoofer. I don’t actually like subwoofer that much, or at least I didn’t, because the low-frequency sounds give (or gave) me headaches, and so while it does sound majestic to watch a good movie with the subwoofer on, I rarely do that.

On the other hand, it was still preferable to certain noise coming from the neighbours, particularly if we ended up not being in the same room as the device itself. Which meant we started using the subwoofer more — but unlike the AV receiver, that can be controlled with a network endpoint, the subwoofer has a physical switch to turn on and off… a perfect use case for setting this up with a smart plug!

Since I didn’t want to reuse the original plug for the Christmas tree (among other things, it’s stashed away with the Christmas tree), I ended up going online and ordering a new one — and I selected a TP-Link, that I thought would work just the same as my previous one… except it didn’t. Turns out TP-Link has two separate Smart Home brands, and while they share the same account management, they use different apps and have different integration support. The Christmas tree uses a Kasa-branded plug, while the one I ordered was a Tapo-branded plug — the latter does not work with Home Assistant, which was a bit annoying, while the former worked well, when I used it.

When TP-Link then also got in the news for having “fixed” a vulnerability that allowed Home Assistant to control the Kasa plugs on the local network, I got annoyed enough that I decided to do something about it. (Although it’s good to note that nowadays Home Assistant works fine with the “fixed” Kasa plugs, too.)

I asked once again help to Srdjan who has more patience than me to look up random IoT projects out there, and he suggested me the way forward… which turned out a bit more tortuous than expected, so let me try to recount it here, showing shortcuts as much as I can at the time of writing

The Hardware

Things start a bit iffy to begin with — I say that because the hardware I ended up getting myself was Gosund SP111 from Amazon, after checking reviews that they were still shipping an older version of the hardware that can be converted with tuya-convert (I’ll get back to the software in a moment). There’s plenty of warnings about the new models, but in a very similar fashion to the problem with CGG1 sensors, there’s no way to know beforehand what version of a firmware you’re going to find.

But in particular, SP111 are not Gosund engineering’s own work. Tuya is a company that build “white label” goods for many different brands, and that’s how these plugs were made. You can find them under a number of different brand names, but they all share the same firmware and, critically, the same pairing and update keys.

One of the best part about these Tuya/Gosund plugs is that they are tiny in the sense of taking very little space. They are less than half the size of my first Kasa-branded TP-Link smart plug, and even when compared with the newer Tapo-branded one they are quite slimmer. This makes for adding them easily to places that are a bit on the constrained side.

The Firmware

I did not buy these devices to run with the original firmware. Unlike the CGG1 and pretty much everything else I’m running at home, this time I went straight for the “I want to run ESPHome on them.” The reason for that was on one side, I’m annoyed and burnt by the two TP-Link devices, and from the other, the price of Hue-compatible smart plugs was annoyingly high. That would have been my default alternative.

Of the various important things to me, Home Assistant support grown from a “meh, sure” to “yeah I want that” — and in part because I did manage to set up scripts for quite a bit of tools at home through it. One of my original concerns (wanting to still be able to control most of these features by voice) is taken care of by signing up for Nabu Casa, which provides integration for both Google Assistant and Alexa, so even with the plug running a custom and maybe janky, firmware, getting it to work with the rest of the house would be a breeze.

There’s other options for open source firmware for the SP111, as well as other smart plugs. Tasmota is one of the most commonly used for this, and there’s another called ESPurna. I have not spent time investigating them, because I already have one ESPHome device running, and it was easier to lower my cognitive load to use something I already kinda know. After all, the plan is to replace the Kasa plug once we take out the Christmas tree, which would remove not one but two integrations from Google and Amazon (and one from Home Assistant).

All of these options can be flashed the first time around with tuya-convert, even though the procedure ended up not being totally clear to me — although in part that was caused by my… somewhat difficult set up. This was actually part of the requirements. Most smart home devices appear to be built around ESP8622 or ESP32, which means you can, with enough convincing, flash them with ESPHome (I’m still convincing my acrylic lamp circuit board), but quite a few require you have physical access to the serial port. I wanted something I could flash without having to take it apart.

The way this works, in very rough terms, is that the Tuya-based devices can be tricked into connecting to a local open network, and from there with the right protocol, they can be convinced to dump their firmware and to update it with an arbitrary firmware binary. The tuya-convert repository includes pretty much all the things you need to set this up, neatly packaged in a nearly user-friendly way. I say nearly, because as it turns out there’s so much that can go wrong with it, that the frustration is real.

The Process.

Part 1: WiFi.

First of all, you need a machine that has a WiFi adapter that supports Access Point mode (AP mode/hostapd mode, those are the keywords to look for it). This is very annoying to know for sure, because manufacturers tend to use the same model number across hardware revisions (that may entirely change the chipset) and countries — after all, Matthew ended up turning to Xbox One controller adapters! (And as it turns out, he says they should actually support that mode, with a limited range.)

The usual “go-to” for this is to use a laptop which also has an Ethernet port. Unfortunately I don’t have one, and in particular, I don’t have a Linux laptop anymore. I tried using a couple of Live Distros to set this up, but for one reason or another they were a complete bust (I couldn’t even type on Ubuntu’s Terminal, don’t even ask.)

In my case, I have a NUC on top of my desk, and that’s my usual Linux machine (the one I’m typing on right now!) so I could have used that… except I did disable the WiFi in the firmware when I got it, since I wired it with a cable, and I didn’t feel the need to keep it enabled. This appears to have been a blessing in disguise for a while, or I would have been frustrated at one of the openSUSE updates in December, when a kernel bug caused the system to become unusable with the WiFi on. Which is what happened when I turned the WiFi on in the firmware.

Since I don’t like waiting, and I thought it would generally be a good idea to have at least one spare USB WiFi dongle at home (it would have turned useful at least once before), I went and ordered one on Amazon that people suggested might work. Except it probably got a hardware revision in the middle, and the one I received wasn’t suitable — or, some of the reports say that it depends on the firmware loaded on it; I really didn’t care to debug that too much once I got to that stage.

Fast forward a few weeks, the kernel bug is fixed, so I tried again. The tuya-convert script uses Docker to set up everything, so it sounded like just installing Docker and docker-compose on my openSUSE installation would be enough, right? Well, no. Somehow the interaction of Docker and KVM virtual machines had side effects on the networking, and when I tried I both lost connectivity to Home Assistant (at least over IPv6), and the tuya-convert script kept terminating by itself without providing any useful information.

So instead, I decided to make my life easier and more difficult at the same time.

Part 1.1: WiFi In A Virtual Machine

I didn’t want Docker to make a mess of my networking setup. I also wasn’t quite sure of what tuya-convert would be doing on my machine (yes, it’s open source, but hey I don’t have time to audit all of it). So instead of trying to keep running this within my normal openSUSE install, I decided to run this in a virtual machine.

Of course I need WiFi in the VM, and as I said earlier, I couldn’t just pass through the USB dongle, because it wouldn’t work with hostapd. But modern computers support PCI pass-through, when IOMMU is enabled. My NUC’s WiFi supports hostapd, and it’s sitting unused, since I connect to the network over a cable.

The annoying part was that for performance issues, IOMMU is disabled by default, at least for Intel CPUs, so you have to add intel_iommu=on for the option of passing through PCI devices to KVM virtual machines to be available. This thread has more information, but you probably don’t need all of it, as that focuses on passing through graphic cards, which is a much more complicated topic.

The next problem was what operating system to run in the VM itself. At first I tried using the LiveDVD of openSUSE — but that didn’t work out: the Docker setup that tuya-convert uses is pretty much installing a good chunk of Ubuntu, and it runs out of memory quickly, and when it does it throws a lot of I/O errors from the btrfs loaded into memory. Oops.

Missing a VM image of openSUSE Tumbleweed, I decided to try their image for JeOS instead, which is a stripped down version meant to be used in virtualized environments. This seemed to fit like a glove at first, but then my simplicity plans got foiled by not realizing that usually virtualized environments don’t care for WiFi. Although the utter lack of NetworkManager or any other WiFi tooling turned out to be handy to make sure that nothing tried to steal the WiFi away from tuya-convert.

In addition to changing the kernel package with a version that cares about WiFi drivers, you need to install the right firmware package for the card. After that, at least the first part is nearly taken care of — you will most likely need a few more tools, such as Git and your editor of choice. And of course, Docker and docker-compose.

And then, do yourself a favour, and turn off firewalld entirely in your virtual machine. Maybe I should have said earlier “Don’t let the VM be published to the Internet at large”, but I hope if you get to try to pass-through a WiFi device, you knew better than doing that anyway. The firewall is something that is not obvious is going to get in your way later when you set to run tuya-convert, and it’ll make the whole setup fail silently in the hardest way possible to debug.

Indeed, when I looked for my issues I found tons of posts, issues, blogs all complaining about the same symptom I had, which was all caused by having a firewall in place. The tuya-convert script does a lot of things to set up stuff, but it can’t easily take down a firewall, and that is a biggie.

Indeed, and I’ll repeat that later, at some point the instructions tell you to connect some other device to their network and suggest otherwise it might not be working. My impression is that this is done because if it doesn’t work, you shouldn’t try taking the next steps yet. But the problem is that there is no note anywhere to help you if it doesn’t work — and the reason for it failing is likely the firewall stopping the DHCP server from receiving the requests. Oops.

Part 2: The Firmware Blob

ESPHome configurations are… sometimes very personal. I have found one for the SP111 on the Home Assistant forums and adapted it, but… I don’t really feel like recommending that one. So I’m afraid I won’t take responsibility for how you configure your ESPHome firmware for the plug.

Also, once you have ESPHome on the device, changing the config is nearly trivial, from the Home Assistant integration, so I feel it’s important to have something working at first, and then worry about perfecting it.

I think someone will be confused here on why am I jumping on configuring the firmware blob before we got to convert the device to use it. The reason for that is that you want to have the binary file (either built locally or generated with the Home Assistant integration and downloaded), and you put it into tuya-convert/files/, you will be able to directly flash that version, without going through the intermediate step of using one of the bundled firmware just to be able to update to an arbitrary firmware. But to do that, it needs to happen before you complete the Docker setup.

So, find yourself a working config for the device on the forums (and if you find one that is maintained and templated, so that one can just drop it in and just configure the parameters, please let me know), and generate your ESPHome firmware from there.

Also note that the firmware itself identifies the specific device. This means you cannot flash more than one device with the same firmware or you’ll have quite the headache to sort them out afterwards. Not saying it isn’t possible, but I just found it easier to make the firmware for the devices I was going to flash, and then load each one. As usual, my favourite tool to remember what is what would be my label maker, so that I don’t mix up which one I flashed with which binary.

Part 3: The Conversion

Okay so here’s the inventory of what you should have by this point before we move on to the actual conversion:

a virtual machine with a passed-through WiFi card that is supported by hostapd;
an operating system in the VM with the drivers for the WiFi, Docker, docker-compose, and no firewall;
a checkout of tuya-convert repository;
one or more ESPHome firmware binary files (one per device you want to flash), in the files/ directory of the checkout.

Only at this point you can go and follow the instruction of tuya-convert: create Docker image, setup docker-compose, and run the image. The firmware files need to be added before creating the docker image, because docker-compose does not bind the external files/ directory at all.

Once the software starts, it’ll ask you to connect another device that is not the plug to the WiFi. I’m not entirely sure if it’s just for diagnostics, but in either case, you should be able to connect to the network — the password should be flashmeifyoucan, although I don’t think I’ve seen that documented anywhere except when googling around for other people having had issues with their process.

If you try this from your phone, you should be prompted to login into the WiFi network through a captive portal — the portal is just a single page telling you that the setup is completed. If your phone gets stuck in the “Obtaining IP Address” phase, like mine did, make sure you really took down the firewall. This got me stuck for a while because I thought that the Docker itself controlled the whole firewall settings — but that does not appear to be the case.

Final Thoughts

I guess that this guide is not going to be very useful, with the new versions of the SP111 not being supported by tuya-convert (and not clear if it can be supported), but since I have two plugs still unused, it helps me to have written down the process to avoid getting myself stuck again.

The plugs appear to have configurable sensors for voltage, amperage, and total wattage used — and the configuration of those is why I’m not comfortable sharing the config I’m using: I took someone’s from a forum post but I don’t quite agree with some of the choice made, some of the values appear fairly pointless to me.

Voltage monitoring would have been an useful piece of information when I was back in Italy — those who read the blog a long time ago might remember that the power company over there didn’t really have any decent power available. Over here it feels like it’s very stable, so I doubt we’ll notice anything useful with these.

Having Smart Home devices that don’t rely on cloud services is much more comfortable than otherwise. I do like the idea of being able to just ask one of the voice assistants to turn off the subwoofer while I’m playing Fallout 76, for sure — but it’s one thing to have the convenience, and another to depend on it to control it. And as I said some time ago, I disagree with the assertion that there cannot be a secure and safe IoT Smart Home (and yes, “secure” and “safe” are two separate concepts).

As for smart plugs in particular? I’m still not entirely sold, but I can see that there definitely are devices where trying to bring the smart in the device is unlikely to help. Not as many though — it’s still a problem to find something that cannot be served better by more fine-grained control. In the case of the subwoofer, most of the controls (volume, cross-over, phase) are manual knobx on the back of the device. Would it have made sense to have a “smart subwoofer” that can tweak all of those values from the Home Assistant interface? I would argue yes — but at the same time, I can see in this case an expense of £10 for a smart plug beats the idea of replacing the subwoofer entirely.

I honestly have doubts about the Christmas tree lights as well. Not that I expect to be able to control them with an app, but the “controller” for them seems to be fairly standard, so I do expect if I search AliExpress for some “smart” controller for those I will probably find something — the question is whether I would find something I can use locally without depending on an external cloud service from an unknown Chinese brand. So maybe I’ll go back to one of my oldest attempts at electronics (13 years ago!) and see what I can find.

By the way, if you’re curious what else I am currently planning to use these smart plugs on… I’m playing with the idea of changing my Birch Books to use 12V LEDs – originally meant for Gunpla and similar models – and I was thinking that instead of leaving it always-on, I can just connect it with the rest of the routines that we use to turn the “living” items on and off.

Musings after buying a smart plug

I know that people will go and start ranting on using terms like “Internet of Shit” just for the title I’m using here. Despite being as wary and cynical about the subject of connected appliances as the next security-aware engineer, I want to point out that those reactions are blind and lacking empathy. So if your answer is to think that you’re smarter than the plug and me combined, there’s maybe no reason for you to stay around to read the post.

I also need to put the usual disclaimer forward: I work for Google, a company that produces “smart” appliances. I don’t have anything to do with the hardware products, have no special insight into them, and I am her talking about things as myself alone. I’m also not really talking about Google hardware beside for a few references to the Assistant here and there, and that’s simply because I happen to be using Google Home as my hub.

As I said I’m fairly cynical about smart appliances. It took quite a bit for me to even buy a single one, but I’m now a very happy user of a LIFX Mini Colour smart bulb. It was probably this year’s best gadget buy for me, and it is not just about the ability to control the light with an app on my phone — or with the Assistant. The bulb can dim, change colours, and can be set onto a dynamic schedule. It’s extremely convenient, and an improvement in my quality of life, particularly by setting it to red as I go to sleep, instead of keeping it bright white.

Of course, like always when buying a device that relies on external services to work (the infamous “cloud”), I am still worried about the risk of the company going under, or dropping support for my specific device, and letting me deal with the broken pieces. But quite honestly, if you tried to avoid all the cloud-based services and hardware nowadays, you will end up a luddite. And maybe you want that. Besides IKEA, that requires their full bridge, I don’t know of any other smart home brand that provides local-only controls — and local-only means no talking to the Assistant to turn on the light as part of the morning routine.

I’m happy enough that my LIFX can be controlled without an active Internet connection (this happened before). Maybe I’ll follow Matthew Garrett’s example and start reverse engineering it into a Python script for the rainy days.

But I digressed enough. What I wanted to talk about was rather smart plugs. Because that’s a device I’m not entirely sold on the idea of smart plugs, I started the original draft of this post because I thought they were completely useless. I changed my own mind as I was writing this, and that’s why I actually wanted to post this.

So why did I buy a smart plug if I am not sold on the idea? Well, since this is our first Christmas together, my girlfriend wants to have a proper Christmas tree at home. And since I would like to see the tree while I approach the apartment on the bus or on foot (hey, I have not had a Christmas Tree for more than a decade, I can have some fun!), I would like to have IFTTT turn it on for me.¹

I ended up buying a TP-Link Smart Plug (UK version), which comes with their own app, and integration with the various services including IFTTT and Google Assistant. Which means we’ll be able to say “Hey Google, turn on the Christmas Tree!”

There are differences between a smart bulb and a plug though. The former adds a significant amount of value add, with things like dimming, different colours, and so on. A smart plug is still only a binary operator, it’s either on, or off. You cannot do fine-grained control over that, you can only turn things on or off.

So after thinking about this, I realized there are a few requirements for something to make sense to have connected to a smart plug:

It needs to be something that cannot stay on standby the whole day. Because if it can, there’s no real advantage in having a smart plug for it, keeping it in stand by is easier, and can easily be cheaper, as the stand-by of the plug connected to WiFi might be higher consumption than the device itself.

It needs to be something that can be at least “readied” unattended. Turning on the plug for a hairdryer is not going to be very useful, if you’re not there to use it. Also if readying something unattended is too risky, it’s a bad idea to use a smart plug. This is the case for clothes irons for instance; I wouldn’t want to turn mine on if I’m not there to make sure that it’s not on top of something it shouldn’t be.

If it’s something that comes with consumables, it needs to have big enough reserves, or a way to feed itself. Going back to the clothes iron, the one I have does not have enough of a water tank. If I was to turn it on too soon, it would just waste all of it and I would go and find it empty, which is just as bad.

Given these considerations, one of the common suggestions I hear is coffee makers. At first I thought this was pointedly American, as indeed a percolator style coffee can be filled in in the evening, and then be set to turn on in the morning and make coffee for you to drink. When I spent extensive time in Los Angeles, I used the timer on a percolator to make sure I would have hot “coffee” ready immediately after waking up. But then I realized that this is very similar for Italian-style espresso machines, too: they have an internal boiler that takes a while to get to temperature and be usable, they usually have a tank big enough for a full day (or in some cases they may be connected to the water mains), and they consume enough power in standby that you wouldn’t want to keep it turned on overnight. For those who don’t drink coffee, the same can be true of automated teawakers or teamakers — I had one from Twinings back in Italy.

Another appliance that fits the bill fairly well is the electric bathroom heater, or towel rack. Heating in general is likely better suited by a smarter “whitebox” approach — indeed I have booked an appointment to install a Nest thermostat at my apartment, after getting my landlord’s permission, because I want to be able to automate hot water availability and easily tweak the temperature over the day. But in some cases, you have additional bathroom heating that has less control: I have on/off towel racks in my bathrooms in London, and my mother uses a small electric heater in Italy, after we messed up with the house’s heating plan by replacing a bulky and leaky boiler with a more modern and efficient one.

Now for both of these examples, smart plugs are not the only obvious solution. Indeed, percolators, teawakers, and espresso machines, as well as many small electric heater, often come with their own timer. This works great for the people who have a clear schedule and fixed routine. In my case that’s rarely the case: I wake up at a different time depending on what my day looks like, sometimes I oversleep because I had a bad night, sometimes I’m up earlier than average because my girlfriend is staying over and she has to go to work. A similar result exists for my mother due to different requirements: she lives alone and really doesn’t have any reason to get up a fixed time unless she’s waiting for deliveries, services, or stuff like that. And since the house is on two floors, and she has knee pain, being able to turn on the heating, get the bathroom ready, or make sure that the coffee machine is warmed up without having to get downstairs immediately, would be a very nice feature.

I can definitely see myself appreciating the idea of saying “Hey Google, Good Morning”, and know that by the time I finished listening to the BBC News headlines, the coffee is ready and still hot for me, while the bathroom is warm enough to take a shower in. Doesn’t really work for me here, because I make pour-over coffee, and the towel rack is not controlled by a normal plug, but I can dream can’t I?

By the way, Google Assistant can do that, although it’s a bit hidden: from the Home app, go into the Account tab (the last one on the right), click Settings, go to the Assistant tab, and then select Routines. From there you can set up the actions you want taken when you give it a specific hotphrase.

For most of other appliances, I would probably need more whitebox smartness. I already rely on the timer for my washing machine, but it would be nice to just put it into “standby”, loaded and locked, but not start it until I wake up, or until I’m actually leaving the apartment (I don’t get woken up by the noise of the one I have here in London, but I would have been by the one in Dublin). And something that can remind me was I get home (“Hey Google, I’m home”) that I need to unload the dishwasher.

One of the things that I actually nearly considered giving a smart plug to was the Air Wick freshner. While I would love having a fine grained intensity control that would keep a background fragrance during the day, but raise it just as I’m ready to get home, to make me feel good, just having the ability to turn it off the moment I leave and on again when I come back home, would be a very nice thing to have. On the other hand, it turns out that the plug-in device consumes significantly less power than the smart plug in stand-by, so it makes no sense as it is.

I guess using more sophisticated fragrance delivery devices, such as Yankee Candle’s Scenterpiece (that my mother has, at home) would make more sense. Alternatively, Muji has very nice oil burners, though they have a small tank for water, and candle warmers are getting more common (these are probably better than the Scenterpiece in my experience). Unfortunately these are usually table-top devices, rather than plug-in, and I don’t have the space where I would want to use it. So if someone from Air Wick or Ambi Pur is reading, consider that I would pay just as much as a smart plug to have a smart plug-in freshener that can be set to adjust the intensity over the day!

So to close it up, I’m somewhat skeptical about getting more smart plugs for myself, but I can definitely see a number of useful cases for them, as well as for smarter “whitebox” appliances. Indeed, if my mother had a decent Internet connection in 2018, I would probably set her up with quite a few of those, to make her life easier. Call them accessibility helpers, maybe.

You may remember that I have some particular attachment to Christmas lights Rube Goldberg machinery. The idea of having my own IFTTT-compatible smart Chrimast light tube did pass through my head. ↩