Linux kernel driver for the Photonicat 2 power management unit (PMU).

Per-firmware observed behavior is recorded in the wiki.

The charge stop threshold is enforced by the PMU, not by the driver: writing charge_control_end_threshold sends the value to the PMU and reports the result of the PMU's ACK. Values outside 50–100 are rejected with EINVAL before any command is sent, a PMU refusal returns EIO, and firmware without charge threshold support returns ETIMEDOUT. Reads return ENODATA until the PMU has answered a threshold query at least once, which promotes pmu_charge_threshold_capability to enabled-probe.

/dev/rtc0 appears once the PMU clock passes runtime validation (pmu_rtc_capability reaches enabled-probe), which takes as long as the PMU needs to send three valid, advancing RTC samples. Registering it earlier made the kernel's boot-time read of the RTC fail and the system clock keep whatever seeded it. If validation never passes, /dev/rtc0 is registered anyway 10 seconds after probe, with reads reporting invalid data and alarm programming failing; that firmware is listed in the wiki.

status_led and beeper reads report the state from the PMU's last STATUS_LED_BEEPER_V2_SET_ACK, not the value last written. A read issued immediately after a write returns the requested value because the ACK has not arrived yet; wait about a second before reading back a confirmed state. A readback that reverts means the PMU refused the write — older firmware ignores the set command outright, which the wiki records.

The PMU reports a power button press with a PMU_REQUEST_SHUTDOWN frame. The pmu-button-mode device tree property decides what the driver does with it:

The button on this board is wired to the PMU, not to the SoC. The rk805 pwrkey input device that a Photonicat 2 also exposes belongs to the PMIC and is a different button, so HandlePowerKey= has no effect on the PMU button unless pmu-button-mode = "input" is set.

The PMU sends one frame per press and never announces a release, so the driver reports a press immediately followed by a release. Userspace sees every press as a short press; HandlePowerKeyLongPress= cannot trigger from this button.

The mode can also be set with the button_mode module parameter, which overrides the device tree property. This avoids a device tree overlay and a reboot when trying a mode out:

# One boot only
rmmod photonicat_pm && insmod photonicat-pm.ko button_mode=input

# Persistently
echo 'options photonicat-pm button_mode=input' > /etc/modprobe.d/photonicat-pm.conf

The driver logs the mode it settled on and where it came from at probe: PMU button mode: input (module parameter).

On a desktop, the desktop environment usually takes over the power key from systemd-logind and applies its own policy — GNOME defaults to suspend, not power off. Whether the PMU button can wake this board from suspend has not been verified, so set the desktop's power button action deliberately before relying on input mode there.

# Confirm the input device is present (input mode only)
grep -A4 'photonicat-pm power button' /proc/bus/input/devices

# Watch presses without acting on them (by-path name comes from the UART
# address, so it is board-specific; this is the Photonicat 2 one)
sudo evtest /dev/input/by-path/platform-2afc0000.serial-event

The firmware debounces the button itself: on RA2E1260702000 a quick tap or a hold under about two seconds sends nothing at all, and a hold of about three seconds sends the request. A stray press in a bag therefore never reaches the host in the first place. Holding past that sends nothing further: a 12 second hold reported one KEY_POWER and left the board running, so the firmware has no hard-cutoff hold to escalate to.

# Build package and run lintian
docker compose up --build

# Build only (skip lintian)
docker compose up deb

# Output: build/photonicat-pm-dkms_*.deb

# Install DKMS package
dpkg -i build/photonicat-pm-dkms_*.deb

The driver reads Device Tree properties during probe. Board developers (e.g. Armbian, OpenWrt) must add a photonicat-pm node to their board DTS. The example below shows a typical configuration for Photonicat 2.

&uart10 {
    pinctrl-0 = <&uart10m2_xfer>;
    status = "okay";

    pcat_pm: pcat-pm {
        compatible = "photonicat-pm";

        /* Hardware: must match PMU firmware baud rate */
        baudrate = <115200>;

        /* Hardware: GPIO wired to PMU power-sense input (from schematic) */
        power-gpio = <&gpio0 RK_PC1 GPIO_ACTIVE_HIGH>;

        /* Hardware: PMU protocol version on this board */
        pm-version = <2>;

        /* Config: force power off if shutdown hangs (seconds, 0 = disabled) */
        force-poweroff-timeout = <60>;

        /* Config: what a PMU power button press does */
        pmu-button-mode = "input";

        /* Optional: exposes board temperature to the kernel thermal framework */
        #thermal-sensor-cells = <0>;

        /* Required child: links to battery description for charger subsystem */
        charger {
            monitored-battery = <&battery>;
        };

        /* Required child: registers fan as a thermal cooling device */
        pcat_fan: fan {
            #cooling-cells = <2>;
        };
    };
};

