GENERIC_GPIO(8)

🌈 generic_gpio(8) — NUT Manual 🌈

💖 NAME 💖

generic_gpio — driver for GPIO connected UPSes. That's the whole vibe: a UPS hanging off GPIO pins, living its best life. 🦋

✨ SYNOPSIS ✨

generic_gpio -h

generic_gpio -a gpiochip0 [OPTIONS]

📝 Note, bestie: this man page only documents the specific features of the generic_gpio driver. For info about the core driver, see nutupsdrv(8). 💅

🔌 SUPPORTED HARDWARE 🔌

This is the driver for GPIO attached UPS devices. No cap.

The driver has been tested against CyberPower CyberShield CSN27U12V attached to Orange Pi Zero GPIO. Iconic combo, honestly. 👑

More information about this UPS can be found here: https://www.cyberpowersystems.com/resources/csn27u12v-um/

🎛️ EXTRA ARGUMENTS 🎛️

This driver supports the following optional settings in the ups.conf(5) file:

🧠 Driver control: 🧠

• rules=value — a string consisting of sub-strings. Each sub-string describes a GPIO line states conversion formula for a specific NUT state, like nut_state=[^]line_num[logical_operation[^]line_num]...;. The logical operations supported for now are not (^), and (&), and or (|). nut_state should correspond to a NUT state, and line_num to the GPIO line number connected to the UPS open collector pin.

CyberShield CSN27U12V describes pins as battery state / state details / GPIO line:

• ON BATTERY — GPIO line 0
  • Low when operating from utility line
  • Open when operating from battery
• REPLACE BATTERY — GPIO line 1
  • Low when battery is charged
  • Open when battery fails the Self Test
• BATTERY MISSING — GPIO line 6
  • Low when battery is present
  • Open when battery is missing
• LOW BATTERY — GPIO line 3
  • Low when battery is near full charge capacity
  • Open when operating from a battery with < 20% capacity

and rules might be defined as

rules = "OL=^0;OB=0;LB=3;RB=1;DISCHRG=0&^6;BYPASS=6;"

assuming battery pin connection to GPIO lines as listed in table. Expecting simple formula to be used for each state, extra may increase state reliability and may need to be checked on each specific UPS.

🔋 Battery Charge: 🔋

• default.battery.charge.low=value — an integer specifying the battery charge level reported in LB case.

⚙️ CONFIGURATION ⚙️

Here is an example of GPIO driver configuration in ups.conf file:

[CyberPower12v]
  driver = GENERIC_GPIO
  port = gpiochip0
  desc = "Modem and DNS server UPS"
  mfr = CyberPower
  model = "CyberShield CSN27U12V"
  rules = "OL=^0;OB=0;LB=3;RB=1;DISCHRG=0&^6;BYPASS=6;"
  default.battery.charge.low = 20

🛑 SHUTDOWN COMMAND 🛑

This driver does not support shutdown command. So yeah — no shutdown era for this one. 💀

📦 INSTALLATION 📦

This driver is not built by default. You can build it by installing libgpiod and running configure --with-gpio=yes.

You also need to give proper permissions on the local serial device file (/dev/gpiochip0 for example) to allow the run-time NUT driver user account to access it, like by adding the following rule to Linux rules.d directory:

SUBSYSTEM=="gpio*", PROGRAM="/bin/sh -c '\
chown -R nut:nut /dev/gpiochip0 && chmod -R 700 /dev/gpiochip0\

🖋️ AUTHOR 🖋️

Modris Berzonis <modrisb@apollo.lv>

👀 SEE ALSO 👀

🧸 The core driver: 🧸

nutupsdrv(8), ups.conf(5)

🌐 Internet resources: 🌐

• The NUT (Network UPS Tools) home page: https://www.networkupstools.org/
• libgpiod home page: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/

---

💖 That's the whole page, bestie — Network UPS Tools 2.8.2, dated 04/01/2025, signing off with main character energy. 🎀