Turn your black thumb into a green thumb by building an internet-enabled plant monitoring system by combining Google Cloud IoT Core with CircuitPython.

This smart-planter monitors your plant's vitals on the PyPortal's screen, logs this data to a Google Cloud registry for long-term storage and even correctly waters your plants remotely by controlling a peristaltic water pump.

Using Google Cloud IoT with your CircuitPython IoT projects allows you to quickly prototype (and even mass-prototype) advanced internet-of-things devices and connect them to the Google Cloud Platform. 

Google Cloud IoT

Google Cloud IoT provides a complete solution for collecting, processing, analyzing, and visualizing data from IoT devices in real time:

  • Device management, with per-device authentication and management.
  • Data aggregation with Cloud IoT Pub/Sub 
  • Scalable - Google Cloud IoT is serverless and scales instantly.

Connecting CircuitPython to Google Cloud IoT unlocks over 100 products and services available from Google Cloud Services. Some of these services are especially useful with IoT projects, such as:

CircuitPython

CircuitPython is perfect for building Internet-of-Things projects. This project uses the ESP32SPI CircuitPython library, which can use the ESP32 as a WiFi-coprocessor.

We've built a CircuitPython Google Cloud IoT Core helper module to make interacting with Google's Cloud IoT MQTT Broker incredibly simple. Provisioning CircuitPython for Google Cloud IoT Core is as simple as adding your device's settings to a file. Our library even handles JSON Web Token (JWT) generation.

You can rapidly update your code without having to compile and store WiFi, device configuration, and secret keys on the device. This means that there's no editing code and re-uploading whenever you move the PyPortal to another network - just update a file and you're set. 

Prerequisite Guides

If you're new to CircuitPython, take a moment to walk through the following guides to get you started and up-to-speed:

Parts

PyPortal, our easy-to-use IoT device that allows you to create all the things for the “Internet of Things” in minutes. Make custom touch screen interface...
Out of Stock
Most low cost soil sensors are resistive style, where there's two prongs and the sensor measures the conductivity between the two. These work OK at first, but eventually...
$7.50
In Stock
Move fluid safely from here to there with this very nice little pump. Unlike most liquid pumps, this is a peristaltic type - the...
$24.95
In Stock

Materials

You'll need some extra parts and supplies to finish this project. If you do not have them already, pick some up from Adafruit.

1 x PN2222 Transistor
NPN Bipolar Transistors (PN2222) - 10 pack
1 x 1N4148 Diode
1N4148 Signal Diode - 10 pack
1 x 220 ohm resistor
Through-Hole Resistors - 220 ohm 5% 1/4W - Pack of 25
1 x Breadboard
Half-size breadboard
1 x Breadboarding Wire
Breadboarding wire bundle
1 x Female DC Power adapter
Female DC Power adapter - 2.1mm jack to screw terminal block
1 x 12VDC 1000mA Switching Power Adapter
12V DC 1000mA (1A) regulated switching power adapter
1 x PyPortal Stand
Adafruit PyPortal Desktop Stand Enclosure Kit
1 x USB Cable
Pink and Purple Braided USB A to Micro B Cable - 2 meter long

Connecting the STEMMA Soil Sensor

We recommend using a Female-to-Female STEMMA Connector and plugging it in between the PyPortal and the STEMMA Soil Sensor. No soldering is involved - just connect the cable between the Stemma Soil Sensor and the PyPortal I2C port.

1 x STEMMA Cable
STEMMA Cable - 150mm/6" Long 4 Pin JST-PH Cable–Female/Female

The cable makes the following connections between the PyPortal's I2C port and the STEMMA Soil Sensor:

  • PyPortal 3.3V to Sensor VIN
  • PyPortal GND to Sensor GND
  • PyPortal SCL to Sensor SCL
  • PyPortal SDA to Sensor SDA

Connecting the Peristaltic Liquid Pump

Add a ground and power wire to the end of the DC motor using alligator clips or by soldering wires directly to the terminals.

Make the following connections:

  1. Connect the JST PH 3-Pin to Male Header Cable to the D3 STEMMA connector on the PyPortal.
  2. Connect the header cable's power (red) and ground (black) to the breadboard's red and blue power rails.
  3. Ensuring the flat side of the transistor is facing towards the PyPortal; Connect the emitter to the GND rail. 
  4. Connect the transistor's base to one lead of the 220ohm resistor. Connect the other lead of the resistor to the white (yellow in this wiring diagram) male header cable.
  5. Connect the female DC power adapter to the power and ground rails on the opposite side of the breadboard.
  6. Connect the left and right ground rails together.
  7. Connect the DC motor's power (green in this diagram) to the red power rail. 
  8. Connect one lead of a 1N4148 diode to the transistor's collector lead.
  9. Connect one end of the motor to the striped diode lead. Connect the motor's other terminal to the  un-striped diode lead.
  10. Re-read the notes above the diagram to ensure you did not make any errors while connecting components. It does not matter which way you connect the motor's leads for now.

When you're ready, stick the STEMMA Soil sensor into your plant's soil. Be sure to leave the white portion of the sensor not covered by soil. You may also want to position the sensor at the edge of your planter.

Affix one end of the silicone tubing from the end of the pump to the planter (tape, putty or glue work great), positioning it away from the soil sensor.

Insert the other end of the silicone tubing into a water bottle. The pump will be fed from the water bottle. Select the largest/widest bottle you have.

You'll need an account to access the Google Cloud platform. Head over to https://cloud.google.com and make a new account.

Please note: Google Cloud IoT Core is a PAID IoT service - you will be charged for usage. For non-production usage, keep track of the billing & make sure that you disable any running services if you're not using them.

Google Cloud IoT API Setup

Once logged in, navigate to https://console.cloud.google.com/iot.

Click Enable to enable the Cloud IoT API. It may take some time for the API to set up.

The Google Cloud IoT API links with your existing Google Cloud Services projects.

If you already have a project, select your project using the Select a project dropdown.

If you do not have a project, or would like to create a new one for this guide, select Create a project from the Select a project dropdown. Fill out the project name.

Click Create

Setup Project Registry

The header of your Google Cloud dashboard will display the project you created.

Click the navigation menu. From the navigation menu, click IoT Core.

You'll need to create a registry for your devices. A registry is a "container of devices...created in a specific cloud region, and belongs to a cloud project". 

Click Create Registry

Set the Registry ID to the name of your container. The Registry ID must  start with a lower case letter.

Select the Region closest to where your devices will be physically located.

You'll be connecting using the MQTT protocol to Cloud IoT Core. Under Protocol, select MQTT.

Underneath the Default telemetry topic dropdown, Create a new Default telemetry topic .

Name the topic events.

Then, Create a new Device State topic. Name the topic state.

Stackdriver Logging allows you to monitor and visualize network traffic as it comes into your Google IoT Core registry, in real-time. 

Set the Stackdriver Logging level for this registry to Debug. This will enable Stackdriver logging for each device created in the registry.

Click Create

Now that you created your registry, it's time to add a device to it! 

From the Registry details page, click Devices.

From the device page, click Create A Device

Create a Device ID. This value is permanently tied to the device, make sure you like it before clicking Create.

Ensure that the public key format selected is RS256 since CircuitPython authenticates with the server using a RS256 private key.

Do not fill out the Public key value, you'll create one later in this guide.

Click Create

Ensure your Device Details page displays a green checkmark underneath Device communication.

  • If you see a red X, click Edit Device and select allow device communication.

