Huzzah Weather Display

2015-12-02 | By Adafruit Industries

License: See Original Project Arduino

Courtesy of Adafruit

Guide by Andy Doro

Overview

The Huzzah ESP8266 module is an inexpensive microcontroller with WiFi capabilities. It can be programmed with the Arduino IDE so that you don't need a separate microcontroller! This device gets the latest weather information from forecast.io and displays it on a 1.3" monochrome OLED display.

Note on difficulty: this is an intermediate level project and involves running a PHP script on a web server to parse data from forecast.io before it gets read by the Huzzah. It's helpful to know some basics about PHP and web servers before starting this project!

This project was created by Daniel Eichhorn and the code was forked to work with Adafruit hardware and libraries.

The weather icons were created by Alessio Atenzi.

Dano Wall designed the lasercut enclosure.

Parts List

Electronic Parts

Huzzah ESP8266 Breakout
Monochrome 1.3" 128 x 64 OLED graphic display
USB micro-B breakout
2 x 1-pin male headers (these are included in the above breakouts) 6-pin right angle header (cut from one of these)
thin wire
MicroUSB cable (for powering the clock)
5 V 2 A USB port power supply (if you don't want to just power the clock from your computer's USB port)
A web server running a small PHP script. You can even use a Raspberry Pi running locally on the network or any web hosting service you use.

Enclosure Parts

2 x laser-cut acrylic pieces (download vectors from repository)
3 x 1" 2-56 screws
1 x 3/4" 2-56 screw
2 x 1/4" 2-56 screw
15 x 2-56 hex nuts
2 x 3/16" nylon spacers

Tools

A computer which can program the Trinket Pro 5V
FTDI cable (for programming the Huzzah breakout)
A soldering iron
Solder
Wire strippers
Diagonal cutters
Small flathead screwdriver (2.4mm)

Circuit Assembly

Overview

The goal is to solder the Huzzah and OLED breakout boards so that the OLED screen and Huzzah module are facing in opposite directions. The two buttons on the Huzzah need to be accessible to put the module into bootloader mode and program the Huzzah.

The power and ground will ultimate be connected to the 5V and GND pins on the microUSB breakout board. We'll use a microUSB cable to power the device.

First Steps

On the OLED breakout, solder the two solder jumper pads SJ1 and SJ2 so that you can use the I2C protocol. Do this before soldering the boards together!

You should get a 6-pin right angle header to solder into the Huzzah FTDI pins. Do this before soldering other things together! Be sure to solder all six headers securely.

Ultimately you will solder the two boards with a header pin lining up V on the Huzzah and Vin on the 1.3" OLED. This way all the boards will stack up nicely. Make the other wire connections before soldering the two together however, since it will make the process easier. I've found that thin-gauge, wrapping style wire works best.

Start by soldering a header pin into the Vin on the 1.3" OLED breakout.

If we examine the schematic again, notice that the Huzzah has two GND pins. Since there will be multiple connections to the same GND pin, it can be helpful to solder a male header pin into one of the GND pins. Make sure it's sticking out more on top, so solder it on the bottom of the Huzzah board.

Now make the other connections between the Huzzah and OLED breakout board following the schematic below using thin wire. Remember, ultimately you'll use the header pin soldered into the OLED breakout to make the 5V power connection between the two boards.

From the Huzzah to the OLED breakout, connect:

pin 2 to Rst
pin 12 to Clk
pin 14 to Data
GND to GND

Now you can solder the Huzzah and OLED breakout boards together. They should be facing away from each other and lined up like this. Place the Vin header pin on the OLED breakout into the V on the Huzzah.

Now connect the MicroUSB breakout. Connect the 5V pin to the header pin going through V on the Huzzah.

You can also connect the GND pin on the MicroUSB breakout to the header pin sticking out of the Huzzah GND.

Once you've attached the MicroUSB breakout you can cut down the excess header on the V pin and GND pin. The circuit is assembled!

PHP script

Download the code from github by clicking Download ZIP. Uncompress the file and find the folder named php.

Using an FTP client, upload these files to a web server which runs PHP-- most of them do. You can even run it on a Raspberry Pi on your local network. Be sure to also include the contents of the lib folder.

This PHP script parses some information from Forecast.io and takes some of the heavy string processing off the shoulders of the ESP8266.

The script is setup to get the temperature in Fahrenheit and other information in English. If you'd like to change this modify the following lines of code:

Copy Code

$units = 'us';  // Can be set to 'us', 'si', 'ca', 'uk' or 'auto' (see forecast.io API); default is auto
$lang = 'en'; // Can be set to 'en', 'de', 'pl', 'es', 'fr', 'it', 'tet' or 'x-pig-latin' (see forecast.io API); default is 'en'

Go to https://developer.forecast.io/register and sign up for a free API key. At the free level there's a pretty generous limit to the number of requests per day you can make, well below what we'll be using.

It's a good idea to test the PHP script at this point by pointing your web browser to: http://YOUR_DOMAIN_NAME/weather.php?apiKey=APIKEY&lat=40.71&lon=-74&units=us

Alter this URL to point to your PHP script, replacing YOUR_DOMAIN_NAME with the actual domain name hosting your script and replacing APIKEY with the API key you received from forecast.io. This longitude and latitude are for New York City- feel free to change them to get the weather for your location in the world. NASA has a good tool for finding your longitude and latitude.

