Use diozero for GPIO

docs/source/docs/advanced-installation/sw_install/files/Limelight2+/hardwareConfig.json

@@ -3,7 +3,6 @@
   "supportURL" : "https://limelightvision.io",
   "ledPins" : [ 13, 18 ],
   "ledsCanDim" : true,
-  "ledPWMRange" : [ 0, 100 ],
   "ledPWMFrequency" : 30000,
   "vendorFOV" : 75.76079874010732
 }

docs/source/docs/hardware/customhardware.md

@@ -8,29 +8,69 @@ By default, PhotonVision attempts to make minimal assumptions of the hardware it
 
 ## LED Support
 
-For Raspberry-Pi based hardware, PhotonVision can use [PiGPIO](https://abyz.me.uk/rpi/pigpio/) to control IO pins. The mapping of which pins control which LED's is part of the hardware config. The pins are active-high: set high when LED's are commanded on, and set low when commanded off.
+When running on Linux, PhotonVision can use [diozero](https://www.diozero.com) to control IO pins. The mapping of which pins control which LED's is part of the hardware config. The illumination LED pins are active-high: set high when LED's are commanded on, and set low when commanded off.
 
 ```{eval-rst}
 .. tab-set-code::
    .. code-block:: json
 
       {
         "ledPins" : [ 13 ],
-        "ledSetCommand" : "",
         "ledsCanDim" : true,
-        "ledPWMRange" : [ 0, 100 ],
-        "ledPWMSetRange" : "",
+        "ledBrightnessRange" : [ 0, 100 ],
         "ledPWMFrequency" : 0,
-        "ledDimCommand" : "",
-        "ledBlinkCommand" : "",
         "statusRGBPins" : [ ],
+        "statusRGBActiveHigh" : false,
       }
 ```
 
 :::{note}
 No hardware boards with status RGB LED pins or non-dimming LED's have been tested yet. Please reach out to the development team if these features are desired, they can assist with configuration and testing.
 :::
 
+### GPIO Pinout
+
+::::{tab-set}
+
+:::{tab-item} Raspberry Pi
+
+The following diagram shows the GPIO pin numbering of the 40-pin header on Raspberry Pi hardware, courtesy of [pinout.xyz](https://pinout.xyz). Compute modules use the pin numbering from their respective datasheet.
+
+```{image} https://raw.githubusercontent.com/pinout-xyz/Pinout.xyz/master/resources/raspberry-pi-pinout.png
+:alt: Raspberry Pi GPIO Pinout
+```
+
+:::
+::::
+
+### Custom GPIO
+
+If your hardware does not support diozero's default provider, custom commands can be provided to interact with the GPIO lines. The examples below show what parameters are provided to each command, which can be used in any order or multiple times as needed.
+
+```{eval-rst}
+.. tab-set-code::
+   .. code-block:: json
+
+      {
+        "getGPIOCommand" : "getGPIO {p}",
+        "setGPIOCommand" : "setGPIO {p} {s}",
+        "setPWMCommand" : "setPWM {p} {v}",
+        "setPWMFrequencyCommand" : "setPWMFrequency {p} {f}",
+        "releaseGPIOCommand" : "releseGPIO {p}",
+      }
+```
+
+The following template strings are used to input parameters to the commands:
+
+| Template | Parameter  | Values     |
+| -------- | ---------- | ---------- |
+| `{p}`    | pin number | integers   |
+| `{s}`    | state      | true/false |
+| `{v}`    | value      | 0.0-1.0    |
+| `{f}`    | frequency  | integers   |
+
+If you were using custom LED commands from 2025 or earlier and still need custom GPIO commands, they can likely be copied over. `ledSetCommand` can be reused as `setGPIOCommand`. `ledDimCommand` can be reused with edits as `setPWMCommand`, replacing any occurrences of `{v}` with `$(awk 'BEGIN{ print int({v}*100) }')` if your command requires integer percentages.
+
 ## Hardware Interaction Commands
 
 For Non-Raspberry-Pi hardware, users must provide valid hardware-specific commands for some parts of the UI interaction (including performance metrics, and executing system restarts).
@@ -101,14 +141,16 @@ Here is a complete example `hardwareConfig.json`:
         "deviceLogoPath" : "",
         "supportURL" : "https://www.youtube.com/watch?v=b-CvLWbfZhU",
         "ledPins" : [2, 13],
-        "ledSetCommand" : "",
         "ledsCanDim" : true,
-        "ledPWMRange" : [ 0, 100 ],
-        "ledPWMSetRange" : "",
+        "ledBrightnessRange" : [ 0, 100 ],
         "ledPWMFrequency" : 0,
-        "ledDimCommand" : "",
-        "ledBlinkCommand" : "",
         "statusRGBPins" : [ ],
+        "statusRGBActiveHigh" : false,
+        "getGPIOCommand" : "getGPIO {p}",
+        "setGPIOCommand" : "setGPIO {p} {s}",
+        "setPWMCommand" : "setPWM {p} {v}",
+        "setPWMFrequencyCommand" : "setPWMFrequency {p} {f}",
+        "releaseGPIOCommand" : "releseGPIO {p}",
         "cpuTempCommand" : "",
         "cpuMemoryCommand" : "",
         "cpuUtilCommand" : "",

photon-core/build.gradle

@@ -31,6 +31,7 @@ dependencies {
     // These stay as implementation dependencies since they don't have native code that gets packaged
     implementation 'org.zeroturnaround:zt-zip:1.14'
     implementation "org.xerial:sqlite-jdbc:3.41.0.0"
+    implementation 'com.diozero:diozero-core:1.4.1'
 
     // The JNI libraries use wpilibNatives, the java libraries use implementation
     if (jniPlatform == "linuxarm64") {

photon-core/src/main/java/org/photonvision/common/configuration/HardwareConfig.java

@@ -28,12 +28,18 @@ public class HardwareConfig {
 
     // LED control
     public final ArrayList<Integer> ledPins;
-    public final String ledSetCommand;
     public final boolean ledsCanDim;
     public final ArrayList<Integer> ledBrightnessRange;
-    public final String ledDimCommand;
-    public final String ledBlinkCommand;
+    public final int ledPWMFrequency;
     public final ArrayList<Integer> statusRGBPins;
+    public final boolean statusRGBActiveHigh;
+
+    // Custom GPIO
+    public final String getGPIOCommand;
+    public final String setGPIOCommand;
+    public final String setPWMCommand;
+    public final String setPWMFrequencyCommand;
+    public final String releaseGPIOCommand;
 
     // Metrics
     public final String cpuTempCommand;
@@ -55,12 +61,16 @@ public HardwareConfig(
             String deviceLogoPath,
             String supportURL,
             ArrayList<Integer> ledPins,
-            String ledSetCommand,
             boolean ledsCanDim,
             ArrayList<Integer> ledBrightnessRange,
-            String ledDimCommand,
-            String ledBlinkCommand,
+            int ledPwmFrequency,
             ArrayList<Integer> statusRGBPins,
+            boolean statusRGBActiveHigh,
+            String getGPIOCommand,
+            String setGPIOCommand,
+            String setPWMCommand,
+            String setPWMFrequencyCommand,
+            String releaseGPIOCommand,
             String cpuTempCommand,
             String cpuMemoryCommand,
             String cpuUtilCommand,
@@ -76,12 +86,16 @@ public HardwareConfig(
         this.deviceLogoPath = deviceLogoPath;
         this.supportURL = supportURL;
         this.ledPins = ledPins;
-        this.ledSetCommand = ledSetCommand;
         this.ledsCanDim = ledsCanDim;
         this.ledBrightnessRange = ledBrightnessRange;
-        this.ledDimCommand = ledDimCommand;
-        this.ledBlinkCommand = ledBlinkCommand;
+        this.ledPWMFrequency = ledPwmFrequency;
         this.statusRGBPins = statusRGBPins;
+        this.statusRGBActiveHigh = statusRGBActiveHigh;
+        this.getGPIOCommand = getGPIOCommand;
+        this.setGPIOCommand = setGPIOCommand;
+        this.setPWMCommand = setPWMCommand;
+        this.setPWMFrequencyCommand = setPWMFrequencyCommand;
+        this.releaseGPIOCommand = releaseGPIOCommand;
         this.cpuTempCommand = cpuTempCommand;
         this.cpuMemoryCommand = cpuMemoryCommand;
         this.cpuUtilCommand = cpuUtilCommand;
@@ -100,12 +114,16 @@ public HardwareConfig() {
         deviceLogoPath = "";
         supportURL = "";
         ledPins = new ArrayList<>();
-        ledSetCommand = "";
         ledsCanDim = false;
         ledBrightnessRange = new ArrayList<>();
-        ledDimCommand = "";
-        ledBlinkCommand = "";
+        ledPWMFrequency = 0;
         statusRGBPins = new ArrayList<>();
+        statusRGBActiveHigh = false;
+        getGPIOCommand = "";
+        setGPIOCommand = "";
+        setPWMCommand = "";
+        setPWMFrequencyCommand = "";
+        releaseGPIOCommand = "";
         cpuTempCommand = "";
         cpuMemoryCommand = "";
         cpuUtilCommand = "";
@@ -127,7 +145,7 @@ public final boolean hasPresetFOV() {
     }
 
     /**
-     * @return True if any command has been configured to a non-default empty, false otherwise
+     * @return True if any info command has been configured to be non-empty, false otherwise
      */
     public final boolean hasCommandsConfigured() {
         return cpuTempCommand != ""
@@ -137,11 +155,21 @@ public final boolean hasCommandsConfigured() {
                 || cpuUptimeCommand != ""
                 || gpuMemoryCommand != ""
                 || ramUtilCommand != ""
-                || ledBlinkCommand != ""
                 || gpuMemUsageCommand != ""
                 || diskUsageCommand != "";
     }
 
+    /**
+     * @return True if any gpio command has been configured to be non-empty, false otherwise
+     */
+    public final boolean hasGPIOCommandsConfigured() {
+        return getGPIOCommand != ""
+                || setGPIOCommand != ""
+                || setPWMCommand != ""
+                || setPWMFrequencyCommand != ""
+                || releaseGPIOCommand != "";
+    }
+
     @Override
     public String toString() {
         return "HardwareConfig[deviceName="
@@ -152,18 +180,26 @@ public String toString() {
                 + supportURL
                 + ", ledPins="
                 + ledPins
-                + ", ledSetCommand="
-                + ledSetCommand
                 + ", ledsCanDim="
                 + ledsCanDim
                 + ", ledBrightnessRange="
                 + ledBrightnessRange
-                + ", ledDimCommand="
-                + ledDimCommand
-                + ", ledBlinkCommand="
-                + ledBlinkCommand
+                + ", ledPWMFrequency="
+                + ledPWMFrequency
                 + ", statusRGBPins="
                 + statusRGBPins
+                + ", statusRGBActiveHigh"
+                + statusRGBActiveHigh
+                + ", getGPIOCommand="
+                + getGPIOCommand
+                + ", setGPIOCommand="
+                + setGPIOCommand
+                + ", setPWMCommand="
+                + setPWMCommand
+                + ", setPWMFrequencyCommand="
+                + setPWMFrequencyCommand
+                + ", releaseGPIOCommand="
+                + releaseGPIOCommand
                 + ", cpuTempCommand="
                 + cpuTempCommand
                 + ", cpuMemoryCommand="