search

jpasqua / JAWS

Just Another Weather Station
0 stars 0 forks source link

readme

JAWS - Just Another Weather Station

This is just another weather station (JAWS) which is derived from the Solar Powered WiFi Weather Station project from instructables. You build some electronics, 3D-print a case, load this software, configure an app on your phone, and you're all set. What could be simpler? This software relies on the Blynk service to collect data in the cloud and make it available to the app on your phone. In the future, other services may be supported.

The weather station is configured using a Web User Interface where the user will specify information such as:

Some of this configuration information is specific to JAWS while other information is common to any web-connected device. You can learn more about such WebThing's here.

JAWS also has an optional GUI that can be used for simple weather modules (typically indoors) where you would like to be able to see the readings directly.

Dependencies

Libraries

The following third party libraries are used within this project:

† The primary sensor in JAWS may be a BME280 or a DHT22. Depending on which you choose, you will only need the library associated with it.
†† This library is only needed if you have an attached display showing a GUI.
††† The primary sensor can be augmented with a more accurate temperature sensor. These libraries are only needed if you are doing so.

Services

The following services play a role in providing parts of the functionality:

Organization

Directory Structure

The directory structure of the project is shown below. You don't need to know this to build and use the project, but if you want to work on it, this will give you an idea of where everything is located.

    JAWS
        [Primary Source files including JAWS.ino]
        /data
            [HTML page templates for JAWS]
            /wt
                [HTML page templates for WebThing]
        /doc
            /images
        /src
            /clients
                [Sensor Interfaces]
            /gui
                [Implementation of all of the Screens]

Code Structure

The primary functional areas of JAWS are given below. You don't need to know this to build and use the project, but if you want to work on it, this will give you an idea of where the different functionality is implemented.

Building JAWS

JAWS has been built and tested with Arduino IDE 1.8.10 and ESP8266 cores 2.6.1 and 2.7.1. Newer versions are likely to work, but I haven't tried other specific combinations. If you have never built an Arduino project using an ESP8266, you'll need to prepare your development environment. JAWS also supports the ESP32, but has minimal testing to date. It requires v1.0.5rc2 or later of the ESP32 Arduino core.

Hardware

Configuring Your Hardware

There are many ways to assemble a working weather station and a couple of primary examples are given below. Regardless of which you choose, you need to provide some configuration information by editing the file HWConfig.h. In it you will specify things such as which pins to use for the I2C bus, whether there is a display attached for a local GUI, and whether there is a secondary sensor attached. There are a number of pre-configured blocks of settings you can choose from, or you can specify all the details for yourself.

Notes:

Full Weather Station

You can build a full solar-powered weather station using the list of required hardware and assembly instructions from the instructables site. There is even a PCB available which makes for a very neat result.

In a few minutes you'll be reading about low power mode and it will mention using a switch/jumper to bypass it. You'll need to add that switch or jumper to the PCB. I used the same type of slide switch used for the power switch. Place it on the board on the pads labeled GND, D7, and VCC. Sliding the switch so it connects D7 to GND bypasses low-power mode.

Simple Weather Module

If you want to have a simple weather sensor that does not have solar charging, you can use a standard ESP8266 with a BME280 sensor. For example, you may want a module in the garage, a shed, the attic, etc. For these applications (typically indoors or otherwise protected), you may also have a display to show the readings locally. You can even use an integrated module like this one that has the display pre-integrated.

Adding a Display

By adding a local display and a push button, JAWS can provide a very simple GUI which reads out the primary values from the weather sensor. The display must be:

Interacting with the device requires a single momentary push button. You must tell JAWS about the hardware you chose and how you chose to connect it. This is done in the HWConfig.h file.

Notes:

Sensors

JAWS has a primary sensor and an optional extra sensor. You specify which primary sensor you are using and whether you have an extra sensor in HWConfig.h.

JAWS normally takes all of its readings (temperature, humidity, and barometric pressure) from a single BME280 sensor. The PCB mentioned above accommodates a BME280. However, some people may prefer (or happen to have) a DHT22 sensor. JAWS allow either to be used as its primary sensor, though the DHT22 does not support barometer readings. Therefore when using a DHT22 pressure and relative pressure readings will not be shown in the Web UI, sent to Blynk, or displayed in the (optional) GUI.

You choose your primary sensor in HWConfig.h. If you wish to use the BME280, set DHT22_PIN to -1. To use the DHT22 instead fo the BME280, set DHT22_PIN to the actual pin that you are using.

