.. pemmican: notifies users of Raspberry Pi 5 power issues
..
.. Copyright (c) 2024 Dave Jones <dave.jones@canonical.com>
.. Copyright (c) 2024 Canonical Ltd.
..
.. SPDX-License-Identifier: GPL-3.0

============
pemmican-mon
============

.. include:: subst.rst


Synopsis
========

.. code-block:: text

    usage: pemmican-mon [-h] [--help-all] [--help-gapplication]
                        [--gapplication-service]

.. program:: pemmican-mon

Options
=======

.. option:: -h, --help

    show the help message and exit

.. option:: --help-all

    show all available help options and exit

.. option:: --help-gapplication

    show help options specific to GLib.Application and exit

.. option:: --gapplication-service

    run the application in GApplication service mode (for DBus service files)


Usage
=====

:program:`pemmican-mon` is intended to be a background service, launched as a
user-slice systemd service by the "graphical-session" target. It monitors udev
for power supply related events, reporting those of interest via the
freedesktop `notification service <notifications-spec_>`_.

Power supply undervolt (typically reported in the event the supply drops below
4.8V) is likely the most important event the application warns about. If you
wish to suppress this warning for your user, touch the file
|user/undervolt.inhibit|. If you wish to suppress this warning system-wide,
touch the file |system/undervolt.inhibit|.

.. warning::

    It is strongly recommended that any such notice is heeded, as brownout is
    very likely to lead to any manner of other (hard to predict or replicate)
    issues up to and including data corruption.

    Put simply, suppressing this warning is probably a very bad idea!

USB over-current is the other event the application will warn about. This
occurs when peripherals attached to the USB ports attempt to draw more current
that permitted. If the Pi 5 is being supplied by a PSU that did not negotiate a
5A feed at boot time, the USB ports will be limited in their supply and this
warning is more likely.

If you wish to suppress this warning for your individual user, touch the file
|user/overcurrent.inhibit|. To suppress this warning system-wide, touch
|system/overcurrent.inhibit|.


Environment
===========

Because the notifications generated by this application are capable of
launching a web-browser (via the "More Information" action), the script will
also bail with an error in the event that ``DISPLAY`` or ``WAYLAND_DISPLAY``
are not found in the environment at startup.


See Also
========

.. only:: not man

    :doc:`pemmican-cli`, :doc:`pemmican-reset`

.. only:: man

    :manpage:`pemmican-cli(1)`, :manpage:`pemmican-reset(1)`

The freedesktop `notifications specification <notification service_>`_.

.. _notification service: https://specifications.freedesktop.org/notification-spec/latest/


Bugs
====

|bug-link|
