UPS monitoring
==============
`NUT <https://networkupstools.org>`__ UPS monitoring and notifications
via Telegram notification or email or both.
Use case
--------
Connect your primary internet router to UPS (e.g., CyberPower) to
protect your network internet connectivity (and internal WiFi, ZigBee)
from power outage (e.g., accident or sabotage). You may have backup LTE
modem installed should power outage disable the primary link.
With UPS backup your internal network keeps running. Commodity models of
UPSs do not provide notification on status change so if you are not
physically present on premise, you won’t get notified of such event.
This package helps with that. It is supposed to be running on a PC
(e.g., RPi) connected via USB to the UPS, powered by the UPS as well. On
the PC, `NUT <https://networkupstools.org>`__ should be configured to
monitor UPS state (`setup
tutorial <https://www.howtoraspberry.com/2020/11/how-to-monitor-ups-with-raspberry-pi/>`__).
This package then collects events from
`NUT <https://networkupstools.org>`__ and continuously monitors UPSs
state. For example, when UPS state changes, you get an email and
Telegram notification about such event. Also, if UPS is running on
battery, you get periodic heartbeat status message on Telegram so you
know expected battery running time and to see that system is still
operating.
::
┌──────────┐
USB link │ RPi │
┌───────────┤ │
│ └───┬────┬─┘
┌──────┴───────┐ │ │
┌──────┐ │ │ │
│Power ├───┤ UPS ├───────┤ │
└──────┘ │ │ │ Eth
└──────────────┘ │ │
┌───┴────┴─┐
│ WiFi │
│ router │
└──────────┘
Setup
-----
- pip-install this package ``pip install -U ph4-upsmonit``
- Configure ``config.json`` according to
`assets/config-example.json <assets/config-example.json>`__
- Configure notification channels, either
- `Telegram
bot <https://www.teleme.io/articles/create_your_own_telegram_bot?hl=en>`__
- or Email sender (e.g.,
`Gmail <https://www.lifewire.com/get-a-password-to-access-gmail-by-pop-imap-2-1171882>`__)
or both
- Run ``assets/install.sh`` to install ``ph4upsmon.service`` systemd
service
- Configure `NUT <https://networkupstools.org>`__ to send events to
``ph4upsmon`` as install script instructs you
- Run ``systemctl start ph4upsmon.service``
Notification examples
---------------------
System startup:
::
UPS state report [OL, age=0.00]: {
"battery.charge": 100.0,
"battery.runtime": 13370.0,
"battery.voltage": 26.8,
"input.voltage": 242.0,
"output.voltage": 242.0,
"ups.load": 0.0,
"ups.status": "OL",
"ups.test.result": "No test initiated",
"meta.battery.runtime.m": 222.6,
"meta.time_check": 1674067083.7017221,
"meta.dt_check": "01/18/2023, 18:38:04"
}
System is running on battery
::
UPS state report [OB DISCHRG, age=0.00]: {
"battery.charge": 100.0,
"battery.runtime": 13370.0,
"battery.voltage": 26.8,
"input.voltage": 242.0,
"output.voltage": 242.0,
"ups.load": 0.0,
"ups.status": "OB DISCHRG",
"ups.test.result": "No test initiated",
"meta.battery.runtime.m": 222.6,
"meta.time_check": 1674067076.121453,
"meta.dt_check": "01/18/2023, 18:37:56"
}
Telegram channel gets updated regularly until state of the UPS returns
back to normal. Note that ``meta.battery.runtime.m`` field shows
remaining battery time estimation in minutes.
Telegram bot supports also several commands, e.g., ``/status`` and
``/full_status``, to which it responds with current state. You can
manually request status information and to check that system is
responsive.
Note that Email notifier sends only state changes, while Telegram
notifier sends also regular state updates when UPS is running on the
battery. If email user is empty, email notifier is not use. Likewise, if
bot API key is empty, telegram is not used.
Usage
-----
Send ``/help`` message to the Telegram bot
::
Help:
/start - register
/stop - deregister
/status - brief status
/full_status - full status
/log - log of latest events
/noemail - disable email reporting
/doemail - enable email reporting
/doedit <time> - edit last status message instead of sending a new one. Time to edit the old message in seconds.
Dependencies
------------
This project uses monitoring tool library
https://github.com/ph4r05/ph4-monitlib
Similar project for monitoring network connections (SSH tunnels):
https://github.com/ph4r05/ph4-connmon
Raw data
{
"_id": null,
"home_page": "https://github.com/ph4r05/ph4-upsmonit",
"name": "ph4-upsmonit",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Dusan Klinec",
"author_email": "dusan.klinec@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/12/53/d2e14098f18ff91bd6329a2868edbf03b1efcf64226f6908ca4348fa6368/ph4-upsmonit-0.0.8.tar.gz",
"platform": null,
"description": "UPS monitoring\n==============\n\n`NUT <https://networkupstools.org>`__ UPS monitoring and notifications\nvia Telegram notification or email or both.\n\nUse case\n--------\n\nConnect your primary internet router to UPS (e.g., CyberPower) to\nprotect your network internet connectivity (and internal WiFi, ZigBee)\nfrom power outage (e.g., accident or sabotage). You may have backup LTE\nmodem installed should power outage disable the primary link.\n\nWith UPS backup your internal network keeps running. Commodity models of\nUPSs do not provide notification on status change so if you are not\nphysically present on premise, you won\u2019t get notified of such event.\n\nThis package helps with that. It is supposed to be running on a PC\n(e.g., RPi) connected via USB to the UPS, powered by the UPS as well. On\nthe PC, `NUT <https://networkupstools.org>`__ should be configured to\nmonitor UPS state (`setup\ntutorial <https://www.howtoraspberry.com/2020/11/how-to-monitor-ups-with-raspberry-pi/>`__).\n\nThis package then collects events from\n`NUT <https://networkupstools.org>`__ and continuously monitors UPSs\nstate. For example, when UPS state changes, you get an email and\nTelegram notification about such event. Also, if UPS is running on\nbattery, you get periodic heartbeat status message on Telegram so you\nknow expected battery running time and to see that system is still\noperating.\n\n::\n\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n USB link \u2502 RPi \u2502\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 \u2502\n \u2502 \u2514\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u252c\u2500\u2518\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502 \u2502\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502 \u2502 \u2502\n \u2502Power \u251c\u2500\u2500\u2500\u2524 UPS \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502 \u2502 \u2502 Eth\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502 \u2502\n \u250c\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2534\u2500\u2510\n \u2502 WiFi \u2502\n \u2502 router \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\nSetup\n-----\n\n- pip-install this package ``pip install -U ph4-upsmonit``\n- Configure ``config.json`` according to\n `assets/config-example.json <assets/config-example.json>`__\n- Configure notification channels, either\n\n - `Telegram\n bot <https://www.teleme.io/articles/create_your_own_telegram_bot?hl=en>`__\n - or Email sender (e.g.,\n `Gmail <https://www.lifewire.com/get-a-password-to-access-gmail-by-pop-imap-2-1171882>`__)\n or both\n\n- Run ``assets/install.sh`` to install ``ph4upsmon.service`` systemd\n service\n- Configure `NUT <https://networkupstools.org>`__ to send events to\n ``ph4upsmon`` as install script instructs you\n- Run ``systemctl start ph4upsmon.service``\n\nNotification examples\n---------------------\n\nSystem startup:\n\n::\n\n UPS state report [OL, age=0.00]: {\n \"battery.charge\": 100.0,\n \"battery.runtime\": 13370.0,\n \"battery.voltage\": 26.8,\n \"input.voltage\": 242.0,\n \"output.voltage\": 242.0,\n \"ups.load\": 0.0,\n \"ups.status\": \"OL\",\n \"ups.test.result\": \"No test initiated\",\n \"meta.battery.runtime.m\": 222.6,\n \"meta.time_check\": 1674067083.7017221,\n \"meta.dt_check\": \"01/18/2023, 18:38:04\"\n }\n\nSystem is running on battery\n\n::\n\n UPS state report [OB DISCHRG, age=0.00]: {\n \"battery.charge\": 100.0,\n \"battery.runtime\": 13370.0,\n \"battery.voltage\": 26.8,\n \"input.voltage\": 242.0,\n \"output.voltage\": 242.0,\n \"ups.load\": 0.0,\n \"ups.status\": \"OB DISCHRG\",\n \"ups.test.result\": \"No test initiated\",\n \"meta.battery.runtime.m\": 222.6,\n \"meta.time_check\": 1674067076.121453,\n \"meta.dt_check\": \"01/18/2023, 18:37:56\"\n }\n\nTelegram channel gets updated regularly until state of the UPS returns\nback to normal. Note that ``meta.battery.runtime.m`` field shows\nremaining battery time estimation in minutes.\n\nTelegram bot supports also several commands, e.g., ``/status`` and\n``/full_status``, to which it responds with current state. You can\nmanually request status information and to check that system is\nresponsive.\n\nNote that Email notifier sends only state changes, while Telegram\nnotifier sends also regular state updates when UPS is running on the\nbattery. If email user is empty, email notifier is not use. Likewise, if\nbot API key is empty, telegram is not used.\n\nUsage\n-----\n\nSend ``/help`` message to the Telegram bot\n\n::\n\n Help: \n /start - register\n /stop - deregister\n /status - brief status\n /full_status - full status\n /log - log of latest events\n /noemail - disable email reporting\n /doemail - enable email reporting\n /doedit <time> - edit last status message instead of sending a new one. Time to edit the old message in seconds.\n\nDependencies\n------------\n\nThis project uses monitoring tool library\nhttps://github.com/ph4r05/ph4-monitlib\n\nSimilar project for monitoring network connections (SSH tunnels):\nhttps://github.com/ph4r05/ph4-connmon\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "UPS Monitoring tool",
"version": "0.0.8",
"project_urls": {
"Homepage": "https://github.com/ph4r05/ph4-upsmonit"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1253d2e14098f18ff91bd6329a2868edbf03b1efcf64226f6908ca4348fa6368",
"md5": "b90934e1d82e4465c96ab328aac69913",
"sha256": "5350af909372fd6d515face9ac99aa78ced3cfa2add347ceeee4b2d8a47e945e"
},
"downloads": -1,
"filename": "ph4-upsmonit-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "b90934e1d82e4465c96ab328aac69913",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12992,
"upload_time": "2023-09-24T07:28:25",
"upload_time_iso_8601": "2023-09-24T07:28:25.830986Z",
"url": "https://files.pythonhosted.org/packages/12/53/d2e14098f18ff91bd6329a2868edbf03b1efcf64226f6908ca4348fa6368/ph4-upsmonit-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-24 07:28:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ph4r05",
"github_project": "ph4-upsmonit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ph4-upsmonit"
}
JSON