Congrats - you've successfully set up Google Cloud IoT Core with a new device!

To use all the amazing features of your PyPortal with CircuitPython, you must first install a number of libraries. This page covers that process.

Adafruit CircuitPython Bundle

Download the Adafruit CircuitPython Library Bundle. You can find the latest release here:

Download the adafruit-circuitpython-bundle-*.x-mpy-*.zip bundle zip file where *.x MATCHES THE VERSION OF CIRCUITPYTHON YOU INSTALLED, and unzip a folder of the same name. Inside you'll find a lib folder. You have two options:

  • You can add the lib folder to your CIRCUITPY drive. This will ensure you have all the drivers. But it will take a bunch of space on the 8 MB disk
  • Add each library as you need it, this will reduce the space usage but you'll need to put in a little more effort.

At a minimum we recommend the following libraries, in fact we more than recommend. They're basically required. So grab them and install them into CIRCUITPY/lib now!

  • adafruit_esp32spi - This is the library that gives you internet access via the ESP32 using (you guessed it!) SPI transport. You need this for anything Internet
  • adafruit_requests - This library allows us to perform HTTP requests and get responses back from servers. GET/POST/PUT/PATCH - they're all in here!
  • adafruit_pyportal - This is our friendly wrapper library that does a lot of our projects, displays graphics and text, fetches data from the internet. Nearly all of our projects depend on it!
  • adafruit_portalbase - This library is the base library that adafruit_pyportal library is built on top of.
  • adafruit_touchscreen - a library for reading touches from the resistive touchscreen. Handles all the analog noodling, rotation and calibration for you.
  • adafruit_io - this library helps connect the PyPortal to our free datalogging and viewing service
  • adafruit_imageload - an image display helper, required for any graphics!
  • adafruit_display_text - not surprisingly, it displays text on the screen
  • adafruit_bitmap_font - we have fancy font support, and its easy to make new fonts. This library reads and parses font files.
  • adafruit_slideshow - for making image slideshows - handy for quick display of graphics and sound
  • neopixel - for controlling the onboard neopixel
  • adafruit_adt7410 - library to read the temperature from the on-board Analog Devices ADT7410 precision temperature sensor
  • adafruit_sdcard - support for reading/writing data from the onboard SD card slot.
  • adafruit_bus_device - low level support for I2C/SPI
  • adafruit_fakerequests - This library allows you to create fake HTTP requests by using local files.

Once you have CircuitPython setup and libraries installed we can get your board connected to the Internet. Note that access to enterprise level secured WiFi networks is not currently supported, only WiFi networks that require SSID and password.

To get connected, you will need to start by creating a secrets file.

What's a secrets file?

We expect people to share tons of projects as they build CircuitPython WiFi widgets. What we want to avoid is people accidentally sharing their passwords or secret tokens and API keys. So, we designed all our examples to use a secrets.py file, that is in your CIRCUITPY drive, to hold secret/private/custom data. That way you can share your main project without worrying about accidentally sharing private stuff.

Your secrets.py file should look like this:

# This file is where you keep secret settings, passwords, and tokens!
# If you put them in the code you risk committing that info or sharing it

secrets = {
    'ssid' : 'home ssid',
    'password' : 'my password',
    'timezone' : "America/New_York", # http://worldtimeapi.org/timezones
    'github_token' : 'fawfj23rakjnfawiefa',
    'hackaday_token' : 'h4xx0rs3kret',
    }

Inside is a python dictionary named secrets with a line for each entry. Each entry has an entry name (say 'ssid') and then a colon to separate it from the entry key 'home ssid' and finally a comma ,

At a minimum you'll need the ssid and password for your local WiFi setup. As you make projects you may need more tokens and keys, just add them one line at a time. See for example other tokens such as one for accessing github or the hackaday API. Other non-secret data like your timezone can also go here, just cause it's called secrets doesn't mean you can't have general customization data in there!

For the correct time zone string, look at http://worldtimeapi.org/timezones and remember that if your city is not listed, look for a city in the same time zone, for example Boston, New York, Philadelphia, Washington DC, and Miami are all on the same time as New York.

Of course, don't share your secrets.py - keep that out of GitHub, Discord or other project-sharing sites.

Connect to WiFi

OK now you have your secrets setup - you can connect to the Internet. Lets use the ESP32SPI and the Requests libraries - you'll need to visit the CircuitPython bundle and install:

  • adafruit_bus_device
  • adafruit_esp32spi
  • adafruit_requests
  • neopixel

Into your lib folder. Once that's done, load up the following example using Mu or your favorite editor:

# SPDX-FileCopyrightText: 2019 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import board
import busio
from digitalio import DigitalInOut
import adafruit_requests as requests
import adafruit_esp32spi.adafruit_esp32spi_socket as socket
from adafruit_esp32spi import adafruit_esp32spi

# Get wifi details and more from a secrets.py file
try:
    from secrets import secrets
except ImportError:
    print("WiFi secrets are kept in secrets.py, please add them there!")
    raise

print("ESP32 SPI webclient test")

TEXT_URL = "http://wifitest.adafruit.com/testwifi/index.html"
JSON_URL = "http://api.coindesk.com/v1/bpi/currentprice/USD.json"


# If you are using a board with pre-defined ESP32 Pins:
esp32_cs = DigitalInOut(board.ESP_CS)
esp32_ready = DigitalInOut(board.ESP_BUSY)
esp32_reset = DigitalInOut(board.ESP_RESET)

# If you have an AirLift Shield:
# esp32_cs = DigitalInOut(board.D10)
# esp32_ready = DigitalInOut(board.D7)
# esp32_reset = DigitalInOut(board.D5)

# If you have an AirLift Featherwing or ItsyBitsy Airlift:
# esp32_cs = DigitalInOut(board.D13)
# esp32_ready = DigitalInOut(board.D11)
# esp32_reset = DigitalInOut(board.D12)

# If you have an externally connected ESP32:
# NOTE: You may need to change the pins to reflect your wiring
# esp32_cs = DigitalInOut(board.D9)
# esp32_ready = DigitalInOut(board.D10)
# esp32_reset = DigitalInOut(board.D5)

spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)

requests.set_socket(socket, esp)

if esp.status == adafruit_esp32spi.WL_IDLE_STATUS:
    print("ESP32 found and in idle mode")
print("Firmware vers.", esp.firmware_version)
print("MAC addr:", [hex(i) for i in esp.MAC_address])

for ap in esp.scan_networks():
    print("\t%s\t\tRSSI: %d" % (str(ap["ssid"], "utf-8"), ap["rssi"]))

print("Connecting to AP...")
while not esp.is_connected:
    try:
        esp.connect_AP(secrets["ssid"], secrets["password"])
    except RuntimeError as e:
        print("could not connect to AP, retrying: ", e)
        continue
print("Connected to", str(esp.ssid, "utf-8"), "\tRSSI:", esp.rssi)
print("My IP address is", esp.pretty_ip(esp.ip_address))
print(
    "IP lookup adafruit.com: %s" % esp.pretty_ip(esp.get_host_by_name("adafruit.com"))
)
print("Ping google.com: %d ms" % esp.ping("google.com"))

# esp._debug = True
print("Fetching text from", TEXT_URL)
r = requests.get(TEXT_URL)
print("-" * 40)
print(r.text)
print("-" * 40)
r.close()

print()
print("Fetching json from", JSON_URL)
r = requests.get(JSON_URL)
print("-" * 40)
print(r.json())
print("-" * 40)
r.close()

