Build the ESP32 Maker Project
The Gigabits IoT Platform is a backend that makes it easy to acquire, display, store and analyze data from projects. Gigabits IoT Platform's ability to combine a user's data with remote datasets makes it stand out.
This project shows how to use the Gigabits IoT Platform with a several sensors to produce a simple plant monitor or weather station. It illustrates the use of 4 physical sensors, Soil Moisture (helps you decide whether plants need water), Humidity & Temperature, Gas (detects combustible gasses and smoke) and Visible Light.
The directions for assembling the components are pretty simple – order the components (or equivalents or replacements) listed below and assemble them as shown in the “Schematics” section.
Here are the parts:
ESP32 with pin/headers from Amazon: https://www.amazon.com/HiLetgo-ESP-WROOM-32-Development-Microcontroller-Integrated/dp/B0718T232Z/ref=sr_1_1_sspa?keywords=esp32&qid=1580910712&sr=8-1-spons&psc=1&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUExRlFXRU44QzdOTVJFJmVuY3J5cHRlZElkPUEwNzU0Nzk0MjQzS1ZDSTE4RUFNWCZlbmNyeXB0ZWRBZElkPUEwMjA4NDMxMk8zUVNWVlRSVEExTiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU=
Hygrometer Moisture sensor from Amazon: https://www.amazon.com/ARCELI-Hygrometer-Moisture-Detection-Arduino/dp/B07CQT5RC8/ref=sr_1_11?crid=1WEGHUCNCVBFJ&keywords=arduino+soil+moisture+sensor&qid=1580910603&sprefix=arduino+soil+mo%2Caps%2C214&sr=8-11
DHT11 from Amazon: https://www.amazon.com/KeeYees-Temperature-Humidity-Single-Bus-Raspberry/dp/B07V5MTQJG/ref=sr_1_7?crid=1GRR0SA2ZWHPG&keywords=dht11+temperature+and+humidity+sensor&qid=1580910808&sprefix=DHT11+%2Caps%2C242&sr=8-7
Air quality sensor from Amazon: https://www.amazon.com/HiLetgo-Sensor-Methane-Detection-Arduino/dp/B00LODGQCS
Amazon has several flavors of wires. Some folks like using wires that are all the same length and have finished ends so that you don't need to cut or strip them. I think the extra length of these wires looks messy. This recommendation uses a selection of pre-cut wires in various lengths.
If you'd like to really trim the wires to just the right length, you may also need a wire cutter/stripper. It should go down to 22 AWG wire. There are several at Amazon, this one looks good: https://www.amazon.com/dp/B082KL14QP/ref=dp_cerb_1
3 10K ohm resistors (use 10K resistors from this kit): https://www.amazon.com/Resistors-Assortment-Tolerance-Excellently-Breadboards/dp/B07D2Z45CG/ref=sr_1_2_sspa?keywords=resistor+kit&qid=1582393289&s=industrial&sr=1-2-spons&psc=1&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUExUDI1WE9NVDcyNjJHJmVuY3J5cHRlZElkPUEwNDQxMTM3MkVXMjNDU0hSNzhEQiZlbmNyeXB0ZWRBZElkPUEwMDY0MDQ5MjRMUDZJQ1BBODZPVyZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU=
2 half-length breadboards: https://www.amazon.com/HiLetgo-Solderless-Breadboard-Circuit-Prototyping/dp/B00LSG5BJK/ref=sxin_2_ac_d_rm?ac_md=4-3-bWluaSBicmVhZGJvYXJk-ac_d_rm&cv_ct_cx=breadboard&keywords=breadboard&pd_rd_i=B00LSG5BJK&pd_rd_r=f9e7856e-d8ee-4810-a038-3d0a29453491&pd_rd_w=ErQs1&pd_rd_wg=73CET&pf_rd_p=ec111f65-4a46-499c-be78-f47997212bd0&pf_rd_r=R086KGQ6P9TGDY8HDVQW&psc=1&qid=1582392692
Here are the schematics. Note that we used two half-length breadboards abutted together. The ESP32 is placed so that most of the pins we use directly match the breadboard pin numbers. The ESP32 is also placed so that the sensors do not interfere with the USB cable.
There are many ways the Espressif ESP32 module can be mounted on a “breakout board” or “development board.” The rules governing how the ESP32 module’s General Purpose IO (GPIO) pins are mapped to the HiLetgo ESP32S board are complex. You may want to reference https://randomnerdtutorials.com/esp32-pinout-reference-gpios/ to see how the pins are used by the ESP32 module. You may also want to reference https://forum.fritzing.org/t/esp32s-hiletgo-dev-boad-with-pinout-template/5357 to see how the module pins are mapped to the HiLetgo ESP32S development board.
Half the fun of IoT is experimenting with different sensors. A selection of other sensors can be seen on https://www.amazon.com/s?k=arduino+sensor&ref=nb_sb_noss_1. There are many ways to connect sensors to a microprocessor. Since this is an introductory project, let’s keep things simple by only showing how to replace one of the existing sensors with a new sensor that has the same number of pins. If your original and replacement sensors each have 3 pins, the red wire in the original sensor should attach to a pin on the replacement sensor labelled “VCC” or “+”. The black wire should connect to a pin labelled “GND” or “-“. The white wire should connect to the pin labelled something like “DATA”, “SIG”, “S” or “OUT”. When replacing a sensor that has 4 pins, connect to original sensor’s red wire to the new sensor’s “VCC” pin. The black wire should go to the pin labelled “GND” and the colored wire should go to the pin labelled “AO”. Make sure that your new sensor has pins with these labels.
Software Step 1: Open a web browser and go to “app.gigabits.io”.
Software Step 2: If you haven’t registered with Gigabits yet, use your Beta Key to register now.
Software Step 3: Once you’ve registered, go back to app.gigabits.io and sign in.
Software Step 4: Create a new project by selecting the plus sign. This will create a project named “New Project”
Software Step 5: Select the blue square that’s next to your project’s name and give your project a nice name by replacing “New Project”.
📷Software Step 6: Select “Edit Project” after pressing the project’s blue square. This should show you the page used to edit projects.
Software Step 7: Every project should have exactly one device (microcontroller). Press the blue “Add Devices” button on the far right. If you can’t see that button, make your browser window wider.
Software Step 8: Add an ESP32 device for your project.
Software Step 9: If you see a mostly blank screen, try clicking on “Gigabits” in the upper left. Then select your project’s blue square and select “Edit Project”.
Software Step 10: You should now see the page used to edit a project. It should have a device.
Software Step 11: Click the “Edit” button in your device’s row. This will take you to the page used to edit devices.
Software Step 12: Give your device a descriptive name by replacing the default (“My New Device”). Later on, we’ll want to display weather data from around the country. Fill in the Zip Code that specifies which weather you’d like to see.
Software Step 13: Add a sensor to your device by clicking on the “Add Sensors” button. This will take you to a page that describes the sensor being added.
Clicking on the “Add” button will take you back to the page used to edit devices. The device will now have one sensor.
Software Step 14: Add another sensor to your device by clicking on the “Add Sensors” button again, then clicking on the “Add” button on the next page again.
Software Step 15: Repeat the “Add Sensors, Add” sequence 3 more times for a total of 5 sensors.
Software Step 16a: Go through all the sensors again. This time, give each sensor a useful name and a color. The name will have two parts. The first part describes the physical sensor type, like “HCPA-5BV-U3” or “TSL2651”. The second part is used to identify the sensor, like “HVAC, Room 1”. Each sensor type is statically assigned a number called the “sensorIndex” by the system. Each sensor value pushed to the Gigabits server is accompanied by a sensorIndex. That tells the server how to treat the value. Table 1 shows the current mapping from sensor type to sensorIndex. This will grow as sensors are added.
There’s currently a loophole that we take advantage of. As shown, each sensorIndex corresponds to a particular sensor type. The loophole is that the system doesn’t check the sensor type. That means that you can usually replace one sensor with another that has the same class of output (e.g. Numeric) and the system will dutifully display the new sensor’s output. You can use the sensor’s name to describe the actual sensor output.
HCPA-5V-U3, Humidity output
HCPA-5C-U3, Temperature output
Invert Display button (actuator, not sensor)
MPL115A2 Barometric Pressure
MQ2 Propane, Butane, Methane, Hydrogen, Alcohol Sensor
Soil Moisture Sensor
TMD26721 Proximity Sensor
TSL2561, Visible Light output
TSL2561, Infrared Light output
Software Step 16b: While you’re giving a sensor a name, you should also assign it a nice color. The color will be used to quickly identify gauges and chart lines. The mechanics of assigning a color to a sensor varies between web browsers. In all cases, you click on the color box, then use a browser-specific method to assign a color.
Software Step 16c: Here’s a sample device with all its sensors
Software Step 17: Now that the dashboard is configured, we can start loading software. Start by loading the Arduino IDE. Open a web browser to https://www.arduino.cc/en/main/software.
Using the script “Windows Installer, for Windows XP and up”, install a copy of the Arduino IDE.
Software Step 18: We need to load the code that links the ESP32 boards with the Arduino IDE. Open File -> Preferences. Put the string “https://dl.espressif.com/dl/package_esp32_index.json“into the text box labelled “Additional Boards Manager URLs:”. Close the Preferences window.
Software Step 19: Select Tools -> Board -> Boards Manager. Search for “esp32 by Espressif Systems”. Install this Board package. It will take a few minutes. It may ask if it can modify your PC. Say yes.
Software Step 20: The “esp32” package that you just installed includes many boards. In Tools -> Board, choose the board named “Adafruit ESP32 Feather”. In theory, it hardly matters what board you choose. In practice, we haven’t found another board that works with the ESP32 device and adaptor from NCD.
Software Step 21: Open the Windows Device Manager (On Windows 10, search for “Device Manager”. Scroll down to “Ports (COM & LPT). There should be a port with an interesting name, like “Silicon Labs CP210x USB to UART Bridge (COM<a number>)”. In this example, the number is 11. Any number other than 1 or 2 should work.
Software Step 22a: That’s the Windows COM port that we’ll use to communicate with our board. Back in the Arduino IDE, go to Tools -> Port and make sure the port shown is the port from the Device Manager.
Software Step 22b: If not, press Tools -> Port and select the port from the list of ports. If you don’t see your port’s name, make sure the ESP32 is turned on and connected. If that’s not the problem, try going into the Device Manager again, go down to Ports, right-click on the interesting one and select “Update Driver”. If it’s still not working, you might installing the drivers from https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers.
Software Step 23a: Use your Arduino IDE to fetch the "Gigabits" library (Sketch -> Include Library -> Library Manager; search for Gigabits). Press its “Install” button.
Software Step 23b: Install the “ArduinoJson” library.
Software Step 23c: Install the “Adafruit_GFX” library.
Software Step 23d: Install the “Adafruit_SSD1306” library. Close the Library Manager window.
Software Step 24: It’s finally time to open the sketch (a program written in Arduino language). If you’re writing your own sketch, you can use the rest of these instructions for inspiration. The important parts are including Gigabits.h, calling WiFi.begin with your router’s ssid and password, calling gigabits.begin with your device’s device key and secret (see below) and calling gigabits.sendRecord each time you want to send a sensor value to the server.
Software Step 25: Using the Arduino IDE, select File -> Examples -> Gigabits. Load the folder named “ESP32SecureDemoApp”.
At this point, there will be two Arduino IDE windows open. Close the one that we didn’t just open.
Hardware Step 1: We’re going to modify the sketch inside that folder. We can’t do that from where the folder is now because the directory is read-only. From the Arduino IDE, select “File -> Save As” to write the sketched elsewhere. Saving it on the user’s desktop is convenient. That’s at C:\Users\<your windows name>\Desktop.
Hardware Step 2: In the version of ESPSecureDemoApp.ino that you just copied from the user’s desktop, scroll down until you get to a line that says “Change these!”
Change “ssid” to your router’s name. Similarly, replace “pass” with your router’s password.
Hardware Step 3: Way back up above, we declared a project that contained some devices. In the dashboard, go to Projects -> <your project’s name> -> Edit. The project’s “Device Key” and “Secret” are shown. Copy the Device Key for the project and insert it in place of “devkey” in our sketch. Similarly, replace the sketch’s Secret with the project’s secret.
Hardware Step 4: We need to say something about running in secure and insecure (unencrypted) mode. All data moving between the MCU’s and the main server ought to be encrypted. However, we can’t force all our users to do that. Some MCU’s are too wimpy to perform the encryption algorithms at a tolerable speed. Debugging is easier when the data is not encrypted. Some users may not care whether their elementary school’s plant project is hacked. Nonetheless, using encryption is a good idea.
Using SSL with the EXP32 is pretty easy. The differences between secure and insecure implementations are small.
- We use WiFiClientSecure package instead of WiFiClient.
- We copied a Root Certificate from https://www.amazontrust.com/repository/AmazonRootCA1.pem. Before MQTT is started, the Root Certificate is an argument to the net.setCACert routine.
We haven’t explored processors other than the ESP32 and the MKR1000 yet. If you dig in and make them work, we’d love to hear from you!
Hardware Step 5: The code to gather sensor data and send it to a server is also pretty reasonable. You should read the sensor data manuals to see how to control each sensor.
- There’s a setup routine for each sensor that needs one. The standard Arduino setup routine calls all the sensor setup routines, then calls WiFi.begin to connect to the internet. Any security setup would happen here also.
- A routine called setupGigabits is called after setup is complete. This routine starts MQTT processing by calling the gigabits.begin routine. The “devKey”, “secret” and “net” arguments default to the right values for encrypted processing. If you want to disable encryption, append “mqtt.gigabits.io, 1883” to gigabits.begin’s arguments. “mqtt.gigabits.io” is the MQTT broker and 1883 is the port number of unencrypted data.
- Every sensor has a routine used to send data. At some reasonable rate, the standard Arduino “loop” routine calls each sensor’s “send” routing. That routine does whatever’s necessary to acquire the sensors’ data. A dictionary accumulates one or more key/value pairs from each sensor by calling gigabits.sendRecord. The keys are sensor indices (See Table 1 above) and the values are sensor values.
- When a snapshot of all the sensor’s data is on the dictionary, the dictionary is converted into a JSON object. The JSON object is published over MQTT along with a topic.
There are many more sensors and actuators than we can test. If you can connect your new favorite sensor, have at it!
Hardware Step 6: Finally, press the Compile and Upload button (in the upper left of the Arduino IDE window, it looks like an arrow facing to the right).
This will compile the sketch and start running it. It should start pumping sensor data to the dashboard. You should be able to see this on the Serial Monitor. You can open the Serial Monitor by selecting “Tools -> Serial Monitor”
You've completed the Gigabits setup and are ready to start configuring your dashboard’s gauges and charts!
In this section, we will show how to set up charts, gauges and command buttons.
Dashboard Step 1: Open a web browser to “app.gigabits.io”
Sign in. That should take you to the Projects page.
Dashboard Step 2: Click on the name of the project whose dashboard we’ll set up. It’s important to click on the project name, not the blue square next to that name. If you’re following our example, click on the name “Tim’s Demo”, not the blue square next to “Tim’s Demo”.
Dashboard Step 3: On the left side of the User Project page, there are four commands New Chart, New Gauge, New Button and Edit Project. If the commands are chopped off, try making the browser window wider or narrower.
Dashboard Step 4: Let’s start by making a new gauge. A gauge shows a sensor’s current value. Click on the “New Gauge” command. A gauge will appear on the left side of the dashboard. It will be below the lowest gauge, chart or button, which can make it tricky to find because that location is often off the bottom of the screen.
The gauge can be resized by dragging the tiny chevron in the bottom/right corner of the gauge. The gauge will have a configuration icon (three horizontal lines). Press the icon to configure the gauge.
Dashboard Step 5: The next page shows the settings for an unconfigured page. One of the first things to notice is that pressing the Delete button deletes the gauge.
Dashboard Step 6: Here’s a configured gauge. It has the on-boarding information discussed above. The Device is from our project. The sensor senses humidity. The name is informative. The Minimum and Maximum bound the range of values shown on the gauge. The Unit of Measurement is used to label the chart axes. The color of the sensor data was chosen when the sensor was set up. Remember to press the Save button when you’re done.
Dashboard Step 7: To position the gauge on the dashboard, simply drag it around with the cursor. Dashboard items must be at the top of the dashboard or immediately under another item.
Dashboard Step 8: You can also use gauges to display data from external databases. To illustrate this, Gigabits can display weather data. Go to your project and choose New Gauge. Press the new gauge’s configuration icon. This time, click on the “External” tab at the top of Settings page. The only choice for “Source” is currently “Open Weather”. There are 3 data types, Temperature, Humidity and Barometric Pressure. Pick an informative name. The weather data is for a US Zip Code. That Zip Code was chosen when the project was created. You can also select a nice color for the gauge, minimum and maximum values and a Unit of Measurement. Here is the Settings page for data from Open Weather.
Dashboard Step 9: On to line charts! Press the “New Chart” command. An unconfigured chart will appear on the dashboard. Press its configuration icon. Give the chart a useful name. You can often leave the Unit of Measurement blank since the data being charted normally has different sources.
Dashboard Step 10: You can either use a new chart line or modify an existing one. To begin, choose the “Sensor Lines” tab and set “Line” to “Create New Line”. Fill in the Device and Sensor items as you did for gauges. Press the Save button. The window does not disappear because it’s waiting for another chart line.
Dashboard Step 11: To close the Settings window, click on the “x” in its upper right corner.
Dashboard Step 12: To modify a chart line, open the Settings window, choose the desired line in “Line” and modify the remaining items.
Dashboard Step 13: To delete a chart line, open the chart’s Settings, select the chart line in the Line menu and click the Delete button.
Dashboard Step 14: You can also create chart lines from external data. Press the “External Lines” tab on the Chart Settings page. Fill out “Line” as you did for chart sensors. Fill in Source and Data Point as you for the sensor gauges. Give the line a name and a color.
Congratulations! You’re ready to explore your data!