SCSmartDevice Class Reference

See the Getting Started Guide for a guide to getting started with the smart device package.

Unified smart-device controller.

Aggregates one or more hardware providers (currently ShellyProvider and TasmotaProvider) behind a single, stable public API. Client apps should never depend on a provider class directly.

`devices` `property`

Normalized snapshot of all device dicts.

`inputs` `property`

Normalized snapshot of all input component dicts.

`meters` `property`

Normalized snapshot of all meter component dicts.

`outputs` `property`

Normalized snapshot of all output component dicts.

`temp_probes` `property`

Normalized snapshot of all temperature probe dicts.

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

Accepts the SCSmartDevices: config block parsed from the client app's YAML file and instantiates the appropriate hardware providers.

Signature matches the legacy ShellyControl constructor so existing client apps require minimal changes.

Parameters:

Name	Type	Description	Default
`logger`	`SCLogger`	SCLogger instance from sc-foundation.	required
`device_settings`	`dict`	The `SCSmartDevices` dict from the app config.	required
`app_wake_event`	`Event \| None`	Optional threading.Event set when a webhook fires.	`None`

Raises:

Type	Description
`RuntimeError`	If config is invalid or the model file cannot be loaded.

`change_output(output_identity, new_state)`

Change an output relay to the requested state.

Parameters:

Name	Type	Description	Default
`output_identity`	`dict \| int \| str`	Output dict, ID, or name.	required
`new_state`	`bool`	True to turn on, False to turn off.	required

Returns:

Type	Description
`bool`	`(success, did_change)` — success is False when the device is
`bool`	offline; did_change is False when the output was already in the
`tuple[bool, bool]`	requested state.

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.

`does_device_have_webhooks(device)`

Return True if any component of the device has webhooks enabled.

`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

Returns:

Name	Type	Description
`device`	`dict`	The device object if found.

Raises:

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

`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', 'meter' or 'temp_probe').	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`

Returns:

Name	Type	Description
`component`	`dict`	The component index if found.

Raises:

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

`get_device_information(device_identity, refresh_status=False)`

Return a consolidated copy of one device and all its components.

Parameters:

Name	Type	Description	Default
`device_identity`	`dict \| int \| str`	Device dict, ID, or name.	required
`refresh_status`	`bool`	If True, fetch fresh state from hardware first.	`False`

Returns:

Type	Description
`dict`	Device dict augmented with `Inputs`, `Outputs`, `Meters`,
`dict`	and `TempProbes` sub-lists.

Raises:

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

`get_device_location(device_identity)`

Gets the timezone and location of a 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

Returns:

Name	Type	Description
`location`	`dict \| None`	A dictionary containing the timezone and location of the device, or None if not available.

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.

`get_device_status(device_identity)`

Gets the status of a 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

Returns:

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

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.

`get_input(input_identity)`

Shorthand for get_device_component("input", input_identity).

Returns:

Type	Description
`dict`	The internal input component dict.

`get_meter(meter_identity)`

Shorthand for get_device_component("meter", meter_identity).

Returns:

Type	Description
`dict`	The internal meter component dict.

`get_output(output_identity)`

Shorthand for get_device_component("output", output_identity).

Returns:

Type	Description
`dict`	The internal output component dict.

`get_temp_probe(probe_identity)`

Shorthand for get_device_component("temp_probe", probe_identity).

Returns:

Type	Description
`dict`	The internal temperature probe component dict.

`get_view()`

Return a frozen, indexed, thread-safe snapshot of current device state.

Use this in multi-threaded applications (e.g. alongside SmartDeviceWorker) to safely read device state without holding a lock.

Returns:

Type	Description
`SmartDeviceView`	SmartDeviceView built from the current normalized status.

`initialize_settings(device_settings, refresh_status=True)`

Reload device configuration without restarting the webhook server.

Useful for hot-reloading when the YAML config file changes at runtime.

Parameters:

Name	Type	Description	Default
`device_settings`	`dict`	Updated `SCSmartDevices` dict.	required
`refresh_status`	`bool`	If True (default) refresh device state after loading.	`True`

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

Install a webhook on a device component.

See https://nickelseyspelloc.github.io/sc-smart-device/shelly_webhooks/ for details on supported events and payloads.

Parameters:

Name	Type	Description	Default
`event`	`str`	Shelly event name, e.g. `"input.toggle_on"`.	required
`component`	`dict`	Component dict (from get_device_component).	required
`url`	`str \| None`	Override the callback URL. Auto-constructed if None.	`None`
`additional_payload`	`dict \| None`	Extra query-string parameters to include.	`None`

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

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.

Raises:

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

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

Returns:

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

Raises:

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

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

Prints the model library for all providers that have one.

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`
`provider_id`	`Optional(str)`	If provided, filters the models by this provider name ('shelly' or 'tasmota'). If None, prints models from all providers.	`None`

Returns:

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

`pull_webhook_event()`

Return the oldest queued webhook event and remove it from the queue.

Returns:

Type	Description
`dict \| None`	Event dict with keys `timestamp`, `Event`, `Device`,
`dict \| None`	`Component`, etc.; or None if the queue is empty.

`refresh()`

Alias for refresh_all_device_statuses.

`refresh_all_device_statuses()`

Refreshes the status of all devices across all providers.

Raises:

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

`shutdown()`

Stop all provider services and release resources.

Call this when the client application is terminating.

SCSmartDevice Class Reference

devices property

inputs property

meters property

outputs property

temp_probes property

__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)

get_input(input_identity)

get_meter(meter_identity)

get_output(output_identity)

get_temp_probe(probe_identity)

get_view()

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

pull_webhook_event()

refresh()

refresh_all_device_statuses()

shutdown()

`devices` `property`

`inputs` `property`

`meters` `property`

`outputs` `property`

`temp_probes` `property`

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

`get_input(input_identity)`

`get_meter(meter_identity)`

`get_output(output_identity)`

`get_temp_probe(probe_identity)`

`get_view()`

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

`pull_webhook_event()`

`refresh()`

`refresh_all_device_statuses()`

`shutdown()`