pyenergi¶

pyenergi is an unofficial Python API client for the myenergi API.

Getting started¶

API reference¶

class pyenergi.Hub(serial_number=None, api_key=None)¶

A myenergi Hub.

Parameters:

serial_number (str | None) – A myenergi Hub serial number.
api_key (str | None) – The API key for the myenergi Hub.

async test()¶

Attempt to connect to the myenergi API.

Use this to test myenergi API connectivity, including the validity of the configured authorisation credentials.

Return type:

bool

Returns:

True if the connection was successful, False otherwise.

Raises:

AuthenticationError: If the provided authentication credentials are invalid.

PyenergiError: If the connection was unsuccessful.

async get_zappis()¶

Get all Zappis associated with this myenergi Hub.

Return type:: list[Zappi]

Zappi¶

class pyenergi.Zappi(*, _client, serial_number, firmware_version, is_new_bootloader_available, system_datetime, is_daylight_savings, last_command_status, last_command_waiting_seconds, charge_status, charge_mode, is_boosting, minimum_green_level, smart_boost_end_time, smart_boost_energy_to_add, scheduled_boost_start_time, scheduled_boost_energy_to_add, priority, grid_frequency, grid_voltage, phases, cts, diversion_amount, power_generation, power_grid, is_locked, should_lock_when_plugged_in, should_lock_when_unplugged, should_charge_when_locked, should_charge, is_being_tampered_with)¶

A myenergi Zappi device.

serial_number: int¶: Hardware serial number.

firmware_version: str¶: Firmware version.

is_new_bootloader_available: bool¶: Is a new bootloader version available?

system_datetime: datetime¶: The Zappi’s system date / time.

is_daylight_savings: bool¶: Whether or not daylight savings is turned on.

last_command_status: LastCommandStatus¶: The status of the last command sent to the Zappi.

last_command_waiting_seconds: int¶

How long, in seconds, it has been since the last command was sent.

This value is as it is returned by the myenergi API. It does not autmoatically increment as time passes, unless you re-query the API.

charge_status: ChargeStatus¶: The Zappi’s current charge status.

charge_mode: ChargeMode¶: The Zappi’s current charging mode.

is_boosting: bool¶: Is the Zappi currently charging due to a Boost?

minimum_green_level: int¶: The minimum green energy level (for Eco and Eco+ modes).

smart_boost_end_time: time | None¶: The time at which the Smart Boost will end.

smart_boost_energy_to_add: int | None¶: The amount of energy (in kWh) to add during the Smart Boost.

scheduled_boost_start_time: time | None¶: The time at which the Scheduled Boost will start.

scheduled_boost_energy_to_add: int | None¶: The amount of energy (in kWh) to add during the Scheduled Boost.

priority: int¶: This Zappi’s priority relative to other devices associated with this myenergy Hub.

grid_frequency: float¶: The grid’s current frequency.

grid_voltage: float¶: The grid’s current voltage.

phases: Literal[1, 3]¶: The number of electrical phases.

cts: dict[int, CT]¶: Information pertaining to each of the Zappi’s current transformers.

diversion_amount: int¶: Power being diverted to the Zappi, in watts.

power_generation: int¶: The amount of power currently being generated, as measured by the Zappi.

power_grid: int¶

The amount of power currently being drawn from the grid, as measured by the Zappi.

If this value is negative, power is currently being exported to the grid.

is_locked: bool¶: Is the Zappi currently locked?

should_lock_when_plugged_in: bool¶: Should the Zappi lock when an EV is plugged in?

should_lock_when_unplugged: bool¶: Should the Zappi lock when an EV is unplugged?

should_charge_when_locked: bool¶: Should the Zappi charge a connected EV when locked?

should_charge: bool¶: Is the Zappi allowed to charge an EV?

is_being_tampered_with: bool¶: Is the Zappi currently being tampered with?

async set_charge_mode(mode)¶

Set the Zappi’s charge mode.

Parameters:

mode (ChargeMode) – The charge mode to set.

Returns:

True if the charge mode was successfully set.

Raises:

ValueError: If the charge mode is invalid.

PyenergiError: If another API-related error occurs.

async set_boost_mode(*, mode, energy_to_add=None, finish_by=None)¶

Set the Zappi’s Boost mode.

Parameters:

mode (BoostMode) – The Boost mode to set.
energy_to_add (TypeAliasType | None) – The amount of energy to add during the Boost.
finish_by (time | None) – The time at which the Boost should finish.

The finish_by and energy_to_add parameters are sometimes required, and sometimes not allowed at all, depending on the mode parameter. See the override signatures for more information.

Returns:

True if the Boost mode was successfully changed.

Raises:

ValueError: If the charge mode is invalid.

PyenergiError: If another API-related error occurs.

class pyenergi.CT(**data)¶

Information pertaining to a particular CT (current transformer).

type: CTType¶: The type that has been assigned to the CT.

power: int | None¶: The power, in watts, that the CT has most recently measured.

Enums¶

class pyenergi.ChargeMode(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

FAST = 1¶: Fast

ECO = 2¶: Eco

ECO_PLUS = 3¶: Eco+

STOPPED = 4¶: Stopped

class pyenergi.ChargeStatus(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

NOT_CONNECTED = 1¶: No EV is connected.

WAITING_FOR_EV = 2¶: The Zappi is waiting for the connected EV to allow charging to begin.

CHARGING = 3¶: Charging is underway.

FAULT = 4¶: An EV is connected, but the connection has faulted.

PAUSED = 5¶: An EV is connected, and charging is paused.

COMPLETE = 6¶: An EV is connected, and charging is complete.

class pyenergi.LastCommandStatus(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

The status of the last command sent to a Zappi.

PROCESSING = 'Processing'¶: The Zappi is currently processing the command.

SUCCESS = 'Success'¶: The command was successfully executed by the Zappi.

FAILED = 'Failed'¶: The command failed to be executed by the Zappi.

NOT_SENT = 'Not sent'¶: No command has been sent to the Zappi.

Exceptions¶

exception pyenergi.exceptions.PyenergiError¶: Base class for all Pyenergy-related errors.

exception pyenergi.exceptions.MissingCredentialsError¶: Raised when required credentials are not provided.

exception pyenergi.exceptions.AuthenticationError¶: Raised for issues related to authenticating with the myenergi API.

exception pyenergi.exceptions.DirectorError¶: Raised for issues related to the myenergi Director.