The BME280 sensors have taken some heat (no pun intended) for yielding inaccurate / inconsistent temperature readings. You may wish to use a sensor designed for temperature such as the DS18B20. If you add one of these sensors, you'll need to enable it in HWConfig.h file. You'll see a line that designates which pin the DS18B20 sensor is connected to. If the pin is set to -1, then JAWS assumes no additional sensor is attached. If it is not -1 then JAWS will access the DS18B20 using that pin. It will use the temperature value from the DS18B20 in place of the reading from the BME280 (or the DHT22 if you're using that in place of the BME280).

3D Model

The original housing for this project as well as some others are available on thingiverse. Here is a sampling:

Software

Building the software for JAWS is a bit more complex than a typical application because it stores files on the ESP8266/ESP32 file system. This means that you need to use a plug-in to the Arduino IDE to upload those files to the Arduino. The file structure is described in detail in the WebThing readme file. In this section I will describe the steps involved.

  1. Download and install the ESP8266 Sketch Data Upload plugin. For ESP32, use the ESP32 Sketch Data Upload plugin plugin. Note that installing this plugin is not the same as installing a normal Arduino library. Follow the installation instructions here. If you have installed successfully, you will see a new menu item in the Arduino IDE Tools menu. See the screen shot below.
  2. Copy or link the wt directory from WebThing data directory to the JAWS data directory. When you're done you'll have a data directory that contains a number of HTML files and a wt subdirectory. The wt subdirectory will also contain HTML files.
  3. You need to reserve some flash memory space for the file system.
    • ESP8266: In the Tools menu of the Arduino IDE you will see a Flash Size submenu. Choose FS: 1MB.
    • ESP32: Use the defaults - no need to make any changes.
  4. Now connect your ESP8266 to your computer via USB and select the ESP8266 Sketch Data Upload item from the tools menu. You will see all the files in your data directory, including those in the wt subdirectory being loaded onto your ESP8266. The process is the same for ESP32, though the specific names/menu items will be different.
  5. Finally you can proceed as usual and compile / upload JAWS to your ESP8266/ESP32.

Setting up JAWS

Understanding and Configuring Low Power Mode

First things first: JAWS is designed for low power operation. The way it achieves this is by powering on, taking readings, sending the data to Blynk, and powering back off again. It will wake up again some time in the future (say 10 minutes) and repeat the cycle. Low power mode is great for long life with on a battery that recharges with solar energy. It's not the right model if you want to have a responsive, always-on device. We'll look at these cases separately.

Making the Most of Low Power Mode

When you power-up JAWS for the first time, low power mode will be disabled. That means you can interact with the Web interface freely to get it configured just the way you want it before turning on low power mode. Once you've enabled low power mode and rebooted, JAWS will enter the power-on, take-readings, power-off, cycle mentioned above.

But what if you want to change a setting? You won't be able to get to the Web interface because JAWS will power itself before you have a chance to do anything! That's where the override mode comes in. If you're using the full hardware implementation described above, you'll have a switch/jumper you can use to override low power mode in hardware. Flip that switch and reboot.

At that point JAWS will not enter low power mode even though it has been configured to do so. Now you are free to connect to the web interface and change any settings you'd like (including the setting for low power mode). When you've made your changes and saved them, you can flip the switch/jumper back and reboot. JAWS will now go back to honoring the power mode setting.

Always-on Operation

If you have an attached display for a GUI, or want to be able to access the Web interface any time, or want to use HomeBridge integration, you'll need to avoid low power mode. Of course this will drain your battery much faster, so you will probably want to use a power supply of some sort instead.

Since low power mode is off by default in JAWS, you don't need to do anything special. If you have turned on low power mode for some reason, use the instructions in the previous section to turn it back off.

Getting Started with Configuration

Before you get started, you will need API keys for the services mentioned above (Google Maps, TimezoneDB, and Blynk). All are free. Please go to each site, create a key, and keep track of them. You'll need to supply them during the configuration process.

Connecting to your network

Once you have assembled your hardware and loaded the firmware, the weather station will boot and create its own WiFi access point. Connect to the new access point you will see on your phone or computer's wifi connection list. It will have an SSID of the form jawsNNNNNN. Once you do, you will enter a "captive portal" where you can configure the weather station for your actual WiFi base station. When you've done that, you can reset the weather station and it will connect to your wifi network.

At this point it will make a web interface available. You can connect using either an IP address or a hostname:

Configuring JAWS

Once connected, you can use the web interface to configure various settings of your weather station. You get to the settings by selecting an item from the hamburger menu in the top left of the web page. Before getting to settings that are specific to JAWS, you need to configure some general information for your web-connected device including a username / password. You do this using the General Settings menu item as described below.

Note: If you have mounted your display in an enclosure in a way that is upside-down relative to the default configuration, you're image will be upside down until you get around to the [Configure JAWS)[] menu. This isn't a problem since the configuration will be happening in the Web UI, not on the display, but if it bothers you, you can skip to that step to flip the display orientation and then come back here.

These settings are common to many network connected devices and are encapsulated by the WebThing library. The settings you must configure are listed below in the order you will want to enter them on a new device. In general, once you have entered the General Settings once, you won't need to change them again. When you are setting up your device for the first time, you will need to enter some of the settings, save, and reboot before you can enter the rest. In particular, you'll need to enter the API keys before you can geolocate your address.

Now that the General Settings are out of the way, you can adjust settings that are specfic to JAWS:

As discussed above, you can adjust low power mode and related settings on this page. The settings are as follows:

Using JAWS

Accessing JAWS using the Blynk App

JAWS lets you view your weather data using the Blynk App for iPhone or Android. Follow these steps to get going:

  1. Download the appropriate app using the links above.
  2. Open the Blynk app and create a new Blynk account if you don't have one already.
  3. Touch the QR code icon at the top of the screen.
  4. Scan the QR code below. This will load the Solar Weather Station app which you may customize if you wish using the Blynk app (no coding required).
  5. Blynk will send you an "Auth Token" via email. Enter this in the settings screen of the web interface in the field labeled "Blynk API Key". Hit save and restart the weather station.
  6. Use the Blynk app to see current and historical values.

Blynk QR Code:

Accessing JAWS using the Web UI

You can always access the current JAWS readings via the Web UI. This is the same UI you used to configure JAWS. Just go to the home page and you will see current readings. You'll also find an item in the hamburger menu that allows you to force JAWS to take a new reading.

Additionally there is a chart page that produces a chart of temperature over time. This is the same sort of graph that is displayed on the Graph screen in the GUI (if you have that enabled). The chart shows the temperature over time. It currently stores 128 readings, so if you are taking readings every 10 minutes, then this is roughly 21 hours of data. The chart also displays a moving average of the temperature that will give you a smoothed view of the data. You can control the level of smoothing using the slider below the chart.

If you hover your mouse over a point on either line (temperature or moving average), you'll see a popup with the timestamp and value). You can also turn on/off either of the lines by clicking the corresponding label in the legend. An example of the chart page is given below. Click the image to see a larger version.

Using the GUI

The GUI is organized into a simple set of screens. You navigate through the screens by pressing the attached button. A press moves from the current screen to the next. The sequence is as follows:

When JAWS boots up you will see a WiFi screen while it is connecting to your network.

If it hasn't been configured yet or you move it to a different location with different WiFi base station, JAWS will display a Configuration screen telling you to connect to a specified hotspot in order to configure network access.

Once JAWS has connected to your network it will display a Splash screen while it finishes initializing.

After initialization is complete, you will see the Time screen which displays the time in a large font, and the temperature and humidity below that.

If you press the button you'll move to the Temperature screen, then the Humidity Screen, the Barometric Pressure screen, and the "All Readings" screen

The next button press takes you to the Graph screen. It shows a graph of the temperature over time as well as the high temp and low temp shown on the graph and the current temperature.

Another button press takes you to the Info screen which shows various information such as the version of JAWS, the hostname, IP address, and WiFi signal strength.

Press the button again and you will be taken to the "Off" screen. You'll see the word "Off..." display for 2 seconds and then the screen will go black. Pressing the button at any time will move back to the Time screen and the cycle begins again.

Operational Info for Developers

Developer Endpoints and the Developer Menu

Developer Menu

There are a number of web endpoints for developers that can help with extending and debugging JAWS. Each of the endpoints is listed below. Though it is not normally part of the main menu, you can get to an additional page of options by entering the url http://[JAWS_Address]/dev into your browser. Once you go to that page, you'll get an option to enable the Developer menu item which will make it easier to get to in the future.

Internally this has the effect of changing the value of the showDevMenu setting. If you prefer to have the Developer menu on by default, you can edit JAWSSettings.h and initialize showDevMenu to true.

Viewing your settings

It can sometimes be useful to see all the settings in their JSON representation. The /dev page has a View Settings button which will return a page with the JSON representation of the settings. You can also get to this page directly with the url http://[MultiMon_Adress]/dev/settings. If you save these settings as a file named settings.json and place it in your data directory, it can be uploaded to your device using ESP8266 Sketch Data Uploader. There is no need to do this, but developers may find it useful to easily switch between batches of settings.

The /dev page also has a View WebThing Settings button which will return a page with the JSON representation of the WebThing settings. This includes things such as the hostname, API keys, and the web color scheme.

Screenshots

Similarly you can get a screen shot of whatever is currently displayed on the device using the Take a screen shot button. This will display an image in your browser which corresponds to the current content of the display. You can also get to this page directly with the url http://[MultiMon_Adress]/dev/screenShot.

Rebooting

Finally, the /dev page also has a Request Reboot button. If you press the button you will be presented with a popup in your browser asking if you are sure. If you confirm, your JAWS device will immediately reboot as if the reset button had been pressed.

Optional Integration with HomeBridge

Your weather station is able to report information into the Apple HomeKit world via HomeBridge. In particular, if you install the homebridge-http-temperature-humidity plugin, you can configure it to request readings from JAWS. To do so, follow the plugin's instructions on how to configure it in HomeBridge. This involves editing a JSON config file. This config file will contain a URL that points to the weather station. For example:

"accessories": [
       "accessories": [
       {
           "accessory": "HttpTemphum",
           "name": "Living Room Weather",
           "url": "http://JAWS.local/weather",
           "sendimmediately": "",
           "http_method": "GET"
       }
   ]

Acknowledgments

This project is a variation of the Solar Powered WiFi Weather Station from instructables. It also leverages work from 3KU_Delta's Solar WiFi Weather Station Project which in turn leverages other work. Additionally, the web interface uses the WebThing library which borrows from / is inspired by Qrome's great Octoprint Printer Monitor.