This codelab is part of the Viam for educators program, and provides a suggested delivery plan and resources for instructors interested in delivering a hands-on workshop. Take these resources, and make it your own!

Workshop Overview

What You'll Teach

Watch the Video

See a demonstration of the plant watering automation in this video.

Review the list of required components (hardware, software), and determine which materials are provided or required for participants to bring on their own. Provide instructions to participants, giving them ample time to prepare and complete prerequisites.

Hardware and supplies requirements

Software and other device requirements

Learning Objectives

Review the suggested learning objectives, and adjust it according to your goals and audience.

Agenda

Review the suggested agenda, and adjust it according to your goals and audience.

Pre-workshop checklist ✅

Review these setup steps as you're planning the workshop to help prepare for it.

  1. Planning and Logistics
    • Verify equipment inventory: Decide which materials are provided or required for participants to bring on their own. Order any materials and supplies that are provided to participants.
    • Confirm workstation setup: Verify the workshop room layout supports hardware work, such as tables. Ensure participants have power outlets and internet access, as well as water and paper towels in case of a spill. Have spare supplies, such as Raspberry Pis, adapters/readers, and cables, in case of failures. For virtual workshops, confirm logistics for breakout sessions, providing support, and checkpoints.
    • Communicate prerequisites: Share a participant guide prior to the workshop with learning objectives and instructions for installing software and preparing laptops. Provide a checklist for participants to confirm readiness.
    • Establish support channels: Determine how participants can get support for real-time troubleshooting (e.g. Slack or Discord channel for virtual workshops, additional helpers in the room for on-site workshops)
    • Request Viam stickers: Don't forget to request Viam stickers for the workshop.
  2. Content Preparation
    • Prepare workshop teaching materials: Review the Delivery Plan, sample slide deck, and provided resources. Tailor these materials to suit your participants' needs. Decide whether to present them to the group or provide them for independent reference, such as through a web browser or printed handouts.
    • Determine extensibility: During the Hands-on Experiment portion of the delivery plan, there are many options to guide the workshop on a different learning path. Determine if this section will be self-guided exploration, a group exercise, or self-paced learning for participants to explore on their own after the workshop.
    • Prepare code and documentation: Review the provided code and add comments as necessary.
    • Review discussion topics: Review the suggested group discussion topics and adjust for your participants.
    • Review quiz questions: Review the suggested quiz questions and adjust for your participants. Determine if knowledge assessment will be completed throughout the workshop or afterwards.
  3. Dry Run and Testing
    • Test the workshop project: Run through the build following the prepared documentation to ensure it works as expected. Simulate common issues and prepare troubleshooting tips for these scenarios. If physical space is limited, consider sharing supplies.
    • Bring backups: In addition to the backup supplies mentioned earlier during planning.

Feel free to make a copy of this sample slide deck, customize it, and make it your own.

workshop slides

During the workshop, instructors can present this customizable slide deck (see above) tailored to your specific workshop needs. Alternatively, learners can follow step-by-step instructions and checkpoints independently by referencing the pages linked below in a web browser.

  1. Hardware Assembly
    • Set up your plant watering components
    • Set up your Raspberry Pi
  2. Software Setup
    • Configure your machine
    • Add your Raspberry Pi
  3. Hands-On Experiment
    • Test the moisture sensor
    • Test the pump
    • Program your plant watering device
    • Configure a Viam process

Set up your plant watering device

Before programming the Pi to make the plant watering robot functional, you need to physically set up the plant watering robot by wiring the different components together. You will set up the robot to receive signals from the resistive soil moisture sensor and signal to the pump when it is time to pump water from the water's container to the plant's container.

Refer back to this full wiring diagram as you complete the steps to wire your hardware.

Full Wiring Diagram

Connect your Raspberry Pi to the moisture sensor module:

For connecting the soil moisture sensor to the sensor module, + goes to +, and - to -.

Connect your Raspberry Pi to the relay module:

