WiFi Color Display Kit§
How to assemble and program the ThingPulse ESP8266 WiFi Color Display Kit.
It is advisable to read these instructions carefully before you start soldering. In particular please make sure that you have all parts and tools ready.
In addition to the components in the kit you will need:
- soldering iron
- insulating/electrical/duct tape
- cutting pliers or desoldering braid to remove the SD card holder
If you need help at any point with the following guide do not hesitate to reach out to ThingPulse and their community through https://support.thingpulse.com/.
Here is the list of parts: display module (left), custom PCB (bottom right), WeMos D1 mini Pro (top middle) and the two pin header rows.
Dry run assembly§
Stack the parts up as shown below without soldering and adjust it until it makes sense.
While you could insert the pin headers into the D1 mini like in the picture consider this: if you turned them upside down and inserted them with the longer end from underneath the D1 mini, this would allow you to later add an extension shield on top (there's a picture below). If you do not need that flexibility and want to place the pin headers like in the picture then you need to solder them to the D1 mini first. D1 mini-plus-headers are then soldered to the PCB. Otherwise the order is reversed.
Prepare display module§
THIS IS OPTIONAL
In order to get a stack which uses the least amount of space you will want to modify the display module a bit. The SD card holder has to go, sorry. Depending on your (de)soldering skills you can either use a desoldering braid or just cut the SD card holder off with pointy cutting pliers.
Short circuit prevention§
To prevent the D1 mini from accidentally causing a short circuit with the display board you can tape off the area below the connector board.
Connect PCB and D1 mini§
The options of which way to place the pin headers between PCB and the D1 mini were discussed earlier; hope you made up your mind. To achieve what you see below the recommended steps are as follows:
- stack the parts up as shown
- hold the stack between your fingers and flip it over
- solder the pins to the PCB from the back
- flip the stack back and solder the D1 mini from the top
Connect PCB to display§
In the last step of the hardware setup you will solder the connector PCB to the display as shown below.
Here is a speed-up video with all the steps above. Note how PCB and display are connected in a more "space-generous" way.
Development Environment Setup§
A prerequisite to program ESP8266-based modules usually is to establish a communications channel from your development platform (PC, Mac, Linux) to the device over USB. This in turn requires your system to detect the USB-to-Serial (aka USB-to-TTL, aka USB-to-UART) adapter on the ESP8266 module. There are two commonly used adapters in the wild these days:
- Silicon Labs CP210x
- Winchiphead CH340x / CH341x
Popular modules that use the former are the NodeMCU v1.0 (i.e. V2) module and some revisions of the WeMos D1 mini Pro. Examples of modules that use the CH340G chip are the WeMos D1 mini and the D1 mini Lite.
Note that there is no harm done if you install both drivers even if you currently just use one! If you are not sure which adapter your ESP8266 module uses then just install both.
Silicon Labs CP210x§
Silicon Labs maintains a page in English that lists downloadable driver binaries that also contains installation instructions.
Winchiphead CH340x / CH341x§
Winchihead (WCH) maintains its website only in Chinese. However, the download page for the drivers is so simple that even non-Chinese speakers will find the right download link.
Prepare Arduino IDE for ESP8266§
The Arduino Integrated Development Environment (IDE) is the tool you will use to program the ESP8266. IDEs are more than just editors; they help you with various tasks during the development process.
To install the Arduino IDE go to https://www.arduino.cc/en/Main/Software and download the latest version for your operating system:
- For macOS you can download a ZIP file which you then have to extract.Take the extracted application “Arduino” and move it to your 'Applications' folder.
- For Windows you have the option between an executable installer and a ZIP file.The ZIP file might be the better option if you do not have administrator permissions on your system. The installer on the other hand can put the libraries in the proper places.
Now you have a bare Arduino IDE which brings everything needed to write programs for the standard Arduino ATmega chips. But we want to write and compile code for the ESP8266.
Install the ESP8266 toolchain§
A tool chain is the set of tools that lets you compile and create binaries for a certain platform. Since we want to create binaries for the ESP8266 we need a different tool chain than the one that comes with the plain vanilla Arduino IDE. One of its wonderful feature is the Board Manager. It lets you install support for many different chips and boards with just a few clicks.
- In the Arduino IDE open the preferences/settings and enter http://arduino.esp8266.com/stable/package_esp8266com_index.json into the text box Additional Board Manager URLs.
- Now go to Tools > Board: ... > Boards Manager..., search for the "ESP8266" board and click Install.
- Take a break until the installer finishes.
From time to time you want to come back to the Board Manager and make sure that you have the latest version of the ESP8266 tool chain installed. To do that simply click on the ESP8266 entry and select the latest version from the dropdown. Then hit Update.
Select board and serial port§
The Arduino IDE knowing about ESP8266 modules in general is not enough as they are not all the same. There are subtle
but important differences as for available flash memory and how they can be programmed. The selection of the correct
board also defines the names of the GPIO pins. The designers of the NodeMCU module for example decided to introduce a
completely new naming scheme for the pins. Instead of calling them
GPIO2, etc. they relabeled them and
prefixed each one with “D”.
D0 is GPIO16,
D1 is GPIO5 and so on. By selecting a specific board in the Arduino IDE
you automatically have the correct naming scheme and other relevant parameters available,. This helps a lot as for
the NodeMCU modules for example those names are also printed on the PCB.
Not all ThingPulse kits come with the same ESP8266 chips/modules. We carefully selected the best option for each kit. It's essential that you know which module you get with a specific kit so you can configure Arduino IDE correctly
- Starter Kit → NodeMCU 1.0 aka v2
- Color Display Kit → WeMos D1 mini (Pro)
- ESPaper Kits → Generic ESP8266
In the Arduino IDE do as follows:
Tools > Board: * > select as per the above list
In an earlier step you installed drivers for the USB-to-Serial converter. If everything went well and the device is
plugged into your computer you should now be able to select the serial connection. It should show up in the Menu
under Tools > Port. On macOS the serial devices are called
/dev/cu.xxx. On a PC it should be listed
as a COM port labelled
COM# (where # is some number).
If you cannot see your device in the port list, try to unplug it and re-plug it after a few seconds. Also try a different USB socket. If that does not help try restarting your computer and/or try with a different USB cable.
Depending on what you had previously been working with in the Arduino IDE you need to adjust the UART baud rate. Tools > Upload Speed should be at least 115200. Depending on host OS and driver you can go all the way up to 921600. You need to experiment with this setting a bit; higher is better of course
The ThingPulse Weather Station Color depends on a number of other libraries. They need to be made available to the Arduino IDE for them to be compiled and linked into the final application.
Go to Sketch > Include Library... > Manage Libraries.... Then, for each library, put its name into the text field to have its metadata pulled from the internet and displayed below. Select the latest version and install it. Make sure to come back to this dialog from time to time to keep each library up to date. Also make sure that you only have one version of each of the libraries installed.
- Mini Grafx by Daniel Eichhorn
- ESP8266 WeatherStation by Daniel Eichhorn
- Json Streaming Parser by Daniel Eichhorn
- simpleDSTadjust by neptune2
- XPT2046 TouchScreen by Paul Stoffregen
Create Wunderground API key§
Important note regarding the use of Weather Underground data
The open-source software that ThingPulse provides for its devices relies on weather data pulled from Weather Underground. The standard setup process involves creating a Wunderground API key (documented below). The usage was free for up to 500 requests per day or 10 requests per minute.
In the evening of May 15th The Weather Company, a subsidiary of IBM, announced that it will no longer provide free weather API keys. There was no prior announcement and the change became effective immediately. It is unclear for how long existing keys will still be valid. As not even the tens of thousand of weather station owners who deliver their data to Wunderground for free will get a key to read their data back the uproar in the community is big.
For you this means that unless you already obtained a key from Wunderground you can not use the ready-made software for your ThingPulse device. We are very sorry, and furious, about this development but our hands are tied. The promise to our customers is that we will be working hard and not rest until we can offer an adequate alternative integration. We started working on a new service integration on May 19th.
So, again, as per the note above the instructions below became effectively void on May 15th. They remain here for the time being until the dust over this issue has fully settled.
As your device will be displaying data from Weather Underground you need an "API key" from them. It uniquely ties requests from your device(s) to your account and ensures that the number of requests remains withing your allotted quota.
- Go to https://docs.thingpulse.com/go/create-wunderground-key
- Select the "Stratus Plan".
- Take note of the "Developer" rate limits and hit the "Purchase Key" (even if you do not actually purchase) button.
- Fill in email and password to sign-up for a new account
- Fill in required information about how you intend to use the API key
Once the API key is created you can come back to this page any time to regenerate or edit it.
If the instructions above are not detailed enough or if you would like more visual guidance there is a good video how-to at https://youtu.be/yQHrnmeWTRk.
Weather Station Color project§
With all the preparation done you will - finally, sigh - turn to the Weather Station Color project itself. Fortunately, this last step is a rather simple one.
Obtain the code
The WiFi Color Kit project is, as all of ThingPulse's open-source code, publicly accessible on GitHub. Hence, there are two options to download the code:
- Clone the repository with Git:
git clone https://github.com/ThingPulse/esp8266-weather-station-color
- Download the sources from https://github.com/ThingPulse/esp8266-weather-station-color/archive/master.zip and unpack them somewhere to your local file system
Open project in Arduino IDE
- Start the Arduino IDE
- File > Open
- find and select
esp8266-weather-station-color.inofrom the previous step.
Configuration & customization
In one of the tabs the IDE opened
Go through the file and adjust the two handful of configuration parameters. They are all documented inside the file
directly. Everything should be self-explanatory. Most importantly you will need to set the Wunderground API key you
obtained in a previous step.
Upload code to device
The very last step really is to upload the code and all its dependencies to the device from the Arduino IDE. You do this through CTRL + U (⌘ + U on macOS) or Sketch > Upload or the right-arrow icon in the toolbar.