TP-Link TD-W9970 “Error code:1 Internal error” – Solved

When trying to change WiFi settings on my TP-Link TD-W9970 v4 I got “Error code:1 Internal error” (and one button saying “OK”; it is not OK!). The TP-Link forms indicate I am not the first, but the TP-Link support people haven’t given any useful advice. Taking a backup of settings, resetting, and restoring the settings DID NOT fix things… just a waste of time.

Eventually, I stumbled upon the solution: I enabled the “Guest Network”.

Then I could change WiFi settings, especially the way the default “auto” settings are for a 40MHz bandwidth on an auto-selected WiFi channel (which is not helpful for managing multiple access points and a Zigbee network). The Guest Network can be turned off again afterwards.


Breakout Board for E18 Modules – DIY Zigbee at a Fraction of the Cost of an XBee

Having recently wanted to get my hands dirty with DIY Zigbee – see my other post on low cost DIY Zigbee – I couldn’t find any suitable breakout boards so, after having found the CC2530-based Ebyte E18-MS1 modules (which are rather economical and available from the manufacturer on Aliexpress… and seemingly without the curse of a glut of clones and fakes), I decided to make my own.

I wanted something quite simple but also flexible, with maximal scope for experimenting and learning. The main use case is to plug into breadboard but there was enough PCB space for some “convenience” components: two switches and three LEDs and associated resistors.

This is what it looked like once assembled (you can just see a BH1750 I2C light sensor on the rear):

Some notes on motivation, layout pragmatics, and options:

  • The long header is meant to be populated with right-angle pins. This will put the antenna nicely up and leaves plenty of space for other components on the breadboard (I find the breakouts with very wide dual-in-line pin-outs to be rather irritating, and Arduino style sockets and flying leads are not great when more than a few connections are to be made).
  • The 5 pin header is for firmware flashing. I opted for this, rather than the full 10 pin “debug” header which CCDebugger uses, for econonmy of space. These 5 pins are quite sufficient for using CCDebugger with TI SmartRF Flash Programmer (I made a little adapter) or if using something like Flash CC2531, which works fine for CC2530’s, (or my patched version for use with Pi v1 GPIOs).
  • The 4 pin header may be convenient for either UART or I2C connections. I’m expecting to be using PTVO and for the CC2530 it fixes UART pins to be P0.2 and P0.3. This header is meant to be mounted on the same side as the E18 module (opposite to switches).
    • The switches should be configured using the solder jumpers.
    • SJ1 handles the “Reset” button: A connects to E18 Reset; B connects to P0.0.
    • SJ2 handles the “Key” button: A connects to P0.1; B connects to P1.7 (which is used by the E18 factory firmware).
    • The on-board LEDs (and the enabling jumpers) visually correlate with the pins they are connected to: P0.4, P0.5, and P2.0.

Eagle design files are available on github but I am also currently (July 2023) selling surplus PCBs on ebay.

Connecting a Raspberry Pi (etc) Direct to a PC with a USB-LAN Adapter

There are a number of articles on the web which describe how to connect a Raspberry Pi direct to a Windows PC with a USB to LAN adapter. This can be quite handy when tinkering, especially with an original version 1. This article is quite good but I struggled to make it work. This article explains the problem and solution… but read that article first, as I don’t explain a few things!

The root of the problem is that I was using a USB to LAN adapter. It appears that Windows (Windows 11 at least) does not trust these devices because the network is fixed as being “Public”; I could not find a way to change this. The second part of my initial downfall was that when TFTPD64* started up, and Windows Firewall popped up the “public or private network” challenge, I thought nothing of allowing it to proceed with “private”. Thus, the firewall is between my USB-LAN dongle and the DHCP server.

* – an alternative is OpenDHCPServer.

If, like me, you missed the chance to choose “public” when starting the DHCP server software, you need to find your way into Windows “Settings”, then “Privacy & Security > Windows Security > Firewall & network Protection > Allow an app through firewall” (take a breath)… click the “Change settings” button then scroll down the list and enable the entry for tftpd64 or opendhcpserver for “public”.

Oh: one thing which the article above was not clear on was to use a different subnet ip address for the USB-LAN dongle than the PC is on. e.g. if your PC is, don’t use any 192.168.1.* address for the static IP entry.

And What About Internet Connection?

