.\" btw (c) ge <https://nixhacks.net>
.\" License: The Unlicense <https://unlicense.org/>
.\" vim: set filetype=groff:
.TH BTW 1 "2022-10-10" "btw 1.0" "User Commands"
.SH NAME
btw \- battery watchdog
.SH SYNOPSIS
.SY btw
.OP \-c|\-\-crit level
.OP \-p|\-\-preriod seconds
.OP \-l|\-\-log file
.OP \-j|\-\-syslog
.OP \-s|\-\-summary text
.OP \-b|\-\-body text
.OP \-w|\-\-watch
.SY btw
.B \-\-help
.SY btw
.B \-\-version
.YS
.SH DESCRIPTION
Send notification when critical battery level reached.
.SH OPTIONS
.TP
\fB\-v\fR, \fB\-\-version\fR
Print version and exit.
.TP
\fB\-h\fR, \fB\-\-help\fR
Print this help message and exit.
.TP
\fB\-c\fR, \fB\-\-crit\fR \fIlevel\fR
Battery critical level in percents [default: 10]
.TP
\fB\-p\fR, \fB\-\-preriod\fR \fIseconds\fR
Battery check out period in seconds [default: 30]
.TP
\fB\-l\fR, \fB\-\-log\fR \fIfile\fR
Log file [default: ~/.cache/btw.log]
.TP
\fB\-j\fR, \fB\-\-syslog\fR
Use logger instead of log file.
.TP
\fB\-s\fR, \fB\-\-summary\fR \fItext\fR
Custom notification title text.
.TP
\fB\-b\fR, \fB\-\-body\fR \fItext\fR
Custom notification body text.
.TP
\fB\-w\fR, \fB\-\-watch\fR
Follow to the log file (tail -f).
.SH INVOKING
Run watchdog in background. See application autostart options for your
desktop environment or init system. For example add in your ~/.xinitrc:
.PP
.in +4m
.EX
btw &
.EE
.in
.PP
or create ~/.config/autostart/btw.desktop if you have GNOME Desktop:
.PP
.in +4m
.EX
[Desktop Entry]
Name=Laptop battery watchdog (btw)
Exec=btw
Type=Application
.EE
.in
.PP
.SH LOGGING
btw writes battery status log in log file. Set file by --log option.
.PP
Log format:
.PP
.in +4m
.EX
[date time] [state] [level]%
.EE
.in
.PP
There is:
.TP
[date time]
`date +'%Y-%m-%d %H:%M:%S'` command output.
.TP
[state]
Battery status, can be 'Charging' or 'Discharging'.
.TP
[level]
Battery current level in percents.
.PP
If --syslog option is passed use following commands to watch log.
.PP
.in +4m
.EX
btw -jw
# or
journalctl -t btw -f
.EE
.in
.PP
.SH EXAMPLES
.B btw
will send notification at every battery checkout while current battery
level is lower than critical level. For example, with following command:
.PP
.in +4m
.EX
btw -c 15 -p 30
.EE
.in
.PP
you will recieve notification every 30 seconds until battery is under 15%.
You can set up custom notification text via --summary and --body options.
.PP
Variables can be used in notification:
.TP
.B level
Current battery level in percents.
.TP
.B state
Battery status, can be
.IR full ,
.IR charging
or
.IR discharging .
.PP
For example:
.PP
.in +4m
.EX
btw -s 'Battery is very low!' -b 'Status: $state, $level%'
.EE
.in
.PP
.SH FILES
.TP
~/.cache/btw.log
Log file.
.TP
/tmp/btw.lock
Lock file. Prevents unwanted notifications.
.SH SEE ALSO
.BR acpi (1),
.BR notify-send (1)