print("Done!")

And save it to your board, with the name code.py

Don't forget you'll also need to create the secrets.py file as seen above, with your WiFi ssid and password.

In a serial console, you should see something like the following. For more information about connecting with a serial console, view the guide Connecting to the Serial Console.

In order, the example code...

Initializes the ESP32 over SPI using the SPI port and 3 control pins:

esp32_cs = DigitalInOut(board.ESP_CS)
esp32_ready = DigitalInOut(board.ESP_BUSY)
esp32_reset = DigitalInOut(board.ESP_RESET)

spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)

Tells our requests library the type of socket we're using (socket type varies by connectivity type - we'll be using the adafruit_esp32spi_socket for this example). We'll also set the interface to an esp object. This is a little bit of a hack, but it lets us use requests like CPython does.

requests.set_socket(socket, esp)

Verifies an ESP32 is found, checks the firmware and MAC address

if esp.status == adafruit_esp32spi.WL_IDLE_STATUS:
    print("ESP32 found and in idle mode")
print("Firmware vers.", esp.firmware_version)
print("MAC addr:", [hex(i) for i in esp.MAC_address])

Performs a scan of all access points it can see and prints out the name and signal strength:

for ap in esp.scan_networks():
    print("\t%s\t\tRSSI: %d" % (str(ap['ssid'], 'utf-8'), ap['rssi']))

Connects to the AP we've defined here, then prints out the local IP address, attempts to do a domain name lookup and ping google.com to check network connectivity (note sometimes the ping fails or takes a while, this isn't a big deal)

print("Connecting to AP...")
while not esp.is_connected:
    try:
        esp.connect_AP(secrets["ssid"], secrets["password"])
    except RuntimeError as e:
        print("could not connect to AP, retrying: ", e)
        continue
print("Connected to", str(esp.ssid, "utf-8"), "\tRSSI:", esp.rssi)
print("My IP address is", esp.pretty_ip(esp.ip_address))
print(
    "IP lookup adafruit.com: %s" % esp.pretty_ip(esp.get_host_by_name("adafruit.com"))

OK now we're getting to the really interesting part. With a SAMD51 or other large-RAM (well, over 32 KB) device, we can do a lot of neat tricks. Like for example we can implement an interface a lot like requests - which makes getting data really really easy

To read in all the text from a web URL call requests.get - you can pass in https URLs for SSL connectivity

TEXT_URL = "http://wifitest.adafruit.com/testwifi/index.html"
print("Fetching text from", TEXT_URL)
r = requests.get(TEXT_URL)
print('-'*40)
print(r.text)
print('-'*40)
r.close()

Or, if the data is in structured JSON, you can get the json pre-parsed into a Python dictionary that can be easily queried or traversed. (Again, only for nRF52840, M4 and other high-RAM boards)

JSON_URL = "http://api.coindesk.com/v1/bpi/currentprice/USD.json"
print("Fetching json from", JSON_URL)
r = requests.get(JSON_URL)
print('-'*40)
print(r.json())
print('-'*40)
r.close()

Requests

We've written a requests-like library for web interfacing named Adafruit_CircuitPython_Requests. This library allows you to send HTTP/1.1 requests without "crafting" them and provides helpful methods for parsing the response from the server.

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

# adafruit_requests usage with an esp32spi_socket
import board
import busio
from digitalio import DigitalInOut
import adafruit_esp32spi.adafruit_esp32spi_socket as socket
from adafruit_esp32spi import adafruit_esp32spi
import adafruit_requests as requests

# Add a secrets.py to your filesystem that has a dictionary called secrets with "ssid" and
# "password" keys with your WiFi credentials. DO NOT share that file or commit it into Git or other
# source control.
# pylint: disable=no-name-in-module,wrong-import-order
try:
    from secrets import secrets
except ImportError:
    print("WiFi secrets are kept in secrets.py, please add them there!")
    raise

# If you are using a board with pre-defined ESP32 Pins:
esp32_cs = DigitalInOut(board.ESP_CS)
esp32_ready = DigitalInOut(board.ESP_BUSY)
esp32_reset = DigitalInOut(board.ESP_RESET)

# If you have an externally connected ESP32:
# esp32_cs = DigitalInOut(board.D9)
# esp32_ready = DigitalInOut(board.D10)
# esp32_reset = DigitalInOut(board.D5)

# If you have an AirLift Featherwing or ItsyBitsy Airlift:
# esp32_cs = DigitalInOut(board.D13)
# esp32_ready = DigitalInOut(board.D11)
# esp32_reset = DigitalInOut(board.D12)

spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)

print("Connecting to AP...")
while not esp.is_connected:
    try:
        esp.connect_AP(secrets["ssid"], secrets["password"])
    except RuntimeError as e:
        print("could not connect to AP, retrying: ", e)
        continue
print("Connected to", str(esp.ssid, "utf-8"), "\tRSSI:", esp.rssi)

# Initialize a requests object with a socket and esp32spi interface
socket.set_interface(esp)
requests.set_socket(socket, esp)

TEXT_URL = "http://wifitest.adafruit.com/testwifi/index.html"
JSON_GET_URL = "https://httpbin.org/get"
JSON_POST_URL = "https://httpbin.org/post"

print("Fetching text from %s" % TEXT_URL)
response = requests.get(TEXT_URL)
print("-" * 40)

print("Text Response: ", response.text)
print("-" * 40)
response.close()

print("Fetching JSON data from %s" % JSON_GET_URL)
response = requests.get(JSON_GET_URL)
print("-" * 40)

print("JSON Response: ", response.json())
print("-" * 40)
response.close()

data = "31F"
print("POSTing data to {0}: {1}".format(JSON_POST_URL, data))
response = requests.post(JSON_POST_URL, data=data)
print("-" * 40)

json_resp = response.json()
# Parse out the 'data' key from json_resp dict.
print("Data received from server:", json_resp["data"])
print("-" * 40)
response.close()

json_data = {"Date": "July 25, 2019"}
print("POSTing data to {0}: {1}".format(JSON_POST_URL, json_data))
response = requests.post(JSON_POST_URL, json=json_data)
print("-" * 40)

json_resp = response.json()
# Parse out the 'json' key from json_resp dict.
print("JSON Data received from server:", json_resp["json"])
print("-" * 40)
response.close()

The code first sets up the ESP32SPI interface. Then, it initializes a request object using an ESP32 socket and the esp object.

import board
import busio
from digitalio import DigitalInOut
import adafruit_esp32spi.adafruit_esp32spi_socket as socket
from adafruit_esp32spi import adafruit_esp32spi
import adafruit_requests as requests

# If you are using a board with pre-defined ESP32 Pins:
esp32_cs = DigitalInOut(board.ESP_CS)
esp32_ready = DigitalInOut(board.ESP_BUSY)
esp32_reset = DigitalInOut(board.ESP_RESET)

# If you have an externally connected ESP32:
# esp32_cs = DigitalInOut(board.D9)
# esp32_ready = DigitalInOut(board.D10)
# esp32_reset = DigitalInOut(board.D5)

spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)

print("Connecting to AP...")
while not esp.is_connected:
    try:
        esp.connect_AP(b'MY_SSID_NAME', b'MY_SSID_PASSWORD')
    except RuntimeError as e:
        print("could not connect to AP, retrying: ",e)
        continue
print("Connected to", str(esp.ssid, 'utf-8'), "\tRSSI:", esp.rssi)

