Update README.md and add examples reference

sparkfun · Jan 22, 2025 · f78dbbd · f78dbbd
1 parent 5b57ceb
commit f78dbbd
Show file tree

Hide file tree

Showing 3 changed files with 99 additions and 59 deletions.
diff --git 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" )
 
-<p align="center">
-   <img src="https://cdn.sparkfun.com/assets/custom_pages/2/7/2/qwiic-logo-registered.jpg"  width=200>  
-   <img src="https://www.python.org/static/community_logos/python-logo-master-v3-TM.png"  width=240>   
-</p>
-<p align="center">
-	<a href="https://pypi.org/project/sparkfun-qwiic-soil-moisture-sensor/" alt="Package">
-		<img src="https://img.shields.io/pypi/pyversions/sparkfun-qwiic_soil_moisture_sensor.svg" /></a>
-	<a href="https://github.com/sparkfun/Qwiic_Soil_Moisture_Sensor_Py/issues" alt="Issues">
-		<img src="https://img.shields.io/github/issues/sparkfun/Qwiic_Soil_Moisture_Sensor_Py.svg" /></a>
-	<a href="https://qwiic-soil-moisture-sensor-py.readthedocs.io/en/latest/?" alt="Documentation">
-		<img src="https://readthedocs.org/projects/qwiic-soil-moisture-sensor-py/badge/?version=latest&style=flat" /></a>
-	<a href="https://github.com/sparkfun/Qwiic_Soil_Moisture_Sensor_Py/blob/master/LICENSE" alt="License">
-		<img src="https://img.shields.io/badge/license-MIT-blue.svg" /></a>
-	<a href="https://twitter.com/intent/follow?screen_name=sparkfun">
-        	<img src="https://img.shields.io/twitter/follow/sparkfun.svg?style=social&logo=twitter"
-           	 alt="follow on Twitter"></a>
+# SparkFun Qwiic Soil Moisture Sensor - Python Package
 
-</p>
+![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)
 
-<img src="https://cdn.sparkfun.com/assets/parts/1/6/8/4/8/17731-SparkFun_Qwiic_Soil_Moisture_Sensor-01.jpg"  align="right" width=300 alt="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-<version>.tar.gz
+pip install sparkfun_qwiic_soil_moisture_sensor-<version>.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)		
 ```
 <p align="center">
 <img src="https://cdn.sparkfun.com/assets/custom_pages/3/3/4/dark-logo-red-flame.png" alt="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
diff --git a/examples/README.md 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)