PhotonVision/docs/source/docs/hardware/customhardware.md

# Deploying on Custom Hardware

## Configuration

By default, PhotonVision attempts to make minimal assumptions of the hardware it runs on. However, it may be configured to enable custom LED control, branding, and other functionality.

`hardwareConfig.json` is the location for this configuration. It is included when settings are exported, and can be uploaded as part of a .zip, or on its own.

## LED Support

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 ],
        "ledsCanDim" : true,
        "ledBrightnessRange" : [ 0, 100 ],
        "ledPWMFrequency" : 0,
        "statusLEDType": "RGB",
        "statusLEDPins" : [ ],
        "statusLEDActiveHigh" : false,
      }
```

There are currently two types of status LEDs supported:

* `RGB` (default): A singular LED mixing separate red, green, and blue inputs
* `GreenYellow`: A pair of independent green and yellow LEDs

For an explanation of the colors used for status LEDs, see {ref}`Status LEDs<docs/troubleshooting/status-leds:Status LEDs>`

### 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-Linux hardware, users must provide the hardware-specific command for executing system restarts.

Leaving this command blank will disable the restart functionality.

```{eval-rst}
.. tab-set-code::
   .. code-block::  json

      {
        "restartHardwareCommand" : "",
      }
```

:::{note}
This setting has no effect if PhotonVision detects it is running on Linux. On Linux, the restart is accomplished by executing `reboot now` in a shell.
:::

## Known Camera FOV

If your hardware contains a camera with a known field of vision, it can be entered into the hardware configuration. This will prevent users from editing it in the GUI.

```{eval-rst}
.. tab-set-code::
   .. code-block:: json

      {
        "vendorFOV" : 98.9
      }
```

## Device Name Branding

To help differentiate your hardware from other solutions, a device name may be set.

```{eval-rst}
.. tab-set-code::
   .. code-block:: json

      {
        "deviceName" : "Super Cool Custom Hardware",
      }
```

:::{note}
Not all configuration is currently presented in the User Interface. Additional file uploads may be needed to support custom images.
:::

## Example

Here is a complete example `hardwareConfig.json`:

```{eval-rst}
.. tab-set-code::
   .. code-block:: json

      {
        "deviceName" : "Blinky McBlinkface",
        "ledPins" : [2, 13],
        "ledsCanDim" : true,
        "ledBrightnessRange" : [ 0, 100 ],
        "ledPWMFrequency" : 0,
        "statusLEDType": "RGB",
        "statusLEDPins" : [ ],
        "statusLEDActiveHigh" : false,
        "getGPIOCommand" : "getGPIO {p}",
        "setGPIOCommand" : "setGPIO {p} {s}",
        "setPWMCommand" : "setPWM {p} {v}",
        "setPWMFrequencyCommand" : "setPWMFrequency {p} {f}",
        "releaseGPIOCommand" : "releaseGPIO {p}",
        "restartHardwareCommand" : "",
        "vendorFOV" : 72.5
      }
```