eipi.xyz

Embedded, Linux, system software, technology, hacks

Installing ESPurna on a Sonoff TH16

2020.05.04 Home automation NixOS Embedded ESP8266

contents

This post will cover the process of installing ESPurna on a Sonoff WiFi switch, from scratch, using a Linux host. Other host operating systems will have a similar process, and there are parts which can be skipped if not using a Linux host.

The Sonoff is a basic mains relay device using the ubiquitous ESP8266 WiFi chipset, which has Arduino toolchain support. ESPurna is a 3rd party firmware for a variety of devices, it seems to be the more "techy" option, where another option might be Tasmota.

Such firmwares allow you to customise functionality, and integrate such devices into an open source home automation ecosystem such as one using Domoticz or Home Assistant, rather than simply the app they are provided with.

Requirements

Useful resources

The following resources have information about flashing this device:

Hardware setup

The device requires the following connections to your USB-TTL converter:

These are exposed on the unpopulated header on the PCB. You can power the device from USB way during flashing via this header.

Flashing process

You must put the device into flashing mode before flashing. To do this, hold the front panel button while applying power, e.g.:

Flash a test sketch in Arduino (optional)

You can flash the following sketch to flash the LEDS, to demonstrate the flashing process. This cause the LED turn on and off every 4 seconds.

#define DEL 2000
#define LED 13

void setup() {
  pinMode(LED, OUTPUT);
}

void loop() {
  digitalWrite(LED, HIGH);
  delay(DEL);
  digitalWrite(LED, LOW);
  delay(DEL);
}

See Flashing process above for instructions on how to place the device into flashing mode.

Building and flashing ESPurna

ESPurna's build and flash instructions are here, on which this guide is loosely based. Platformio simplifies the process, and ESPurna makes very good use of this.

Install Platformio

Debian

TBD

NixOS 

nix-env -iA  nixpkgs.platformio

Windows

TBD

Build ESPurna

Enter the ESPurna source tree:

git clone https://github.com/xoseperez/espurna.git
cd espurna/code
pio lib update

Build the firmware:

pio run -e itead-sonoff-th

This will run for a while, download the required dependencies, and build the firmware. It should finish saying the following, which suggests that some features could be turned off in the future to allow for an image which fits in half the flash size, and therefore can be programmed OTA.

RAM:   [======    ]  57.8% (used 47336 bytes from 81920 bytes)
Flash: [=====     ]  49.5% (used 518783 bytes from 1048576 bytes)
check_printsize([".pio/build/itead-sonoff-th/firmware.bin"], [".pio/build/itead-sonoff-th/firmware.elf"])
Binary size: 522928 bytes
********************************************************************************
File is too large for OTA! Here you can find instructions on how to flash it:
https://github.com/xoseperez/espurna/wiki/TwoStepUpdates
********************************************************************************

Customisation and pre-configuration

You can set build flags for platformio by exporting them in the environment. This wiki shows some of the flags that ESPurna can make use of. Setting variables this way means you don't have to set them manually on the web interface, useful for installing to multiple units. It also means the device will connect directly to the WiFi network, avoiding having to use SoftAP mode at all.

You can disable features to save flash space, or even pre-configure the device settings.

export PLATFORMIO_BUILD_FLAGS='-DWEB_FORCE_PASS_CHANGE=0 -DALEXA_SUPPORT=0 -DTELNET_SUPPORT=0 -DTHINGSPEAK_SUPPORT=0 -DMQTT_USER=\"device\" -DMQTT_PASS=\"yourpass\" -DMQTT_SERVER=\"192.168.1.160\" -DADMIN_PASS=\"yourpass\" -DWIFI1_SSID=\"YARD\" -DWIFI1_PASS=\"yourpass\" -DWIFI1_IP=\"192.168.1.166\" -DWIFI1_GW=\"192.168.1.254\" -DWIFI1_MASK=\"255.255.255.0\" -DWIFI1_DNS=\"192.168.1.254\" -DDOMOTICZ_ENABLED=1 -DMQTT_ENABLED=1'

The variables set here are as follows:

Wifi variables (for the first stored WiFi network):

General settings:

MQTT settings:

Feature flags:

You have to be careful about escaping when setting build flags in this way to avoid build errors where variables are not properly passed. After setting the environment variable, run pio run -e itead-sonoff-th again to build. After this, the MQTT, web admin and WiFi passwords should be set on boot.

This also ends up using just shy of 50% of the flash, allowing for OTA:

RAM:   [======    ]  57.0% (used 46728 bytes from 81920 bytes)
Flash: [=====     ]  48.2% (used 505703 bytes from 1048576 bytes)

All that remmains to be configured after flashing is to set the unique IDX obtained from Domoticz, in the Domoticz tab on the web interface.

Flash

See Flashing process above for instructions on how to place the device into flashing mode.

pio run -t upload -e itead-sonoff-th

After this, if all goes well, the LED on the front of the device will be flashing, and you will have ESPurna installed.

Manual device setup

This is required if you didn't pre-configure passwords etc. by setting build flags, see Customisation and pre-configuration. The ESPurna documentation is here.

On initial power-up it will go into wireless access point (SoftAP) mode.

Install an MQTT broker

You will need an MQTT broker on your home server. On NixOS, this is fairly easy:

{
  # ...

  services.mosquitto = {
    enable = true;
    host = "0.0.0.0";
    port = 1883;
    users = {
      device = {
        hashedPassword = "YOURHASHEDPASSWORD";
        acl = [
          "topic readwrite domoticz/#"
        ];
      };
    };
  };

  # ...
}

The derivation for mosquitto is here.

To generate a hashed password for mosquitto, run the following:

mosquitto_passwd -c passwd.txt <username>
cat passwd.txt

Debugging MQTT

To monitor all MQTT messages for debugging:

mosquitto_sub -h 192.168.1.160 -v -t "#" -u device

For the above commands you will need to install the mosquitto client tools... apt install mosquitto-clients on Debian, or nix-env -iA nixos.mosquitto on NixOS.

Integration with Domoticz

You need to do two things in the Hardware tab:

Don't worry about how these things are connected, they just need to be there. To associate a virtual device in Domoticz with your Sonoff, all you need is the IDX number provided after the next step.

As the UI says, it will now be available in the Devices listing, with the IDX, or you can go to the Switches tab, and click Edit on a switch to find out the IDX assigned to that switch by Domoticz.

That's it, the Domoticz UI should be able to switch the relay on or off, and if the relay is manually switched, this will be reflected on Domoticz's UI.

Domoticz uses two MQTT endpoints, and uses JSON payloads:

If in doubt, use the command above to view MQTT traffic.