Last step in the wiring section is connecting the relay and Raspberry Pi to the pump. The wire connectors may be required to connect the jumper wires to the bare wires coming from the pump motor:

Submerge the pump in the cup of water, making sure the wire connectors hang outside the the cup and don't touch the water. The legs of the moisture sensor can be placed in the other cup of soil or coffee grounds.

Where is the sensor module getting its power from?

The Raspberry Pi Battery pack Electrical socket

Set up your Raspberry Pi

The Raspberry Pi boots from a microSD card. You need to install Raspberry Pi OS on a microSD card that you will use with your Pi. For more details about alternative methods of setting up your Raspberry Pi, refer to the Viam docs.

Install Raspberry Pi OS

  1. Connect the microSD card to your computer.
  2. Download the Raspberry Pi Imager and launch it. raspberry pi imager
  3. Click CHOOSE DEVICE. Select your model of Pi, which is Raspberry Pi 4.
  4. Click CHOOSE OS. Select Raspberry Pi OS (64-bit) from the menu.
  5. Click CHOOSE STORAGE. From the list of devices, select the USB flash drive you intend to use in your Raspberry Pi. raspberry pi storage
  6. Configure your Raspberry Pi for remote access. Click Next. When prompted to apply OS customization settings, select EDIT SETTINGS.
  7. Check Set hostname and enter the name you would like to access the Pi by in that field, for example, planter.
  8. Select the checkbox for Set username and password and set a username (for example, your first name) that you will use to log into the Pi. If you skip this step, the default username will be pi (not recommended for security reasons). And specify a password.
  9. Connect your Pi to Wi-Fi so that you can run viam-server wirelessly. Check Configure wireless LAN and enter your wireless network credentials. SSID (short for Service Set Identifier) is your Wi-Fi network name, and password is the network password. Change the section Wireless LAN country to where your router is currently being operated. raspberry pi hostname username and password
  10. Select the SERVICES tab, check Enable SSH, and select Use password authentication. raspberry pi enable SSH
  11. Save your updates, and confirm YES to apply OS customization settings. Confirm YES to erase data on the microSD card. You may also be prompted by your operating system to enter an administrator password. After granting permissions to the Imager, it will begin writing and then verifying the Linux installation to the microSD card.
  12. Remove the microSD card from your computer when the installation is complete.

What is the purpose of setting a custom `hostname` during the Raspberry Pi OS configuration?

To improve the speed of the Raspberry Pi. To identify and access the Pi on the network. To secure the Pi by changing the default password. To enable remote access to the Pi.

Connect with SSH

  1. Place the microSD card into your Raspberry Pi and boot the Pi by plugging it in to an outlet. A red LED will turn on to indicate that the Pi is connected to power.
  2. Once the Pi is started, connect to it with SSH. From a command line terminal window, enter the following command. The text in <> should be replaced (including the < and > symbols themselves) with the user and hostname you configured when you set up your Pi. 
    ssh <USERNAME>@<HOSTNAME>.local
  3. If you are prompted "Are you sure you want to continue connecting?", type "yes" and hit enter. Then, enter the password for your username. You should be greeted by a login message and a command prompt. raspberry pi SSH login
  4. Update your Raspberry Pi to ensure all the latest packages are installed 
    sudo apt update
sudo apt upgrade

Configure your machine

  1. In the Viam app under the LOCATIONS tab, create a machine by typing in a name and clicking Add machine. add machine
  2. Click View setup instructions. setup instructions
  3. Install viam-server on the Raspberry Pi device that you want to use to communicate with and automate your plant watering. Select the Linux / Aarch64 platform for the Raspberry Pi to control the rover, and leave your installation method as viam-agent. select platform
  4. Use the viam-agent to download and install viam-server on your Raspberry Pi. Follow the instructions to run the command provided in the setup instructions from the SSH prompt of your Raspberry Pi. installation agent The setup page will indicate when the machine is successfully connected.

Why is it important to connect your machine to the Viam app during setup?