# Initialize a requests object with a socket and esp32spi interface
requests.set_socket(socket, esp)

HTTP GET with Requests

The code makes a HTTP GET request to Adafruit's WiFi testing website - http://wifitest.adafruit.com/testwifi/index.html.

To do this, we'll pass the URL into requests.get(). We're also going to save the response from the server into a variable named response.

While we requested data from the server, we'd what the server responded with. Since we already saved the server's response, we can read it back. Luckily for us, requests automatically decodes the server's response into human-readable text, you can read it back by calling response.text.

Lastly, we'll perform a bit of cleanup by calling response.close(). This closes, deletes, and collect's the response's data. 

print("Fetching text from %s"%TEXT_URL)
response = requests.get(TEXT_URL)
print('-'*40)

print("Text Response: ", response.text)
print('-'*40)
response.close()

While some servers respond with text, some respond with json-formatted data consisting of attribute–value pairs.

CircuitPython_Requests can convert a JSON-formatted response from a server into a CPython dict. object.

We can also fetch and parse json data. We'll send a HTTP get to a url we know returns a json-formatted response (instead of text data). 

Then, the code calls response.json() to convert the response to a CPython dict

print("Fetching JSON data from %s"%JSON_GET_URL)
response = requests.get(JSON_GET_URL)
print('-'*40)

print("JSON Response: ", response.json())
print('-'*40)
response.close()

HTTP POST with Requests

Requests can also POST data to a server by calling the requests.post method, passing it a data value.

data = '31F'
print("POSTing data to {0}: {1}".format(JSON_POST_URL, data))
response = requests.post(JSON_POST_URL, data=data)
print('-'*40)

json_resp = response.json()
# Parse out the 'data' key from json_resp dict.
print("Data received from server:", json_resp['data'])
print('-'*40)
response.close()

You can also post json-formatted data to a server by passing json_data into the requests.post method.

    json_data = {"Date" : "July 25, 2019"}
print("POSTing data to {0}: {1}".format(JSON_POST_URL, json_data))
response = requests.post(JSON_POST_URL, json=json_data)
print('-'*40)

json_resp = response.json()
# Parse out the 'json' key from json_resp dict.
print("JSON Data received from server:", json_resp['json'])
print('-'*40)
response.close()
  

Advanced Requests Usage

Want to send custom HTTP headers, parse the response as raw bytes, or handle a response's http status code in your CircuitPython code?

We've written an example to show advanced usage of the requests module below.

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import board
import busio
from digitalio import DigitalInOut
import adafruit_esp32spi.adafruit_esp32spi_socket as socket
from adafruit_esp32spi import adafruit_esp32spi
import adafruit_requests as requests

# Add a secrets.py to your filesystem that has a dictionary called secrets with "ssid" and
# "password" keys with your WiFi credentials. DO NOT share that file or commit it into Git or other
# source control.
# pylint: disable=no-name-in-module,wrong-import-order
try:
    from secrets import secrets
except ImportError:
    print("WiFi secrets are kept in secrets.py, please add them there!")
    raise

# If you are using a board with pre-defined ESP32 Pins:
esp32_cs = DigitalInOut(board.ESP_CS)
esp32_ready = DigitalInOut(board.ESP_BUSY)
esp32_reset = DigitalInOut(board.ESP_RESET)

# If you have an externally connected ESP32:
# esp32_cs = DigitalInOut(board.D9)
# esp32_ready = DigitalInOut(board.D10)
# esp32_reset = DigitalInOut(board.D5)

spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)

print("Connecting to AP...")
while not esp.is_connected:
    try:
        esp.connect_AP(secrets["ssid"], secrets["password"])
    except RuntimeError as e:
        print("could not connect to AP, retrying: ", e)
        continue
print("Connected to", str(esp.ssid, "utf-8"), "\tRSSI:", esp.rssi)

# Initialize a requests object with a socket and esp32spi interface
socket.set_interface(esp)
requests.set_socket(socket, esp)

JSON_GET_URL = "http://httpbin.org/get"

# Define a custom header as a dict.
headers = {"user-agent": "blinka/1.0.0"}

print("Fetching JSON data from %s..." % JSON_GET_URL)
response = requests.get(JSON_GET_URL, headers=headers)
print("-" * 60)

json_data = response.json()
headers = json_data["headers"]
print("Response's Custom User-Agent Header: {0}".format(headers["User-Agent"]))
print("-" * 60)

# Read Response's HTTP status code
print("Response HTTP Status Code: ", response.status_code)
print("-" * 60)

# Close, delete and collect the response data
response.close()

WiFi Manager

That simpletest example works but it's a little finicky - you need to constantly check WiFi status and have many loops to manage connections and disconnections. For more advanced uses, we recommend using the WiFiManager object. It will wrap the connection/status/requests loop for you - reconnecting if WiFi drops, resetting the ESP32 if it gets into a bad state, etc.

Here's a more advanced example that shows the WiFi manager and also how to POST data with some extra headers:

# SPDX-FileCopyrightText: 2019 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
import board
import busio
from digitalio import DigitalInOut
import neopixel
from adafruit_esp32spi import adafruit_esp32spi
from adafruit_esp32spi import adafruit_esp32spi_wifimanager

print("ESP32 SPI webclient test")

# Get wifi details and more from a secrets.py file
try:
    from secrets import secrets
except ImportError:
    print("WiFi secrets are kept in secrets.py, please add them there!")
    raise

# If you are using a board with pre-defined ESP32 Pins:
esp32_cs = DigitalInOut(board.ESP_CS)
esp32_ready = DigitalInOut(board.ESP_BUSY)
esp32_reset = DigitalInOut(board.ESP_RESET)

# If you have an externally connected ESP32:
# esp32_cs = DigitalInOut(board.D9)
# esp32_ready = DigitalInOut(board.D10)
# esp32_reset = DigitalInOut(board.D5)

spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)
"""Use below for Most Boards"""
status_light = neopixel.NeoPixel(
    board.NEOPIXEL, 1, brightness=0.2
)  # Uncomment for Most Boards
"""Uncomment below for ItsyBitsy M4"""
# status_light = dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1, brightness=0.2)
# Uncomment below for an externally defined RGB LED
# import adafruit_rgbled
# from adafruit_esp32spi import PWMOut
# RED_LED = PWMOut.PWMOut(esp, 26)
# GREEN_LED = PWMOut.PWMOut(esp, 27)
# BLUE_LED = PWMOut.PWMOut(esp, 25)
# status_light = adafruit_rgbled.RGBLED(RED_LED, BLUE_LED, GREEN_LED)
wifi = adafruit_esp32spi_wifimanager.ESPSPI_WiFiManager(esp, secrets, status_light)

counter = 0

while True:
    try:
        print("Posting data...", end="")
        data = counter
        feed = "test"
        payload = {"value": data}
        response = wifi.post(
            "https://io.adafruit.com/api/v2/"
            + secrets["aio_username"]
            + "/feeds/"
            + feed
            + "/data",
            json=payload,
            headers={"X-AIO-KEY": secrets["aio_key"]},
        )
        print(response.json())
        response.close()
        counter = counter + 1
        print("OK")
    except (ValueError, RuntimeError) as e:
        print("Failed to get data, retrying\n", e)
        wifi.reset()
        continue
    response = None
    time.sleep(15)

You'll note here we use a secrets.py file to manage our SSID info. The wifimanager is given the ESP32 object, secrets and a neopixel for status indication.

