SmartDeviceWorker Class Reference

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

Runs a background loop that processes DeviceSequenceRequest jobs.

The worker is designed to run in its own thread (pass run as the thread target). All public methods are thread-safe.

Parameters:

Name	Type	Description	Default
`smart_device`	`SCSmartDevice`	A fully-initialised SCSmartDevice instance. The worker does not take ownership — the caller is responsible for calling shutdown when done.	required
`logger`	`SCLogger`	SCLogger instance from sc-foundation.	required
`wake_event`	`Event`	`threading.Event` that is `set()` whenever the worker finishes a request, so that the main application thread can react.	required
`max_concurrent_errors`	`int`	Number of consecutive sequence errors before an additional notifiable issue is raised (default 4).	`4`
`critical_error_report_delay_mins`	`int \| None`	Minutes to delay before sending a critical-error notification. `None` disables notifications.	`None`

`does_device_have_webhooks(device)`

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

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

Return a frozen snapshot of the most recently refreshed device state.

Thread-safe; safe to call from any thread.

Returns:

Type	Description
`SmartDeviceView`	SmartDeviceView snapshot.

`get_location_info()`

Return the latest device location data, keyed by device name.

Returns:

Type	Description
`dict[str, dict]`	Dict mapping device name → location dict (`tz`, `lat`, `lon`).

`get_result(req_id)`

Return the result for a completed request, or None if not yet done.

Parameters:

Name	Type	Description	Default
`req_id`	`str`	The request ID returned by submit.	required

Returns:

Type	Description
`DeviceSequenceResult \| None`	`DeviceSequenceResult` or `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`	`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:

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

Raises:

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

`print_device_status(device_identity=None)`

Print the status of a device or all devices.

Parameters:

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

Returns:

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

Print 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`	`str \| None`	If provided, filters the models by this model name. If None, prints all models.	`None`

Returns:

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

`reinitialise_settings(device_settings=None)`

Re-apply device settings and refresh status.

Parameters:

Name	Type	Description	Default
`device_settings`	`dict \| None`	Updated `SCSmartDevices` config dict to pass to initialize_settings. Pass `None` (the default) to skip re-loading config and only trigger a full status refresh.	`None`

`request_device_location(device_name)`

Enqueue a location-lookup job for a single device.

Parameters:

Name	Type	Description	Default
`device_name`	`str`	The name (or ID) of the device to locate.	required

Returns:

Type	Description
`str`	Request ID string.

`request_refresh_status()`

Enqueue a status-refresh job and return its request id.

Convenience wrapper around submit for the common case of triggering a full status refresh.

Returns:

Type	Description
`str`	Request ID string.

`run()`

Main worker loop — pass this as the target of a threading.Thread.

Runs until stop is called. Picks requests off the internal queue one at a time and calls _execute_request.

`stop()`

Signal the worker loop to exit on the next iteration.

`submit(req)`

Enqueue a DeviceSequenceRequest for execution.

Parameters:

Name	Type	Description	Default
`req`	`DeviceSequenceRequest`	The sequence request to enqueue.	required

Returns:

Type	Description
`str`	The request `id` string; pass to get_result or
`str`	wait_for_result.

`wait_for_result(req_id, timeout=None)`

Block until a specific request completes or until timeout seconds elapse.

Parameters:

Name	Type	Description	Default
`req_id`	`str`	The request ID returned by submit.	required
`timeout`	`float \| None`	Maximum seconds to wait. `None` waits indefinitely.	`None`

Returns:

Type	Description
`bool`	`True` if the request completed before the timeout.