To remotely monitor, configure, and control hardware components through the cloud. To store video data directly on the webcam. To eliminate the need for a physical Raspberry Pi. To ensure the machine only works offline.

Add your Raspberry Pi

  1. In the Viam app, find the CONFIGURE tab. It's time to configure your hardware.
  2. Click the + icon in the left-hand menu and select Component. select component
  3. Select board, and find the raspberry-pi:rpi module. This adds the module for working with the Raspberry Pi 4's GPIO pins. Leave the default name board-1 for now. add board
  4. Notice adding this module adds the board hardware component called board-1. The collapsible card on the right corresponds to the part listed in the left sidebar. added board
  5. Click Save in the top right to save and apply your configuration changes.

How does adding modules like `board-1` contribute to the overall architecture of your machine?

They abstract hardware-specific details, allowing software to interact with components through a consistent API. They provide direct power and connectivity to the components. They eliminate the need for the Raspberry Pi in the system. They store the configuration locally on the air sensor.

Test the moisture sensor

  1. In the Viam app under the CONTROL tab, you can see the hardware component called board-1. That's your Raspberry Pi that you configured on the CONFIGURE tab. control tab
  2. The module we added has a GetGPIO function to get the digital output of a pin. Enter 40 in the "Pin" field, select the "Read" mode, and click "Get" for the "State" section under "READ PIN". "Low" means there is enough moisture, "High" means the moisture level has fallen below the threshold: read GPIO

Test the pump

  1. In the Viam app under the CONTROL tab, you can see the hardware component called board-1. That's your Raspberry Pi that you configured on the CONFIGURE tab. control tab
  2. The module we added has a SetGPIO function to set the digital output of a pin. Enter 8 in the "Pin" field, select the "Write" mode, then select "High" and click "Set" for the "State" section under "WRITE PIN". "High" will turn on the pump motor, "Low" will turn it off. write GPIO

Program your plant watering device

At this point, you have configured and tested your machine and peripherals, but nothing is happening automatically. In the next section, program your plant watering device to be a little smarter. Make your machine periodically get sensor data, turn on the pump motor if the value is low, and turn off again when the value is high.

process diagram

Create an automation script

  1. To configure the machine to automatically run a command to execute a script, use a Viam process. Create a new file on your computer called process.py.On MacOS, Linux, or Windows WSL:
    touch process.py
    On Windows:
    type nul > process.py
  2. Copy and paste this sample code into the new file process.py. This code will allow your Raspberry Pi to connect to both the sensor and pump and execute our logic.
  3. Now it's time to move your control code to your Raspberry Pi device. SSH into your Raspberry Pi if you're not already SSH'd.
  4. From the SSH prompt on your Raspberry Pi, install the Python package manager.
    $ sudo apt install -y python3-pip
  5. Install the Viam Python SDK into a new directory called process.
    $ pip3 install --target=process viam-sdk
  6. Display the full path of the current directory you are working in on your Raspberry Pi with the pwd command. Make a note of this output for the next steps.
    $ pwd
  7. Find the executable path of Python3 to run process.py on your Raspberry Pi with which python3. Again, make a note of this output for the next steps.
    $ which python3
  8. Run the following command from your computer (not the SSH prompt to your Raspberry Pi) to copy the code from your computer to your Raspberry Pi. In the command, you will copy process.py over to your Raspberry Pi, with the section following the colon : indicating where your file should be copied to on the Raspberry Pi (the path of the directory you are working in on your Raspberry Pi, along with the filename).
    $ scp process.py user@host.local:/home/myboard/process/process.py

What is the primary role of the `process.py` script in the plant watering system?

To display moisture sensor readings directly on the Raspberry Pi. To define the logic for periodically checking sensor readings and toggling the pump. To update the firmware of the moisture sensor and motor pump. To configure the network settings for the Raspberry Pi.