While the procedure in the above-mentioned article is fine for accessing the Pi from your PC, as soon as you need to access the internet from the Pi, it is aparrent that you can’t! Network interactions time out because there is no route for network traffic from the dongle adapter to the PC’s LAN/WiFi.

This is easily solved using “Sharing”. First thing: shut the Pi down. Starting with your PC’s “real” network adapter, right-click > Properties > Sharing (tab) > select the top “Allow” and choose the dongle for “Home networking connection”.

This will change the dongle’s IP addres so a return to TFTPD64 will be required to change settings, after which the Pi can be powered on again to get its new IP address. Changed settings I used:

  • IP pool start address =
  • Def router (Opt3) =

Watching the TFTPD64 log I noticed that it allocates two IP addresses. I suspect the first one (it had MAC address 00:AB:00:00:00:00, which is not normal!) is part of WIndows’ sharing magic. The other one should have your usual (and of course remembered!) Pi’s MAC. For me this was


Debugging ESP8266 with GDB and VSCode + Platformio

VSCode with the Platformio IDE plugin makes for an excellent platform for developing ESP8266 code, especially using the Arduino Framework for ESP8266 but the Platformio debugging features do not work. It is, however, possible to use GDB together with VSCode and Plaformio to be able to single-step through code, inspecting flow of control and variable values as you go, in an experience that is comparable to VisualGDB but costs nothing.

There are some limitations, “gotchas”, etc, but once these are understood it really does work!

Setting Up Debug Compilation

The program must be compiled differently for debugging to work because additional information must be included, along with the GDBStub (see below). Once debugging is over, however, the firmware uploaded to the ESP8266 should not have this overhead.

Allowing for both options to be compiled and uploaded is easy in Platformio if you use platformio.ini environments. For example:

platform = espressif8266
framework = arduino
upload_port = COM15
upload_speed = 115200
monitor_port = ${env.upload_port}
monitor_speed = ${env.upload_speed}

board = d1_mini_pro

board = d1_mini_pro
build_flags = -Og -ggdb3 -g3 -D WITH_GDB
Note that I have created two targets – “d1_mini_pro” and “debug_d1_mini_pro” – with the latter defining some non-default build_flags. The “-g” flags make the compiler include debug information, while -Og prevents the compiler optimising code (which breaks the nice relationship between lines of source code and compiled MCU code). I have also included “-D WITH_GDB”; the -D directive is equivalent to a “#define” in the source code and means we can use “#ifdef” to selectively include chunks of code depending on whether we’re using the debug_d1_mini_pro target or not.
Remember to recompile and upload before debugging any changes you make.

Adding GDBStub to Your Code

The GDBStub is code which executes on the ESP8266 to communicate with GDB running on your PC via the serial port. Serial.print() will still work so long as you avoid using a rapidly-repeating loop() which contains little more then Serial.print().

The Arduino Framework already contains the GDBStub code and their documentation explains the basics, although in the context of using the Arduino IDE.

Following on from the use of “WITH_GDB” in the previous section, add the following chunks of code.

At the top:

#ifdef WITH_GDB
#include <GDBStub.h>
At the start of setup():
  Serial.begin(115200);  // or whatever baud rate you prefer
  #ifdef WITH_GDB

Command Line GDB

An essential truth is that you must use the correct gdb for the core processor of the ESP8266: xtensa-lx106-elf-gdb.exe. For my Platformio install, this can be found at (“~” denotes my home directory, i.e. C:\Users\Adam): ~/.platformio/packages/toolchain-xtensa/bin/xtensa-lx106-elf-gdb.exe

A second essential truth is that GDB needs to be set up correctly before you can actually debug. This is most easily done with a set of commands stored in a file, which I call “gdbcmds” and which should be created in the home folder of the Platformio project (i.e. in the same folder as platformio.ini). My gdbcmds file contains:

# ESP8266 HW limits the number of breakpoints/watchpoints
set remote hardware-breakpoint-limit 1
set remote hardware-watchpoint-limit 1
# Some GDBstub settings
set remote interrupt-on-connect on
set remote kill-packet off
set remote symbol-lookup-packet off
set remote verbose-resume-packet off
# The memory map, so GDB knows where it can install SW breakpoints
mem 0x20000000 0x3fefffff ro cache
mem 0x3ff00000 0x3fffffff rw
mem 0x40000000 0x400fffff ro cache
mem 0x40100000 0x4013ffff rw cache
mem 0x40140000 0x5fffffff ro cache
mem 0x60000000 0x60001fff rw
# Locate the ELF file
file .pio/build/debug_d1_mini_pro/firmware.elf
# Change the following to your serial port and baud
set serial baud 115200
target remote \\.\COM15

