Battery Applet with Monitoring and Shutdown (BAMS)

UUID: batterymonitor@pdcurtis
Last edited:
1 week ago 2024-03-05, 14:18
Last commit: [48834b3c] batterymonitor@pdcurtis: Update es.po (#5559)

Displays charge as percentage and allows alerts and actions

README

Close

Battery Applet with Monitoring and Shutdown (BAMS)

Summary

This is a simple applet I have written for my laptop because I have recently had a couple of times where I have missed the notifications about low battery and have had shutdowns losing data and potentially reducing battery capacity through a complete discharge. The applet draws on my code for the NUMA (Network Utilisation Monitoring and Alert) Applet so much of the code is well developed and tested.

This applet allows one to set a level at which the machine starts to shutdown (suspend to memory as currently set up) with plenty of warning - the shutdown level is 2/3 of the initial alert level which can be adjusted between 10% and 40%.

Rationale

The current Settings and Power Applet only allow limited choices of handling low battery state - in fact latest version of Cinnamon seems to have lost the setting to specify the action when the battery is critical and there seems to be no easy way to set the 'critical shutdown' level in Mint 18 Sarah/Cinnamon 3.0 and higher. This applet complements the existing power facilities by allowing much more and easier control of automatic shutdown and recovery thereby considerably reducing the chances of both data lose or shortening battery life through accidental total discharge.

Status

Fully supported by Author, under continuing development and in continuous use on several of his machines.

Features

The applet normally shows the percentage charge on a coloured background which is:

  • Green when above the alert level (set currently to 1.5 times the 'shutdown' level.)
  • Green has Red Border when discharging.
  • Orange between the warning and shutdown level
  • Red and flashing at and below the Shutdown level (even when charging).

    When the battery is Discharging the warning and shutdown regions have a much longer flashing message in the applet which is difficult to miss.

  • When the Alert level is reached a modal alert is put up which can not be missed as no input can be made until it is cleared and short fixed audible alert is also given. For Cinnamon versions earlier than 2.6 an critical alert is used instead as modal alerts are not available. The default alert sound is short and high pitched.
  • The audible alert sound file can be specified in the Applet Settings rather than use a preset system file when used with Cinnamon 3.2 and higher. Mine lasts for 30 seconds and can be heard throughout the house so is not ideal for libraries - thanks to Brandon at http://soundbible.com/1911-Mandatory-Evacuation.html and used under Attribution 3.0 Licence. A brief warning is displayed whenever the applet starts if user specified files are in use te remind users of potential consequences of long loud files. The warning can be inhibited but this is not recommended.
    • note1: The file must be an .oga with mime type audio/x-vorbis+ogg - the mime type is crucial to it being recognised. You can convert any audio file (.mp3, .wav, etc) into this format by using any number of different free on-line conversion tools. When doing the conversion, you must be sure to select Ogg(Vorbis) as the Codec to be used during the conversion process. If your conversion was successful, it will be possible to preview the sound with the arrow button attached to the BAMS file selection dialog box.
    • note2: There cannot be any spaces in the filename.
  • When the Shutdown level is reached an alert box is put up with options of an immediate suspend or cancel - if nothing is done it suspends 30 seconds latter. If cancelled (or the machine is turned back on without the battery being on charge) the alert and shutdown sequence is restarted after the battery has dropped another 1%. The alert box is accompanied by an audible alert which can be specified in Settings with Cinnamon 3.2 and higher. This should be a short sound just to alert one if using the machine as it cannot be cancelled and could continue when the machine is reactivated.

The alert level can be set to between 10% and 40% of full by a slider on the left click menu or in the configuration screen. The refresh rate can also be set in the configuration screen.

The intention is to allow the possibility of leaving suspend with enough battery to close programs and shut down after powering up from suspend without a charger after an accidental unattended suspend. It is suggested that the 'shutdown level' is set to about 10% to allow time. Do not forget that the battery still drains, although slowly, during suspend.

Version 1.3.0 introduced support for vertical panels and has extra display modes including an optional icon showing battery state. The modes, which are selected in the Configure screen, are:

  • Classic - Battery Percentage with an extended message in the panel as above (only for horizontal panels)
  • Classic Plus - Classic with addition of a Battery Icon (only for horizontal panels)
  • Compact - Battery Percentage without an extended message, just the background changes (suitable for vertical panels)
  • Compact Plus - Compact with addition of Battery Icon (suitable for vertical panels)
  • Battery Icon Only - retains the coloured background showing status (suitable for vertical panels)

If a Classic mode is used on a vertical panel the extended message is not shown which allows it to be used in a vertical panel in the default 'Classic' configuration.

The right click menu gives access to some useful utilities as well as the change log and this help file.

Many laptops do not implement a suspend well. The suspend which is in use is a Suspend to Memory which is better supported than Hibernate (suspend to disk) but it does use power a little power when in that mode so it is still possible to loose work if the level is set too low or it is left too long. It is sensible to make sure the laptop does suspend reliably before trusting this applet to save work. The code for suspending is different in Mint 18 and higher to Mint 17.3 and earlier versions. The script calls both methods which should not cause problems but you can comment out the redundant one if you want in suspendScript.

Translations and other Contributions

The internal changes required in the applet to allow translations are implemented and several translations are available. Translations are usually contributed by people fluent in the language and will be very much appreciated. Users please note I will rarely be able to take responsibility for the accuracy of translations!

Although comments and suggestions are always welcome any contributions which are contemplated must follow discussion. Changes can have many unintended consequences and the integrity of the applet is paramount. Unsolicited Pull Requests will never be authorised other than for urgent and critical bug fixes from the Cinnamon Team.

Requirements:

Cinnamon Version 2.2 or higher which is available for all the Mint versions which are still supported - currently back to Mint 17.0 LTS. Cinnamon 2.6 or higher is required to support Modal Alerts. The latest versions have been tested up to Cinnamon 5.6.

For full facilities including notifications and audible alerts the zenity sox and libsox-fmt-mp3 libraries must be installed. They can be installed wih the Synaptic Package Manager or using the following terminal command:

    sudo apt-get install zenity sox libsox-fmt-mp3

Manual Installation:

  • Download from the Spices Web Site
  • Unzip and extract folder batterymonitor@pdcurtis to ~/.local/share/cinnamon/applets/
  • Install the additional programs required.
  • Enable the applet in System Settings -> Applets
  • You can also access the Settings Screen from System Settings -> Applets or from the Applets Context menu

License

Yaru icon theme (C) Canonical distributed under the CC-BY-SA 4.0 license

https://creativecommons.org/licenses/by-sa/4.0/

CHANGELOG

Open

Log In To Comment!

33 Comments

Bhante Subhtui
Bhante Subhtui-2 months ago
This was a great find! It shows me what I need to see at the right time. (original mint monitor) -> Sometimes my charger plug does not stick inside the plug (international adapters) and I don't get a good visual cue with the standard mint monitor. I also need warnings that are obvious. I normally charge, discharge and run off battery, so this applet is quite essential for me. Much appreciation for this applet.
LinuxOnTheDesktop
LinuxOnTheDesktop-6 months ago
This comment is one of appreciation. The applet is marvellous in its configurability and is highly useful. Moreover, it has worked with all the iterations of Cinnamon with which I have tried it. Well done, and thank you.
dkop11
dkop11-11 months ago
Is there any way to keep updates from wiping my CSS settings each time?
CSoellinger
CSoellinger-1 year ago
I like your extension but i would love to get a more native like applet. Best would be to fork the original power applet and "only" add the monitoring things. Two reasons why: First, i like the "black & white" icon color style. Also the a bit more detailed icons from the original are a bit niceier (battery is filling indicated by the power level). Second i like to get power informations from my bluetooth devices too. This happens if you click on the original power applet :)
Trekmate
Trekmate-1 year ago
Hi Generally very useful and reliable applet, but after update to Version 1.5.0 (2022-12-11 16:32:08) only shows icon and percentage as "--%". “Waiting” is shown on hover. Same with all toolbar display types. Tried uninstall/reinstall and zenity sox and libsox-fmt-mp3 are installed. Linux Mint 21.0, no outstanding updates. Cinnamon 5.4.12+vanessa. Any thoughts on recovering the percentage figures, please?
Trekmate
Trekmate-1 year ago
Fixed - update had reset Battery Capacity Directory to BAT0 (BAT1 needed)
Marty6
Marty6-1 year ago
This did the trick! Thank you so much!
Scrat-fflm
Scrat-fflm-2 years ago
Hello Some problems on LM 19.3 Cinnamon 4.4.8 with last BAMS update (v 1.4.1) : if the laptop is set on stanby by closing the screen, BAMS seems to be frozen when I wake the laptop from standby and always show the battery level when the laptop was set on standby, while the system battery icon shows the correct decreasing battery level. When the battery level falls near zero, BAMS always shows the same non zero level and does not send any warning, and there is the automatic shutdown from the system. This problem does not happen every time I use standby, but it happens very often. No problem if I use full shutdown ending with power off instead of standby by closing the screen. When setting power on, BAMS is OK after login : it always shows the same battery level as the system icon, and it sends a warning when the level reaches the prescribes alert level.
Peter Curtis
Peter Curtis-2 years ago
I have also seen occasional freezing dependent on how the machine is suspended but they are not limited to BAMS and occur with other Apps. A Cinnamon restart always seems to clear the problems. It does not seem very dependent on LM version but is machine dependent. Some machines can also occasionally freeze completely for close to 60 secs when suspended via recent versions of Cinnamon but never when it is repeated or after a Cinnamon restart.
Yavidh
Yavidh-2 years ago
Hello All: Is is possible to tweak this app so that suspend occurs when the battery is at 50%? I have several laptops that are getting equipped with Linux (in my effort to break away from the micromanagement of Microsoft), and when I'm not using them, I like to store them with their batteries at 50%. This prolongs lithium-ion battery life. Once a month, I pull each one out of storage, update its apps, fully charge the battery, then discharge it to 50%. It would be helpful if I could do so without having to keep a close eye on each machine during the hours it's discharging. Thanks in advance for any help you can provide.
Rajesh Pandian M
Rajesh Pandian M-3 years ago
Is there an option to add notification for battery full? It will be really helpful for laptops.
Peter Curtis
Peter Curtis-3 years ago
Rajesh, I have had a few thoughts and it needs to be implemented quite carefully so the function of the applet for existing users is not put at risk during development. The level should be adjustable as some laptops never seem to reach 100% or do so very slowly and some users try to prevent batteries being fully charged or emptied to increase life. There also needs to be 'hysteresis' built in. One way forwards is to create an Issue marked clearly as a Feature Request to gauge the level of interest and give chance for discussion of the requirements and implementation before going any further.
Peter Curtis
Peter Curtis-3 years ago
I will have a look next time I update the Applet. I thank you for your response to Juan - if you want to generate a suitable Pull Request for a change which is via an extra option in settings to I am open to merging it. Are you suggesting an alert of some form or just a more prominent [colour] change in the applet?
Juan Francisco Perez
Is there any way to go around the 40% limit to set the alert? I need to set it 100% or 99%
Rajesh Pandian M
Rajesh Pandian M-3 years ago
Edit the file at ~/.local/share/cinnamon/applets/batterymonitor@pdcurtis/3.2/applet.js find the below line and add a new line inside "if" if (this.batteryPercentage == 100 && !this.isHorizontal ) { this.set_applet_label(this.batteryMessage + this.batteryPercentage + ""); GLib.spawn_command_line_async('play ' + this.batteryLowSound); //new line to add - rajz } Now I get alert for both low battery and full battery :-) Cheers, Rajesh
Nikolay Nechaev
Nikolay Nechaev-3 years ago
This is a very cool applet. Thank you! I think, it would be a nice feature if there was some switch temporarily disabling the applet without removing it from a panel
the-big-dude
the-big-dude-3 years ago
Hello and thanks for a much needed tool. The only problem I have is that it doesn't automatically suspend the machine when I fall asleep watching a movie in VLC. Is there a way to get around this?
Peter Curtis
Peter Curtis-3 years ago
Updated ready for Cinnamon 4.6 and Mint 20 I have also noted a number of suggestions for future enhancements but I am personally not in favour of mixing functions in applets and I prefer use of a separate brightness applet if panel space permits otherwise keyboard shortcuts. Both the available brightness applets also adjust brightness on a monitor as well as the laptop screen
Andrei Miculita
Andrei Miculita-3 years ago
I also feel that a hovering scroll function for brightness is needed. The way it is right now, I see this applet as an improvement on the default battery applet in Cinnamon, so I'd expect at least feature parity. Display backlights use a lot of power, so at least for me, turning down the brightness is the first thing I think of when I want to squeeze a bit more use out of the charge I have (a belief influenced by my smartphone, but probably also applicable to laptops). When I'm in a mouse-dominant workflow, it's nice to just go to the corner on the screen and change the brightness/volume without switching to the keyboard. Besides, scrolling while hovering on this applet at the moment does nothing, so there would be no feature to replace (and therefore lose). I did try having a self-hiding side panel but I did not need any other applets beside the one for brightness, and there are many programs that have buttons of the sides of the screen when maximized, which become harder to access without triggering the side panel. Same goes for top panels, where you have the window controls, and browser tabs. If I could use this applet without it taking any space on by panel (i.e. just for the custom alerts, no icon display - which would make it more appropriate as an extension instead of an applet) and still have the default Cinnamon Battery applet, I would. But overall I like it and it has replaced the default Cinnamon Battery applet for me.
Peter Curtis
Peter Curtis-4 years ago
Updated ready for Cinnamon 4.4
FlowXP
FlowXP-4 years ago
Please please please add an option if level drops below 15% to FORCE SHUTDOWN immediately. Thank you !
Peter Curtis
Peter Curtis-4 years ago
There is already a way to cause any sort of shutdown you want in place of a suspend. It is undocumented as forcing shutdowns can lose data and configurations if not worse. The suspend is implemented via a standard script file called suspendScript in the appropriate applet folder which you can modify or even replace. Note that the changes will not be persistent and lost if you reload the applet. Use with great caution especially any 'force' options. I have deliberately not added this even as an option or linked to the script file as on other applets because of the dangers.
FlowXP
FlowXP-4 years ago
I did change the line with "systemctl suspend" into "shutdown" but the still the laptop went into sleep mode. The batterymonitorwarning.mp3 does not play if selected from applet in "Battery Low Alert Settings"
FlowXP
FlowXP-4 years ago
Should I add a forced shutdown if level drops to say 5% ... ? Yes, but it safer for the battery to be at least 15%
FlowXP
FlowXP-4 years ago
I have read the readme.md file and understand that "The intention is to allow the possibility of leaving suspend with enough battery to close programs and shut down after powering up from suspend without a charger after an accidental unattended suspend. It is suggested that the 'shutdown level' is set to about 10% to allow time. Do not forget that the battery still drains, although slowly, during suspend." But for example in my case I just need when the battery reaches 20% to force shutdown, no questions asked. So it wold be very usefull to just have a warning at 40% and force shutdown at 20%
FlowXP
FlowXP-4 years ago
Hello, the applet looks awesome but it does not shutdown, just stand by.
jxpx666
jxpx666-4 years ago
Great applet! Perfect for my personal use. My opinion: the lack of a feature: while hovering the panel icon with the mouse, it should respond to mouse scroll wheel down and up , the command should be the decrease or increase the light level of monitor (like the sound applet). This is the only feature that the original battery cinnamon applet do not lack in comparison. It would be great
Bundy01
Bundy01-4 years ago
Hello, the applet is no longer compatible with Cinnamon 4.2. Can you do the update. Thank you.
Peter Curtis
Peter Curtis-4 years ago
Updated for Cinnamon 4.2
pranavsrivatsav
pranavsrivatsav-4 years ago
Hi, The indicator works well, and having the alert front and center with alarm really helps. Thanks for the great work. Have 2 requests: 1. Another alert for when the battery is almost full (>80 - User variable). 2. A scroll action to change brightness similar to the inbuilt power manager applet. Running an aging laptop here and battery management is one of the important maintenance tasks and your applet makes the task slightly easier. I'm sure many of the Cinnamon users will appreciate the implementation of the above requests. Thanks once again.
Peter Curtis
Peter Curtis-4 years ago
The Applet was written with preservation of data in mind rather than battery management although that is also important. There is good evidence that a total discharge or even a discharge down to a few percent is bad for batteries. At the other end the battery management is handled well by the laptop/battery manufacturers who have all the optimisation data available so I have never seen an up limit as anything other than a convenience. I always leave my laptops on mains power continuously when at home where I use an external monitor, mouse and keyboard. If you want an alert it would be best to use a separate applet and mine could easily be 'reversed' in a few checks to do that and I can see you are a programmer familiar with git and my applet is reasonably commented. Again I think the way the battery and brightness are combined in one applet is wrong. A separate brightness applet has uses but [almost] every laptop has keys for changing brightness or a hot key can be programmed from a keyboard. The only justification for combining disparate functions is to save panel space on a small screen but adding a 'self hiding' vertical panel is more flexible to my mind.
The Clown
The Clown-6 years ago
Thanks, indicator works well, but my battery still will not charge (internal, HP Pavillion 15-AW053NR). I know it is not anything you can do, and I do appreciate your work and the awesome applet, so thanks again! The only thing that activates the charger is an overnight visit to the freezer for the laptop and power supply.
Peter Curtis
Peter Curtis-6 years ago
As the author I am committed to maintaining and developing this and all my other applets. I can be contacted here however posting a comment does not automatically cause me to be notified so if you want a rapid response please also alert me via http://www.pcurtis.com/contact_form.htm?applets . On github, @pdcurtis in any conversation should cause a copy to be emailed to me. Please take the time to 'like' applets you find useful even if you do not comment, it is a great motivator for the authors