Device Discovery#

The device discovery functions allow the application to find Joulescopes connected to the host. Most scripts that only support a single Joulescopes will use:

joulescope.scan_require_one(config='auto')

To support multiple Joulescopes, use:

joulescope.scan(config='auto')

To select devices, provide device specifications, the same as pyjoulescope_driver Driver.device_paths():

joulescope.scan_require_one('js320', config='auto')  # the only JS320
joulescope.scan_require_one('8W2A')                  # by serial number
joulescope.scan('u/js220/000415, js320')             # comma-separated
joulescope.scan(['js220', 'js320'])                  # list

A specification is a full device path, such as “u/js320/8W2A”, the backend and model “u/js320”, the model and serial number “js320/8W2A” or “js320-8W2A”, the model “js320”, or the serial number “8W2A”. Matching is case-insensitive. The joulescope package only returns Joulescope instruments, so other devices that the driver reports, such as MiniBitty devices, never match.

Scans exclude devices in bootloader mode, unless you request them with “bootloader” or a “&” model specification, such as “&js220”. For backwards compatibility, “Joulescope” selects all devices. Device.firmware reports “app” or “bootloader” for each device.

scan_require_one() raises joulescope.v1.driver.ScanError when zero or multiple devices match. Its message lists the matching and available devices. ScanError is both a ValueError and, for backwards compatibility, a RuntimeError.

See joulescope.v1.device.Device.

scan#

joulescope.scan(specs=None, config=None, name=None) → List[Device][source]#

Scan for connected devices.

Parameters:

  • specs –

    The device specifications, which is one of:

    • None (default) to select all devices.

    • a string containing one or more comma-separated device specifications, such as “js320” or “31NB, u/js220/000415”.

    • a list of device specification strings.

    See pyjoulescope_driver.DevicePath.match() for the specification format. For backwards compatibility, “Joulescope” selects all devices, and “bootloader” selects all devices in bootloader mode.

  • config – The configuration for the Device.

  • name – Deprecated alias for specs, for backwards compatibility.

Returns:

The list of Device instances, sorted by name. Devices in bootloader mode are only included when requested by “bootloader” or a “&” model specification, such as “&js220”.

Raises:

TypeError – If specs has an invalid type.

scan_require_one#

joulescope.scan_require_one(specs=None, config=None, name=None) → Device[source]#

Scan for one and only one device.

Parameters:

  • specs – The device specifications. See scan().

  • config – The configuration for the Device.

  • name – Deprecated alias for specs.

Returns:

The Device found.

Raises:

ScanError – If zero or multiple devices match.

scan_for_changes#

joulescope.scan_for_changes(specs=None, devices=None, config=None, name=None)[source]#

Scan for device changes.

Parameters:

  • specs – The device specifications. See scan().

  • devices – The list of existing Device instances returned by a previous scan. Pass None or [] if no scan has yet been performed.

  • config – The configuration for the Device which is one of [‘auto’, ‘ignore’, ‘off’]. None is equivalent to ‘auto’.

  • name – Deprecated alias for specs.

Returns:

The tuple of lists (devices_now, devices_added, devices_removed). “devices_now” is the list of all currently connected devices. If the device was in “devices”, then return the Device instance from “devices”. “devices_added” is the list of connected devices not in “devices”. “devices_removed” is the list of devices in “devices” but not “devices_now”.

ScanError#

class joulescope.v1.driver.ScanError(specs, brand, matches, available)[source]#

The scan did not find exactly one device.

This exception is both a pyjoulescope_driver.device_filter.DeviceFilterError (a ValueError) and, for backwards compatibility, a RuntimeError.