/* Optional: thermal zone wiring board temperature sensor to fan cooling device */
thermal-zones {
    board-thermal {
        polling-delay-passive = <1000>;  /* ms between passive cooling steps */
        polling-delay = <5000>;          /* ms between idle polls */
        thermal-sensors = <&pcat_pm>;

        trips {
            board_alert: board-alert {
                temperature = <55000>;   /* 55 °C — start active cooling */
                hysteresis  = <5000>;
                type = "active";
            };
            board_crit: board-crit {
                temperature = <85000>;   /* 85 °C — critical shutdown */
                hysteresis  = <5000>;
                type = "critical";
            };
        };

        cooling-maps {
            map0 {
                trip = <&board_alert>;
                cooling-device = <&pcat_fan THERMAL_NO_LIMIT THERMAL_NO_LIMIT>;
            };
        };
    };
};

/* Standard simple-battery node — values from battery datasheet */
battery: battery {
    compatible = "simple-battery";
    device-chemistry = "lithium-ion";
    voltage-min-design-microvolt = <6800000>;
    voltage-max-design-microvolt = <8400000>;
    energy-full-design-microwatt-hours = <51800000>;
    ocv-capacity-celsius = <20>;
    ocv-capacity-table-0 =  <8344000 100>, <8184000 95>, <8070000 90>, <7980000 85>,
                            <7878000 80>, <7790000 75>, <7704000 70>, <7614000 65>,
                            <7524000 60>, <7426000 55>, <7344000 50>, <7294000 45>,
                            <7258000 40>, <7226000 35>, <7196000 30>, <7156000 25>,
                            <7100000 20>, <7038000 15>, <6958000 10>, <6876000 5>,
                            <6800000 0>;
};

cat /sys/class/power_supply/battery/capacity
# 0-100 (battery capacity percentage)
# v2 PMU status reports use PMU SOC directly; shorter reports use OCV fallback

cat /sys/class/power_supply/battery/status
# Charging or Discharging

cat /sys/class/power_supply/battery/energy_full
# Static design full charge capacity from device tree, not live/measured capacity

cat /sys/class/power_supply/battery/power_now
# Computed from voltage_now and current_now

test ! -e /sys/class/power_supply/battery/energy_now
# energy_now is intentionally not exported by current driver releases

# Stop charging at 80% (accepted range is 50-100)
echo 80 > /sys/class/power_supply/battery/charge_control_end_threshold

# Read the threshold currently stored in the PMU
cat /sys/class/power_supply/battery/charge_control_end_threshold

# Charge to full again
echo 100 > /sys/class/power_supply/battery/charge_control_end_threshold

# Check whether the running firmware answered the threshold query
cat /sys/kernel/photonicat-pm/pmu_charge_threshold_capability
# pending-probe or enabled-probe

The PMU stores the threshold, so it survives driver reload, reboot, and power off. Once the battery is above the threshold, status reads Not charging until the threshold is raised or the battery drains below it.

The PMU has two fan speed modes:

• Unmanaged fan speed — the PMU controls the fan based on its own internal logic (default).
• Managed fan speed — the driver sends a SET command to lock the fan at a specific percentage (0–100%).

