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 ofaioguardian.commands.iot.IOTCommands()
.client.system
is an instance ofaioguardian.commands.system.SystemCommands()
.client.sensor
is an instance ofaioguardian.commands.sensor.SensorCommands()
.client.valve
is an instance ofaioguardian.commands.valve.ValveCommands()
.client.wifi
is an instance ofaioguardian.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
(asclient.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
(asclient.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
(asclient.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
(asclient.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
(asclient.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.