Battery Applet with Monitoring and Shutdown (BAMS)
Battery Applet with Monitoring and Shutdown (BAMS)
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%.
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.
Fully supported by Author, under continuing development and in continuous use on several of his machines.
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.
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 been tested up to Cinnamon 3.8 and no changes are expected for 4.0.
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
- Download from the Spices Web Site
- Unzip and extract folder
- 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
- Updates README.md to stress audio file must be .oga mime type audio/x-vorbis+ogg - the mime type is crucial to it being recognised by the soundfilechoser widget
- Cinnamon versions up to 5.2
- Removes dependency on 'batteryscript.sh'. This script writes two files on every update, maybe wearing out the harddisk. Now it uses asyncronous calls to execute the 'upower' command directly and captures its output.
- Checks for dependency on 'upower'.
- Increases maximum refresh interval to 5 min (300 s).
- Simplification of the logic to select the icon to display.
- Removes (outdated) 3.2/changelog.txt.
- Added a button to the configuration box to delete the old temporary files.
- Updated cinnamon version to 4.4.
- Adds events-sounds property to soundfilechoser widget to allow any sound file to be selected under Cinnamon 4.2
- Adds additional option to inhibit notifications when user selected audible alert is in use
- closes feature request #2511
- Change location of temporary files to home folder to avoid permissions problem when switching users
- Fixes #2502
- Change to cinnamon-version in metadata.json to add use under Cinnamon 4.2
- Change to allow Multiversion 3.2
- Change to allow selection of audible alert file in Applet Settings for 3.2 and higher.
- puts up warning about high volumes and times in public spaces.
- Translation File update only
- Update stylesheet to better match Cinnamon 4.0 System Styles - less rounded.
- Add an initial mechanism to provide persistence for user edits of the stylesheet.
- Use ModalDialog.NotifyDialog or main.criticalNotify in place of internal code for Alerts
- Provide option of users sound file called batterymonitorwarning.mp3 in home folder
- Checks for presence and uses if found otherwises uses default
- puts up warning about high volumes and times in public spaces.
- Use xdg-open in place of gedit or xed to allow use on more distros
- Add checks that sox and zenity are installed and warn that full facilities are not available without them.
- Remove instance of depreciated code giving a harmless warning in .xsession-errors.
- Update batterymonitor.pot so translations can be updated.
Bug Fix for use with early versions of Cinnamon
- Inhibited use of hide_applet_label() to Cinnamon version 3.2 or higher in vertical panels.
Major update - now includes support for Vertical Panels, Battery icons and 5 Display Modes
- Renamed batterytempscript to batteryscript - cosmetic
- Change to improved form of l10n support function
- Code added to allow display on vertical panels and added on_orientation_changed function with call to initialise.
- Options of display of icon and shortening message text with prime aim of support of vertical panels
- Display Modes added to Configuration as Dropdown with 5 types (modes) and implemented. Includes a Classic mode which is the same as version 1.2.3 of applet.
- Removed some redundant code still present from earlier versions which affected vertical display
- Code comments improved and some commented out code removed.
- Update README.md, CHANGELOG.md and metadata.json
- Recreate batterymonitor.pot to allow translation support to be updated.
- Added CHANGELOG.md to applet folder with symbolic link to it in UUID so it shows on latest cinnamon spices web site.
- CHANGELOG.md is a simplified and reformatted version of changelog.txt which currently remains in applet folder.
- Changed 'view changelog' in context menu to use CHANGELOG.md
- Changed to use a symbolic link for README.md
- Changes to text strings to remove spaces from start and end of strings for translation
- Some extra strings marked for translation
- Version numbering harmonised with other Cinnamon applets and added to metadata.json so it shows in 'About...'
- icon.png copied back into applet folder so it shows in 'About...'
- Added audible warning at alert stage (requested)
- Added 'discharging' indication via border colour (requested)
- Move audible alert from suspendScript to applet
- Added translation support to applet.js and identified strings
- Updated documentation and tidied comments in applet
- Initial transition to new cinnamon-spices-applets repository from github.com/pdcurtis/cinnamon-applets
- Changed help file from help.txt to README.md, updated and put copy in UUID.
- Added ability to edit stylesheet.css to context menu.
- Added warnings about editing to stylesheet.css
- Initial Release 16-07-2016
- Developed using code from NUMA, Bumblebee and Timer Applets
- Includes changes to work with Mint 18 and Cinnamon 3.0 (gedit -> xed)
- Tested with Cinnamon 3.0 in Mint 18 and Cinnamon 2.4 in Mint 17.1