Note, you'll need to add a some additional information to your secrets file so that the code can query the Adafruit IO API:

  • aio_username
  • aio_key

You can go to your adafruit.io View AIO Key link to get those two values and add them to the secrets file, which will now look something like this:

# This file is where you keep secret settings, passwords, and tokens!
# If you put them in the code you risk committing that info or sharing it

secrets = {
    'ssid' : '_your_ssid_',
    'password' : '_your_wifi_password_',
    'timezone' : "America/Los_Angeles", # http://worldtimeapi.org/timezones
    'aio_username' : '_your_aio_username_',
    'aio_key' : '_your_aio_key_',
    }

Next, set up an Adafruit IO feed named test

We can then have a simple loop for posting data to Adafruit IO without having to deal with connecting or initializing the hardware!

Take a look at your test feed on Adafruit.io and you'll see the value increase each time the CircuitPython board posts data to it!

CircuitPython Library Installation

First make sure you are running the latest version of Adafruit CircuitPython for your board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle matching your version of CircuitPython. PyPortal requires at least CircuitPython version 4.0.0.

Connect your PyPortal to your computer using a known good data+power USB cable. The board should show up in your operating system file explorer/finder as a flash drive names CIRCUITPY.

Before continuing make sure your board's lib folder on CIRCUITPY has the following files and folders copied over.

  • adafruit_binascii.mpy
  • adafruit_imageload
  • adafruit_bitmap_font
  • adafruit_itertools
  • adafruit_rsa
  • adafruit_bus_device
  • adafruit_jwt.mpy
  • adafruit_seesaw
  • adafruit_logging.mpy
  • neopixel.mpy
  • adafruit_esp32spi
  • adafruit_minimqtt
  • adafruit_gc_iot_core.mpy
  • adafruit_ntp.mpy
  • adafruit_hashlib.mpy
  • adafruit_register

Add CircuitPython Code and Project Assets

In the embedded code element below, click on the Download: Project Zip link, and save the .zip archive file to your computer.

Then, uncompress the .zip file, it will unpack to a folder named PyPortal_GC_IOT_CORE_PLANT_MONITOR.

Copy the contents of thePyPortal_GC_IOT_CORE_PLANT_MONITOR directory to your PyPortal's CIRCUITPY drive.

"""
PyPortal Google Cloud IoT Core Planter
=======================================================
Water your plant remotely and log its vitals to Google
Cloud IoT Core with your PyPortal.

Author: Brent Rubell for Adafruit Industries, 2019
"""
import time
import json
import board
import busio
import gcp_gfx_helper
import neopixel
from adafruit_esp32spi import adafruit_esp32spi, adafruit_esp32spi_wifimanager
import adafruit_esp32spi.adafruit_esp32spi_socket as socket
from adafruit_gc_iot_core import MQTT_API, Cloud_Core
import adafruit_minimqtt.adafruit_minimqtt as MQTT
from adafruit_seesaw.seesaw import Seesaw
import digitalio

# Delay before reading the sensors, in minutes
SENSOR_DELAY = 10

# Get wifi details and more from a secrets.py file
try:
    from secrets import secrets
except ImportError:
    print("WiFi secrets are kept in secrets.py, please add them there!")
    raise

# PyPortal ESP32 Setup
esp32_cs = digitalio.DigitalInOut(board.ESP_CS)
esp32_ready = digitalio.DigitalInOut(board.ESP_BUSY)
esp32_reset = digitalio.DigitalInOut(board.ESP_RESET)
spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)
status_light = neopixel.NeoPixel(board.NEOPIXEL, 1, brightness=0.2)
wifi = adafruit_esp32spi_wifimanager.ESPSPI_WiFiManager(
    esp, secrets, status_light)

# Connect to WiFi
print("Connecting to WiFi...")
wifi.connect()
print("Connected!")

# Initialize MQTT interface with the esp interface
MQTT.set_socket(socket, esp)

# Soil Sensor Setup
i2c_bus = busio.I2C(board.SCL, board.SDA)
ss = Seesaw(i2c_bus, addr=0x36)

# Water Pump Setup
water_pump = digitalio.DigitalInOut(board.D3)
water_pump.direction = digitalio.Direction.OUTPUT

# Initialize the graphics helper
print("Loading GCP Graphics...")
gfx = gcp_gfx_helper.Google_GFX()
print("Graphics loaded!")


# Define callback methods which are called when events occur
# pylint: disable=unused-argument, redefined-outer-name
def connect(client, userdata, flags, rc):
    # This function will be called when the client is connected
    # successfully to the broker.
    print('Connected to Google Cloud IoT!')
    print('Flags: {0}\nRC: {1}'.format(flags, rc))
    # Subscribes to commands/# topic
    google_mqtt.subscribe_to_all_commands()


def disconnect(client, userdata, rc):
    # This method is called when the client disconnects
    # from the broker.
    print('Disconnected from Google Cloud IoT!')


def subscribe(client, userdata, topic, granted_qos):
    # This method is called when the client subscribes to a new topic.
    print('Subscribed to {0} with QOS level {1}'.format(topic, granted_qos))


def unsubscribe(client, userdata, topic, pid):
    # This method is called when the client unsubscribes from a topic.
    print('Unsubscribed from {0} with PID {1}'.format(topic, pid))


def publish(client, userdata, topic, pid):
    # This method is called when the client publishes data to a topic.
    print('Published to {0} with PID {1}'.format(topic, pid))


def message(client, topic, msg):
    # This method is called when the client receives data from a topic.
    try:
        # Attempt to decode a JSON command
        msg_dict = json.loads(msg)
        # Handle water-pump commands
        if msg_dict['pump_time']:
            handle_pump(msg_dict)
    except TypeError:
        # Non-JSON command, print normally
        print("Message from {}: {}".format(topic, msg))


def handle_pump(command):
    """Handles command about the planter's
    watering pump from Google Core IoT.
    :param json command: Message from device/commands#
    """
    print("handling pump...")
    # Parse the pump command message
    # Expected format: {"power": true, "pump_time":3}
    pump_time = command['pump_time']
    pump_status = command['power']
    if pump_status:
        print("Turning pump on for {} seconds...".format(pump_time))
        start_pump = time.monotonic()
        while True:
            gfx.show_gcp_status('Watering plant...')
            cur_time = time.monotonic()
            if cur_time - start_pump > pump_time:
                # Timer expired, leave the loop
                print("Plant watered!")
                break
            water_pump.value = True
    gfx.show_gcp_status('Plant watered!')
    print("Turning pump off")
    water_pump.value = False


# Initialize Google Cloud IoT Core interface
google_iot = Cloud_Core(esp, secrets)

# JSON-Web-Token (JWT) Generation
print("Generating JWT...")
jwt = google_iot.generate_jwt()
print("Your JWT is: ", jwt)

# Set up a new MiniMQTT Client
client = MQTT.MQTT(broker=google_iot.broker,
                   username=google_iot.username,
                   password=jwt,
                   client_id=google_iot.cid)

# Initialize Google MQTT API Client
google_mqtt = MQTT_API(client)

# Connect callback handlers to Google MQTT Client
google_mqtt.on_connect = connect
google_mqtt.on_disconnect = disconnect
google_mqtt.on_subscribe = subscribe
google_mqtt.on_unsubscribe = unsubscribe
google_mqtt.on_publish = publish
google_mqtt.on_message = message

print('Attempting to connect to %s' % client.broker)
google_mqtt.connect()

# Time in seconds since power on
initial = time.monotonic()

