Device

class joulescope.driver.Device(usb_device, config=None)

The device implementation for use by applications.

Parameters

• usb_device – The backend USB usb.device instance.

• config – The initial default configuration following device open. Choices are [‘auto’, ‘off’, ‘ignore’, None]. * ‘auto’: enable the sensor and start collecting data with current sensor autoranging. * ‘ignore’ or None: Leave the device in its existing state. * ‘off’: Turn the sensor off and disable data collection.

bootloader(progress_cbk=None)

Start the bootloader for this device.

Parameters

progress_cbk – The optional Callable[float] which is called with the progress fraction from 0.0 to 1.0

Returns

(bootloader, existing_devices) Use the bootloader instance to perform operations. Use existing_devices to assist in determining when this device returns from bootloader mode.

close()

Close the device and release resources

property device_serial_number

Get the Joulescope device serial number assigned during manufacturing.

Returns

The serial number string.

enter_test_mode(index=None, value=None)

Enter a custom test mode.

Parameters

• index – The test mode index.

• value – The test mode value.

You probably should not be using this method. You will not destroy anything, but you will likely stop your Joulescope from working normally until you unplug it.

extio_status()

Read the EXTIO GPI value.

Returns

A dict containing the extio status. Each key is the status item name. The value is itself a dict with the following keys:

• name: The status name, which is the same as the top-level key.

• value: The actual value

• units: The units, if applicable.

• format: The recommended formatting string (optional).

info()

Get the device information structure.

Returns

The device information structure.

First implemented in 0.3. Older firmware returns None.

property input_sampling_frequency

The original input sampling frequency.

property is_streaming

Check if the device is streaming.

Returns

True if streaming. False if not streaming.

open(event_callback_fn=None)

Open the device for use.

Parameters

event_callback_fn – The function(event, message) to call on asynchronous events, mostly to allow robust handling of device errors. “event” is one of the DeviceEvent values, and the message is a more detailed description of the event.

Raises

IOError – on failure.

The event_callback_fn may be called asynchronous and from other threads. The event_callback_fn must implement any thread safety.

property output_sampling_frequency

The output sampling frequency.

parameter_get(name, dtype=None)

Get a parameter value.

Parameters

• name – The parameter name.

• dtype – The data type for the parameter. None (default) attempts to convert the value to the enum string. ‘actual’ returns the value in its actual type used by the driver.

Raises

KeyError – if name not found.

parameter_set(name, value)

Set a parameter value.

Parameters

• name – The parameter name

• value – The new parameter value

Raises

• KeyError – if name not found.

• ValueError – if value is not allowed

parameters(name=None)

Get the list of joulescope.parameter.Parameter instances.

Parameters

name – The optional name of the parameter to retrieve. None (default) returns a list of all parameters.

Returns

The list of all parameters. If name is provided, then just return that single parameters.

read(duration=None, contiguous_duration=None, out_format=None, fields=None)

Read data from the device.

Parameters

• duration – The duration in seconds for the capture. The duration must fit within the stream_buffer.

• contiguous_duration – The contiguous duration in seconds for the capture. As opposed to duration, this ensures that the duration has no missing samples. Missing samples usually occur when the device first starts. The duration must fit within the stream_buffer.

• out_format –

  The output format which is one of:

  • calibrated: The Nx2 np.ndarray(float32) with columns current and voltage.

  • raw: The raw Nx2 np.ndarray(uint16) Joulescope data.

  • samples_get: The StreamBuffer samples get format. Use the fields parameter to optionally specify the signals to include.

  • None: equivalent to ‘calibrated’.

• fields – The fields for samples_get when out_format=samples_get.

If streaming was already in progress, it will be restarted. If neither duration or contiguous duration is specified, the capture will only be stopped by callbacks registered through stream_process_register().

run_from_bootloader(fn)

Run commands from the bootloader and then return to the app.

Parameters

fn – The function(bootloader) to execute the commands.

property sampling_frequency

The output sampling frequency.

sensor_firmware_program(data, progress_cbk=None)

Program the sensor microcontroller firmware

Parameters

• data – The firmware to program as a raw binary file.

• progress_cbk – The optional Callable[float] which is called with the progress fraction from 0.0 to 1.0

Raise

on error.

property serial_number

Get the unique 16-byte LPC54608 microcontroller serial number.

Returns

The microcontroller serial number.

The serial number assigned during manufacturing is available using self.info()[‘ctl’][‘hw’][‘sn_mfg’].

start(stop_fn=None, duration=None, contiguous_duration=None)

Start data streaming.

Parameters

• stop_fn – The function(event, message) called when the device stops. The device can stop “automatically” on errors. Call stop() to stop from the caller. This function will be called from the USB processing thread. Any calls back into self MUST BE resynchronized.

• duration – The duration in seconds for the capture.

• contiguous_duration – The contiguous duration in seconds for the capture. As opposed to duration, this ensures that the duration has no missing samples. Missing samples usually occur when the device first starts.

If streaming was already in progress, it will be restarted.

statistics_accumulators_clear()

Clear the charge and energy accumulators.

property statistics_callback

Get the registered statistics callback.

statistics_callback_register(cbk, source=None)

Register a statistics callback.

Parameters

• cbk – The callable(data) where data is a statistics data structure. See the statistics documentation for details on the data format. This function will be called from the USB processing thread. Any calls back into self MUST BE resynchronized.

• source – The statistics source where the computation is performed. which is one of: * stream_buffer: The host-side stream buffer (default). * sensor: The device-side FPGA.

WARNING: calling statistics_callback() after calling this method may result in unusual behavior. Do not mix these API calls.

statistics_callback_unregister(cbk, source=None)

Unregister a statistics callback.

Parameters

• cbk – The callback previously provided to statistics_callback_register().

• source – The callback source.

status()

Get the current device status.

Returns

A dict containing status information.

stop()

Stop data streaming.

Returns

True if stopped. False if was already stopped.

This method is always safe to call, even after the device has been stopped or removed.

stream_process_register(obj)

Register a stream process object.

Parameters

obj – The instance compatible with StreamProcessApi. The instance must remain valid until its close() is called.

Call stream_process_unregister() to disconnect the instance.

stream_process_unregister(obj)

Unregister a stream process object.

Parameters

obj – The instance compatible with StreamProcessApi that was previously registered using stream_process_register().

property usb_device

Get the USB backend device implementation.

This method should only be used for unit and system tests. Production code should NEVER access the underlying USB device directly.

view_factory()

Construct a new View into the device’s data.

Returns

A View-compatible instance.