Merge pull request #27 from pimoroni/patch-simplify-gpio

Simplify GPIO setup.

README.md

@@ -7,30 +7,44 @@
 
 # Installing
 
-Stable library from PyPi:
+**Note** The code in this repository supports both the Enviro+ and Enviro Mini boards. _The Enviro Mini board does not have the Gas sensor or the breakout for the PM sensor._
 
-* Just run `sudo pip install pms5003`
+![Enviro Plus pHAT](https://raw.githubusercontent.com/pimoroni/enviroplus-python/main/Enviro-Plus-pHAT.jpg)
+![Enviro Mini pHAT](https://raw.githubusercontent.com/pimoroni/enviroplus-python/main/Enviro-mini-pHAT.jpg)
 
-Latest/development library from GitHub:
+:warning: This library now supports Python 3 only, Python 2 is EOL - https://www.python.org/doc/sunset-python-2/
+
+## Install and configure dependencies from GitHub:
 
 * `git clone https://github.com/pimoroni/pms5003-python`
 * `cd pms5003-python`
-* `sudo ./install.sh`
-
-# Requirements
+* `./install.sh`
 
-The serial port on your Raspberry Pi must be enabled:
+**Note** Libraries will be installed in the "pimoroni" virtual environment, you will need to activate it to run examples:
 
 ```
-# Disable serial terminal over /dev/ttyAMA0
-sudo raspi-config nonint do_serial 1
-
-# Enable serial port
-raspi-config nonint set_config_var enable_uart 1 /boot/config.txt
+source ~/.virtualenvs/pimoroni/bin/activate
 ```
 
-And additionally be using a full UART (versus the default miniUART):
+**Note** Raspbian/Raspberry Pi OS Lite users may first need to install git: `sudo apt install git`
+
+## Or... Install from PyPi and configure manually:
+
+* `python3 -m venv --system-site-packages $HOME/.virtualenvs/pimoroni`
+* Run `python3 -m pip install pms5003`
+
+**Note** this will not perform any of the required configuration changes on your Pi, you may additionally need to:
+
+### Bookworm
+
+* Enable serial: `raspi-config nonint do_serial_hw 0`
+* Disable serial terminal: `raspi-config nonint do_serial_cons 1`
+* Add `dtoverlay=pi3-miniuart-bt` to your `/boot/config.txt`
+
+### Bullseye
 
-Add the line `dtoverlay=pi3-miniuart-bt` to your `/boot/config.txt`
+* Enable serial: `raspi-config nonint set_config_var enable_uart 1 /boot/config.txt`
+* Disable serial terminal: `sudo raspi-config nonint do_serial 1`
+* Add `dtoverlay=pi3-miniuart-bt` to your `/boot/config.txt`
 
-This will switch Bluetooth over to miniUART, see https://www.raspberrypi.org/documentation/configuration/uart.md for more details.
+In both cases the last line will switch Bluetooth over to miniUART, see https://www.raspberrypi.org/documentation/configuration/uart.md for more details.

examples/all.py

@@ -14,30 +14,46 @@
 # Configure the PMS5003 for Enviro+
 # pins and ports may vary for your hardware!
 
-# Default, try to auto-detect platform
+# Default, assume Raspberry Pi compatible, running Raspberry Pi OS Bookworm
 pms5003 = PMS5003(device="/dev/ttyAMA0", baudrate=9600)
 
 # Raspberry Pi 4 (Raspberry Pi OS)
+#
 # GPIO22 and GPIO27 are enable and reset for Raspberry Pi 4
 # use "raspi-config" to enable serial, or add
 # "dtoverlay=uart0" to /boot/config.txt
+#
 # pms5003 = PMS5003(device="/dev/ttyAMA0", baudrate=9600, pin_enable="GPIO22", pin_reset="GPIO27")
 
 # Raspberry Pi 5 (Raspberry Pi OS)
-# PIN15 and PIN13 are enable and reset for Raspberry Pi 5
+#
+# GPIO22 and GPIO27 are enable and reset for Raspberry Pi 5
+# On older versions of Bookworm these might be PIN15 and PIN13
 # use "raspi-config" to enable serial, or add
 # "dtoverlay=uart0-pi5" to /boot/firmware/config.txt
-# pms5003 = PMS5003(device="/dev/ttyAMA0", baudrate=9600, pin_enable="PIN15", pin_reset="PIN13")
+#
+# pms5003 = PMS5003(device="/dev/ttyAMA0", baudrate=9600, pin_enable="GPIO22", pin_reset="GPIO27")
 
 # ROCK 5B
+#
 # Use "armbian-config" to enable rk3568-uart2-m0
 # Disable console on ttyS2 with:
 # sudo systemctl stop serial-getty@ttyS2.service
 # sudo systemctl disable serial-getty@ttyS2.service
 # sudo systemctl mask serial-getty@ttyS2.service
 # add "console=display" to /boot/armbianEnv.txt
+#
 # pms5003 = PMS5003(device="/dev/ttyS2", baudrate=9600, pin_enable="PIN_15", pin_reset="PIN_13")
 
+# Other
+#
+# Use gpiod to request the pins you want, and pass those into PMS5003 as LineRequest, offset tuples.
+#
+# from pms5003 import OUTL, OUTH
+# from gpiod import Chip
+# lines = Chip.request_lines(consumer="PMS5003", config={22: OUTH, 27: OUTL})
+# pms5003 = PMS5003(device="/dev/ttyAMA0", baudrate=9600, pin_enable=(lines, 22), pin_reset=(lines, 27))
+
 try:
     while True:
         data = pms5003.read()

examples/specific.py

@@ -13,30 +13,47 @@
 # Configure the PMS5003 for Enviro+
 # pins and ports may vary for your hardware!
 
-# Default, try to auto-detect platform
+# Default, assume Raspberry Pi compatible, running Raspberry Pi OS Bookworm
 pms5003 = PMS5003(device="/dev/ttyAMA0", baudrate=9600)
 
 # Raspberry Pi 4 (Raspberry Pi OS)
+#
 # GPIO22 and GPIO27 are enable and reset for Raspberry Pi 4
 # use "raspi-config" to enable serial, or add
 # "dtoverlay=uart0" to /boot/config.txt
+#
 # pms5003 = PMS5003(device="/dev/ttyAMA0", baudrate=9600, pin_enable="GPIO22", pin_reset="GPIO27")
 
 # Raspberry Pi 5 (Raspberry Pi OS)
-# PIN15 and PIN13 are enable and reset for Raspberry Pi 5
+#
+# GPIO22 and GPIO27 are enable and reset for Raspberry Pi 5
+# On older versions of Bookworm these might be PIN15 and PIN13
 # use "raspi-config" to enable serial, or add
 # "dtoverlay=uart0-pi5" to /boot/firmware/config.txt
-# pms5003 = PMS5003(device="/dev/ttyAMA0", baudrate=9600, pin_enable="PIN15", pin_reset="PIN13")
+#
+# pms5003 = PMS5003(device="/dev/ttyAMA0", baudrate=9600, pin_enable="GPIO22", pin_reset="GPIO27")
 
 # ROCK 5B
+#
 # Use "armbian-config" to enable rk3568-uart2-m0
 # Disable console on ttyS2 with:
 # sudo systemctl stop serial-getty@ttyS2.service
 # sudo systemctl disable serial-getty@ttyS2.service
 # sudo systemctl mask serial-getty@ttyS2.service
 # add "console=display" to /boot/armbianEnv.txt
+#
 # pms5003 = PMS5003(device="/dev/ttyS2", baudrate=9600, pin_enable="PIN_15", pin_reset="PIN_13")
 
+# Other
+#
+# Use gpiod to request the pins you want, and pass those into PMS5003 as LineRequest, offset tuples.
+#
+# from pms5003 import OUTL, OUTH
+# from gpiod import Chip
+# lines = Chip.request_lines(consumer="PMS5003", config={22: OUTH, 27: OUTL})
+# pms5003 = PMS5003(device="/dev/ttyAMA0", baudrate=9600, pin_enable=(lines, 22), pin_reset=(lines, 27))
+
+
 try:
     while True:
         data = pms5003.read()

pms5003/__init__.py

@@ -13,12 +13,6 @@
 
 OUTL = gpiod.LineSettings(direction=Direction.OUTPUT, output_value=Value.INACTIVE)
 OUTH = gpiod.LineSettings(direction=Direction.OUTPUT, output_value=Value.ACTIVE)
-PLATFORMS = {
-    "Radxa ROCK 5B": {"enable": ("PIN_15", OUTH), "reset": ("PIN_13", OUTL)},
-    "Raspberry Pi 5": {"enable": ("PIN15", OUTH), "reset": ("PIN13", OUTL)},
-    "Raspberry Pi 4": {"enable": ("GPIO22", OUTH), "reset": ("GPIO27", OUTL)},
-    "Raspberry Pi Zero W": {"enable": ("GPIO22", OUTH), "reset": ("GPIO27", OUTL)}
-}
 
 
 class ChecksumMismatchError(RuntimeError):
@@ -97,17 +91,14 @@ def __str__(self):
 
 
 class PMS5003:
-    def __init__(self, device="/dev/ttyAMA0", baudrate=9600, pin_enable=None, pin_reset=None):
+    def __init__(self, device="/dev/ttyAMA0", baudrate=9600, pin_enable="GPIO22", pin_reset="GPIO27"):
         self._serial = None
         self._device = device
         self._baudrate = baudrate
 
-        if pin_enable is not None and pin_reset is not None:
-            gpiodevice.friendly_errors = True
-            self._pin_enable = gpiodevice.get_pin(pin_enable, "PMS5003_en", OUTH)
-            self._pin_reset = gpiodevice.get_pin(pin_reset, "PMS5003_rst", OUTL)
-        else:
-            self._pin_enable, self._pin_reset = gpiodevice.get_pins_for_platform(PLATFORMS)
+        gpiodevice.friendly_errors = True
+        self._pin_enable = gpiodevice.get_pin(pin_enable, "PMS5003_en", OUTH)
+        self._pin_reset = gpiodevice.get_pin(pin_reset, "PMS5003_rst", OUTL)
 
         self.setup()
 

pyproject.toml

@@ -36,7 +36,7 @@ classifiers = [
 ]
 dependencies = [
     "gpiod",
-    "gpiodevice",
+    "gpiodevice>=0.0.4",
     "pyserial"
 ]
 
@@ -117,4 +117,8 @@ ignore = [
 [tool.pimoroni]
 apt_packages = []
 configtxt = []
-commands = []
+commands = [
+	"printf \"Setting up serial for PMS5003..\\n\"",
+	"sudo raspi-config nonint do_serial_cons 1",
+	"sudo raspi-config nonint do_serial_hw 0"
+]

tests/conftest.py

@@ -57,6 +57,7 @@ def gpiod():
 def gpiodevice():
     gpiodevice = mock.Mock()
     gpiodevice.get_pins_for_platform.return_value = [(mock.Mock(), 0), (mock.Mock(), 0)]
+    gpiodevice.get_pin.return_value = (mock.Mock(), 0)
 
     sys.modules['gpiodevice'] = gpiodevice
     yield gpiodevice