Temperature-driven control is available in software: define a thermal zone in the device tree wiring the board temperature sensor (via #thermal-sensor-cells) to the fan cooling device (via #cooling-cells), and the kernel thermal governor sends SET commands as the temperature crosses trip points. See the Device Tree example. Once the system shuts down the governor stops and the PMU retains the last SET value.

Check whether the driver has set a fixed speed:

cat /sys/kernel/photonicat-pm/fan_state

A value from 0 to 100 is the managed fan speed percentage set by the driver; unmanaged is the driver-local state described in the caution above.

The snippets below run the write through sudo sh -c so the privileged shell performs the cur_state redirection, which makes them safe to paste into bash, zsh, or fish.

Set fan speed (switches PMU to managed speed). Replace the final argument with the percentage to set; use 100 for maximum:

sudo sh -c '
speed=$1
fan_cdev=
for cdev in /sys/class/thermal/cooling_device*; do
    [ "$(cat "$cdev/type" 2>/dev/null)" = "pcat-pm-fan" ] || continue
    fan_cdev=$cdev
    break
done
[ -n "$fan_cdev" ] || { echo "pcat-pm-fan cooling device not found" >&2; exit 1; }
echo "$speed" > "$fan_cdev/cur_state"
' sh 50

Read current setting:

sh -c '
fan_cdev=
for cdev in /sys/class/thermal/cooling_device*; do
    [ "$(cat "$cdev/type" 2>/dev/null)" = "pcat-pm-fan" ] || continue
    fan_cdev=$cdev
    break
done
[ -n "$fan_cdev" ] || { echo "pcat-pm-fan cooling device not found" >&2; exit 1; }
cat "$fan_cdev/cur_state"
'

status_led and beeper take 1 or 0, and read back the state from the PMU's last ACK, so a read needs about a second to reflect a write:

echo 0 > /sys/kernel/photonicat-pm/status_led
sleep 1
cat /sys/kernel/photonicat-pm/status_led

On firmware that refuses the write, the read reverts to the PMU's own state. See LEDs & Peripherals.

cat /sys/kernel/photonicat-pm/pmu_hw_version
cat /sys/kernel/photonicat-pm/pmu_fw_version
cat /sys/kernel/photonicat-pm/pmu_rtc_capability

The raw version ACK frames are also forwarded to /dev/pcat-pm-ctl for tools that query the PMU through the control device.

The driver registers an RTC device with alarm support. Setting an alarm sends the time to the PMU (SCHEDULE_STARTUP_TIME_SET), which stores it and powers on the board at that time even from a full power-off. The alarm is one-shot.

All firmware starts in pending-probe. The driver registers /dev/rtc0 once it observes three consecutive valid, advancing PMU RTC samples, so the kernel's boot-time read of the RTC seeds the system clock from the PMU. Firmware that never passes the probe gets /dev/rtc0 registered 10 seconds after probe instead, where reads report invalid data and alarm programming fails. Raw scheduled-boot commands through /dev/pcat-pm-ctl are gated the same way, and no firmware version string enables either by itself.

Works with standard Linux RTC tools such as rtcwake(8):

# Power off now, automatically power on after 60 seconds
rtcwake -m off -s 60

# Power off now, automatically power on at the specified time
rtcwake -m off -t $(date -d "2026-02-11 08:00:00" +%s)

# Set a wake alarm 120 seconds from now, but do not power off (useful for testing)
rtcwake -m no -s 120

# Read current RTC alarm
cat /proc/driver/rtc

# Set LED blink pattern: 50ms on, 50ms off, infinite repeat (wired mode)
echo 50 > /sys/kernel/photonicat-pm/net_status_led_on_time
echo 50 > /sys/kernel/photonicat-pm/net_status_led_off_time
echo 0 > /sys/kernel/photonicat-pm/net_status_led_repeat

# Set LED blink pattern: 20ms on, 380ms off (mobile mode)
echo 20 > /sys/kernel/photonicat-pm/net_status_led_on_time
echo 380 > /sys/kernel/photonicat-pm/net_status_led_off_time

# Solid on
echo 100 > /sys/kernel/photonicat-pm/net_status_led_on_time
echo 0 > /sys/kernel/photonicat-pm/net_status_led_off_time

# Read the mode stored in the PMU
cat /sys/kernel/photonicat-pm/power_on_mode
# unconfigured, enabled, or disabled

# Power on automatically when external power is applied
echo enabled > /sys/kernel/photonicat-pm/power_on_mode

# Back to manual power-on
echo disabled > /sys/kernel/photonicat-pm/power_on_mode

Raw escape hatch for advanced PMU commands using the binary serial protocol. See Protocol below for the frame format, and the pcat-pm-ctl(4) man page for the commands the driver refuses to forward and the responses that can be read back.

The driver communicates with the PMU over UART using a framed binary protocol:

┌──────┬─────┬─────┬─────────┬────────┬─────────┬─────────┬──────────┬─────────┬──────┐
│ 0xA5 │ SRC │ DST │ FRAME#  │ LENGTH │ COMMAND │ PAYLOAD │ NEED_ACK │  CRC16  │ 0x5A │
│      │     │     │ (2B LE) │ (2B LE)│ (2B LE) │  [...]  │   (1B)   │ (2B LE) │      │
└──────┴─────┴─────┴─────────┴────────┴─────────┴─────────┴──────────┴─────────┴──────┘

• 0xA5: Header sync byte
• SRC: Source address (0x01 = host, 0x81 = PMU)
• DST: Destination address (0x01 = host, 0x81 = PMU, 0x80 = broadcast, 0xFF = all)
• FRAME#: Frame number, auto-incremented by driver (little-endian)
• LENGTH: Payload length + 3 (includes COMMAND + NEED_ACK, little-endian)
• COMMAND: Command type (little-endian, see photonicat-pm.h)
• PAYLOAD: Optional command-specific data
• NEED_ACK: 1 = request acknowledgment, 0 = no ACK needed
• CRC16: Modbus CRC16 of bytes from SRC through NEED_ACK (little-endian)
• 0x5A: Tail marker

See photonicat-pm.h for command definitions.

The PMU firmware is closed source and no protocol specification exists. Command numbers and payload layouts come from the vendor's userspace manager, photonicat/rockchip_rk3568_pcat_manager (src/pmu-manager.c), and from observing the wire. The vendor's firmware changelog records user-facing changes, including MCU sections in later releases, but not command semantics, so protocol behavior is established by testing and can differ between firmware versions.

PMU command logging uses the kernel dev_dbg facility. Messages are compiled out, or dynamically off, by default.

Requires CONFIG_DYNAMIC_DEBUG in the kernel (enabled by most distros):

# Enable PMU command logs
echo 'file pcat-pm-uart.c +p' > /sys/kernel/debug/dynamic_debug/control

# Disable
echo 'file pcat-pm-uart.c -p' > /sys/kernel/debug/dynamic_debug/control

# View logs
dmesg | grep "PMU cmd="

Add -DDEBUG to the module CFLAGS to enable all dev_dbg messages unconditionally:

# In src/Makefile
ccflags-y += -DDEBUG