# Pichondria Library
[](https://pypi.org/project/pichondria/)
[](https://opensource.org/licenses/MIT)
## Description
Pichondria is a Python library designed to communicate with and configure the Pichondria UPS HAT for Raspberry Pi. The Pichondria UPS HAT is a power management solution that provides uninterruptible power supply functionality to Raspberry Pi devices.
With the Pichondria library, you can easily interact with the Pichondria UPS HAT using I2C communication from your Raspberry Pi. It allows you to monitor battery status, input voltage, output load, and perform various power management tasks.
**Key Features**
- Read battery status, voltage, and capacity
- Monitor input voltage and output load
- Configure UPS settings, such as startup voltage, shutdown voltage, wake-up timer, shutdown timer, and boot-up timer
- Enable/disable autopilot mode for automatic boot-up after a battery low shutdown
- Initiate shutdown, reboot, and scheduled shutdown commands
## Hardware
Pichondria hardware specifications and details can be found at [Pichondria Official Website](https://pichondria.com)
## Overview of functions
| Function Name | Arguments | Response | Bandwidth Usage | Requires Applying to take effect |
|-----------------------------|----------------------------------|----------------------------------------------------------|-----------------|----------------------------------|
| apply_settings | None | Returns True if settings applied successfully, False if not | NA | NA |
| check_shutdown | None | Returns True if shutdown command is received from Pichondria, False if not | Higher | NA |
| check_shutdown_ad | pichondria_address (hex) | Returns True if shutdown command is received from Pichondria, False if not | Lower | NA |
| enable_acknowledgement_mode | None | Returns True if acknowledgement mode enabling is successful, False if not | NA | No |
| disable_acknowledgement_mode| None | Returns True if acknowledgement mode disabling is successful, False if not | NA | No |
| check_acknowledgement_mode | None | Returns True if acknowledgement mode is enabled, False otherwise | NA | NA |
| enable_autopilot | None | Returns True if autopilot mode enabling is successful, False if not | NA | No |
| disable_autopilot | None | Returns True if autopilot mode disabling is successful, False if not | NA | No |
| check_autopilot_mode | None | Returns True if autopilot mode is enabled, False otherwise | NA | NA |
| get_battery_voltage | None | Returns the battery voltage as a float | Higher | NA |
| get_battery_voltage_ad | pichondria_address (hex) | Returns the battery voltage as a float | Lower | NA |
| get_bootup_timer | None | Returns the boot-up timer value as an int | NA | NA |
| get_input_voltage | None | Returns the input voltage as a float | Higher | NA |
| get_input_voltage_ad | pichondria_address (hex) | Returns the input voltage as a float | Lower | NA |
| get_output_voltage | None | Returns the output voltage as a float | Higher | NA |
| get_output_voltage_ad | pichondria_address (hex) | Returns the output voltage as a float | Lower | NA |
| get_pichondria_address | None | Returns the address of the Pichondria device | NA | NA |
| get_shutdown_timer | None | Returns the shutdown timer value as an int | NA | NA |
| get_shutdown_voltage | None | Returns the shutdown voltage as a float | NA | NA |
| get_startup_voltage | None | Returns the startup voltage as a float | NA | NA |
| get_wake_up_timer | None | Returns the wake-up timer value as an int | NA | NA |
| input_availability | None | Returns True if input power is available, False if not | Higher | NA |
| input_availability_ad | pichondria_address (hex) | Returns True if input power is available, False if not | Lower | NA |
| is_charging | None | Returns True if the battery is charging, False if not | Higher | NA |
| is_charging_ad | pichondria_address (hex) | Returns True if the battery is charging, False if not | Lower | NA |
| req_power_restore_shutdown | None | Returns True if power restore shutdown requested successfully, False if not | Higher | NA |
| req_power_restore_shutdown_ad| pichondria_address (hex) | Returns True if power restore shutdown requested successfully, False if not | Lower | NA |
| req_reboot | None | Returns True if reboot requested successfully, False if not | Higher | NA |
| req_reboot_ad | pichondria_address (hex) | Returns True if reboot requested successfully, False if not | Lower | NA |
| req_scheduled_reboot | None | Returns True if scheduled reboot requested successfully, False if not | Higher | NA |
| req_scheduled_reboot_ad | pichondria_address (hex) | Returns True if scheduled reboot requested successfully, False if not | Lower | NA |
| req_shutdown | None | Returns True if shutdown requested successfully, False if not | Higher | NA |
| req_shutdown_ad | pichondria_address (hex) | Returns True if shutdown requested successfully, False if not | Lower | NA |
| send_acknowledgement | None | Returns True if acknowledgement sent successfully, False if not | NA | NA |
| set_bootup_timer | timer (int) | Returns True if boot-up timer set successfully, False if not | NA | Yes |
| set_pichondria_address | address (hex) | Returns True if successful, False if not | NA | No |
| set_shutdown_timer | timer (int) | Returns True if shutdown timer set successfully, False if not | NA | Yes |
| set_shutdown_voltage | voltage (float) | Returns True if shutdown voltage set successfully, False if not | NA | Yes |
| set_startup_voltage | voltage (float) | Returns True if startup voltage set successfully, False if not | NA | Yes |
| set_wake_up_timer | timer (int) | Returns True if wake-up timer set successfully, False if not | NA | Yes |
When communicating with the Pichondria, since the address of Pichondria is configurable, in normal usage, the Raspberry Pi reads the address of Pichondria from the EEPROM and then communicates with the address read from EEPROM. To lower the communication required, you can use 'get_pichondria_address( )' and then pass on the address to all functions which end with _ad. This reduces the number of bits by ~33% in the I2C bus.
Some functions need 'apply_settings( )' to take effect. If any variables are changed in EEPROM and not applied, the system will not work as expected. Always apply changes.
## Installation
You can install `pichondria` using pip. Make sure you have Python 3.6+ installed.
```bash
pip install pichondria
```
## Usage
To get started with Pichondria, import the library and create an instance of the Pichondria class:
Creating instance of Pichondria:
```bash
import pichondria
```
### Getting the Pichondria I2C Address
```bash
pichondria_address = pichondria.get_pichondria_address()
```
### Setting the Pichondria I2C Address
```bash
new_address = 0x51 # Replace this with the desired address (e.g., 0x51)
success = pichondria.set_pichondria_address(new_address)
if success:
print(f"Pichondria I2C Address set to {hex(new_address)} successfully!")
else:
print("Failed to set Pichondria I2C Address.")
```
### Checking Input Availability
```bash
input_available = pichondria.input_availability()
```
### Checking Charging Status
```bash
charging_status = pichondria.is_charging()
```
### Getting Input Voltage
```bash
input_voltage = pichondria.get_input_voltage()
```
### Getting Output Voltage
```bash
output_voltage = pichondria.get_output_voltage()
```
### Getting Battery Voltage
```bash
battery_voltage = pichondria.get_battery_voltage()
```
### Applying Settings
```bash
pichondria.apply_settings()
```
### Configuring Startup Voltage
```bash
pichondria.set_startup_voltage(3.4)
pichondria.apply_changes()
```
### Configuring Shutdown Voltage
```bash
pichondria.set_shutdown_voltage(3.4)
pichondria.apply_changes()
```
### Configuring Wake-Up Timer
```bash
pichondria.set_wake_up_timer(1800)
pichondria.apply_changes()
```
### Configuring Shutdown Timer
```bash
pichondria.set_shutdown_timer(120)
pichondria.apply_changes()
```
### Configuring Boot-Up Timer
```bash
pichondria.set_bootup_timer(30)
pichondria.apply_changes()
```
### Enabling/Disabling/Checking Autopilot Mode
```bash
pichondria.enable_autopilot()
pichondria.disable_autopilot()
pichondria.check_autopilot_mode()
```
### Enabling/Disabling/Checking Acknowledgement Mode
```bash
pichondria.enable_acknowledgement_mode()
pichondria.disable_acknowledgement_mode()
pichondria.check_acknowledgement_mode()
```
### Sending Acknowledgement
```bash
pichondria.send_acknowledgement()
```
### Checking Shutdown Request
```bash
shutdown_requested = pichondria.check_shutdown()
if shutdown_requested:
if acknowledgement_mode_enabled:
pichondria.send_acknowledgement()
subprocess.run(["sudo", "shutdown", "now"])
```
## License
Pichondria code is released under the MIT License
## Contact
For support or any inquiries, you can reach out to us at support@pichondria.com
Raw data
{
"_id": null,
"home_page": "https://github.com/pichondria/pichondria",
"name": "pichondria",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "Python,Pichondria,UPS,UPS HAT,Pichondria UPS,RaspberryPi,RPi",
"author": "John KG, Pichondria",
"author_email": "pichondria@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/13/94/3041ef4b0bc8b89702f4704362c3d53b8aa88a31477159acb3fa6ed81c23/pichondria-1.0.2.tar.gz",
"platform": null,
"description": "# Pichondria Library\n\n[](https://pypi.org/project/pichondria/)\n[](https://opensource.org/licenses/MIT)\n\n## Description\n\nPichondria is a Python library designed to communicate with and configure the Pichondria UPS HAT for Raspberry Pi. The Pichondria UPS HAT is a power management solution that provides uninterruptible power supply functionality to Raspberry Pi devices.\n\nWith the Pichondria library, you can easily interact with the Pichondria UPS HAT using I2C communication from your Raspberry Pi. It allows you to monitor battery status, input voltage, output load, and perform various power management tasks.\n\n**Key Features**\n\n- Read battery status, voltage, and capacity\n- Monitor input voltage and output load\n- Configure UPS settings, such as startup voltage, shutdown voltage, wake-up timer, shutdown timer, and boot-up timer\n- Enable/disable autopilot mode for automatic boot-up after a battery low shutdown\n- Initiate shutdown, reboot, and scheduled shutdown commands\n\n## Hardware\nPichondria hardware specifications and details can be found at [Pichondria Official Website](https://pichondria.com)\n\n## Overview of functions\n| Function Name | Arguments | Response | Bandwidth Usage | Requires Applying to take effect |\n|-----------------------------|----------------------------------|----------------------------------------------------------|-----------------|----------------------------------|\n| apply_settings | None | Returns True if settings applied successfully, False if not | NA | NA |\n| check_shutdown | None | Returns True if shutdown command is received from Pichondria, False if not | Higher | NA |\n| check_shutdown_ad | pichondria_address (hex) | Returns True if shutdown command is received from Pichondria, False if not | Lower | NA |\n| enable_acknowledgement_mode | None | Returns True if acknowledgement mode enabling is successful, False if not | NA | No |\n| disable_acknowledgement_mode| None | Returns True if acknowledgement mode disabling is successful, False if not | NA | No |\n| check_acknowledgement_mode | None | Returns True if acknowledgement mode is enabled, False otherwise | NA | NA |\n| enable_autopilot | None | Returns True if autopilot mode enabling is successful, False if not | NA | No |\n| disable_autopilot | None | Returns True if autopilot mode disabling is successful, False if not | NA | No |\n| check_autopilot_mode | None | Returns True if autopilot mode is enabled, False otherwise | NA | NA |\n| get_battery_voltage | None | Returns the battery voltage as a float | Higher | NA |\n| get_battery_voltage_ad | pichondria_address (hex) | Returns the battery voltage as a float | Lower | NA |\n| get_bootup_timer | None | Returns the boot-up timer value as an int | NA | NA |\n| get_input_voltage | None | Returns the input voltage as a float | Higher | NA |\n| get_input_voltage_ad | pichondria_address (hex) | Returns the input voltage as a float | Lower | NA |\n| get_output_voltage | None | Returns the output voltage as a float | Higher | NA |\n| get_output_voltage_ad | pichondria_address (hex) | Returns the output voltage as a float | Lower | NA |\n| get_pichondria_address | None | Returns the address of the Pichondria device | NA | NA |\n| get_shutdown_timer | None | Returns the shutdown timer value as an int | NA | NA |\n| get_shutdown_voltage | None | Returns the shutdown voltage as a float | NA | NA |\n| get_startup_voltage | None | Returns the startup voltage as a float | NA | NA |\n| get_wake_up_timer | None | Returns the wake-up timer value as an int | NA | NA |\n| input_availability | None | Returns True if input power is available, False if not | Higher | NA |\n| input_availability_ad | pichondria_address (hex) | Returns True if input power is available, False if not | Lower | NA |\n| is_charging | None | Returns True if the battery is charging, False if not | Higher | NA |\n| is_charging_ad | pichondria_address (hex) | Returns True if the battery is charging, False if not | Lower | NA |\n| req_power_restore_shutdown | None | Returns True if power restore shutdown requested successfully, False if not | Higher | NA |\n| req_power_restore_shutdown_ad| pichondria_address (hex) | Returns True if power restore shutdown requested successfully, False if not | Lower | NA |\n| req_reboot | None | Returns True if reboot requested successfully, False if not | Higher | NA |\n| req_reboot_ad | pichondria_address (hex) | Returns True if reboot requested successfully, False if not | Lower | NA |\n| req_scheduled_reboot | None | Returns True if scheduled reboot requested successfully, False if not | Higher | NA |\n| req_scheduled_reboot_ad | pichondria_address (hex) | Returns True if scheduled reboot requested successfully, False if not | Lower | NA |\n| req_shutdown | None | Returns True if shutdown requested successfully, False if not | Higher | NA |\n| req_shutdown_ad | pichondria_address (hex) | Returns True if shutdown requested successfully, False if not | Lower | NA |\n| send_acknowledgement | None | Returns True if acknowledgement sent successfully, False if not | NA | NA |\n| set_bootup_timer | timer (int) | Returns True if boot-up timer set successfully, False if not | NA | Yes |\n| set_pichondria_address | address (hex) | Returns True if successful, False if not | NA | No |\n| set_shutdown_timer | timer (int) | Returns True if shutdown timer set successfully, False if not | NA | Yes |\n| set_shutdown_voltage | voltage (float) | Returns True if shutdown voltage set successfully, False if not | NA | Yes |\n| set_startup_voltage | voltage (float) | Returns True if startup voltage set successfully, False if not | NA | Yes |\n| set_wake_up_timer | timer (int) | Returns True if wake-up timer set successfully, False if not | NA | Yes |\n\n\nWhen communicating with the Pichondria, since the address of Pichondria is configurable, in normal usage, the Raspberry Pi reads the address of Pichondria from the EEPROM and then communicates with the address read from EEPROM. To lower the communication required, you can use 'get_pichondria_address( )' and then pass on the address to all functions which end with _ad. This reduces the number of bits by ~33% in the I2C bus.\n\nSome functions need 'apply_settings( )' to take effect. If any variables are changed in EEPROM and not applied, the system will not work as expected. Always apply changes.\n\n\n## Installation\n\nYou can install `pichondria` using pip. Make sure you have Python 3.6+ installed.\n\n```bash\npip install pichondria\n```\n\n## Usage\nTo get started with Pichondria, import the library and create an instance of the Pichondria class:\n\nCreating instance of Pichondria:\n```bash\nimport pichondria\n```\n\n### Getting the Pichondria I2C Address\n```bash\npichondria_address = pichondria.get_pichondria_address()\n```\n\n### Setting the Pichondria I2C Address\n```bash\nnew_address = 0x51 # Replace this with the desired address (e.g., 0x51)\nsuccess = pichondria.set_pichondria_address(new_address)\nif success:\n print(f\"Pichondria I2C Address set to {hex(new_address)} successfully!\")\nelse:\n print(\"Failed to set Pichondria I2C Address.\")\n```\n\n### Checking Input Availability\n```bash\ninput_available = pichondria.input_availability()\n```\n\n### Checking Charging Status\n```bash\ncharging_status = pichondria.is_charging()\n```\n\n### Getting Input Voltage\n```bash\ninput_voltage = pichondria.get_input_voltage()\n```\n\n### Getting Output Voltage\n```bash\noutput_voltage = pichondria.get_output_voltage()\n```\n\n### Getting Battery Voltage\n```bash\nbattery_voltage = pichondria.get_battery_voltage()\n```\n\n### Applying Settings\n```bash\npichondria.apply_settings()\n```\n\n### Configuring Startup Voltage\n```bash\npichondria.set_startup_voltage(3.4)\npichondria.apply_changes()\n```\n\n### Configuring Shutdown Voltage\n```bash\npichondria.set_shutdown_voltage(3.4)\npichondria.apply_changes()\n```\n\n### Configuring Wake-Up Timer\n```bash\npichondria.set_wake_up_timer(1800)\npichondria.apply_changes()\n```\n\n### Configuring Shutdown Timer\n```bash\npichondria.set_shutdown_timer(120)\npichondria.apply_changes()\n```\n\n### Configuring Boot-Up Timer\n```bash\npichondria.set_bootup_timer(30)\npichondria.apply_changes()\n```\n\n### Enabling/Disabling/Checking Autopilot Mode\n```bash\npichondria.enable_autopilot()\npichondria.disable_autopilot()\npichondria.check_autopilot_mode()\n```\n\n### Enabling/Disabling/Checking Acknowledgement Mode\n```bash\npichondria.enable_acknowledgement_mode()\npichondria.disable_acknowledgement_mode()\npichondria.check_acknowledgement_mode()\n```\n\n### Sending Acknowledgement\n```bash\npichondria.send_acknowledgement()\n```\n\n### Checking Shutdown Request\n```bash\nshutdown_requested = pichondria.check_shutdown()\nif shutdown_requested:\n if acknowledgement_mode_enabled:\n pichondria.send_acknowledgement()\n subprocess.run([\"sudo\", \"shutdown\", \"now\"])\n```\n\n## License\nPichondria code is released under the MIT License\n\n\n## Contact\nFor support or any inquiries, you can reach out to us at support@pichondria.com\n",
"bugtrack_url": null,
"license": "",
"summary": "Pichondria library is the official library to communicate with Pichondria UPS HAT for RaspberryPi over I2C. https://pichondria.com",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/pichondria/pichondria"
},
"split_keywords": [
"python",
"pichondria",
"ups",
"ups hat",
"pichondria ups",
"raspberrypi",
"rpi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f0211f1d059228b3857fbd8784811264d66f9e727d02aad56a8c5f2caff0579a",
"md5": "e51c21c56646508169b3012974ee0d13",
"sha256": "896bc30f9196c2a49fbe1b7ee5633b58de81a8a8eb271f4fc23fb45c5cd86666"
},
"downloads": -1,
"filename": "pichondria-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e51c21c56646508169b3012974ee0d13",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 5947,
"upload_time": "2024-02-05T10:04:53",
"upload_time_iso_8601": "2024-02-05T10:04:53.328315Z",
"url": "https://files.pythonhosted.org/packages/f0/21/1f1d059228b3857fbd8784811264d66f9e727d02aad56a8c5f2caff0579a/pichondria-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "13943041ef4b0bc8b89702f4704362c3d53b8aa88a31477159acb3fa6ed81c23",
"md5": "772f9aa28b34883e0763a79a89a8f0a4",
"sha256": "b19e9959ac13c490c89c0b39c8f39a131cbb5c4cc18aafca612e46d39455cec7"
},
"downloads": -1,
"filename": "pichondria-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "772f9aa28b34883e0763a79a89a8f0a4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 8407,
"upload_time": "2024-02-05T10:04:56",
"upload_time_iso_8601": "2024-02-05T10:04:56.274612Z",
"url": "https://files.pythonhosted.org/packages/13/94/3041ef4b0bc8b89702f4704362c3d53b8aa88a31477159acb3fa6ed81c23/pichondria-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-05 10:04:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pichondria",
"github_project": "pichondria",
"github_not_found": true,
"lcname": "pichondria"
}
JSON
