The ESP32 is a fantastic MCU, but when you are designing a project with it you need to choose the I/O pins very carefully.
Many of the I/O pins have special purposes, such as being bootstrapping pins that change the way the ESP32 boots up. Some have limitations, such as being OK to use as inputs but they don’t have pullup or pulldown resistors, so you have to bias them externally.
And some of the strange behaviour is really obscure: for example, you can’t use analog input on any pin associated with ADC2 while WiFi is in use!
To help me navigate these limitations I created a spreadsheet that lists the pins and their strange behaviour:
When I start a new project, I use this spreadsheet as a template and make a duplicate just for the project. Then I add notes to the “Purpose” column to say what I’m going to use each pin for.
I’ve made the template public, so you can make copies of it yourself for your projects. Click the preview above to open it in Google Sheets.
Many of the cells have notes attached to them, explaining specific limitations.
Because I mostly use Wroom32 modules, the spreadsheet has a column for Wroom32 pin numbers. You can change this to suit whatever module you use in your project, or ignore it and work from the direct ESP32 pin numbers which are also listed.
I needed PCB trays to keep boards organised during the production process, so I laser-cut a simple design.
The trays used by professional PCB assemblers are usually made from static-dissipative material that can also withstand immersion in an ultrasonic bath. My design isn’t intended as a replacement for those, but just as a handy way for hobbyists to keep small batches of boards organised on the workbench or shelves. This is much better than stacking populated PCBs on top of each other because it saves the parts and boards being scratched or damaged.
The Fusion360 file includes parameters so that you can tune the material thickness and the slot size to suit your own requirements. There is also a parameter for board width, but it’s broken at the moment.
DXFs have also been included, for 3mm MDF and 2mm PCB slots.
Some countries and services are not available, and the situation is changing by the day. As of today, there is a list of about 119 countries that I can’t ship to at all. For the rest, “Economy” class packages aren’t being processed, and for some classes of package there are delays of 2 to 5 weeks added to the normal shipping time.
If you add items to your cart and begin the checkout process, the online store will use your delivery address to determine if it’s possible to ship to you, and only offer you shipping methods that are currently available for your country.
So feel free to go ahead and place an order. I’m watching the situation very carefully and checking every order, so if there are any problems I’ll follow up with you.
For the latest status from Australia Post, you can check on their COVID-19 updates page:
Because of the decrease in international travel over the last couple of months, the postal service doesn’t have enough flights available to carry international letters and parcels.
As of this week, Australia Post can’t process “Economy” class international packages at all. Some premium classes of package, such as trackable services and International Express, are still being accepted at post offices. However, even these more expensive shipping options are experiencing weeks of delays.
Sadly, this means that I simply can’t ship international packages at the moment. I can still ship orders to Australian customers without any problems: domestic packages are being processed and transported as normal. It’s the lack of international flights that is the big problem.
I’ve now turned off all shipping methods for international customers.
The moment that the postal service has resumed international service, I’ll turn international shipping back on. Until then, I can only process orders for Australian customers.
You can build the Air Quality Sensor project without understanding how the software works, but if you want to know what’s really going on behind the scenes you can join me for a deep dive into the source code.
Printing a case is totally optional, of course. You can use whatever enclosure you like. My case has been designed to be a press-fit over the PMS5003, which holds the two halves together by friction. See the link above to download the STLs if you want to print it yourself, or you can buy a case from me if you don’t have access to a printer. I’ll include a 6x6x9mm tact switch with the “Display” version of the case:
Put switch into case
The space for the tact switch is very tight.
To fit it into the slot, trim off the pins from the right side and trim the pins on the left side so they are a couple of millimeters long. Bend those leads out at a 45 degree angle, and solder a pair of jumper wires to them.
Push the switch into the cavity in the case as shown above, and guide the wires around the slot to the left and then down.
The button connects between GND and I/O pin D3:
Connect 128×32 OLED to D1 Mini
The 0.91″ 128×32 OLED module already has I2C pull-ups included, so there’s no need to add them. All we need to do is connect power and I2C:
The connections are:
OLED GND to D1 Mini GND
OLED VCC to D1 Mini 3.3V
OLED SCK to D1 Mini pin D1
OLED SDA to D1 Mini pin D2
Connect PMS5003 to D1 Mini
In the “Basic” version of this project, we only needed to connect to the 5V, GND, and Tx pins of the PMS5003. Now we also need to connect I/O pin D6 to the sensor’s Rx pin, to allow commands to be sent to the sensor:
The connections are:
PMS5003 pin 1 (5V) to D1 Mini 5V
PMS5003 pin 2 (GND) to D1 Mini GND
PMS5003 pin 4 (Rx) to D1 Mini pin D6
PMS5003 pin 5 (Tx) to D1 Mini pin D4
Close the case
This can be more tricky than it sounds! Be gentle so you don’t damage anything.
With the electronics sitting neatly in the “back” (or “right”) half of the case, make sure all the wiring is neatly tucked into the slots. It should look something like this:
Slide the other half of the case over the modules, checking that no wires are pinched between the halves. The case should close completely.
Set up Arduino IDE for ESP8266
If you don’t already have it, download and install the Arduino IDE:
By default, the Arduino IDE does not support the ESP8266 processor on the D1 Mini. To add this support, go to the following URL and follow the instructions. The easiest method is to use the Boards Manager:
The “PMS” library is directly embedded within the program, so you don’t need to install it. This is done to force a specific version of the library, which was forked from the official version by GitHub user SwapBap to add extra features. There’s nothing you need to do because it’s part of the project.
In the Arduino IDE, go into “Sketch -> Include Library -> Manage Libraries…“
Then search for each of these libraries, and click “Install”:
The easiest way is to click the green “Clone or download” button near the top right of the page and select “Download ZIP”. Once you’ve downloaded it, extract the folder and put it in your sketchbook directory. You can find the correct location for this by looking in the Arduino IDE preferences.
Configure and compile sketch
Open the Arduino IDE, open the sketch, and have a look at the 4 tabs across the top. You can ignore the first three. Open the “config.h” tab, and modify the settings for WiFi and your MQTT broker:
Plug in the Air Quality Sensor using a USB cable.
Select “Tools -> Board:” and set it to “LOLIN(WEMOS) D1 R2 & mini”. Select the port, and upload the sketch:
After the sketch has uploaded the Air Quality Sensor will reboot, connect to your WiFi and MQTT broker, and show values on the display once it has successfully received data from the PMS5003.
Stay tuned for part 3, which will explain how the sketch works and how to read the data from it.
It’s surprisingly easy to make your own simple air quality sensor. All you need is a cheap laser-scattering particulate matter sensor, a Wemos D1 Mini, a soldering iron, and Tasmota.
Part 1 shows how to make the simplest possible version of the SuperHouse Air Quality Sensor, the “Basic” version.
Part 2 shows how to improve it to make a more advanced “Display” version, Part 3 is a detailed walkthrough of how the firmware works, Part 4 will explain how various Air Quality Index calculations are done around the world, and Part 5 will step it right up with the “Pro” version with VOC sensor.
Here in Australia we’ve recently had a terrible bushfire season, and there’s been a lot of concern about the effects of smoke on air quality. Smoke particles, pollen, and many other forms of air pollution are tiny. Really tiny. Many people have been wearing “PM2.5” face masks, which means they are designed to filter out particles as small as 2.5 microns in size, but pollen and smoke can be even smaller than that.
Detecting tiny particles down in the 0.1 to 10 micron range is hard. Normally you’d need an electron microscope to detect something this small. In fact these particles are so small that they are often smaller than the wavelength of light, which is in the region of 0.5 microns. This means light doesn’t interact with them in the usual way: instead of bouncing off them like a particle, it can bend around them like a wave, and it can also refract inside them like tiny lenses.
Laser-scattering particle detectors pass a laser through a test chamber, with a deflection sensor on the other side. Particles in the test chamber cause the beam to be scattered in different ways, and the deflection sensor can use this scattering to determine the number and size of particles in the chamber.
This process creates a series of concentric rings on the deflection sensor, which can use the spacing of the rings to determine the characteristics of the particles.
The particles that are detected are then categorised, or “binned”, into different size ranges for reporting.
All of this functionality is wrapped up in the tiny Plantower PMS5003 sensor, which provides a serial interface to report the statistics for the particles that it detects.
Reporting is normally provided in a couple of forms.
The simplest number is the PPD value, which stands for “particles per deciliter”. The higher the number, the more particles there are in the air sample.
The most commonly used number is the “ug/m^3” value, which is micrograms per cubic meter. This is the total mass of particles in that size range in a cubic meter of air, so smaller particles will require a higher raw count to add up to the same mass as larger particles.
The “Basic” version of the SuperHouse Air Quality Sensor only requires a a Plantower PMS5003, the connection cable that comes with it, and a Wemos D1 Mini. See the links above for sources to buy them.
You can also print your own 3D-printed enclosure, or buy one from me if you don’t have easy access to a printer.
Connect PMS5003 to D1 Mini
The PMS5003 requires a 5V supply because it has an internal fan to keep air flowing through the test chamber, but all its I/O connections are 3.3V.
This is perfect for a D1 Mini, because we can connect the power pins to 5V on the D1 Mini and connect the sensor “TX” pin to an I/O header on the Mini.
Cut the supplied cable off at about 2/3rds of its length. Plug it into the PMS5003 to check the orientation, and then strip and tin the ends of the wires connected to pins 1, 2, and 5.
Connect VCC and GND from the PMS5003 to the 5V and GND headers on the D1 Mini.
Connect TX from the PMS5003 to the D4 header on the D1 Mini, which is GPIO2 for the ESP8266 MCU.
3D printed case
I’ve designed a case that slips over the PMS5003 and provides a space for the D1 Mini and wires. You can download the STLs and print it yourself, or if you don’t have access to a 3D printer you can buy it from me in a variety of colour options.
The case comes in two halves. Insert the PMS5003 into the case first, and then slip the D1 Mini into the space at the bottom. The case is oriented so that if the USB socket is on the side towards the PMS5003 it will be accessible through a slot.
Push the wires down into the case so everything is neat, and then slide the other half of the case over the top. It may take some jiggling to get the wires out of the way and the D1 Mini properly inserted into the slot.
There are many ways to install Tasmota on the D1 Mini, but my new favorite is to use Tasmotizer. I did a whole video about how to install and use Tasmotizer, so follow the instructions here if you need to install it:
Once you have Tasmotizer running, connect the D1 Mini using a USB cable and select the port.
Note: As of Tasmota v8.2, support for the PMS5003 has been removed from the normal “tasmota.bin” release binary. Instead, you must select “tasmota-sensors.bin”.
Click the button next to “Release“.
From the drop-down, select “tasmota-sensors.bin” (not the regular “tasmota.bin” as shown above)
Click “Tasmotize!” and wait about a minute for the D1 Mini to be flashed and reboot.
Configure WiFi and apply the “SuperHouse AQS” template
After the D1 Mini has been flashed, click “Send config” in Tasmotizer to open the configuration screen.
Click the checkbox to enable the WiFi section, and put in the details for your WiFi network.
If you use MQTT, click the checkbox to enable the WiFi section and put in the address for your broker. My personal preference is to change the “Topic” entry to “tasmota-%06X” so that the MQTT topics will be dynamically generated using the unique ID of each D1 Mini.
Click the button next to “Template”.
Copy the template below, and paste it into the text box at the bottom of the config screen:
Click “Save” to send the new configuration to the D1 Mini.
It will then restart, and will connect to your WiFi network using the values you just provided.
Connect to Tasmota web interface
You can use a serial console connected at 115200bps to get the IP address directly from the D1 Mini, or look in the management interface for your DHCP server to find the recently added device.
Once you’ve found the IP address, put it into a web browser to load up Tasmota’s web interface.
The module will report its latest readings, updating as fast as the sensor is sending them.
You can also configure the D1 Mini manually if you didn’t use the template above. Starting from a default Tasmota installation, log into the web interface and set up the module as shown below.
Access data via MQTT
Tasmota periodically publishes all the PMS5003 readings aggregated into a single JSON string, in the “../SENSOR” topic.
The topic will depend on the settings you applied for MQTT. In my case, with the “Topic” modified as explained above, the readings are published to a topic that looks similar to “tele/tasmota-5F596F/SENSOR” with the unique ID of this particular device substituted.
The published value will look something like this:
You can parse the JSON using your favorite method, such as with Node-RED. I’ll go over this in more detail in Part 2 when we look at more advanced software options.
The “PMx” values are micrograms per cubic meter. The “PBx” values are particles per deciliter.
This “Basic” version of the SuperHouse Air Quality Sensor is very simple to make, but it has a couple of limitations.
The laser and the deflection sensor in the PMS5003 can degrade over time. After about 6000 hours of continuous use it may begin to decrease in sensitivity. The life of the sensor can be dramatically extended by shutting it down for a couple of minutes, then waking it up, giving it time to stabilise, taking a reading, and shutting it down again. With this change the sensor can last for many years.
There is also no way to interact with the device directly. You have to access it over the network, either by loading the Tasmota web interface or by using the data published to MQTT. Adding a screen and a mode button can make it easy to read particulate levels directly on the device.
Both of these limitations are fixed in the “Display” version of the SuperHouse Air Quality Sensor in the next episode. Stay tuned!
Installing Tasmota onto a device such as a Sonoff is usually done using esptool.py, which is a powerful command line utility but it can be a bit confusing if you’re not used to it. Now it’s been paired with an amazing graphical interface called Tasmotizer that gives you point-and-click convenience, and adds some handy features for configuring your devices:
The Tasmotizer page has good installation instructions, with three options given.
If you use Windows, download the executible and run it.
On Linux or MacOS, you can install using Pip.
If you want the absolute latest development version you can clone the Git repo and install manually.
Use whichever method suits you best. I used Pip to install it on my iMac, my Macbook Pro, and my Ubuntu desktop, and the process went smoothly on all of them. Make sure you have the latest version of Pip, and then use it to install Tasmotizer:
If your Python installation is set up so that new programs are automatically available, it should be possible to simply type in the name and press “Enter”:
However, you may not be so lucky. You may have to find where Pip installed it. Pip can tell you where the files are for a specific package, but its output has horrible formatting that’s hard to interpret. Run this command to see a list of all the files in the Tasmotizer package:
pip3 show -f tasmotizer
The output will include a line called “Location” which shows the directory where the program is located. On my iMac, Pip installed Tasmotizer at:
It’s a pity that Python’s installation management is such a mess, and produces unpredictable results. Hopefully you can find the location for your installation without too many problems.
Once you’ve discovered its location, paste in the appropriate command and press “Enter” to launch Tasmotizer.
Connect the device to your computer
Your target device needs to be connected to your computer using USB, either by directly plugging in a cable or by using a USB-to-Serial adapter. Some devices such as Wemos D1 Mini boards have built-in USB. Sonoff boards don’t have USB so you’ll need to make up an adapter to suit the programming header for your specific board. I’ve done many videos and guides for reflashing various Sonoff models, and the Tasmota site has excellent documentation so follow the appropriate guide to make the connections.
Most Sonoff models use a simple 4-pin header, so I designed the Sonoff Programming Adapter to make it easy to plug in a 3.3V USB-to-Serial adapter with a standard 6-pin header.
Place device into bootloader mode
The ESP8266 / ESP8285 processor needs to be placed into a special bootloader mode before it can have Tasmota installed. This is done by powering it up while the GPIO0 pin is held at 0V, which is usually done using the control button. The sequence is:
Press and hold the button.
Wait a couple of seconds, then release the button.
The device then stays in bootloader mode, waiting for new software to be loaded.
Select device in Tasmotizer
Click the “Refresh” button so Tasmotizer will scan for connected devices and update its list. Use the drop-down to find your target device.
Select the firmware image
Tasmotizer gives you three options for selecting a firmware image.
If you have your own binary, such as a version of Tasmota or some other firmware that you’ve compiled or downloaded, click the “BIN file” radio button and select the file from your local disk.
If you want to install the current release version of Tasmota, click the “Release” radio button and then use the drop-down menu to select the specific flavour of Tasmota for your device.
If you like to live on the edge, you can click the “Development” radio button and use the latest development code that hasn’t been released yet.
Set flashing options
If you want Tasmotizer to make a backup of the existing software on your device, click the “Backup original firmware” option. This will allow you to put it back onto the device later if you change your mind.
If you want to make sure the entire memory of the device is cleared, click the “Erase before flashing” option. This makes sure there is nothing remaining from the previous firmware still left on the device, such as saved configuration options. This is a good idea to make sure you have a fresh start and Tasmota won’t read data from a previous installation.
Flash the firmware
With the correct firmware image selected, click the blue “Tasmotize!” button. Tasmotizer will download the selected image (if required) and install it onto your device.
You’ll see a progress bar as the image is installed. Once it’s done, you’ll be prompted to restart it.
Congratulations! Tasmota is installed.
If you want to configure it manually you can do that by following the usual Tasmota instructions. However, Tasmotizer can save you a lot of time by allowing you to do some basic configuration via USB while it’s still connected to your computer.
Select config options
Click the “Send config” button to open a configuration window.
Click the check-box to enable the WiFi section, and enter your WiFi network name and password.
Click the check-box to enable module/template setup, which gives you options to either select a pre-defined module or apply a template. Applying a module profile or a template allows your device to be configured entirely from Tasmotizer.
If you have a common device, select “Module” and find the device in the drop-down list.
If you have a device that has a template provided for it, select “Template” and then paste the template into the text box. There are more than 1000 templates provided at the Tasmota Device Templates Repository.
If you use MQTT in your home automation system, click the check-box to enable MQTT setup and put in the address of your MQTT broker.
You can manually define the topic for this device (such as “bedroom1”) but my personal preference is to allow the device to generate the topic based on its own internal ID. That way all devices come up with their own unique topics, which can then be referenced in the home automation system.
To do that, change the “Topic” setting to add the extension “-%06X”, like this:
What this will do is take the last 6 hexadecimal digits of the device ID and append them, so the topic will be something like “tasmota-6A0B15”. This value is then used to generate the FullTopic value below it automatically, by replacing the “%topic%” placeholder. The result will be full topics that look similar to:
I like this approach because it means that all my Tasmota devices can have the same configuration, but they still end up with unique MQTT topics.
Send config to device
With all your preferred options set, click the “Save” button. Tasmotizer will send your configuration to the device, and you’re all done. This step is a bit strange, because it happens so fast that it seems like it couldn’t possibly have done anything, but if you get a confirmation dialog then you’re all set.
Finished! Your Tasmota device will now reboot and apply the settings that you configured, so after a few seconds it will be on your network. Just follow the Tasmota documentation to learn how to link it to your home automation system.
I’m sure you’ve heard of the crazy coronavirus epidemic that’s rapidly spreading around the world, and has now been declared a global health emergency by the World Health Organization.
One of the areas that has been hardest hit by the virus is the city of Wuhan, on the Yangtze River in east-central China. Wuhan went into a state of lockdown on January 23rd, with businesses closed and everyone told to stay home and avoid contact with other people.
China is taking this threat extremely seriously, responding on a scale that I don’t think would be possible in any other country. I don’t know of anywhere else in the world that could build entire 1000-bed hospitals from the ground up in 6 days, just to respond to a sudden medical need. If anyone can face a challenge like this, it’s the Chinese.
The primary focus has to be on the health of those in the affected areas, of course. So far I haven’t heard of any of my Chinese colleagues being infected, and I hope it stays that way.
Bare PCBs for both Freetronics and SuperHouse products are mostly produced by Gold Phoenix, which is located in Wuhan, right in the bullseye of the epidemic. Like almost all businesses in Wuhan, Gold Phoenix has told workers to stay home and stay safe.
Some of our prototype PCBs are produced in factories around the city of Shenzhen, in southern China just over the border from Hong Kong. Those factories are currently closed too.
Our PCBA (PCB Assembly, which includes pick-and-place installation of parts on the boards) and final testing and packaging is done in Beijing, which has now also gone into lockdown. Not only are factories closed, but roads out of the cities have been closed to prevent the spread of infection so any boards that have aleady been produced are stuck in warehouses.
There are currently batches of EtherMega and EtherTen boards that were scheduled to ship a few days ago, but they are now caught up in the lockdown and can’t leave Beijing.
So over the next little while there will probably be stock problems for both Freetronics and SuperHouse. Please be patient while I do my best to assemble what I can using local stock of bare PCBs and parts, and keep in mind the millions of people who are now stuck at home with dwindling food supplies. It may be frustrating that products are out of stock, but that’s really not important when the health of so many people is at stake.