Device selection

Driver.device_paths(), Driver.find_devices() and Driver.find_one_device() return DevicePath instances, which are str instances that also parse the device path fields. The device specifications select devices by device path, model, model-serial_number or serial number, such as “u/js320/8W2A”, “js320”, “js320-8W2A” or “8W2A”. The optional brand, such as “Joulescope”, restricts the selection to that brand’s devices.

class pyjoulescope_driver.device_path.DevicePath[source]

A device path str, such as “u/js320/31NB”.

DevicePath is a str subclass, so it works anywhere a device path string does. The field properties return None for paths that do not have the “{backend}/{model}/{serial_number}” form.

A device in bootloader mode has a “&” model prefix, such as “u/&js220/000415”. Its model and brand are the same as in application mode, and is_bootloader is True.

property backend

The backend, such as “u” for USB, or None.

property brand

The brand, such as “Joulescope”, or None if unknown.

property is_bootloader

True if this path is a device in bootloader mode.

match(spec)[source]

Check if this path matches a user-provided device specification.

Parameters:

spec –

The device specification, which is one of:

  • the full device path, such as “u/js320/31NB”.

  • the backend and model, such as “u/js320” or “u/js320/”, which selects every JS320 on that interface.

  • the model and serial number, such as “js320/31NB”.

  • the model and serial number, such as “js320-31NB”.

  • the model, such as “js320”.

  • the serial number, such as “31NB”.

Matching is case-insensitive, and serial numbers must match exactly. The model forms match a device in either application or bootloader mode. Use the “&” model prefix, such as “&js220”, to only match devices in bootloader mode.

Returns:

True on a match, False otherwise.

property model

The lowercase model without the bootloader prefix, such as “js320”, or None.

property serial_number

The serial number with its original case, such as “31NB”, or None.

A device path string that parses its own fields.

Device paths have the form “{backend}/{model}/{serial_number}”, such as “u/js320/31NB”. Driver.device_paths() returns DevicePath instances. Paths from other sources, such as “@/!add” callbacks, command-line arguments or configuration files, are plain str. Use DevicePath(path) to convert them.

pyjoulescope_driver.device_path.BRANDS_TO_MODELS = {'Joulescope': ('js110', 'js220', 'js320')}

The lowercase models for each brand.

pyjoulescope_driver.device_path.BRAND_ALIASES = {'js': 'Joulescope'}

Case-insensitive alternate names for brands in BRANDS_TO_MODELS.

pyjoulescope_driver.device_path.brand_validate(brand)[source]

Validate a brand name.

Parameters:

brand – The case-insensitive brand name or alias, such as “joulescope” or “js”.

Returns:

The brand name, such as “Joulescope”.

Raises:

  • TypeError – If brand is not a str.

  • ValueError – If brand is not supported.

Select devices from the driver’s device paths.

The driver reports all devices, including Joulescope instruments and other devices, such as a MiniBitty at “u/mb/{serial_number}”. Use the brand argument to select only Joulescope instruments, or a backend and model specification such as “u/js320/” to select every JS320 on one interface. See DevicePath for the device path and specification formats.

Use this module as a namespace:

from pyjoulescope_driver import device_filter
device_path = device_filter.find_one(paths, '31NB', brand='joulescope')

Driver.device_paths() and Driver.find_one_device() provide the same selection directly.

exception pyjoulescope_driver.device_filter.DeviceFilterError(specs, brand, matches, available)[source]

The device specifications did not match exactly one device.

Variables:

  • specs – The list of device specifications, or None for all.

  • brand – The brand, such as “Joulescope”, or None for all.

  • matches – The list of matching device paths.

  • available – The list of all device paths for the brand.

pyjoulescope_driver.device_filter.find(device_paths, specs=None, brand=None)[source]

Find the device paths for the matching devices.

Parameters:

  • device_paths – The list of device path strings, such as from Driver.device_paths().

  • specs –

    The device specifications, which is one of:

    • None to match all devices.

    • a string containing one or more comma-separated device specifications, such as “js320” or “31NB, u/js220/000415”. Whitespace around each specification is ignored, and an empty string matches all devices.

    • a list of device specification strings.

    A device matches if it matches any specification. See DevicePath.match() for the device specification format.

  • brand – The case-insensitive brand, such as “Joulescope”, to only match devices of that brand. None (default) matches all brands.

Returns:

The list of matching DevicePath instances, in order.

Raises:

  • TypeError – If specs or brand has an invalid type.

  • ValueError – If brand is not supported.

pyjoulescope_driver.device_filter.find_one(device_paths, specs=None, brand=None)[source]

Find the device path for exactly one matching device.

Parameters:

  • device_paths – The list of device path strings, such as from Driver.device_paths().

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

  • brand – The brand. See find().

Returns:

The matching DevicePath.

Raises:

DeviceFilterError – If zero or multiple devices match.