The ELF file location follows the pattern .pio/build/{target}/firmware.elf, where “{target}” matches the relevant entry in platformio.ini.

Obviously: change the serial port and baud rate!

Now open a new terminal in VSCode. It should open with the project home as the working directory (this is necessary). You can open a terminal window outside VSCode too (I like ConEMU) but should make sure the working directory is right.

You need to run xtensa-lx106-elf-gdb.exe, passing the commands file by adding “-x gdbcmds”. I tend to use a bash shell, so the command is:

~/.platformio/packages/toolchain-xtensa/bin/xtensa-lx106-elf-gdb.exe -x gdbcmds

If you prefer a normal Windows command prompt just replace the “~” with C:\Users\You.

If you get an error like “\\.\COM15: No such file or directory.” then you will have the Serial port open somewhere such as the “Monitor”. Close it.

I suggest you read the Arduino Framework notes for “what next”. The GDB documentation is available online but is rather long and has much which is not applicable. Generally useful commands are: thb (see below), next, step, finish, print, and info locals. Interesting to explore are: disassemble and frame.

When single-stepping (step or next), the execution will sometimes step over several lines of code.

Avoid resetting the device while a GDB session is connected; it gets rather confused!

ESP8266 Limitation – One Breakpoint

This causes things to get ugly if you don’t work with care. The first thing to do is to use temporary breakpoints. Rather than the normal “break” GDB command, use “thb”. This means that once the breakpoint has been reached it is deleted. Otherwise you need to use the “delete” command to remove the breakpoint.

Typical uses are to break on entry to a function. So long as the function name is unique, something like “thb loop” works. Since the compiled code contains source from many files, line numbers must identify the file they relate to, so the command should be something like “thb src/main.cpp:25”.

“Visual” Debugging

This is how to get the debugging experience more like what the Platformio and VisualGDB screenshots suggest.

