API Reference

Client

class aioguardian.Client(ip_address: str, *, port: int = 7777, request_timeout: int = 10, command_retries: int = 3)

Define the class that can send commands to a Guardian device.

Parameters:

ip_address – The IP address or hostname of a Guardian valve controller.
port – The port to connect to.
request_timeout – The number of seconds to wait before timing out a request.
command_retries – The number of retries to use on a failed command.

async connect() → None

Connect to the Guardian device.

Raises:: SocketError – Raised on an issue with the UDP socket.

disconnect() → None: Close the connection.

async execute_raw_command(command_code: int, *, params: dict | None = None, silent: bool = True) → dict[str, Any]

Execute a command via its integer-based command code.

Parameters:

command_code – The command code to execute.
params – Any parameters to send along with the command.
silent – If True, silence “beep” tones associated with this command.

Returns:

An API response payload.

Command Helpers

Define command helpers.

class aioguardian.helpers.command.Command(value)

Define a Guardian UDP command mapping.

IOT_PUBLISH_STATE = 65

SENSOR_PAIR_DUMP = 48

SENSOR_PAIR_SENSOR = 49

SENSOR_PAIRED_SENSOR_STATUS = 51

SENSOR_UNPAIR_SENSOR = 50

SYSTEM_DIAGNOSTICS = 1

SYSTEM_FACTORY_RESET = 255

SYSTEM_ONBOARD_SENSOR_STATUS = 80

SYSTEM_PING = 0

SYSTEM_REBOOT = 2

SYSTEM_UPGRADE_FIRMWARE = 4

VALVE_CLOSE = 18

VALVE_HALT = 19

VALVE_OPEN = 17

VALVE_RESET = 20

VALVE_STATUS = 16

WIFI_CONFIGURE = 34

WIFI_DISABLE_AP = 36

WIFI_ENABLE_AP = 35

WIFI_LIST = 38

WIFI_RESET = 33

WIFI_SCAN = 37

WIFI_STATUS = 32

aioguardian.helpers.command.get_command_from_name(command_name: str) → Command

Return the command for a particular name.

Parameters:: command_name – The command string to parse into a Command.
Returns:: A Command object.
Raises:: CommandError – Raised when an unknown command is encountered.

aioguardian.helpers.command.get_command_from_code(command_code: int) → Command

Return the command for a particular code.

Parameters:: command_code – The raw command code to parse into a Command.
Returns:: A Command object.
Raises:: CommandError – Raised when an unknown command is encountered.

Command Classes

The classes should not be instantiated directly; rather, they exist as properties of a aioguardian.Client() class:

client.iot is an instance of aioguardian.commands.iot.IOTCommands().
client.system is an instance of aioguardian.commands.system.SystemCommands().
client.sensor is an instance of aioguardian.commands.sensor.SensorCommands().
client.valve is an instance of aioguardian.commands.valve.ValveCommands().
client.wifi is an instance of aioguardian.commands.wifi.WiFiCommands().

IOT

class aioguardian.commands.iot.IOTCommands(execute_command: Callable[[...], Awaitable[dict[str, Any]]])

Define an object to manage IOT commands.

Note that this class shouldn’t be instantiated directly; an instance of it will automatically be added to the Client (as client.iot).

Parameters:: execute_command – The execute_command method from the Client object.

async publish_state(*, silent: bool = True) → dict[str, Any]

Publish the device’s complete state to the Guardian cloud.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

Sensor

class aioguardian.commands.sensor.SensorCommands(execute_command: Callable[[...], Awaitable[dict[str, Any]]])

Define an object to manage sensor commands.

Note that this class shouldn’t be instantiated directly; an instance of it will automatically be added to the Client (as client.sensor).

Parameters:: execute_command – The execute_command method from the Client object.

async pair_dump(*, silent: bool = True) → dict[str, Any]

Dump information on all paired sensors.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async pair_sensor(uid: str, *, silent: bool = True) → dict[str, Any]

Pair a new sensor to the device.

Parameters:

uid – A UID of a Guardian paired sensor.
silent – Whether the valve controller should beep upon successful command.

Returns:

An API response payload.

Raises:

CommandError – Raised when invalid parameters are provided.

async paired_sensor_status(uid: str, *, silent: bool = True) → dict[str, Any]

Get the status (leak, temperature, etc.) of a paired sensor.

Parameters:

uid – A UID of a Guardian paired sensor.
silent – Whether the valve controller should beep upon successful command.

Returns:

An API response payload.

Raises:

CommandError – Raised when invalid parameters are provided.

