SparkFun gator:soil Hookup Guide

Introduction

Do you have a science experiment involving plant growth?

SparkFun gator:soil - micro:bit Accessory Board

SEN-15272

The gator:soil is the perfect tool to monitor the moisture content of the soil of your test subjects. This tutorial will show you how to get started using this soil moisture sensor with the gator:bit (v2) in the micro:bit development environment.

Required Materials

To get started, you'll need a micro:bit to control everything. Each of the products below includes a micro:bit, but the kit and bundle also include some additional accessories that you may want as well.

micro:bit Board

DEV-14208

10 Retired

Favorited Favorite 44

micro:bit Go Bundle

DEV-14336

18 Retired

Favorited Favorite 28

SparkFun Inventor's Kit for micro:bit

KIT-15228

2 Retired

Favorited Favorite 15

To easily use the gator board ecosystem, a gator:bit (v2) will help breakout the necessary pins and you will also need alligator and/or banana cables to connect the gator:bit to the gator:soil.

Alligator Test Leads - Multicolored (10 Pack)

PRT-12978

$3.50

4

Favorited Favorite 59

Banana to Banana Cable - Right Angle

CAB-15368

$4.95 $4.46

1

Favorited Favorite 5

SparkFun gator:bit v2.0 - micro:bit Carrier Board

DEV-15162

2 Retired

Favorited Favorite 11

(*These banana cables have a special diameter on the attachment points designed specifically for use with the micro:bit ecosystem. They may or may not be compatible with the banana cables used on your test equipment.)

You may already have some of these materials, so feel free to modify your cart as necessary.

Voltage, Current, Resistance, and Ohm's Law

Learn about Ohm's Law, one of the most fundamental equations in all electrical engineering.

Favorited Favorite 144

Analog to Digital Conversion

The world is analog. Use analog to digital conversion to help digital devices interpret the world.

Favorited Favorite 63

Soil Moisture Sensor Hookup Guide

A quick hookup guide and project to get you started with the Soil Moisture Sensor from SparkFun.

Favorited Favorite 35

micro:climate Kit Experiment Guide

A weather station kit that is built on top of the inexpensive, easy-to-use micro:bit and Microsoft MakeCode.

Favorited Favorite 11

If you aren't familiar with the micro:bit, we recommend reading here for an overview.

micro:bit Ecosystem

We would also recommend taking a look at the following tutorials if you aren't familiar with them.

Getting Started with the micro:bit

The BBC micro:bit is a compact, powerful programming tool that requires no software installation. Read on to learn how to use it YOUR way!

Favorited Favorite 15

Getting Started with MicroPython and the SparkFun Inventor's Kit for micro:bit

Learn MicroPython with the micro:bit.

Favorited Favorite 5

How to Load MicroPython on a Microcontroller Board

This tutorial will show you how to load the MicroPython interpreter onto a variety of development boards.

Favorited Favorite 7

SparkFun gator:bit v2 Hookup Guide

The gator:bit v2 is a breakout board for the BBC micro:bit. The gator:bit exposes almost every pin on the micro:bit to clippable pad with circuit protection. It also has as built-in addressable LEDs and a built-in buzzer.

Favorited Favorite 1

Hardware Overview

The gator:soil consists of two probes and three pads (PWR, GND, and SIG).

Note: For more in-depth information on the circuitry, check out the blog post for the circuit that this sensor is based off.

Contacts	Description
PWR	INPUT: Power to the sensor (3.3V - 5V).
SIG	OUTPUT: Analog voltage representing the conductivity between the probes.
GND	REFERENCE: Ground reference (0V).
Probes	Used to sample soil moisture content for sensor.

Power

We recommend powering the gator:soil with between 3.3V - 5V. Please note that the analog value returned will vary depending on what voltage is provided for the sensor.

Power connection pads.

For use with the gator:bit (v2) and micro:bit, you should provide 3.3V through the PWR and GND pads. We recommend not powering the sensor constantly to reduce corrosion of the probes; this can be controlled through one of the digital pins of the gator:bit (v2).

Caution: One commonly known issue with soil moisture senors is their short lifespan due to corrosion of the electrodes from electrolysis. To combat this, we've had the PCB coated in Gold Finishing (Electroless Nickel Immersion Gold), which has a high decomposition potential. However, the life span of the sensor is limited. Applying a higher input voltage, taking frequent readings, and/or leaving the sensor on for extended periods of time will decrease the lifespan. For example, a simple way to extend the lifespan of your sensor is to only power it when you take a reading.

Output Signal

The two probes are used to measure the conductivity of the soil. SIG provides an analog voltage out that can be attached to an ADC pad on the gator:bit (v2).