Configure a Viam process

  1. Now let's allow viam-server to run the process as the root user on your Raspberry Pi by configuring a Viam process. In the Viam app under the CONFIGURE tab, click the + icon in the left-hand menu and select Process.
  2. Find the corresponding card to process-1. Enter the executable path of Python3 running on your Raspberry Pi that you output from a previous step. Add an argument of the process.py file to run on your Raspberry Pi. Enter the working directory where you want the process to execute. configure process
  3. Still within the process-1 card, select the advanced settings icon near the top right corner to review the configuration JSON. Create a new env property, and add your environment variables within the new property, formatted like the following with your own credentials. 
      "env": {
    "BOARD_NAME": "board-1",
    "ROBOT_API_KEY": "your-api-key",
    "ROBOT_API_KEY_ID": "your-api-key-id",
    "ROBOT_ADDRESS": "your-robot-address"
  },
    configure JSON
  4. Save your updates.
  5. You can test the code by updating the process.py file on your Raspberry Pi to swap the logic for the detect_moisture value from the pin connected to the moisture sensor. Save your code changes, and Restart the machine to see if the pump motor turns on when the plant has enough water. restart the machine

Why is the `process-1` configuration in the Viam app important for running the continuous process?

It specifies the environment variables and paths required for the Raspberry Pi to execute the process automatically. It ensures the moisture sensor is calibrated before each reading. It logs all moisture data directly to the Raspberry Pi’s storage. It enables real-time monitoring of the moisture on a connected device.

Additional resources

service icon

Common pitfalls and troubleshooting guidance

  1. Safety
    • Be careful when working with water around powered electrical components. Mixing them could result in them breaking.
  2. Security
    • Do not share your API credentials publicly. Sharing this information could compromise your system security by allowing unauthorized access to your machine, or to the computer running your machine.
  3. Flashing firmware
    • Make sure you are using a 5V 3A (25W) power supply.
    • Participants must remember the hostname and username they set while flashing their Raspberry Pi, as they will need this when they SSH into the Pi.
    • To save time, instructors can flash all the Pis ahead of time with pre-determined credentials and share the credentials with participants during the workshop. Each Pi should have a unique hostname to avoid conflicts on the shared local network, such as <student-name>-planter or <group-name>-planter if they are working in groups.
      • If you're using SD cards, verify that you have a way to write data onto them before providing them to participants.
  4. Configuring machine and peripherals
    • If any problems occur while setting up the machine and peripherals in the Viam app, check under the LOGS tab to see what might be going wrong.
    • Check that all wires are securely attached to the correct pins.
    • Click on the TEST panel on the CONFIGURE or CONTROL tab and test if you can use the board there.
    • Also refer to the overall Viam troubleshooting guide.

raspberry pi icon

Logistics for continued learning

Participants have several options for continuing their projects beyond the workshop environment:

Group discussion topics 🗣️

Review suggested topics for discussion at key points during the workshop.

Quiz questions ❓

Review the suggested quiz questions below to evaluate participants' understanding of key concepts. These questions can be used to assess knowledge either during (see multiple choice answers in the delivery plan) or after the workshop.

  1. Hardware Assembly
    • What is the purpose of setting a custom hostname during the Raspberry Pi OS configuration?
    • What hardware signals are used to indicate with the soil moisture is too low?
  2. Software Setup
    • Why is it important to connect your machine to the Viam app during setup?
    • What does it mean that viam-server enables remote access to the Raspberry Pi?
    • How does the Viam app simplify the process of testing and controlling hardware components like the board?
  3. Hands-on Experiment
    • What is the primary role of viam-server in the system architecture of your plant watering setup?
    • What is the purpose of the env field in your process configuration?

Next-level projects

Here are some ideas for expanding and enhancing the current project to create autonomous behaviors.

viam icons

Post-workshop resources for participants

community icons

Contribute your own workshop

This workshop and other educational codelabs are part of this Viam open-source project. You are invited to document your own workshop(s) to share with the Viam community. Be sure to follow these contributing guidelines, and let us know about it in the Viam Discord community!

decorative accent