Updated: January 21st, 2017
Updated: June 22nd, 2017
When I purchased my first ITEAD Sonoff WiFi switches, I also got a Wemos D1 mini board. I thought getting a ESP8266 development kit would be a good way to prepare for hacking the switches. Two You Tube videos on educ8s.tv, Wemos D1 mini: A first look at this ESP8266 based board and WeMOS D1 ESP8266 vs Arduino Uno, Arduino Due and Teensy 3.2. Which one is the fastest board? and the series of articles at HACKADAY by Elliot Williams were positive influences in that decision. Indeed, what follows borrows heavily from the latter.
The very first thing I did with the Wemos D1 mini is to blink the LED
using the Arduino 1.6.13
IDE. The only problem encountered was getting access to the serial link
(ttyUSB0) on my Linux desktop. I found two solutions, changing the
permissions to the device or, the one I adopted, becoming a member of the
dialout group. The second thing I did was to get an HTML page
from the Web. Both sketches are in the Arduino library.
I then wanted to follow Elliot Williams' articles on MQTT, notably the first MINIMAL MQTT: NETWORKED NODES. He uses NodeMCU firmware, which is based on the ESpressif SDK and was initially developed in conjunction with the NodeMCU development kit. The Wemos D1 mini is like a younger sibling. Using NodeMCU is a little bit trickier than using the Arduino IDE. I have documented how I managed to do it below.
While there is at least one usable IDE for the NodeMCU, Elliot Williams does not suggest using one. Following his lead, we will do this like "real programmers", and use Python command line utilities to flash the NodeMCU firmware and to upload Lua script files.
esptool.pyabout five week ago, I obtained version 1.2.1. A newer version 1.3 is available but I have not needed to update. Interestingly, Wemos recommends Christian Klippel's version: esptool-ck. What's the difference? Dunno!
We also need a way to establish a serial link with the D1 mini. Apparently this
can be done with PuTTy on a
Windows desktop. Since I had the
Linux version installed, I tried using it in my
Ubuntu box, but without success. Initially, I used
GNU Screen but found it very awkward and eventually
decided on using yet another Python script:
miniterm.py. To make
things simple, the latter seems to have been installed along with
esptool, so if that route is chosen nothing needs to
If you do want to use Screen, it may have to be installed on your system:
Flashing the D1 mini
The firmware, NodeMCU , is very modular. It needs to be because the typical Esp8266 based controller has rather limited memory. Everything is relative, my first computer had 4k bytes of memory, my first serious Z80 machine had 64k bytes of memory and external storage was on 256k bytes 8" floppies. In comparison, the Wemos D1 mini has "only" 4M bytes of memory. In any case, not all modules available for the chip will fit in 4MB and there must be some room for the application code. Here are two possible ways of getting the appropriate firmware.
Download Elliot Williams' built of NodeMCU. Go to
https://github.com/hexagon5un/hackaday_mqtt and click on the
green [Clone or download] button then click on the Download
Zip link. I saved the archive to
/home/michel/Téléchargements/WemosD1mini/hackaday and then
extracted the content.
2. To experiment using NodeMCU with Domoticz, I wanted other modules. So, as recommended by Elliot Williams, I went to the NodeMCU custom builds site by Marcel Stör and choose the modules to be included in the binary image to flash. These are the modules I am presently using.
|SJSON||JSON support module which allows encoding and decoding of JSON strings. SJSON is a recent replacement of CJSON previously used (update: June 22nd 2017).|
|DHT||Read DHT humidity and temperature sensors|
|file||provides access to the SPIFFS file system and its individual files on the internal flash memory.|
|GPIO||provides access to the GPIO (General Purpose Input/Output) subsystem.|
|HTTP||basic HTTP client which can do GET/POST/PUT and DELETE requests.|
|MQTT||client that can publish and subscribe to an MQTT broker.|
|node||provides basic chip information and access to the Lua interpreter.|
|timer||provides access to simple timers, alarms, the system counter and uptime.|
|UART||allows configuration of and communication over the UART serial port.|
|WiFi||allows configuration of and communication over the wireless local area network (WiFi).|
/home/michel/Development/NodeMCU/nodemcu-master-10-modules-2017-01-16-19-52-22-integer.binfrom the link provided in the message I received from the build site. The build took only a couple of minutes. If you don't seem to be getting a message, then as suggested on the site, look in the spam folder.
The final step is to download the firmware to the board. Connect the board to the desktop computer with a USB cable. On my system the serial link is the device /dev/ttyUSB0. It could be a different device on another computer. Then change the directory to the one containing the downloaded image file (whichever one you use) and flash it.
To talk to the Wemos D1 mini over the serial link, it must be connected to the desktop computer with a USB cable. If using Screen on the desktop, you need to know the port and then establish a 9600bps 8N1 connection.
Eventually, I settled on using
miniterm.py which prompts for the
port and established the connection details on its own:
Menu: Ctrl+T, nothing much happens if you press that key combination on its own. It is an escape character that must be followed by another keyboard combination. Do the CtrlT CtrlH sequence to get more information.
Once the '>' prompt is obtained, you are actually in the Lua interpreter and you can check that everything is fine by doing something very simple:
Time to blink the builtin led. It is connected to pin 4.
I should mention that
tmr.delay in not a good idea. See the
NodeMCU Documentation on that topic.
Let's make this a little easier to use by creating a
You can repeat the last two steps, varying the blink count, any number of times. I bet you will do it more than once, there is something strangely satisfying in seeing that LED flash on and off at one's command.
Using a File Uploader
By now, if you are not a perfect typist, you know that using the
Screen terminal is a painful experience and
miniterm.py is not much fun either.
We can use the NodeMCU file system to upload and
execute Lua scripts.
Use your favourite text editor to create a short lua script (or
and save it to a file named
I saved that file in the following directory
~/Documents/Site/michel/src/program/misc. The next step is to
change to the file's directory, upload it, check that it is stored in the
D1 mini flash memory and the execute it.
nodemcu-uploader. If problems persist, try resetting the D1 mini. If problems persist and you used
screenwith default values, try inserting the
-B 9600option just before the
The last line of the
blink.luascript calls on the
doBlink function to perform the action which is why something
will be seen when
nodemcu-uploader exec blink.lua is run.
But it will often be the case that a script is meant to be used interactively.
The work flow will then be different. To illustrate how to proceed, remove
the last couple of lines in
blink.lua and reload it just as
You could run
nodemcu-uploader exec blink.lua but nothing visible
will happen. Instead open a serial link with the D1 mini and then run the script
and call on
dofile(script-name)is the equivalent of
nodemcu-uploader exec script-name; it executes the script, which in this case amounts to creating the
doBlinkfunction. The later can then be invoked in the interpreter as often as desired, with whatever value wanted for
You could invoke
miniterm.py without the port and baud options.
The program will find the port. Well it does that on my system maybe because
there is only one serial connection to the computer. But the baud will be set
to 9600 bps and this will cause problems because by default the Wemos D1 mini
sets the rate of its serial port at 115200 bps. And as can be seen above,
nodemcu-uploader uploads the script at that speed. It is difficult
to negotiate a new serial rate. I have found it necessary to reset the D1 mini
miniterm.py with its own default rate. It is much more
productive to use the default 115200 bps rate. And with both
screen (which could be used instead of later but with the same
options), the rate cannot be specified without putting the port before.
While a bit more awkward than an IDE, I have found running the sequence
nodemcu-uploader exec script-file
miniterm.py port 115200
We will finish this introduction with another rather simple program that
will serve as the beginning of a remote garage door sensor. There will
be a contact switch that will be closed when the garage door is closed and
open when the garage door is open. The builtin led, that will serve as a
warning signal, will reflect the opposite state, it will be on when the garage
door is open and off otherwise. The Fritzing image below shows the connection.
Note how D5 is grounded when the reed switch is closed and how it will be pulled
high by a resistor when the reed switch will be open.
Use a text editor to create the following Lua script called
switch.lua or download it.
Upload the script, check that it is in the file system and then execute it.
This program is caught in an infinite loop. To stop, press the RESET button on the D1 mini.