Analog signal connection pad.

The value read on SIG is dependent several variables such as soil composition, contact on the probes, soil compaction, amongst other factors. For example, if you have a high alkaline content in your soil, it will be more conducive and give you a high baseline reading. In most cases, you will probably need to calibrate your sensor reading for each soil sample and sensor. Once calibrated, for a fixed sensor, the primary variables to the measure conductivity in the soil will be the power input and moisture content of the soil.

Hardware Assembly

Note: Unfortunately, the design of this sensor isn't intended for long term exposure to outdoor environments. It is primarily intended for the classroom setting. This is due to the limitations in waterproofing the sensor and its connections.

Connecting your gator:soil to the gator:bit (v2) is simple. Connect GND to GND, SIG to an analog pin (P0-P2)¹, and PWR to either 3.3V OUT or to a digital pin that is not in use (P0-P2, P8, P16, or P5). This can easily be done with alligator cables or these special banana cables.

Example of connections used in example. Click to enlarge.

Example of gator:soil in use application. Click to enlarge.

gator:soil	gator:bit (v2)
PWR	3.3V OUT or Digital Pin: P0 - P2, P8, P16, or P5
SIG	Analog Pin: P0 - P2
GND	GND

Note: If accessible, pins P3, P4, and P10 can be used in addition for ADC measurements.↩

Adding the MakeCode Extension

Note: This tutorial assumes you are familiar with MakeCode, the gato:bit (v2), and the micro:bit board.

If you have not previously used MakeCode, please check out the Quick Start Guide fro micro:bit.
If this is your first time using a micro:bit, please review our Getting Started with the micro:bit guide.
If this is your first time using the gato:bit (v2), please review our SparkFun gator:bit v2 Hookup Guide.

The easiest way to get started using the gator:soil is to use Microsoft MakeCode, a web-based block editor. This tutorial assumes you are familiar with the with MakeCode, the gato:bit (v2), and the micro:bit development board. If this is your first time check out this guides linked in the suggested reading section (above).

Installing Extensions

To get started with using MakeCode with the miccro:bit, head over to the MakeCode for micro:bit website by Microsoft. Then, click the New Project button to start a new project and open the Editor. (*Yes, all you only need to get start coding is a computer with internet access, an up-to-date web browser, and an available USB port!)

Click the New Project button to start a new project and open the Editor. Click on image to enlarge.

Once you have the editor up, click on the the Advanced block in the block library to reveal the drop down menu.

Click on the the Advanced block in the block library to reveal the drop down menu. Click on image to enlarge.

Finally, click on the Extensions block. This should bring up the extensions page. (*Alternatively, you could also click on the extensions link from the settings menu.)

Click on the the Extensions block to open the extensions page. Click on image to enlarge.

There are two methods for finding the gator:soil extension:

Search for the name used on the extension².
Use the link to the GitHub repository for the pxt-package as the search term.

Use the search bar to find the extension you want to install. Click on image to enlarge.

Note: Unfortunately, it does take time to get an extension approved by the micro:bit Educational Foundation before it can be searchable by name. Part of the requirements for the approval process involves a live product page. Therefore, at the time of the launch of this product, the extension has not been approved yet and the only method of adding the extension is to use the link to the GitHub repository of the pxt-package. We will update this tutorial as soon as the extension has been approved.↩

Search for the PXT-Package

Search for the gator:soil extension using the GitHub repository link to the pxt-package:

https://github.com/sparkfun/pxt-gator-soil

Search for Extension. Then, click on the box to add it to the block library. Click on image to enlarge.

Then, click on the box for the extension to add it to the block library. The gator:soil extension should now appear in the block library.

Extension in the block library; click on the block to open menu options. Click on image to enlarge.

To verify that you have added the extension, click on the gator:soil block to make sure that your drop down menu options match the image below.

Available blocks for the gator:soil extension. Click on image to enlarge.

MakeCode Example

Now that you have added the gator:soil extension to the Editor, lets start with some example code. Plug the micro:bit into your computer using an USB micro-B cable after you have assembled your hardware with the instructions from the previous section. The micro:bit should appear on your computer as a removable storage device.

The micro:bit showing up as a USB drive on a Windows computer. Click to enlarge.

To upload new code, this is where you will be copying the downloaded .hex file to later.

Block Function

Get moisture on pin _____ in _____ using power pin _____
This is a value block as indicated by the block's shape. There are three drop down menus with selectable options for how the sensor is wired and the output value of the block. Below is a description of the available menu options (from left to right):

