Skip to content

WiFi Color Display Kit§

How to assemble and program the ThingPulse ESP8266 WiFi Color Display Kit.

Note

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:

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/.

Preparation§

Material inspection§

Here is the list of parts: display module (left), custom PCB (bottom right), WeMos D1 mini (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.

Soldering§

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§

Install drivers§

A prerequisite to program ESP*-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 or ESP32 module. There are two commonly used adapters in the wild these days:

  • Silicon Labs CP210x
  • Winchiphead CH340x / CH341x

Newer boards (2022+) often use the Winchiphead CH9102 chip.

Popular modules that use the CP210x are:

Examples of modules that use the CH340G chip are:

  • WeMos D1 mini
  • D1 mini Lite

Examples of products that use the CH9102 chip are:

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/ESP32 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§

Winchiphead (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.

Warning

Some systems require a reboot before the driver installation can be successfully completed. The installer may or may not tell you about this! If you later connect the ThingPulse device and the system does not recognize it try rebooting as a first measure..

Winchiphead CH9102§

Follow the instructions over at Adafruit.

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. Note: ThingPulse does not recommended to install beta or RC versions.
  • Take a break until the installer finishes.

Arduino IDE board manager ESP8266

From time to time you want to come back to the Board Manager and make sure that you have the latest non-beta non-RC 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 GPIO1, 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

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.

Warning

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.

Select flash mode and flash size§

The WeMos D1 mini module included in this kit has an embedded 4MB SPI flash memory. 3MB of that will be reserved to host a SPIFFS file system. If you select the correct board in the IDE the flash mode and flash size settings should get auto-configured. Verify the settings are as follows:

  • in Tools > Flash Size select "4MB (FS:3MB OTA:~512KB)"

In older versions of the ESP8266 toolchain (ESP8266 Arduino Core) this was "4M (3M SPIFFS)" or similar.

The application might fail to transfer or fail to start if the flash options are not configured properly. Make sure the menu under Tools looks like this:

Install libraries§

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.

Create OpenWeatherMap API key§

As your device will be displaying data from OpenWeatherMap 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 within your allotted quota.

  • Go to https://docs.thingpulse.com/go/create-openweathermap-key
  • Take note of the features in the "Free" column. By using the free plan you are limited to 60 calls per minute.
  • In the "Free" column click on "Get API key and Start". OpenWeatherMap API plan overview
  • On the "How to start" page click on the "Sign Up" button OpenWeatherMap API how to start
  • Fill in email and password to sign-up for a new account OpenWeatherMap API Signup Form
  • Remember the key generated here OpenWeatherMap sign up

Once the API key is created you can come back to this page any time to edit or delete it.

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:

Open project in Arduino IDE

Configuration & customization

In one of the tabs the IDE opened settings.h. 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 OpenWeatherMap 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.

Operation§

Touch calibration§

After a restart press and hold on first screen will force a touch screen re-calibration.

A touch in one of the four quadrants changes the display. Tapping the

  • Top part (date & time) toggles the 12 or 24 hour time format.
  • Middle left cycles one screen left.
  • Middle right cycles one screen right.
  • Bottom part (sun/moon information) jumps to page 0.

Operation