# Tutorial: Monitoring soil moisture with AWS IoT and Raspberry Pi This tutorial shows you how to use a [Raspberry Pi](https://www.raspberrypi.org/), a moisture sensor, and AWS IoT to monitor the soil moisture level for a house plant or garden. The Raspberry Pi runs code that reads the moisture level and temperature from the sensor and then sends the data to AWS IoT. You create a rule in AWS IoT that sends an email to an address subscribed to an Amazon SNS topic when the moisture level falls below a threshold. **Note** This tutorial might not be up to date. Some references might have been superseded since this topic was originally published. **Contents** + [Prerequisites](#iot-moisture-prereqs) + [Setting up AWS IoT](iot-moisture-setup.md) + [Step 1: Create the AWS IoT policy](iot-moisture-policy.md) + [Step 2: Create the AWS IoT thing, certificate, and private key](iot-moisture-create-thing.md) + [Step 3: Create an Amazon SNS topic and subscription](iot-moisture-create-sns-topic.md) + [Step 4: Create an AWS IoT rule to send an email](iot-moisture-create-rule.md) + [Setting up your Raspberry Pi and moisture sensor](iot-moisture-raspi-setup.md) ## Prerequisites To complete this tutorial, you need: + An AWS account. + An IAM user with administrator permissions. + A development computer running Windows, macOS, Linux, or Unix to access the [AWS IoT console](https://console.aws.amazon.com/iot/home). + A [Raspberry Pi 3B or 4B](https://www.raspberrypi.com/products/) running the latest [Raspberry Pi OS](https://www.raspberrypi.com/software/operating-systems/). For installation instructions, see [Install an operating system](https://www.raspberrypi.com/documentation/computers/getting-started.html#installing-the-operating-system) on the Raspberry Pi website. + A monitor, keyboard, mouse, and Wi-Fi network or Ethernet connection for your Raspberry Pi. + A Raspberry Pi-compatible moisture sensor. The sensor used in this tutorial is an [Adafruit STEMMA I2C Capacitive Moisture Sensor](https://www.adafruit.com/product/4026) with a [JST 4-pin to female socket cable header](https://www.adafruit.com/product/3950). # Setting up AWS IoT To complete this tutorial, you need to create the following resources. To connect a device to AWS IoT, you create an IoT thing, a device certificate, and an AWS IoT policy. + An AWS IoT thing. A thing represents a physical device (in this case, your Rasberry Pi) and contains static metadata about the device. + A device certificate. All devices must have a device certificate to connect to and authenticate with AWS IoT. + An AWS IoT policy. Each device certificate has one or more AWS IoT policies associated with it. These policies determine which AWS IoT resources the device can access. + An AWS IoT root CA certificate. Devices and other clients use an AWS IoT root CA certificate to authenticate the AWS IoT server with which they are communicating. For more information, see [Server authentication](server-authentication.md). + An AWS IoT rule. A rule contains a query and one or more rule actions. The query extracts data from device messages to determine if the message data should be processed. The rule action specifies what to do if the data matches the query. + An Amazon SNS topic and topic subscription. The rule listens for moisture data from your Raspberry Pi. If the value is below a threshold, it sends a message to the Amazon SNS topic. Amazon SNS sends that message to all email addresses subscribed to the topic. # Step 1: Create the AWS IoT policy Create an AWS IoT policy that allows your Raspberry Pi to connect and send messages to AWS IoT. 1. In the [AWS IoT console](https://console.aws.amazon.com/iot), if a **Get started** button appears, choose it. Otherwise, in the navigation pane, expand ** Security**, and then choose **Policies**. 1. If a **You don't have any policies yet** dialog box appears, choose **Create a policy**. Otherwise, choose **Create**. 1. Enter a name for the AWS IoT policy (for example, **MoistureSensorPolicy**). 1. In the **Add statements** section, replace the existing policy with the following JSON. Replace *region* and *account* with your AWS Region and AWS account number. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:us-east-1:123456789012:client/RaspberryPi" }, { "Effect": "Allow", "Action": "iot:Publish", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/update", "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/delete", "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/get" ] }, { "Effect": "Allow", "Action": "iot:Receive", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/update/accepted", "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/delete/accepted", "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/get/accepted", "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/update/rejected", "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/delete/rejected" ] }, { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/RaspberryPi/shadow/update/accepted", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/RaspberryPi/shadow/delete/accepted", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/RaspberryPi/shadow/get/accepted", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/RaspberryPi/shadow/update/rejected", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/RaspberryPi/shadow/delete/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:GetThingShadow", "iot:UpdateThingShadow", "iot:DeleteThingShadow" ], "Resource": "arn:aws:iot:us-east-1:123456789012:thing/RaspberryPi" } ] } ``` 1. Choose **Create**. # Step 2: Create the AWS IoT thing, certificate, and private key Create a thing in the AWS IoT registry to represent your Raspberry Pi. 1. In the [AWS IoT console](https://console.aws.amazon.com/iot/home), in the navigation pane, choose **Manage**, and then choose **Things**. 1. If a **You don't have any things yet** dialog box is displayed, choose **Register a thing**. Otherwise, choose **Create**. 1. On the **Creating AWS IoT things** page, choose **Create a single thing**. 1. On the **Add your device to the device registry** page, enter a name for your IoT thing (for example, **RaspberryPi**), and then choose **Next**. You can't change the name of a thing after you create it. To change a thing's name, you must create a new thing, give it the new name, and then delete the old thing. 1. On the **Add a certificate for your thing** page, choose **Create certificate**. 1. Choose the **Download** links to download the certificate, private key, and root CA certificate. **Important** This is the only time you can download your certificate and private key. 1. To activate the certificate, choose **Activate**. The certificate must be active for a device to connect to AWS IoT. 1. Choose **Attach a policy**. 1. For **Add a policy for your thing**, choose **MoistureSensorPolicy**, and then choose **Register Thing**. # Step 3: Create an Amazon SNS topic and subscription Create an Amazon SNS topic and subscription. 1. From the [AWS SNS console](https://console.aws.amazon.com/sns/home), in the navigation pane, choose **Topics**, and then choose **Create topic**. 1. Choose type as **Standard** and enter a name for the topic (for example, **MoistureSensorTopic**). 1. Enter a display name for the topic (for example, **Moisture Sensor Topic**). This is the name displayed for your topic in the Amazon SNS console. 1. Choose **Create topic**. 1. In the Amazon SNS topic detail page, choose **Create subscription**. 1. For **Protocol**, choose **Email**. 1. For **Endpoint**, enter your email address. 1. Choose **Create subscription**. 1. Open your email client and look for a message with the subject **MoistureSensorTopic**. Open the email and click the **Confirm subscription** link. **Important** You won't receive any email alerts from this Amazon SNS topic until you confirm the subscription. You should receive an email message with the text you typed. # Step 4: Create an AWS IoT rule to send an email An AWS IoT rule defines a query and one or more actions to take when a message is received from a device. The AWS IoT rules engine listens for messages sent by devices and uses the data in the messages to determine if some action should be taken. For more information, see [Rules for AWS IoT](iot-rules.md). In this tutorial, your Raspberry Pi publishes messages on `aws/things/RaspberryPi/shadow/update`. This is an internal MQTT topic used by devices and the Thing Shadow service. The Raspberry Pi publishes messages that have the following form: ``` { "reported": { "moisture" : moisture-reading, "temp" : temperature-reading } } ``` You create a query that extracts the moisture and temperature data from the incoming message. You also create an Amazon SNS action that takes the data and sends it to Amazon SNS topic subscribers if the moisture reading is below a threshold value. **Create an Amazon SNS rule** 1. In the [AWS IoT console](https://console.aws.amazon.com/iot/home), choose **Message routing** and then choose **Rules**. If a **You don't have any rules yet** dialog box appears, choose **Create a rule**. Otherwise, choose **Create rule**. 1. In the **Rule properties** page, enter a **Rule name** such as **MoistureSensorRule**, and provide a short **Rule description** such as **Sends an alert when soil moisture level readings are too low**. 1. Choose **Next** and configure your SQL statement. Choose **SQL version** as **2016-03-23**, and enter the following AWS IoT SQL query statement: ``` SELECT * FROM '$aws/things/RaspberryPi/shadow/update/accepted' WHERE state.reported.moisture < 400 ``` This statement triggers the rule action when the `moisture` reading is less than `400`. **Note** You might have to use a different value. After you have the code running on your Raspberry Pi, you can see the values that you get from your sensor by touching the sensor, placing it in water, or placing it in a planter. 1. Choose **Next** and attach rule actions. For **Action 1**, choose **Simple Notification Service**. The description for this rule action is **Send a message as an SNS push notification**. 1. For **SNS topic**, choose the topic that you created in [Step 3: Create an Amazon SNS topic and subscription](iot-moisture-create-sns-topic.md), **MoistureSensorTopic**, and leave the **Message format** as **RAW**. For **IAM role**, choose **Create a new role**. Enter a name for the role, for example, **LowMoistureTopicRole**, and then choose **Create role**. 1. Choose **Next** to review and then choose **Create** to create the rule. # Setting up your Raspberry Pi and moisture sensor Insert your microSD card into the Raspberry Pi, connect your monitor, keyboard, mouse, and, if you're not using Wi-Fi, Ethernet cable. Do not connect the power cable yet. Connect the JST jumper cable to the moisture sensor. The other side of the jumper has four wires: + Green: I2C SCL + White: I2C SDA + Red: power (3.5 V) + Black: ground Hold the Raspberry Pi with the Ethernet jack on the right. In this orientation, there are two rows of GPIO pins at the top. Connect the wires from the moisture sensor to the bottom row of pins in the following order. Starting at the left-most pin, connect red (power), white (SDA), and green (SCL). Skip one pin, and then connect the black (ground) wire. For more information, see [Python Computer Wiring](https://learn.adafruit.com/adafruit-stemma-soil-sensor-i2c-capacitive-moisture-sensor/python-circuitpython-test). Attach the power cable to the Raspberry Pi and plug the other end into a wall socket to turn it on. **Configure your Raspberry Pi** 1. On **Welcome to Raspberry Pi**, choose **Next**. 1. Choose your country, language, timezone, and keyboard layout. Choose **Next**. 1. Enter a password for your Raspberry Pi, and then choose **Next**. 1. Choose your Wi-Fi network, and then choose **Next**. If you aren't using a Wi-Fi network, choose **Skip**. 1. Choose **Next** to check for software updates. When the updates are complete, choose **Restart** to restart your Raspberry Pi. After your Raspberry Pi starts up, enable the I2C interface. 1. In the upper left corner of the Raspbian desktop, click the Raspberry icon, choose **Preferences**, and then choose **Raspberry Pi Configuration**. 1. On the **Interfaces** tab, for **I2C**, choose **Enable**. 1. Choose **OK**. The libraries for the Adafruit STEMMA moisture sensor are written for CircuitPython. To run them on a Raspberry Pi, you need to install the latest version of Python 3. 1. Run the following commands from a command prompt to update your Raspberry Pi software: `sudo apt-get update` `sudo apt-get upgrade` 1. Run the following command to update your Python 3 installation: `sudo pip3 install --upgrade setuptools` 1. Run the following command to install the Raspberry Pi GPIO libraries: `pip3 install RPI.GPIO` 1. Run the following command to install the Adafruit Blinka libraries: `pip3 install adafruit-blinka` For more information, see [Installing CircuitPython Libraries on Raspberry Pi](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/installing-circuitpython-on-raspberry-pi). 1. Run the following command to install the Adafruit Seesaw libraries: `sudo pip3 install adafruit-circuitpython-seesaw` 1. Run the following command to install the AWS IoT Device SDK for Python: `pip3 install AWSIoTPythonSDK` Your Raspberry Pi now has all of the required libraries. Create a file called **moistureSensor.py** and copy the following Python code into the file: ``` from adafruit_seesaw.seesaw import Seesaw from AWSIoTPythonSDK.MQTTLib import AWSIoTMQTTShadowClient from board import SCL, SDA import logging import time import json import argparse import busio # Shadow JSON schema: # # { # "state": { # "desired":{ # "moisture":, # "temp": # } # } # } # Function called when a shadow is updated def customShadowCallback_Update(payload, responseStatus, token): # Display status and data from update request if responseStatus == "timeout": print("Update request " + token + " time out!") if responseStatus == "accepted": payloadDict = json.loads(payload) print("~~~~~~~~~~~~~~~~~~~~~~~") print("Update request with token: " + token + " accepted!") print("moisture: " + str(payloadDict["state"]["reported"]["moisture"])) print("temperature: " + str(payloadDict["state"]["reported"]["temp"])) print("~~~~~~~~~~~~~~~~~~~~~~~\n\n") if responseStatus == "rejected": print("Update request " + token + " rejected!") # Function called when a shadow is deleted def customShadowCallback_Delete(payload, responseStatus, token): # Display status and data from delete request if responseStatus == "timeout": print("Delete request " + token + " time out!") if responseStatus == "accepted": print("~~~~~~~~~~~~~~~~~~~~~~~") print("Delete request with token: " + token + " accepted!") print("~~~~~~~~~~~~~~~~~~~~~~~\n\n") if responseStatus == "rejected": print("Delete request " + token + " rejected!") # Read in command-line parameters def parseArgs(): parser = argparse.ArgumentParser() parser.add_argument("-e", "--endpoint", action="store", required=True, dest="host", help="Your device data endpoint") parser.add_argument("-r", "--rootCA", action="store", required=True, dest="rootCAPath", help="Root CA file path") parser.add_argument("-c", "--cert", action="store", dest="certificatePath", help="Certificate file path") parser.add_argument("-k", "--key", action="store", dest="privateKeyPath", help="Private key file path") parser.add_argument("-p", "--port", action="store", dest="port", type=int, help="Port number override") parser.add_argument("-n", "--thingName", action="store", dest="thingName", default="Bot", help="Targeted thing name") parser.add_argument("-id", "--clientId", action="store", dest="clientId", default="basicShadowUpdater", help="Targeted client id") args = parser.parse_args() return args # Configure logging # AWSIoTMQTTShadowClient writes data to the log def configureLogging(): logger = logging.getLogger("AWSIoTPythonSDK.core") logger.setLevel(logging.DEBUG) streamHandler = logging.StreamHandler() formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s') streamHandler.setFormatter(formatter) logger.addHandler(streamHandler) # Parse command line arguments args = parseArgs() if not args.certificatePath or not args.privateKeyPath: parser.error("Missing credentials for authentication.") exit(2) # If no --port argument is passed, default to 8883 if not args.port: args.port = 8883 # Init AWSIoTMQTTShadowClient myAWSIoTMQTTShadowClient = None myAWSIoTMQTTShadowClient = AWSIoTMQTTShadowClient(args.clientId) myAWSIoTMQTTShadowClient.configureEndpoint(args.host, args.port) myAWSIoTMQTTShadowClient.configureCredentials(args.rootCAPath, args.privateKeyPath, args.certificatePath) # AWSIoTMQTTShadowClient connection configuration myAWSIoTMQTTShadowClient.configureAutoReconnectBackoffTime(1, 32, 20) myAWSIoTMQTTShadowClient.configureConnectDisconnectTimeout(10) # 10 sec myAWSIoTMQTTShadowClient.configureMQTTOperationTimeout(5) # 5 sec # Initialize Raspberry Pi's I2C interface i2c_bus = busio.I2C(SCL, SDA) # Intialize SeeSaw, Adafruit's Circuit Python library ss = Seesaw(i2c_bus, addr=0x36) # Connect to AWS IoT myAWSIoTMQTTShadowClient.connect() # Create a device shadow handler, use this to update and delete shadow document deviceShadowHandler = myAWSIoTMQTTShadowClient.createShadowHandlerWithName(args.thingName, True) # Delete current shadow JSON doc deviceShadowHandler.shadowDelete(customShadowCallback_Delete, 5) # Read data from moisture sensor and update shadow while True: # read moisture level through capacitive touch pad moistureLevel = ss.moisture_read() # read temperature from the temperature sensor temp = ss.get_temp() # Display moisture and temp readings print("Moisture Level: {}".format(moistureLevel)) print("Temperature: {}".format(temp)) # Create message payload payload = {"state":{"reported":{"moisture":str(moistureLevel),"temp":str(temp)}}} # Update shadow deviceShadowHandler.shadowUpdate(json.dumps(payload), customShadowCallback_Update, 5) time.sleep(1) ``` Save the file to a place you can find it. Run `moistureSensor.py` from the command line with the following parameters: endpoint Your custom AWS IoT endpoint. For more information, see [Device Shadow REST API](device-shadow-rest-api.md). rootCA The full path to your AWS IoT root CA certificate. cert The full path to your AWS IoT device certificate. key The full path to your AWS IoT device certificate private key. thingName Your thing name (in this case, `RaspberryPi`). clientId The MQTT client ID. Use `RaspberryPi`. The command line should look like this: `python3 moistureSensor.py --endpoint your-endpoint --rootCA ~/certs/AmazonRootCA1.pem --cert ~/certs/raspberrypi-certificate.pem.crt --key ~/certs/raspberrypi-private.pem.key --thingName RaspberryPi --clientId RaspberryPi` Try touching the sensor, putting it in a planter, or putting it in a glass of water to see how the sensor responds to various levels of moisture. If needed, you can change the threshold value in the `MoistureSensorRule`. When the moisture sensor reading goes below the value specified in your rule's SQL query statement, AWS IoT publishes a message to the Amazon SNS topic. You should receive an email message that contains the moisture and temperature data. After you have verified receipt of email messages from Amazon SNS, press **CTRL\$1C** to stop the Python program. It is unlikely that the Python program will send enough messages to incur charges, but it is a best practice to stop the program when you are done.