.config/awesome/lain/wiki/bat.md

   1 ## Usage
   2
   3 [Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
   4
   5 ### Description
   6
   7 Shows the remaining time and percentage capacity of your laptop battery, as well
   8 as the current wattage. Multiple batteries are supported.
   9
  10 Displays a notification when battery is fully charged, low, or critical.
  11
  12 ```lua
  13 local mybattery = lain.widget.bat()
  14 ```
  15
  16 ## Input table
  17
  18 Variable | Meaning | Type | Default
  19 --- | --- | --- | ---
  20 `timeout` | Refresh timeout (in seconds) | integer | 30
  21 `pspath` | Power supply directory path | string | "/sys/class/power_supply/"
  22 `battery` | Single battery id | string | autodetected
  23 `batteries` | Multiple batteries id table | table of strings | autodetected
  24 `ac` | AC | string | autodetected
  25 `notify` | Show notification popups | string | "on"
  26 `full_notify` | Show a notification popup when the battery's fully charged | string | inherited value from `notify`
  27 `n_perc` | Percentages assumed for critical and low battery levels | table of integers | `{5, 15}`
  28 `settings` | User settings | function | empty function
  29
  30 The widget will try to autodetect `battery`, `batteries` and `ac`. If something
  31 goes wrong, you will have to define them manually. In that case, you only have
  32 to define one between `battery` and `batteries`. If you have one battery, you
  33 can either use `args.battery = "BAT*"` or `args.batteries = {"BAT*"}`, where `BAT*`
  34 is the identifier of your battery in `pspath` (do not use it as a wildcard).
  35 Of course, if you have multiple batteries, you need to use the latter option.
  36
  37 To disable notifications, set `notify` to `"off"`.
  38
  39 If you define `pspath`, **be sure** to not forget the final slash (/).
  40
  41 `settings` can use the `bat_now` table, which contains the following strings:
  42
  43 - `status`, general status ("N/A", "Discharging", "Charging", "Full");
  44 - `n_status[i]`, i-th battery status (like above);
  45 - `ac_status`, AC-plug flag (0 if cable is unplugged, 1 if plugged, "N/A" otherwise);
  46 - `perc`, total charge percentage (integer between 0 and 100 or "N/A");
  47 - `n_perc[i]`, i-th battery charge percentage (like above);
  48 - `time`, time remaining until charge if charging, until discharge if discharging (HH:MM string or "N/A");
  49 - `watt`, battery watts (float with 2 decimals).
  50
  51 and can modify the following three tables, which will be the preset for the naughty notifications:
  52 * `bat_notification_charged_preset` (used if battery is fully charged and connected to AC)
  53 * `bat_notification_low_preset` (used if battery charge level <= 15)
  54 * `bat_notification_critical_preset` (used if battery charge level <= 5)
  55
  56 Check [here](https://awesomewm.org/doc/api/libraries/naughty.html#notify) for
  57 the list of variables they can contain. Default definitions:
  58
  59 ```lua
  60 bat_notification_charged_preset = {
  61         title   = "Battery full",
  62         text    = "You can unplug the cable",
  63         timeout = 15,
  64         fg      = "#202020",
  65         bg      = "#CDCDCD"
  66     }
  67
  68 ```
  69
  70 ```lua
  71 bat_notification_low_preset = {
  72         title = "Battery low",
  73         text = "Plug the cable!",
  74         timeout = 15,
  75         fg = "#202020",
  76         bg = "#CDCDCD"
  77 }
  78 ```
  79 ```lua
  80 bat_notification_critical_preset = {
  81         title = "Battery exhausted",
  82         text = "Shutdown imminent",
  83         timeout = 15,
  84         fg = "#000000",
  85         bg = "#FFFFFF"
  86 }
  87 ```
  88
  89 ## Output table
  90
  91 Variable | Meaning | Type
  92 --- | --- | ---
  93 `widget` | The widget | `wibox.widget.textbox`
  94 `update` | Update `widget` | function
  95
  96 The `update` function can be used to refresh the widget before `timeout` expires.
  97
  98 ## Note
  99
 100 Alternatively, you can try the [`upower` recipe](https://awesomewm.org/recipes/watch).