If you manage to enter the URL correctly, your web browser should give you a webpage that looks like this:

Uploading Code

Arduino Code

Make sure to use Arduino IDE 1.6.4 or higher and follow this tutorial to install the ESP8266 board packages.

Download the code from github by clicking Download ZIP. Uncompress the file and copy the folder to your Arduino sketchbook folder.

Attach the Huzzah ESP8266 to your computer using an FTDI cable. Since it's possible to connect the FTDI cable backwards, make sure to line up the black wire on the FTDI cable to the GND pin on the 6-pin connector. The Huzzah will get power from the FTDI cable, you don't have to have the microUSB plugged in.

Once that is done, open the sketch and select:

Tools → Board → Adafruit HUZZAH ESP8266

CPU Frequency → 80 MHz

Upload Speed → 115200

Port → select the USB port with the FTDI cable

Make sure the code compiles properly. All of the relevant libraries should be included.

For more information on using the Huzzah ESP8266 module with the Arduino IDE, follow this tutorial.

Modifying the Code

You'll need to make some modifications to the code to make it work properly on your WiFi network.

Copy Code

#define WIFISSID "YOUR_WIFI_SSID"
#define PASSWORD "YOUR_WIFI_PASSWORD"

Replace YOUR_WIFI_SSID with the name of your WiFi network and PASSWORD with your WiFi password. Keep the quotation marks!

Copy Code

#define FORECASTAPIKEY "YOUR_FORECAST_API_KEY"

Replace YOUR_FORECAST_API_KEY with the API key you received when you signed up with forecast.io. Keep the quotation marks!

Copy Code

#define DOMAINNAME "YOUR_DOMAIN_NAME"

Replace YOUR_DOMAIN_NAME with the domain name hosting the PHP script, e.g. adafruit.com. Keep the quotation marks!

In WeatherClient.cpp feel free to alter the URL path to reflect the location of your PHP script on the web.

It's a good idea to test the PHP script at this point by pointing your web browser to: http://YOUR_DOMAIN_NAME/weather.php?apiKey=APIKEY&lat=LATITUDE&lon=LONGITUDE&units=UNITS making the appropriate substitutions for APIKEY, LATITUDE, LONGITUDE and UNITS.

Copy Code

// New York City
#define LATITUDE 40.69
#define LONGITUDE -73.99

This longitude and latitude are for New York City- feel free to change them to get the weather for your location in the world. NASA has a good tool for finding your longitude and latitude.

Uploading the Code

Attach the Huzzah to your computer using an FTDI cable, making sure to plug it in the right way. When you're ready to upload the code, put the Huzzah module into bootloader mode. You'll have to do this before each upload. There is no timeout for bootload mode, so you don't have to rush!

Hold down the GPIO0 button, the red LED will be lit
While holding down GPIO0, click the RESET button
When you release the RESET button, the red LED will be lit dimly, this means its ready to bootload

This is what a successful upload will look like:

It can be difficult to access the buttons once the module is in the enclosure! The best way I've found is to manipulate the two buttons with two pairs of tweezers.

Debugging

Use the Arduino IDE Serial Monitor at 115200 baud to check for error messages. The device should connects to WiFi and download the webpage immediately, and then do this again every ten minutes.

If the Huzzah connects to the WiFi network and webpage correctly, the window should look something like this:

Make sure the URL matches the actual location of your PHP script. You can test it by pasting it into a web browser.

If the code is uploaded correctly, you should see the display showing the weather for "Now", "Today" and "Tomorrow".

Enclosure Assembly

The lasercut enclosure consists of two laser-cut pieces of acrylic held together by screws. The vector files are available from the Github repository or you can download them here:

The enclosure can be put together with some 2-56 machine screws and hex nuts:

3 x 1" 2-56 screws
1 x 3/4" 2-56 screw
2 x 1/4" 2-56 screw 1
5 x 2-56 hex nuts
2 x 3/16" nylon spacers

Start by removing the protective sticker from the OLED breakout. Place it into the laser-cut acrylic piece with the corresponding hole or window. Notice the small notch which corresponds to the OLED ribbon connector. It can help at this point to remove the double-stick tape affixing the OLED to the breakout PCB in order to get things lined up well.

Start by putting a 1" screw through the top left hole (if the screen is facing you). This screw will go through all three breakout boards, lining them all up! Start by putting two hex nuts between the the OLED breakout and the Huzzah breakout and putting the screw all the way through. Don't overtighten though!

Add a 3/16" nylon spacer and hex nut at the end.

Place the 3/4" screw into the top right hole of the Huzzah breakout. You might need to angle this in to get past the OLED breakout. Tighten down with a hex nut.

Place the 1/4" screw through the top right hole of the acrylic and secure it on the other side of the OLED breakout with a hex nut. This can be a bit tricky- you may have to hold the hex nut in place with needle-nose pliers while you tighten the screw with a screwdriver.

Add a nylon space and hex nut to the 3/4" screw.

Attach the microUSB breakout to the other piece of lasercut acrylic. Use a 1/4" screw and hex nut to fix the left hole of the breakout to the acrylic on the side with the cutout notch. The cutout notch is there to allow a microUSB cable to connect.

Place the other hole of the microUSB breakout through the 1" screw and secure with a hexnut. You can also secure the other side of the acrylic with a hex nut.