async unpair_sensor(uid: str, *, silent: bool = True) → dict[str, Any]

Unpair a sensor from the device.

Parameters:

uid – A UID of a Guardian paired sensor.
silent – Whether the valve controller should beep upon successful command.

Returns:

An API response payload.

Raises:

CommandError – Raised when invalid parameters are provided.

System

class aioguardian.commands.system.SystemCommands(execute_command: Callable[[...], Awaitable[dict[str, Any]]])

Define an object to manage system commands.

Note that this class shouldn’t be instantiated directly; an instance of it will automatically be added to the Client (as client.system).

Parameters:: execute_command – The execute_command method from the Client object.

async diagnostics(*, silent: bool = True) → dict[str, Any]

Retrieve diagnostics info.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async factory_reset(*, silent: bool = True) → dict[str, Any]

Perform a factory reset on the device.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async onboard_sensor_status(*, silent: bool = True) → dict[str, Any]

Retrieve status of the valve controller’s onboard sensors.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async ping(*, silent: bool = True) → dict[str, Any]

Ping the device.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async reboot(*, silent: bool = True) → dict[str, Any]

Reboot the device.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async upgrade_firmware(*, url: str | None = None, port: int | None = None, filename: str | None = None, silent: bool = True) → dict[str, Any]

Upgrade the firmware on the device.

Parameters:

url – A Guardian-provided URL that hosts firmware files.
port – A port at the Guardian-provided URL that can be accessed.
filename – A firmware filename.
silent – Whether the valve controller should beep upon successful command.

Returns:

An API response payload.

Raises:

CommandError – Raised when invalid parameters are provided.

Valve

class aioguardian.commands.valve.ValveCommands(execute_command: Callable[[...], Awaitable[dict[str, Any]]])

Define an object to manage valve commands.

Note that this class shouldn’t be instantiated directly; an instance of it will automatically be added to the Client (as client.valve).

Parameters:: execute_command – The execute_command method from the Client object.

async close() → dict[str, Any]

Close the valve.

Returns:: An API response payload.

async halt() → dict[str, Any]

Halt the valve.

Note that calling this method will cause the device to no longer respond to leak events; therefore, it is not recommended to leave the device in a “halted” state indefinitely.

Returns:: An API response payload.

async open() → dict[str, Any]

Open the valve.

Returns:: An API response payload.

async reset(*, silent: bool = True) → dict[str, Any]

Reset the valve.

This fully resets system motor diagnostics (including open/close count and lifetime average current draw) and cannot be undone.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async status(*, silent: bool = True) → dict[str, Any]

Retrieve status of the valve.

In the payload that is returned, the state attribute of the valve can be any one of the following:

closed

closing

default

finish_closing

finish_opening

free_spin

halted

opened

opening

stalled

start_closing

start_halt

start_opening

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

WiFi

class aioguardian.commands.wifi.WiFiCommands(execute_command: Callable[[...], Awaitable[dict[str, Any]]])

Define an object to manage WiFi commands.

Note that this class shouldn’t be instantiated directly; an instance of it will automatically be added to the Client (as client.wifi).

Parameters:: execute_command – The execute_command method from the Client object.

async configure(ssid: str, password: str, *, silent: bool = True) → dict[str, Any]

Configure the device to use a wireless network.

Parameters:

ssid – An SSID to connect to.
password – The password to use to connect to the SSID.
silent – Whether the valve controller should beep upon successful command.

Returns:

An API response payload.

Raises:

CommandError – Raised when invalid parameters are provided.

async disable_ap(*, silent: bool = True) → dict[str, Any]

Disable the device’s onboard WiFi access point.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async enable_ap(*, silent: bool = True) → dict[str, Any]

Enable the device’s onboard WiFi access point.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async list(*, silent: bool = True) → dict[str, Any]

List previously scanned nearby SSIDs.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async reset(*, silent: bool = True) → dict[str, Any]

Erase and reset all WiFi settings.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async scan(*, silent: bool = True) → dict[str, Any]

Scan for nearby SSIDs.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

async status(*, silent: bool = True) → dict[str, Any]

Return the current WiFi status of the device.

Parameters:: silent – Whether the valve controller should beep upon successful command.
Returns:: An API response payload.

Errors

Define exception types for aioguardian.

exception aioguardian.errors.GuardianError: Define a base error from which all others inherit.

exception aioguardian.errors.CommandError: Define an error related to commands (invalid commands, invalid params, etc.).

exception aioguardian.errors.SocketError: Define an error related to UDP socket issues.