diff --git a/README.md b/README.md index b9fa4dd..23b0b5d 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,77 @@ -Qwiic_Soil_Moisture_Sensor_Py -=============== +![Qwiic Soil Moisture Sensor Python Package](docs/images/soil_moisture_sensor-gh-banner-py.png "qwiic Soil Moisture Sensor Python Package" ) -

- - -

-

- - - - - - - - - - follow on Twitter +# SparkFun Qwiic Soil Moisture Sensor - Python Package -

+![PyPi Version](https://img.shields.io/pypi/v/sparkfun_qwiic_soil_moisture_sensor) +![GitHub issues](https://img.shields.io/github/issues/sparkfun/qwiic_soil_moisture_sensor_py) +![License](https://img.shields.io/github/license/sparkfun/qwiic_soil_moisture_sensor_py) +![X](https://img.shields.io/twitter/follow/sparkfun) +[![API](https://img.shields.io/badge/API%20Reference-blue)](https://docs.sparkfun.com/qwiic_soil_moisture_sensor_py/classqwiic__soil__moisture__sensor_1_1_qwiic_soil_moisture_sensor.html) -SparkFun Qwiic Soil Moisture Sensor +The SparkFun Qwiic Soil Moisture Sensor provides a simple and cost effective solution for adding soil moisture sensing to your project. Implementing a SparkFun Qwiic I2C interface, these sensors can be rapidly added to any project with boards that are part of the SparkFun Qwiic ecosystem. +This repository implements a Python package for the SparkFun Qwiic Soil Moisture Sensor. This package works with Python, MicroPython and CircuitPython. -Python module for the [SparkFun Qwiic Soil Moisture Sensor](https://www.sparkfun.com/products/17731) +### Contents -This python package is a port of the existing [SparkFun Soil Moisture Sensor Arduino Examples](https://github.com/sparkfun/Zio-Qwiic-Soil-Moisture-Sensor/tree/master/Firmware/Qwiic%20Soil%20Moisture%20Sensor%20Examples) +* [About](#about-the-package) +* [Getting Started](#getting-started) +* [Installation](#installation) +* [Supported Platforms](#supported-platforms) +* [Documentation](https://docs.sparkfun.com/qwiic_soil_moisture_sensor_py/classqwiic__soil__moisture__sensor_1_1_qwiic_soil_moisture_sensor.html) +* [Examples](#examples) -This package can be used in conjunction with the overall [SparkFun qwiic Python Package](https://github.com/sparkfun/Qwiic_Py) +## About the Package + +This python package enables the user to access the features of the Qwiic Soil Moisture Sensor via a single Qwiic cable. This includes reading the moisture level, turning on and off the LED, and more. The capabilities of the moisture sensor are each demonstrated in the included examples. New to qwiic? Take a look at the entire [SparkFun qwiic ecosystem](https://www.sparkfun.com/qwiic). -## Contents +### Supported SparkFun Products -* [Supported Platforms](#supported-platforms) -* [Dependencies](#dependencies) -* [Installation](#installation) -* [Documentation](#documentation) -* [Example Use](#example-use) +This Python package supports the following SparkFun qwiic products on Python, MicroPython and Circuit python. + +* [SparkFun Qwiic Soil Moisture Sensor](https://www.sparkfun.com/sparkfun-qwiic-soil-moisture-sensor.html) + +### Supported Platforms + +| Python | Platform | Boards | +|--|--|--| +| Python | Linux | [Raspberry Pi](https://www.sparkfun.com/raspberry-pi-5-8gb.html) , [NVIDIA Jetson Orin Nano](https://www.sparkfun.com/nvidia-jetson-orin-nano-developer-kit.html) via the [SparkFun Qwiic SHIM](https://www.sparkfun.com/sparkfun-qwiic-shim-for-raspberry-pi.html) | +| MicroPython | Raspberry Pi - RP2, ESP32 | [SparkFun RP2040 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-rp2040.html), [SparkFun RP2350 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-rp2350.html), [SparkFun ESP32 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-esp32-wroom-usb-c.html) +|CircuitPython | Raspberry Pi - RP2, ESP32 | [SparkFun RP2040 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-rp2040.html), [SparkFun RP2350 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-rp2350.html), [SparkFun ESP32 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-esp32-wroom-usb-c.html) -Supported Platforms --------------------- -The qwiic Soil Moisture Sensor Python package current supports the following platforms: -* [Raspberry Pi](https://www.sparkfun.com/search/results?term=raspberry+pi) -* [NVidia Jetson Nano](https://www.sparkfun.com/products/15297) -* [Google Coral Development Board](https://www.sparkfun.com/products/15318) +> [!NOTE] +> The listed supported platforms and boards are the primary platform targets tested. It is fully expected that this package will work across a wide variety of Python enabled systems. -Dependencies --------------- -This driver package depends on the qwiic I2C driver: -[Qwiic_I2C_Py](https://github.com/sparkfun/Qwiic_I2C_Py) +## Installation -Documentation -------------- -The SparkFun qwiic Soil Moisture Sensor module documentation is hosted at [ReadTheDocs](https://qwiic-soil-moisture-sensor-py.readthedocs.io/en/latest/?) +The first step to using this package is installing it on your system. The install method depends on the python platform. The following sections outline installation on Python, MicroPython and CircuitPython. -Installation ---------------- -### PyPi Installation +### Python -This repository is hosted on PyPi as the [sparkfun-qwiic-soil-moisture-sensor](https://pypi.org/project/sparkfun-qwiic-soil-moisture-sensor/) package. On systems that support PyPi installation via pip, this library is installed using the following commands +The package is primarily installed using the `pip` command, downloading the package from the Python Index - "PyPi". Note - the below instructions outline installation an Linux-based (Raspberry Pi) system. + +#### PyPi Installation + +The SparkFun Qwiic Soil Moisture Sensor Python package is part of the overall SparkFun Qwiic Python package which is hosted on PyPi. On systems that support PyPi installation via pip, this library is installed using the following commands For all users (note: the user must have sudo privileges): ```sh -sudo pip install sparkfun-qwiic-soil-moisture-sensor +sudo pip install sparkfun-qwiic ``` For the current user: ```sh -pip install sparkfun-qwiic-soil-moisture-sensor +pip install sparkfun-qwiic ``` +--- +--- +> [!CAUTION] +> **TODO** Put together how this works with the new virtual environments used with the latest Python install +--- +--- +#### Local Installation To install, make sure the setuptools package is installed on the system. Direct installation at the command line: @@ -84,24 +86,47 @@ python setup.py sdist A package file is built and placed in a subdirectory called dist. This package file can be installed using pip. ```sh cd dist -pip install sparkfun-qwiic-soil-moisture-sensor-.tar.gz +pip install sparkfun_qwiic_soil_moisture_sensor-.tar.gz +``` + +### MicroPython Installation +If not already installed, follow the [instructions here](https://docs.micropython.org/en/latest/reference/mpremote.html) to install mpremote on your computer. + +Connect a device with MicroPython installed to your computer and then install the package directly to your device with mpremote mip. +```sh +mpremote mip install github:sparkfun/qwiic_soil_moisture_sensor_py +``` + +### CircuitPython Installation +If not already installed, follow the [instructions here](https://docs.circuitpython.org/projects/circup/en/latest/#installation) to install CircUp on your computer. + +Ensure that you have the latest version of the SparkFun Qwiic CircuitPython bundle. +```sh +circup bundle-add sparkfun/Qwiic_Py +``` + +Finally, connect a device with CircuitPython installed to your computer and then install the package directly to your device with circup. +```sh +circup install --py qwiic_soil_moisture_sensor ``` Example Use - ------------- -See the examples directory for more detailed use examples. + --------------- +Below is a quickstart program to print moisture level and toggle the LED on the Soil Moisture Sensor. + +See the examples directory for more detailed use examples and [examples/README.md](https://github.com/sparkfun/qwiic_soil_moisture_sensor_py/blob/main/examples/README.md) for a summary of the available examples. ```python -from __future__ import print_function import qwiic_soil_moisture_sensor - +import time +import sys def runExample(): - print("\nSparkFun qwiic soil moisture sensor Example 1\n") + print("\nSparkFun Qwiic Soil Moisture Sensor Example 1\n") mySoilSensor = qwiic_soil_moisture_sensor.QwiicSoilMoistureSensor() - if mySoilSensor.connected == False: + if mySoilSensor.is_connected() == False: print("The Qwiic Soil Moisture Sensor device isn't connected to the system. Please check your connection", \ file=sys.stderr) return @@ -117,15 +142,13 @@ def runExample(): time.sleep(1) mySoilSensor.led_off() time.sleep(1) - + if __name__ == '__main__': try: runExample() except (KeyboardInterrupt, SystemExit) as exErr: print("\nEnding Example 1") - sys.exit(0) - - + sys.exit(0) ```

SparkFun - Start Something diff --git a/docs/images/soil_moisture_sensor-gh-banner-py.png b/docs/images/soil_moisture_sensor-gh-banner-py.png new file mode 100644 index 0000000..af7cf4e Binary files /dev/null and b/docs/images/soil_moisture_sensor-gh-banner-py.png differ diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..ff0d6bb --- /dev/null +++ b/examples/README.md @@ -0,0 +1,17 @@ +# Sparkfun Soil Moisture Sensor Examples Reference +Below is a brief summary of each of the example programs included in this repository. To report a bug in any of these examples or to request a new feature or example [submit an issue in our GitHub issues.](https://github.com/sparkfun/qwiic_bme280_py/issues). + +## Example 1: Basic Readings +This example demonstrates basic bringup of the Qwiic Soil Moisture Sensor to print moisture level and toggle the LED on and off. + +The key methods showcased by this example are: + +- [read_moisture_level()](https://docs.sparkfun.com/qwiic_soil_moisture_sensor_py/classqwiic__soil__moisture__sensor_1_1_qwiic_soil_moisture_sensor.html#a21ef69d794e2786b5eb3ef7881ba95db) +- [led_on()](https://docs.sparkfun.com/qwiic_soil_moisture_sensor_py/classqwiic__soil__moisture__sensor_1_1_qwiic_soil_moisture_sensor.html#a344fb9aa9120ca97555afc052aa94aa4) +- [led_off()](https://docs.sparkfun.com/qwiic_soil_moisture_sensor_py/classqwiic__soil__moisture__sensor_1_1_qwiic_soil_moisture_sensor.html#a9799401c60ab796e346a49718a98f601) + + +## Example 2: Change I2C Address +This example demonstrates how to change the I2C address on the Qwiic Soil Moisture Sensor. The user is prompted for a new I2C address in the legal range 0x08 to 0x3F. Then, the address of the sensor is changed to the user's selection. + +The key method showcased by this example is [change_address()](https://docs.sparkfun.com/qwiic_soil_moisture_sensor_py/classqwiic__soil__moisture__sensor_1_1_qwiic_soil_moisture_sensor.html#ad3b91fdbd9f8190798af7ee2227d4d63) \ No newline at end of file