Shelly Smart Switch Control

See the Shelly Control Getting Started Guide for a guide to using the ShellyControl class.

Control interface for Shelly Smart Switch devices.

__init__(logger, device_settings)

Initializes the ShellySwitch object.

Parameters:

Name	Type	Description	Default
logger	SCLogger	The logger instance to use for logging messages.	required
device_settings	dict	A dictionary containing the device, as returned by SCConfigManager.get_shelly_settings().	required

Raises:

Type	Description
RuntimeError	If the switch_settings configuration is invalid or incomplete or the model file cannot be found.

change_output(output_identity, new_state)

Change the state of a Shelly device output to on or off.

Parameters:

Name	Type	Description	Default
output_identity	dict | int | str	An output dict, or the ID or name of the device to check.	required
new_state	bool	The new state to set the output to (True for on, False for off).	required

Raises:

Type	Description
RuntimeError	There was an error changing the device output state.
TimeoutError	If the device is online (ping) but the state change request times out.

Returns:

Name	Type	Description
result	bool	True if the output state was changed successfully, False if the device is offline.
did_change	bool	True if the output state is different than before, False if it was already in the desired state.

get_device(device_identity)

Returns the device index for a given device ID or name.

Parameters:

Name	Type	Description	Default
device_identity	dict | int | str	If a dict, just returns this, otherwise looks up the ID (int) or name (str) of the device to retrieve.	required

Raises:

Type	Description
RuntimeError	If the device is not found in the list of devices.

Returns:

Name	Type	Description
device	dict	The device object if found.

get_device_component(component_type, component_identity)

Returns a device component's index for a given component ID or name.

Parameters:

Name	Type	Description	Default
component_type	str	The type of component to retrieve ('input', 'output', or 'meter').	required
component_identity	int | str	The ID or name of the component to retrieve.	required

Raises:

Type	Description
RuntimeError	If the component is not found in the list.

Returns:

Name	Type	Description
component	dict	The component index if found.

get_device_information(device_identity, refresh_status=False)

Returns a consolidated copy of a Shelly device information as a single dictionary, including its inputs, outputs, and meters.

Parameters:

Name	Type	Description	Default
device_identity	dict | int | str	The device itself or an ID or name of the device to retrieve information for.	required
refresh_status	bool	If True, refreshes the device status before retrieving information. Defaults to False.	False

Raises:

Type	Description
RuntimeError	If the device is not found in the list of devices or if there is an error getting the status.

Returns:

Name	Type	Description
device_info	dict	A dictionary containing the device's attributes, inputs, outputs, and meters.

get_device_status(device_identity)

Gets the status of a Shelly device.

Parameters:

Name	Type	Description	Default
device_identity	dict | int | str	A device dict, or the ID or name of the device to check.	required

Raises:

Type	Description
RuntimeError	If the device is not found in the list of devices or if there is an error getting the status.
TimeoutError	If the device is online (ping) but the request times out while getting the device status.

Returns:

Name	Type	Description
result	bool	True if the device is online, False otherwise.

initialize_settings(device_settings, refresh_status=False)

Initializes the Shelly devices using the provided settings.

Parameters:

Name	Type	Description	Default
device_settings	dict	A dictionary containing the device settings.	required
refresh_status	bool | None	Whether to refresh the status of the devices.	False

Raises:

Type	Description
RuntimeError	If the device settings are invalid or incomplete.

is_device_online(device_identity=None)

See if a device is alive by pinging it.

Returns the result and updates the device's online status. If we are in simulation mode, always returns True.

Parameters:

Name	Type	Description	Default
device_identity	Optional(dict | int | str | None)	The actual device object or ID or name of the device to check. If None, checks all device.	None

Raises:

Type	Description
RuntimeError	If the device is not found in the list of devices.

Returns:

Name	Type	Description
result	bool	True if the device is online, False otherwise. If all devices are checked, returns True if all device are online.

print_device_status(device_identity=None)

Prints the status of a device or all devices.

Parameters:

Name	Type	Description	Default
device_identity	Optional(int | str | None)	The ID or name of the device to check. If None, checks all devices.	None

Raises:

Type	Description
RuntimeError	If the device is not found in the list of devices.

Returns:

Name	Type	Description
device_info	str	A string representation of the device status.

print_model_library(mode_str='brief', model_id=None)

Prints the Shelly model library.

Parameters:

Name	Type	Description	Default
mode_str	str	The mode of printing. Can be "brief" or "detailed". Defaults to "brief".	'brief'
model_id	Optional(str)	If provided, filters the models by this model name. If None, prints all models.	None

Returns:

Name	Type	Description
library_info	str	A string representation of the Shelly model library.

refresh_all_device_statuses()

Refreshes the status of all Shelly devices.

This function iterates through all devices and updates their status by calling get_device_status. It also calculates the total power and energy consumption for each device.

Raises:

Type	Description
RuntimeError	If there is an error getting the status of any device.