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, app_wake_event=None)`

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
`app_wake_event`	`Event \| None`	An optional event to wake the application when a webhook is received.	`None`

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.

`does_device_have_webhooks(device)`

Returns True if the device has any webhooks installed, False otherwise.

Parameters:

Name	Type	Description	Default
`device`	`dict`	The Shelly device dictionary to check for webhooks.	required

Returns:

Name	Type	Description
`bool`	`bool`	True if the device has webhooks installed, False otherwise.

`get_device(device_identity)`

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

For device_identity you can pass: - A device object (dict) to retrieve it directly. - The device ID (int) to look it up by ID. - The device name (str) to look it up by name. - A component object (dict), which will return the parent device.

Parameters:

Name	Type	Description	Default
`device_identity`	`dict \| int \| str`	The identifier for the device.	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, use_index=None)`

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
`use_index`	`bool \| None`	If True, lookup by index instead of ID or name.	`None`

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_location(device_identity)`

Gets the timezone and location of a Shelly device if available.

Returns a dict in the following format

"tz": "Europe/Sofia", "lat": 42.67236, "lon": 23.38738

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
`location`	`dict \| None`	A dictionary containing the timezone and location of the device, or None if not available.

`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=True)`

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.	`True`

Raises:

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

`install_webhook(event, component, url=None, additional_payload=None)`

Install a webhook for the specified device and component.

The function is used internally to install input and/or output webhooks that will be handled by the ShellyControl webhook handler server, but it can also be used to install additional webhooks that point to your own enpoint. If you use this function for custom webhooks, make sure your device supports the webhook event.

The SupportedWebhooks attrbute of the device object lists the webhook events that each device supports (if any). See this page for documentation: https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Webhook#webhookcreate

You must have set the ShellyDevices: WebhooksEnabled configuration parameter to True for this function to install a webhook.

The following arguments will automatically be added to the url string if not already provided

Event: The event type that triggered the webhook DeviceID: The ID attribute of the device that this webhook came from. ObjectType: The type of the component that this webhook came from. One of "input", "output", "meter" ComponentID: The ID attribute of the component that this webhook came from.

For example: http://192.16.81.23:8787/shelly/webhook?Event=input.toggle_on&DeviceID=1&ObjectType=input&ComponentID=2

Parameters:

Name	Type	Description	Default
`event`	`str`	The event type to install the webhook for. This is case sensitive and must match the event type supported by the device and componnent. For example "input.toggle_on". A RunTime error will be thrown is the event type is not supported.	required
`component`	`dict`	The component object for the device component that you want to install the webhook on.	required
`url`	`str \| None`	The URL to send the webhook to. If None, the URL will be constructed using the webhook host, port, and path.	`None`
`additional_payload`	`dict \| None`	Additional key/value pairs to include in the webhook payload, for example active_between.	`None`

Raises:

Type	Description
`RuntimeError`	If the webhook installation fails.

`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, device component object, device ID or device 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.

`pull_webhook_event()`

Pulls a webhook event from the queue.

Use this if your app has been interrupted by a webhook event (your app_wake_event was set). This will return the earliest webhook event that was received and remove it from the queue.

Returns:

Type	Description
`dict \| None`	dict \| None: The next webhook event from the queue, or None if the queue is empty.

`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.

Shelly Smart Switch Control

__init__(logger, device_settings, app_wake_event=None)

change_output(output_identity, new_state)

does_device_have_webhooks(device)

get_device(device_identity)

get_device_component(component_type, component_identity, use_index=None)

get_device_information(device_identity, refresh_status=False)

get_device_location(device_identity)

get_device_status(device_identity)

initialize_settings(device_settings, refresh_status=True)

install_webhook(event, component, url=None, additional_payload=None)

is_device_online(device_identity=None)

print_device_status(device_identity=None)

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

pull_webhook_event()

refresh_all_device_statuses()

`init(logger, device_settings, app_wake_event=None)`

`change_output(output_identity, new_state)`

`does_device_have_webhooks(device)`

`get_device(device_identity)`

`get_device_component(component_type, component_identity, use_index=None)`

`get_device_information(device_identity, refresh_status=False)`

`get_device_location(device_identity)`

`get_device_status(device_identity)`

`initialize_settings(device_settings, refresh_status=True)`

`install_webhook(event, component, url=None, additional_payload=None)`

`is_device_online(device_identity=None)`

`print_device_status(device_identity=None)`

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

`pull_webhook_event()`

`refresh_all_device_statuses()`