while True:
    try:
        gfx.show_gcp_status('Listening for new messages...')
        now = time.monotonic()
        if now - initial > (SENSOR_DELAY * 60):
            # read moisture level
            moisture_level = ss.moisture_read()
            # read temperature
            temperature = ss.get_temp()
            # Display Soil Sensor values on pyportal
            temperature = gfx.show_temp(temperature)
            gfx.show_water_level(moisture_level)
            print('Sending data to GCP IoT Core')
            gfx.show_gcp_status('Publishing data...')
            google_mqtt.publish(temperature, "events")
            time.sleep(2)
            google_mqtt.publish(moisture_level, "events")
            gfx.show_gcp_status('Data published!')
            print('Data sent!')
            # Reset timer
            initial = now
        google_mqtt.loop()
    except (ValueError, RuntimeError) as e:
        print("Failed to get data, retrying", e)
        wifi.reset()
        google_mqtt.reconnect()
        continue

This is what the final contents of the CIRCUITPY drive will look like:

Install Mu Editor 

This guide requires you to edit and interact with CircuitPython code. While you can use any text editor of your choosing,  Mu is a simple code editor that works with the Adafruit CircuitPython boards. It's written in Python and works on Windows, MacOS, Linux and Raspberry Pi. The serial console is built right in, so you get immediate feedback from your board's serial output!

Before proceeding, click the button below to install the Mu Editor. There are versions for PC, mac, and Linux.

Secrets File Setup

Open the secrets.py file on your CIRCUITPY drive using Mu. You're going to edit the file to enter your local WiFi credentials along with data about your Google Cloud Services Project and IoT Core configuration.

Make the following changes to the code below in the secrets.py file:

  • Replace MY_WIFI_SSID with the name of your WiFi SSID
  • Replace MY_WIFI_PASSWORD with your WiFi's password
  • Replace MY_GCS_PROJECT_ID with the name of your Google Cloud Services project.
  • Replace MY_GCS_PROJECT_REGION with the project's region.
  • Replace MY_IOT_REGISTRY with the name of your Cloud IoT registry.
  • Replace MY_IOT_DEVICE with the name of the device you created in your Cloud IoT registry.
# This file is where you keep secret settings, passwords, and tokens!
# If you put them in the code you risk committing that info or sharing it
secrets = {
    'ssid' : 'MY_WIFI_SSID',
    'password' : 'MY_WIFI_PASSWORD',
    'project_id' : 'MY_GCS_PROJECT_ID',
    'cloud_region' : 'MY_GCS_PROJECT_REGION',
    'registry_id' : 'MY_IOT_REGISTRY',
    'device_id' : 'MY_IOT_DEVICE'
}

Authenticating with Google Cloud IoT Core - the JWT

CircuitPython authenticates with Google's MQTT API using a special security key called a JSON Web Token (JWT)

A JSON Web Token is a JSON dictionary containing statements (claims) about the device. In our case, it looks like the following:

token = {
  # The time that the token was issued at
  'iat': issue_time,
  # The time the token expires.
  'exp': expiration_time,
  # Your Project Identifier
  'aud': project_id
}

We are not going to create this JWT manually, the Google Core IoT CircuitPython module handles this automatically for you using the CircuitPython JWT module.

Creating a RSA Key Pair

The final step in generating a JWT involves signing the JWT with a private key. This ensures that the key will only be used to communicate with a public key.

Your CircuitPython device will hold the device's private RSA, while Google Cloud IoT holds the device's public RSA key

While the CircuitPython RSA module can generate RSA keys, it cannot save the key pairs to the device's filesystem. 

We'll be generating a RSA key pair on our computer using a Python script.

Click decode_key_priv.py to download the code below and save the code to your desktop.

# SPDX-FileCopyrightText: 2019 Google Inc.
# SPDX-FileCopyrightText: 2019 Brent Rubell for Adafruit Industries
#
# SPDX-License-Identifier: Apache-2.0

"""
`decode_priv_key.py`
===================================================================

Generates RSA keys and decodes them using python-rsa
for use with a CircuitPython secrets file.

This script is designed to run on a computer,
NOT a CircuitPython device.

Requires Python-RSA (https://github.com/sybrenstuvel/python-rsa)

* Author(s): Google Inc., Brent Rubell
"""
import subprocess
import rsa

# Generate private and public RSA keys
proc = subprocess.Popen(["openssl", "genrsa", "-out", "rsa_private.pem", "2048"])
proc.wait()
proc = subprocess.Popen(
    ["openssl", "rsa", "-in", "rsa_private.pem", "-pubout", "-out", "rsa_public.pem"]
)
proc.wait()

# Open generated private key file
try:
    with open("rsa_private.pem", "rb") as file:
        private_key = file.read()
except:  # pylint: disable=bare-except
    print("No file named rsa_private.pem found in directory.")
pk = rsa.PrivateKey.load_pkcs1(private_key)

print("Copy and paste this into your secrets.py file:\n")
print('"private_key": ' + str(pk)[10:] + ",")

You'll need a local installation of Python (click here to download and install the Python distribution for your operating system) to run this script.

You'll also need to install the python-rsa library, you can do this by typing the following into your terminal:

pip install rsa

Once installed, run the code from your desktop:

python3 decode_key_priv.py

If the script runs successfully, it'll create two files on your desktop - rsa_public.pem and rsa_private.pem. These are your public and private RSA keys. You'll use them in the next step.

It'll also output the decoded private key to your terminal. The private key should have five integer values.

Modify your secrets.py file by copying and pasting the output from the code into the file:

# This file is where you keep secret settings, passwords, and tokens!
# If you put them in the code you risk committing that info or sharing it

secrets = {
    'ssid' : 'MY_WIFI_SSID',
    'password' : 'MY_WIFI_PASSWORD',
    'project_id' : 'MY_GCS_PROJECT_ID',
    'cloud_region' : 'MY_GCS_PROJECT_REGION',
    'registry_id' : 'MY_IOT_REGISTRY',
    'device_id' : 'MY_IOT_DEVICE',
    "private_key": (24438159363269526254144311871580579031858357859966324445350326786364998912771634237547789185814277400858631944952065597018819979449812397621834604674421573629778503529017607686952918724898685881544477812184759676064843937596886704154729857293596401786101074754877589082423154083489847915661860834755738610786688547912322386416918350317006245900073735354143276892049027125601443947584374912401061688828446039255462953272156360234392950941978497936249124410101311599817221805182114152095007037371899964182199631346414794479580997760720063537930724219713985584071493296120508892403130706628712278713361122757185268631117,
                    65531,
                    16011940782440353652943478520006562150052609770159665100376017092734074695430275633005814541997117225275335393994868497733923278721561016736829240348500272695770159475350047668916159269529419591276986698433153493297288534421934404632560234252209126031023393655102364697792853446832385820201112413513111592950042350642403708159079499430564775961436272409066068179381765892260252909360654617051331730162665742415598304194771289070036798676791361721996492207147874480559927670849388398727297101629122127273532260070125100209595266819508897273144318330256879686971164694481555143431693246541875462896679755259675697969793,
                    171180510224532714639208966958930887752631657983050450948053675977812070176625671098825502436380896087798236950227432035881066562828394842137169407540235290205801047834085254364601442602722583477726608017578416412915568120972286874859375397533049118528847434756643019078803240871975917780146737832789354797749,
                    142762310320270325250889040291289810070312245928207105466534900926375358526304862222284449091864287073322237001651192479298990227289938371837057243365681576671132453564694769006817561479289703593958730636340134647097544182128899145836621518733215831051979336393263185036416885910092387701460789142994244341633)
}

