Metadata-Version: 2.1
Name: asus-charge-control
Version: 1.0.3
Summary: Set your recent ASUS notebook's maximum charge level on Linux.
Home-page: https://github.com/cforrester1988/asus-charge-control
Author: Christopher Forrester
Author-email: christopher@cforrester.ca
License: GPLv3+
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# asus-charge-control

> Set your recent ASUS notebook's maximum charge level on Linux.

Recent ASUS notebooks come with a Windows application to set the maximum battery
charge level, in order to reduce stress on the battery and prolong its lifespan. On
Linux kernels >= version 5.4, the ```asus_nb_wmi``` kernel module exposes a sysfs object to manage this setting.

Getting or setting the charge end threshold is rather verbose:

```console
$ cat /sys/class/power_supply/BAT0/charge_control_end_threshold
100

$ echo 80 | sudo tee /sys/class/power_supply/BAT0/charge_control_end_threshold
80
```

asus-charge-control offers a quicker way.

## Installation

asus-charge-control should work with any device running a recent kernel (>= 5.4) with the ```asus_nb_wmi``` module loaded. Use ```lsmod | grep asus_nb_wmi``` to check; if you see a line like ```asus_nb_wmi            32768  0```, then the module is running.

It has been tested with the following ASUS notebooks:

- ASUS VivoBook 15 **X512DA**

A Python version >= 3.7 is necessary to run this script. Most Linux distributions come with the right version. To verify that Python is installed on **Debian**/**Ubuntu**-based distributions, use apt:

```console
sudo apt install python3
```

As root privileges are necessary to set the charge end threshold, asus-charge-control should be installed as a global package:

```console
sudo pip install --system asus-charge-control
```

**DANGER:** Normally, Python packages should not be installed with ```sudo```, as they may execute arbitrary code. I encourage you to read ```setup.py``` before installation.

## Usage

You can get the current charge end threshold by calling ```asuscharge``` from  the command line:

```console
$ asuscharge
Current charge end threshold: 100%
```

Setting the charge end threshold requires root privileges:

```console
$ sudo asuscharge 80
Successfully set charge end threshold to 80%
```

**Note:** The charge end threshold resets back to 100% when the system is rebooted.

You can use a cron job to set the charge end threshold automatically on boot. To do so, find the path of the asuscharge command like so:

```console
$ which asuscharge
/usr/local/bin/asuscharge
```

Modify the root user's crontab file:

```console
sudo crontab -e
```

Add the following line to the end of the file:

```console
@reboot /usr/local/bin/asuscharge MAX
```

Replace ```MAX``` with the charge end threshold you would like, then save and close the file.

## Development

You can use the ```asuscharge``` package in your own applications. The package offers a ```ChargeThresholdController``` object, with a settable ```end_threshold``` property. It also offers three methods to check if the user's platform supports the charge end threshold feature: ```supported_platform(), supported_kernel(), and module_loaded()```.

## Version history

- 1.0.2 (2020-12-28)
  - (fix) ```MAX``` wasn't properly range checked for a value between 60-100.
  - (feature) added ```--force``` to set a threshold value beneath 60.

- 1.0.1 (2020-12-06)
  - (fix) supported_kernel() returned an incorrect value for Linux kernel versions > 5.9.

- 1.0.0 (2020-12-04)
  - Initial release.


