.. 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-reset
==============

.. include:: subst.rst


Synopsis
========

.. code-block:: text

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


.. program:: pemmican-reset

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-reset` is intended to be a one-shot operation, launched as a
user-slice systemd service by the "graphical-session" target. Its operation is
in essence identical to :program:`pemmican-cli`, but rather than printing to
stdout, it reports warnings via the freedesktop `notification service
<notifications-spec_>`_.

It first checks whether the last reset occurred due to a brownout (undervolt)
condition and, if it was, sends a critical notification to the notification
service.

If you wish to suppress this warning for your user, touch the file
|user/brownout.inhibit|. If you wish to suppress this warning system-wide,
touch the file |system/brownout.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!

If the last reset was normal (or there was no last reset), the script further
checks if the power supply negotiated a full 5A feed. If it did not, this also
results in a warning printed to stdout.

The Pi 5 can be reliably operated without a 5A feed, provided the peripherals
attached to it are relatively light in their power draw. Depending on
circumstance, you may well wish to suppress this warning which can be done for
your individual user by touching the file |user/max_current.inhibit| or
system-wide by touching |system/max_current.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-mon`

.. only:: man

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

The freedesktop `notifications specification <notifications-spec_>`_.


Bugs
====

|bug-link|