Adding your RSA Public Key to Google Cloud IoT Core

After the private key is set up on your CircuitPython device, you'll also need to add the public key to the IoT Core Device. 

To view the public key data, enter the following into your terminal:

less rsa_public.pem

It should print the RSA Public Key data to your terminal.

Copy the output starting with -----BEGIN PUBLIC KEY----- to your clipboard.

Navigate to the IoT Core Device details page. Under Authenticationclick Add public key.

Specify the public key format to be RS256 and paste the public key data into the Public key value text box.

Click Add Public Key to add the authentication key to your device.

With the private key stored on your CircuitPython device and the public key stored in Google IoT Core, you're ready to run your code!

Connecting to Google Cloud IoT Core

When the PyPortal starts up, it will first load the gcp_splash.bmp image in the images folder on your CIRCUITPY drive. This is a "loading screen" while the code waits for the fonts and display objects load on the screen.

Opening the REPL will help you view what's happening in the code. First, the code attempts to load the PyPortal's graphical interface

Loading GCP Graphics...
Displaying splash screen
Set icon to  /images/gcp_splash.bmp
Setting up labels...
Graphics loaded!

Next, the code will create a JWT. This will take a while as the code needs to grab the network time, generate a JWT, and sign the JWT with your private key. 

Generating JWT...
Your JWT is: SUPER_LONG_JSON_WEB_TOKEN

Once the JWT is created, the code will attempt to connect to Google Cloud IoT.

Connecting to WiFi...
Connected!
Attempting to connect to mqtt.googleapis.com

When the PyPortal connects with Google Cloud, it'll print out that it's connected and attempt to subscribe to the device's default command topic (more on this later!)

Connected to Google Cloud IoT!
Flags: 0
RC: 0
Subscribed to /devices/pyportal/commands/# with QOS level 1

Viewing Sensor data on PyPortal

You should see the PyPortal display update to display the temperature value and moisture level.

The status indicator at the bottom of the PyPortal will display when it's sending data to Google IoT. The PyPortal only sends data to Google Cloud IoT every SENSOR_DELAY minutes. Adjust this value in the code to increase or decrease the delay.

Viewing Data from Google Cloud Platform

You can view the data published to the feeds by your CircuitPython device. Navigate to the Pub/Sub page for your project at https://console.cloud.google.com/cloudpubsub.

In the topic list, click the topic used by your IoT Core Registry.  

Next to Topic details, click Pull Messages

Select the Cloud Pub/Sub subscription you created earlier and click PULL.

You should see the message, along with the device identifier and the time which the PyPortal published the message.  

You can also view the MQTT commands sent from your PyPortal to Google Cloud. From the device page, click View logs next to Stackdriver Logging.

While the code is running on the PyPortal, the Logger displays incoming MQTT commands.

