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(device_id=None, device_name=None, component_id=None, component_name=None)

Return the oldest queued webhook event matching the filters, and remove it.

With no filters, returns the oldest queued event. When one or more filters are supplied, returns the oldest event for which every supplied filter matches (unsupplied filters are ignored).

Parameters:

Name	Type	Description	Default
device_id	int | None	Only match events whose Device.ID equals this.	None
device_name	str | None	Only match events whose Device.Name equals this.	None
component_id	int | None	Only match events whose Component.ID equals this.	None
component_name	str | None	Only match events whose Component.Name equals this.	None

Returns:

Type	Description
dict | None	Event dict with keys timestamp, Event, Device,
dict | None	Component, etc.; or None if no queued event matches.

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.