ADC or SIG Read Pin- This pin is used to read the SIG output of the sensor. The pin options are as follows:
- P0 to P20
  - P5 to P9 & P11 to P20: Digital pins that can't be used as indicated with (write only).
  - Pins P0 to P4 and P10: Analog pins that can be used, but the only pins that are available on the gator:bit (v2) are P0, P1, and P2.
Measurement Value
This designates the output value that is read. There are two options:
- moisture- A value ranging between 0 and 1.
- adcvalue- A 10-bit integer value from micro:bit ADC ranging between 0 and 1023.
Power Control Pin
This pin is used to control when the sensor input power (PWR). The pin options are as follows:
- P0 to P20
  - Only pins P0 - P2, P5, P8, P11, P13 - P16, and P19 - P20 are available on the gator:bit (v2).

Note: Each measurement is taken with the shortest instance possible so that the power pin doesn't need to be toggled on and off. However, control logic or time delays should be added to reduce the frequency of these measurements. Without such controls, the sensor will be constantly polled in the forever loop, reducing the life span of the probes.

System Calibration

To get any sort of useful data out of your Soil Moisture Sensor, it is advised that you calibrate it to whatever soil you plan to monitor. Different types of soil can affect the sensor, and you may get different readings from one composition to the next. Before you start storing moisture data or triggering events based on that value, you should see what values you are actually getting from your sensor.

Once you have an idea what values your sensor is outputting in completely dry and completely wet situations, it's time to calibrate your sensor for the specific soil you want to monitor. Test your soil when it is as dry as possible, then measure it when the soil is completely saturated with moisture. Getting these values and comparing them to the ones from the previous calibration will give you the best insight into what values mean for your specific plant and soil. This test may take some trial and error and patience. Be careful not to splash water onto the sensor or over-water/under-water your plants during these tests.

Once you have a good handle on the values you can expect, you can map function under the Pins library block to adjust your results.

Basic Read

Below, is a simple example of how to take simple measurements from the sensor. The example uses a extremely short 10 second delay between measurements, primarily for demonstration purposes. To use this example, there are multiple options for accessing the .hex file:

Replicate the block functions from the display below to copy the example project. Then download the .hex file.
Expand the display widow to pull up the example project. Then download the .hex file.
Use this link to pull up the example project. Then download the .hex file.
Download the .hex file from the button below or the link on the bottom of the display.

Download .hex File for Example

The output is redirected over the serial port to avoid conflicts on pins P0 and P1, which are also used for serial communication. To read the sensor values, pull up your favorite serial terminal emulator. Then, connect to the serial port that the micro:bit is on; the default baud rate is 115200 bps. Below, is an example of the sensor output for the example code.

Example of readings from the sensor.

Note: In application, to maximize the life of the sensor with daily monitoring, measurements should be limited to less than 3 measurements a day.

Troubleshooting the Extension

Extension not working?

This product's extension has a dependency on Microsoft's build process. If the usual method of installing the MakeCode extension gives an error, you will need to manually install the MakeCode extension. We have provided a local build of this extension that can be uploaded to MakeCode:

gator:soil extension

To manually install this extension in makecode, go to the "Extensions" tab on the left side of the makecode site:

In the location you'd normally search for an extension, you'll notice an upload button on the right:

Click on this, and you'll get a window allowing you to upload your own built extension. Navigate to where you saved the above extension hex, and upload it to your project.

You should be able to see the extension and its functions now. In addition, you'll be able to build and download your project to your variant of micro:bit.

Other Troubleshooting Tips

Here are a few tips for troubleshooting this device.

Sensor Corrosion

A commonly known issue with soil moisture senors is their short lifespan due to corrosion of the electrodes from electrolysis. To combat this, we've had the PCB coated in Gold Finishing (Electroless Nickel Immersion Gold), which has a high decomposition potential. However, the life span of the sensor is limited. Applying a higher input voltage, taking frequent readings, and/or leaving the sensor on for extended periods of time will decrease the lifespan.

A simple way to extend the lifespan of your sensor is to only power it for the short period of a reading.

Waterproofing

A commonly known issue with soil moisture senor is that it may be exposed to water when you water your plants. Unfortunately, water and electronics do not mix. To prevent shorting out your board and sensor, you should always disconnect your cables when watering your plant. (*You can remove the sensor, but then you will need to recalibrate the sensor every time and this will affect the consistency of your readings.)

Calibration

To get any sort of useful data out of your sensor, it is advised that you calibrate it to whatever soil you plan to monitor. Different types of soil have various affects on the sensor; you may get different readings from one soil sample to the next. Before you start storing moisture data or triggering events based on that value, you should see what values you are actually getting from your sensor.