If your code is idle (you aren't publishing data or subscribing to topics), you should see the device pinging the MQTT broker every 59 seconds (MiniMQTT sets this by default). The device does this to remain connected to the broker (effectively telling it, "hey, I'm still here!").

Sending Commands from Google IoT Core to your PyPortal

If your plant is parched, you can water it from across the world! Google Cloud IoT Core supports cloud-to-device communication. The provided code automatically subscribes to the default command topic (commands/#). Any incoming command will be handled by the code's message() method.

Let's water your plant!

With your PyPortal connected to Cloud IoT Core, navigate to the Device details page. Click the SEND COMMAND button on the IoT Core page header.

The Send Command API allows you to send command data as either plaintext or base64-encoded text. 

A typical rule-of-thumb in building internet-of-things projects is to send data as a single command, even if you're sending multiple commands.

To do this, you'll use the JSON file format to construct a command containing information about the pump. The resulting JSON command will look something like the following:

{"power":  true, "pump_time": 3}

with power representing the pump's state and pump_time representing the duration the pump is on for (in seconds).

Now that you have a command, enter the command into the Command data text field and click SEND COMMAND to send your command to the PyPortal.

You should see the message appear in the CircuitPython REPL:

Turning pump on for 3 seconds...
Plant watered!
Turning pump off

The pump should also turn on and water the plant for the duration you specified.

The pump we're using is a peristaltic type pump - the pump squishes the silicone tubing that contains the liquid instead of impelling it directly. This pump will take a while to move water into the tube, compress it, and push it out the other tube for your plant.

When sending a water pump message to your PyPortal - consider how long this process will take. You could send a message with a large time to determine this value. This'll value depends on a few factors including the length of your tubing and the power of your pump's motor.

That's it - you have a working IoT Planter powered by Google Cloud IoT Core and CircuitPython! The next section will discuss how this code works.

Importing CircuitPython Libraries

import time
import json
import adafruit_esp32spi.adafruit_esp32spi_socket as socket
import board
import busio
import digitalio
import gcp_gfx_helper
import neopixel
from adafruit_esp32spi import adafruit_esp32spi, adafruit_esp32spi_wifimanager
from adafruit_gc_iot_core import MQTT_API, Cloud_Core
from adafruit_minimqtt import MQTT
from adafruit_seesaw.seesaw import Seesaw
from digitalio import DigitalInOut

The code first imports all of the modules required to run the code. Some of these libraries are CircuitPython core modules (they're "burned into" the firmware) and some of them you dragged into the library folder.

The code for this project imports a special adafruit_gc_iot_core library. To help simplify managing communication between your PyPortal and Google IoT Core's interfaces, we wrote a CircuitPython helper module called Adafruit_CircuitPython_GC_IOT_Core

We've also included a gcp_gfx_helper.py file which handles displaying the status of the code on the PyPortal's display.

Configuring the PyPortal's WiFi Hardware

The next chunk of code grabs information from a secrets.py file including wifi configuration. Then, it sets up the ESP32's SPI connections for use with the PyPortal. The wifi object is set up here too - it's used later in the code to communicate with the IoT Hub.

# Get wifi details and more from a secrets.py file
try:
    from secrets import secrets
except ImportError:
    print("WiFi secrets are kept in secrets.py, please add them there!")
    raise

# PyPortal ESP32 Setup
esp32_cs = DigitalInOut(board.ESP_CS)
esp32_ready = DigitalInOut(board.ESP_BUSY)
esp32_reset = DigitalInOut(board.ESP_RESET)
spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)
status_light = neopixel.NeoPixel(board.NEOPIXEL, 1, brightness=0.2) # Uncomment for Most Boards
"""Uncomment below for ItsyBitsy M4"""
#status_light = dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1, brightness=0.2)
wifi = adafruit_esp32spi_wifimanager.ESPSPI_WiFiManager(esp, secrets, status_light)

Configuring the Soil Sensor and Water Pump

An I2C busio device is set up and linked to the soil sensor's address (0x36). The water pump is configured as a digitalio output, since you'll be controlling the pump using the "transistor switch" circuit.

# Soil Sensor Setup
i2c_bus = busio.I2C(board.SCL, board.SDA)
ss = Seesaw(i2c_bus, addr=0x36)

# Water Pump Setup
water_pump = digitalio.DigitalInOut(board.D3)
water_pump.direction = digitalio.Direction.OUTPUT

Configuring the Graphical Helper

The graphics helper, which manages' the PyPortal's display is created. If you wish to display the temperature in Fahrenheit instead of Celsius, add is_celsius=True to the method call.

gfx = gcp_gfx_helper.Google_GFX()

Connection Callback Methods

The following methods are used as MQTT client callbacks. They only execute when the broker (Google Cloud MQTT)  communicates with your PyPortal.

# Define callback methods which are called when events occur
def connect(client, userdata, flags, rc):
    # This function will be called when the client is connected
    # successfully to the broker.
    print('Connected to Google Cloud IoT!')
    print('Flags: {0}\nRC: {1}'.format(flags, rc))
    # Subscribes to commands/# topic
    google_mqtt.subscribe_to_all_commands()

def disconnect(client, userdata, rc):
    # This method is called when the client disconnects
    # from the broker.
    print('Disconnected from Google Cloud IoT!')

def subscribe(client, userdata, topic, granted_qos):
    # This method is called when the client subscribes to a new topic.
    print('Subscribed to {0} with QOS level {1}'.format(topic, granted_qos))


def unsubscribe(client, userdata, topic, pid):
    # This method is called when the client unsubscribes from a topic.
    print('Unsubscribed from {0} with PID {1}'.format(topic, pid))


def publish(client, userdata, topic, pid):
    # This method is called when the client publishes data to a topic.
    print('Published to {0} with PID {1}'.format(topic, pid))


def message(client, topic, msg):
    # This method is called when the client receives data from a topic.
    try:
        # Attempt to load a JSON command
        msg_dict = json.loads(msg)
        # Handle water-pump commands
        if msg_dict['pump_time']:
            handle_pump(msg_dict)
    except:
        # Non-JSON command, print normally
        print("Message from {}: {}".format(topic, msg))

Connecting to Cloud IoT Core

We created a helper class within the adafruit_gc_iot_core module to assist creating the project identifier and handling authentication. Cloud IoT Core's settings (Cloud_Core) are initialized. The JWT (JSON Web Token) used for authenticating with the server is generated for you automatically using the CircuitPython JWT module and the private RSA key you provided earlier.

# Initialize Google Cloud IoT Core interface
google_iot = Cloud_Core(esp, secrets)

# JSON-Web-Token (JWT) Generation
print("Generating JWT...")
jwt = google_iot.generate_jwt()
print("Your JWT is: ", jwt)

After the JWT has been successfully created, we'll set up a new MiniMQTT client for communicating with the Google MQTT API. This client uses a few variables from the google_iot object we created earlier, along with the JWT we just generated.

The code also initializes the Google MQTT API client, an interface which simplifies using MiniMQTT to communicate with Google Core IoT.

# Set up a new MiniMQTT Client
client = MQTT(socket,
              broker=google_iot.broker,
              username=google_iot.username,
              password=jwt,
              client_id=google_iot.cid,
              network_manager=wifi)

# Initialize Google MQTT API Client
google_mqtt = MQTT_API(client)

The connection callback methods created earlier are connected to the google_mqtt client and the code attempts to connect to Google Cloud IoT Core.

# Connect callback handlers to Google MQTT Client
google_mqtt.on_connect = connect
google_mqtt.on_disconnect = disconnect
google_mqtt.on_subscribe = subscribe
google_mqtt.on_unsubscribe = unsubscribe
google_mqtt.on_publish = publish
google_mqtt.on_message = message

print('Attempting to connect to %s' % client.broker)
google_mqtt.connect()

Once Google's MQTT broker successfully connects with your client, it'll call the connect() callback method. This method subscribes to the device's default commands topic (commands/#). Any data sent to this topic will be received by the code's message() callback.  

def connect(client, userdata, flags, rc):
    # This function will be called when the client is connected
    # successfully to the broker.
    print('Connected to Google Cloud IoT!')
    print('Flags: {0}\nRC: {1}'.format(flags, rc))
    # Subscribes to commands/# topic
    google_mqtt.subscribe_to_all_commands()

Main Loop

The main loop takes the current time and compares it to the desired SENSOR_DELAY time in minutes (set at the top of the code).

If the time has exceeded SENSOR_DELAY, the code reads the moisture level and temperature from the STEMMA soil sensor. Then, it displays the values of the soil sensor on the PyPortal using the gfx module. 

if now - initial > (SENSOR_DELAY * 60):
  # read moisture level
  moisture_level = ss.moisture_read()
  # read temperature
  temperature = ss.get_temp()
  # Display Soil Sensor values on pyportal
  temperature = gfx.show_temp(temperature)
  gfx.show_water_level(moisture_level)

Then the temperature and moisture_level are published to the device's default events topic. We added a two second delay between publishing to ensure we don't get throttled by Google's MQTT broker.

Then, the timer will set itself to the current time.monotonic value.

print('Sending data to GCP IoT Core')
gfx.show_gcp_status('Publishing data...')
google_mqtt.publish(temperature, "events")
time.sleep(2)
google_mqtt.publish(moisture_level, "events")
gfx.show_gcp_status('Data published!')
print('Data sent!')
# Reset timer
initial = now

If the SENSOR_DELAY time has not yet elapsed, we'll poll the Google MQTT broker to ensure we retain communication with the broker. google_mqtt.loop() pings Google's MQTT broker and listenings for a response back from it. It also queries the broker for any messages received (such as a message from Google Cloud IoT telling the pump to turn on). 

All of this code is wrapped inside a try/except control flow. If the WiFi module fails at any point, the program will execute the except and reset the module before going back to the top of the try.

Handling the Water Pump Messages

One interesting chunk of this code that we haven't yet discussed is How is data from google cloud received by the PyPortal?

Since the code is subscribed to all messages from the device/commands/# topic, every message will be received by the message() method. 

Since we're sending the PyPortal a message from Google Cloud in JSON format, we attempt to decode if the incoming message is a JSON dictionary. 

If it is a JSON command, the code looks for the pump_time key in the JSON dictionary. If it's found, the JSON dictionary is passed to a handle_pump method.

If it's not a JSON command, the code will simply print out the message and the topic it was received on. 

def message(client, topic, msg):
    # This method is called when the client receives data from a topic.
    try:
        # Attempt to decode a JSON command
        msg_dict = json.loads(msg)
        # Handle water-pump commands
        if msg_dict['pump_time']:
            handle_pump(msg_dict)
    except:
        # Non-JSON command, print normally
        print("Message from {}: {}".format(topic, msg))

The handle_pump method parses the pump_status and pump_time from the command's JSON dictionary.

If the pump command is enabling the pump, the code will print that it is starting the pump for pump_time and start a timer. While the timer is not expired, it'll turn on the pump by setting water_pump.value to True.

Once the timer expires, the screen will output that the plant is watered and the pump will be disabled.

def handle_pump(command):
    """Handles command about the planter's
    watering pump from Google Core IoT.
    :param json command: Message from device/commands#
    """
    print("handling pump...")
    # Parse the pump command message
    # Expected format: {"power": true, "pump_time":3}
    pump_time = command['pump_time']
    pump_status = command['power']
    if pump_status:
        print("Turning pump on for {} seconds...".format(pump_time))
        start_pump = time.monotonic()
        while True:
            gfx.show_gcp_status('Watering plant...')
            cur_time = time.monotonic()
            if cur_time - start_pump > pump_time:
                # Timer expired, leave the loop
                print("Plant watered!")
                break
            water_pump.value = True
    gfx.show_gcp_status('Plant watered!')
    print("Turning pump off")
    water_pump.value = False

This guide was first published on Aug 28, 2019. It was last updated on Aug 28, 2019.