The launch.json file (within the .vscode folder for the Platformio project) should be edited. Ignore the warning about this being an automatically-generated file and replace the platformio debug entries with the following:

    "version": "0.2.0",
    "configurations": [
            "name": "GDB",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/.pio/build/debug_d1_mini_pro/firmware.elf",
            "args": [],
            "stopAtEntry": false,
            "hardwareBreakpoints": {"require": true, "limit": 1},
            "cwd": "${workspaceFolder}",
            "environment": [],
            "externalConsole": true,
            "MIMode": "gdb",
            "miDebuggerPath": "${userHome}/.platformio/packages/toolchain-xtensa/bin/xtensa-lx106-elf-gdb.exe",
            "miDebuggerServerAddress": "\\\\.\\COM15",
            "setupCommands": [
                {"text": "set remote hardware-breakpoint-limit 1"},
                {"text": "set remote hardware-watchpoint-limit 1"},
                {"text": "set remote interrupt-on-connect on"},
                {"text": "set remote kill-packet off"},
                {"text": "set remote symbol-lookup-packet off"},
                {"text": "set remote verbose-resume-packet off"},
                {"text": "mem 0x20000000 0x3fefffff ro cache"},
                {"text": "mem 0x3ff00000 0x3fffffff rw"},
                {"text": "mem 0x40000000 0x400fffff ro cache"},
                {"text": "mem 0x40100000 0x4013ffff rw cache"},
                {"text": "mem 0x40140000 0x5fffffff ro cache"},
                {"text": "mem 0x60000000 0x60001fff rw"},
                {"text": "set serial baud 115200"}

Note that: the entry for “program” will need changing to match your debug compilation target; the serial port appears as “miDebuggerServerAddress” and has additional back-slashes compared to the previous configuration.

This uses the “machine interface” to GDB, which you can see by adding “–interface=mi” after the “-x gdbcmds”. There is a Python package which can interpret the gdb/mi responses: pygdbmi.

You should now be able to use the “Run and Debug” feature of VSCode; there should be an entry called “GDB” (using the “Quick Access” Plaformio Debug > Start Debugging also seems to work but I avoid that route as I don’t know what else it might do). I won’t repeat information on using the VSCode debugging interface here; there is plenty on the web! You should be able to see variables and to inspect the call stack while stepping through the code. What I will provide are some caveats and gotcha-avoidance measures.

Remember there is only one breakpoint

Unfortunately, VSCode does not let you set temporary breakpoints. So you must adopt a working practice of setting a breakpoint and then deleting it as soon as you get there (the config line ‘”hardwareBreakpoints”: {“require”: true, “limit”: 1}’  prevents you from adding more than one, but it isn’t that simple! It appears that the VSCode gdb/mi implementation uses breakpoints for “step over” operations, so you really must delete the breakpoint before stepping. If you get horrible red boxes popping up reporting exceptions etc, the cause is likely to be because you have left a breakpoint.

Where is my Serial.print() output?

In spite of the debugger, I still find Serial.print() very useful for reporting sensor readings etc.

These appear in the Debug Console.

Not all variables are locals

Although the VARIABLES panel shows local variables (and changes these as you select different levels in the call stack), global variables will need you to issue the GDB print command. Locate the Debug Console and note that it has a command entry line at the bottom. GDB commands may be entered here, but must be prefixed by “-exec” (e.g. -exec print foo). You can also add these as WATCH entries.

Adding a breakpoint while things are running

Adding a breakpoint while the ESP8266 is running causes it to stop execution where it is, rather than where the breakpoint has been added. Simply use Continue (F5) to make it continue until the breakpoint is met.

Some things don’t work

Although VSCode suggests otherwise, some things are not supported: PERIPHERALS, MEMORY, DISASSEMBLY.

The Debug Console command line entry comes to the rescue, e.g. try “-exec disassemble”.

Debugging Inside Setup

The problem with attempting to debug inside setup() is that the ESP8266 will normally have exited setup() before you connect GDB.

The neatest way of handling this is to add the following code into setup() just before you want to start debugging:

  #ifdef WITH_GDB

When you reset the ESP8266, this triggers entry into the debugger on the ESP8266, which looks like a breakpoint hit, and means that when you connect GDB you find you are stopped inside gdb_do_break(). Send the “finish” command to GDB twice and you’ll be inside setup().

This works nicely with the command line use of GDB but I haven’t been able to find how to make the VSCode debugger play nicely with it. In this case, the quickest option is to use something like delay(3000) instead of gdb_do_break(). This gives you enough time to start the debugger after resetting the device.

Make sure you quit any GDB session before resetting; things get all messed up otherwise.

Setting Variables

GDB permits variable setting through commands such as “set var my_var = 5”.

Unfortunately, this does not always work. Various comments on the web suggest this comes down to where the variable data is to be found when the program is running, because GDBStub cannot access all possible places.

A work-around is to declare variables with the “volatile” keyword.

Creating Panelised PCBs in Eagle for Seeed Studio

After some misadventure and blind alleys I have an efficient and reliable approach to panelising PCBs in Eagle with v-scoring (v-cuts) to aid in board separation. I am using Eagle 9.6.2 (free version) and send PCBs to Seeed Studio.

The starting point is the Sparkfun-Panelizer ULP. Thanks for open-sourcing this, Sparkfun; I couldn’t have “got there” otherwise. Unfortunately, this completely bombed for me due to its failure to cope with space characters in file paths. This is easily fixed once diagnosed. Towards the end of the ULP, change the line which says sprintf(s, “SCRIPT %s;\n”, scriptFile); to say sprintf(s, “SCRIPT ‘%s’;\n”, scriptFile);. See that I added single quotation marks; what a difference two characters can make in progamming!

A second issue with the Sparkfun ULP is that component names get changed because the Eagle PASTE operation prevents name collision by assigning the next available number. The upshot is that each panelised board gets a different set of component names printed. Arghh! This does make sense if you think about these as being unique identifiers, as Eagle sees the whole composite as “one board”. I got around this using a tool already within Eagle.

The final issue is that the Sparkfun ULP was made for their scenario and there are lots of things which are irrelevant and the default settings need changing each time. I also didn’t want to adopt their workflow concerning design rules and CAM processor config. So I streamlined the script for me (I could do more; there is some cruft remaining). Here it is: Panelizer2

The Procedure

1. Prepare a New Layer with Component Names

From the board in Eagle: Tools > Panelize.

This does not actually panelize anything, but generates a script by iterating through all the components. The result of executing the script is that the component names are written into layers 125 (aka “_tNames” for top components) and 126 (aka “_bNames”) for bottom components). Since these are just written as text, they no longer need to follow the unique naming rule; they are not names!

At this point, show only the new layers and delete anything you dont want (I have found some component names which I deleted from the board re-appear in the new layers). Also: be aware that items in the new layers are created every time the Panelize tool is run.

2. Run the Panelizer ULP

If the Sparkfun ULP works for you, go ahead. There is a tutorial on Or maybe you have spaces in your file paths and can use it with the fix noted above. Alternatively, if you are using Seeed Studio, try using my hacked version.

Run a DRC now!

3. Run a Modified CAM Process

The upshot of step 1 is that we have component names in four layers (two for the top and two for the bottom) and the ones which your usual CAM process rules will put into the silk-screen layer are the wrong ones. The change required is quite simple. Start by taking a copy of the “.cam” file and open it in a plain text editor (Notepad will do, but I prefer “Notepad++”).

You are looking for the occurrence of 25 or 26 within a “layers” structure. For example, a typical setup for a top silk-screen would include the placement and names and define this using:

“layers”: [

Simply change the 25 to 125 (i.e. _tNames) and 26 to 126.

Then just run your modified CAM file in the CAM Processor.

Notes Concerning Seeed Studio

I’ve found them fast (accounting for shipping from China), cheap, and (so far) of good quality. I use the basic PCB service, which has a 100mm x 100mm standard board and panelisation of identical boards attracts no additional fee. There are some rules concerning panelisation which the revised ULP adopts.

Blind Alley

In addition to the gremlins with the Sparkfun ULP, I did attempt to use “gerbmerge”; I had used this quite a few years ago. This time I used gerbmerge3, which is an adapted version for Python 3 (the older version was Python2 which has not been maintained for several years). Unfortunately, after setting up the config files, while the program ran, it barfed on one of my gerber files due to a directive which it did not recognise: “%MOMM*%”. I failed to find out what the significance of this is and whether I could safely hack the code to ignore it… only to find there was some other similar issue… and a rat hole of misery.

Updating EmonPi to Continuous Monitoring

Continuous monitoring with the Open Energy Monitor EmonPi hardare us now possible (since Feb 2023), see: This gives a more accurate measurement of power than sampling at time intervals.

Unfortunately, the process is incompletely documented there and the forum contains several threads which contain errors, distractions, and diversions alongside the information to make the firmware update work. I certainly had to spend time disentangling things to arrive at what is actually a simple procedure, although the forum was a source of some trepidation. Also: do not be tempted into the compilation process described on that firmware web page.

NB: what follows is based on my EmonPi setup. I believe some details will be different for EmonTX + EmonBase setup.

First, ensure that your system is up to date using Setup > Admin > Update: Full Update. This does not change the firmware, but will change what you see available in the Update Firmware Only section. Once updated, you can select options in the drop-down lists in the Update Firmware Only. My hardware is an emonPi and I opted for the “RFM68 LowPowerLabs” radio format (as recommended). Upon hitting the “Update Firmware” button, various messages will appear in the log.

Once it has completed, you will see that there are no updates in Setup > Inputs or Setup > EmonHub. This is because the baud rate and message format have changed. In Setup > EmonHub, use the “Edit config” button to fix this. Changes to two sections are required.

Under “[interfacers]” will be an entry which seems to have gone under different names at different times and/or different hardware configurations. If you have an emonPi, look for the section which contains “com_baud = 38400”, “pubchannels = ToEmonCMS”, and “baseid = 5”. Mine is identified as [[RFM2Pi]]. If you do not have an emonPi then a different baseid will apply. I only changed the com_baud from 38400 to 115200. Leave the rest alone!

Scroll down and find, under “[nodes]”, a section “[[5]]” (matches the baseid above). Leave the “nodename” entry as it is but modify the lines under “[[[rx]]]” to read:

names = Msg, power1,power2,power1pluspower2,vrms,t1,t2,t3,t4,t5,t6,pulse1count,pulse2count,E1,E2
datacodes = L, h, h, h, h, h, h, h, h, h, h, L, L, l, l
scales = 1, 1,1,1, 0.01, 0.01,0.01,0.01,0.01,0.01,0.01, 1, 1, 1,1
units = n,W,W,W, V, C,C,C,C,C,C, p, p, Wh,Wh

Note that the scales line can be used to adjust the power values and Vrms which the emonPi records to accomodate systematic errors due to component tolerances; the text quoted above assumes that this calibration has not been done.

I found that simply saving the config and then using the “View log” button showed this worked. Some people state that EmonHub should be restarted, but I did not find this was needed.

Make a final check that things are working by visiting Setup > Inputs and looking at graphs, visualisation, your app etc. At this point, you might note that there are now two new attributes in the input data: E1 and E2. Unfortunately (again, argh!), the meaning of these (vs the pre-existing power1 and power2) is not properly documented and mentions in the forums are often roundly uninformative.

Peak District Mining History Field Guides

I have written a series of field guides to mining history (and some geology and other historical notes) for selected areas in the Peak District. Each guide consists of a written field guide, maps, and digital location data for GPS devices.

The first guide describes three itineraries near Castleton: New Rake and Cave Dale, Pindale and Siggate, and Dirtlow Rake.
Version 1.0 published May 2023.

The second contains two itineraries around Millers Dale: Maury Rake and Tideswell Dale.
Version 1.0 published December 2023. More itineraries are in preparation for Millers Dale.

The third looks at coal mining west of Buxton, specifically the area around Derbyshire Bridge in the upper Goyt Valley, above Burbage, and across to Thatch Marsh and Cisterns Clough.
Version 1.0 published January 2024.

Castleton Mining History Field Guide

This field guide contains three itineraries around mining history sites (and some geology and other historical notes) near to Castleton in the Peak District: New Rake and Cave Dale, Pindale and Siggate, and Dirtlow Rake.

The main download is a zip file which contains a written field guide, maps, and digital location data for GPS devices.

If you make use this guide, please let me know by adding a comment. You can also post corrections and suggestions (but please note I am unlikely to respond to requests for more information).

Links to all mining history field guides may be found on the Peak District Mining History Field Guides index page.

Getting QGIS to Cache WMS Maps

Unfortunately, simply setting up the QGIS cache (see this guide if you don’t know how) won’t cause caching of plain WMS responses (no matter what that guide says!), whereas WMTS or XYZ servers do get cached. This can be seen by using the “Debugging/Development Tools” panel to monitor network activity.

The reason for this is that the extent which is in view in QGIS determines the WMS response image coverage, so unless you are at exactly the same position and scale, there will be no “hit” on the cache.

The answer is to add the WMS layer using the “Data Source Manager” (shortcut Ctrl-L), rather than from the “Browser”. This offers you the option to set the tile size (width and height) to use. Choose a layer then “Add”. NB: once added, it doesn’t seem possible to change the tile size. This forces requests to discrete tiles, with 1 request for each. Now, so long as you do not change scale, panning back-and-forth will cause QGIS to pick up the cached tiles even if you don’t pan back to the same place, since the tile boundaries are defined in spatial coordinates.

I used a tile size of 500×500 with some hillshade based on 1m spatial resolution Lidar. Small tile sizes are not a good idea as the network latency will kill the performance on first load (this can be used to show that caching is working, e.g. use a tile size of 100×100 clearly shows the 1st load performance contrasted to the use of cached tiles).

Sonoff Basic R3 – DIY Switch via HTTP POST of JSON

The latest firmware of the Sonoff BasicR3 Wifi Switch now allows the device to be controlled through the DIY mode built into its firmware (v3.6.0) without any re-flashing with Tasmota firmware or fooling about with jumpers. The only obvious limitation for some people is that the “eWeLink” app and DIY access cannot both be used together; the switch is either in DIY mode or app-control mode. This is not an issue for me as I have no requirement for remote control from outside my LAN and don’t intend to use the app at all. In any case it would not be hard to either use a general purpose HTTP “shortcuts” app (e.g. HTTP Shortcuts!) for control from a phone from my LAN, or to write/run my own web app of a Raspberry Pi. I begin to digress… the point of this post is to make some notes for myself in a way which someone else might find useful (and adding some extra helpful comments). Much of what follows can be found on the web, but there are some holes, and I didn’t find the documentation quick and easy in parts.

Getting into DIY Mode

The key is to get the device into what the Sonoff User Manual calls “Compatible Pairing Mode”. The push button is used in two stages, with long (5s) holds, first to get the LED signalling “..-” and then again to get continuous rapid flashing.

The switch is now acting as a WiFi access point with SSID (name) of “ITEAD-{device_id}”, where device_id will be something like “100136da83”. Connect to this network using the network security key 12345678 and then visit to access a web page which allows you to enter your own WiFi SSID and password. After a short while, the Sonoff device will have closed its access point and connected to your local network. It is now in DIY mode, and will stay this way when its power supply is disconnected and reconnected. The LED will signal “..”. You can still use the eWeLink app to add the switch to its device list, but this cancels the DIY mode. Also: once in DIY mode, you cannot access, no matter how many times you force the device into making “ITEAD-{device_id}” available. The exception to this is if you power the switch up so it cannot connect to your local network. In which case, the device will eventually (20s) give up trying to connect and become eligible to be forced into Compatible Pairing Mode again.

Finding the Device on the Network

This is not as simple as it might be; it would have been neater if the web page reported its network name before disappearing. This is a bit messy.

Option 1 is to look at the client list in your router admin web interface. This is likely to require the “advanced” option. In my case, my modem-router does provide a client list, but rather confusingly the client name which is reported, and the MAC address have no obvious connection with the device_id revealed above. The client name is like “ESP_80DD76”, which is the standard way an ESP8266 (etc) chip reports its name, which takes the last 3 bytes of the MAC address prefixed by “ESP_”. If you can see something like this, you’ve found the IP address and can progress to the “Control the Switch” section, below, although you will have to trust that the default port is used (I see no reason why it would not be).

Option 2 is to use an mDNS browser. The essence of mDNS is a service which links device names to IP addresses and other info. MS Windows doesn’t seem to have an easy way to do this, but if you also run a Raspberry Pi it is not hard. Mac users can use Bonjour, there are Android Apps, and linux users (of course) can do as follows anyway. The service/tool for the Pi is Avahi. This should already be up and running, which can be confirmed using “service avahi-daemon status”. The mDNS browser requires the avahi-utils package, which was not on my Pi, but installed with “sudo apt-get install avahi-utils”. The simple command is not “avahi-browse –all –resolve”, which will reveal that the mDNS name is of the form “eWeLink_{device_id}.local”. The port entry will report which TCP port should be used to connect to the device, which should be the default of 8081. The txt entry reveals the device state if in DIY mode, or a base-64 string of gobbledy-gook if in eWeLink app mode.

Option 2a is an Android App. I tried one called Service Browser, but there are other mDNS browsers

Option 3 is to take advantage of the observation that the mDNS name is of the form “eWeLink_{device_id}.local”. This is fine so long as your method of controlling the switch can work with mDNS names, which Postman cannot (at present).

Caveat: there is no guarantee that your router will assign the same IP address. In my case, I operate a router which allows “address reservation”, so that several IoT devices I have get known IP addresses. Unless your router has this feature, beyond tinkering, you will have to resort to using mDNS-aware software. If writing your own in Python, it looks like the “zeroconf” package is suitable for dealing with mDNS names and not worrying about reliable IP addresses.

Control the Switch

I use Postman for manual testing, and Python for anything automated.

The documentation for interacting with the device is fairly good, and can be found at This includes info on how to perform an OTA (“over the air”) firmware update, control how the device behaves when its power is restored (allowing you to choose whether it starts up off, on, or in its previous state), and to change the WiFI SSID and password which the device connects to, but I’m content with the info, on, off, and pulse options.

Note that all messages to the device are HTTP (not HTTPS) POST operations, with a JSON body (payload). Although the documentation includes “deviceid” in the JSON, this is completely redundant and can be omitted.


Operation URL JSON Body
Info http://{{ip_addr}}:{{port}}/zeroconf/info
 "data": {}
On http://{{ip_addr}}:{{port}}/zeroconf/switch
  "data": { 
    "switch": "on" 
Off http://{{ip_addr}}:{{port}}/zeroconf/switch
  "data": { 
    "switch": "off" 
Pulse http://{{ip_addr}}:{{port}}/zeroconf/pulse
  "data": { 
    "pulse": "on", 
    "pulseWidth": 2000

Pulse changes the behaviour of “On” operations; if Pulse is on then an “On” operation will only last for pulseWidth milliseconds, after which the device will turn off again. The maximum duration is 1 hour. The JSON payload for Pulse can omit the “pulseWidth” to enable/disable the feature, but it is not possible to change the pulse duration by only specifying “pulseWidth”.