pichondria 1.0.2

Pichondria library is the official library to communicate with Pichondria UPS HAT for RaspberryPi over I2C. https://pichondria.com

Pichondria Library

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

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.

pip install pichondria

Usage

To get started with Pichondria, import the library and create an instance of the Pichondria class:

Creating instance of Pichondria:

import pichondria

Getting the Pichondria I2C Address

pichondria_address = pichondria.get_pichondria_address()

Setting the Pichondria I2C Address

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

input_available = pichondria.input_availability()

Checking Charging Status

charging_status = pichondria.is_charging()

Getting Input Voltage

input_voltage = pichondria.get_input_voltage()

Getting Output Voltage

output_voltage = pichondria.get_output_voltage()

Getting Battery Voltage

battery_voltage = pichondria.get_battery_voltage()

Applying Settings

pichondria.apply_settings()

Configuring Startup Voltage

pichondria.set_startup_voltage(3.4)
pichondria.apply_changes()

Configuring Shutdown Voltage

pichondria.set_shutdown_voltage(3.4)
pichondria.apply_changes()

Configuring Wake-Up Timer

pichondria.set_wake_up_timer(1800)
pichondria.apply_changes()

Configuring Shutdown Timer

pichondria.set_shutdown_timer(120)
pichondria.apply_changes()

Configuring Boot-Up Timer

pichondria.set_bootup_timer(30)
pichondria.apply_changes()

Enabling/Disabling/Checking Autopilot Mode

pichondria.enable_autopilot()
pichondria.disable_autopilot()
pichondria.check_autopilot_mode()

Enabling/Disabling/Checking Acknowledgement Mode

pichondria.enable_acknowledgement_mode()
pichondria.disable_acknowledgement_mode()
pichondria.check_acknowledgement_mode()

Sending Acknowledgement

pichondria.send_acknowledgement()

Checking Shutdown Request

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 [e-mail]