Joulescope

https://joulescope.readthedocs.io/en/latest/
Admin
Joulescope is a Python driver and command-line utility for the Joulescope precision DC energy...
Tokens:64,059
Snippets:435
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and create virtualenv

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Install virtualenv and create a new environment for the project.

```bash
pip3 install -U virtualenv
virtualenv ~/venv/joulescope
```

--------------------------------

### Install pyjoulescope from source

Source: https://joulescope.readthedocs.io/en/latest/user/install.html

Install the package from the source directory.

```bash
pip3 install -U .

```

--------------------------------

### Install virtualenv

Source: https://joulescope.readthedocs.io/en/latest/user/install.html

Install virtualenv using pip.

```bash
pip3 install -U virtualenv

```

--------------------------------

### Install developer dependencies from source

Source: https://joulescope.readthedocs.io/en/latest/user/install.html

Install the package in editable mode with development dependencies.

```bash
pip3 install -U -e .[dev]

```

--------------------------------

### Start signature with private key and flags

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/datafile.html

Initializes signature state, writes a signature start tag with version, flags, and public key. If SIGNATURE_FLAG_KEY_INCLUDE is not set, resets signature data to empty.

```python
        self._signature = {
            'flags': 0 if flags is None else int(flags),
            'key': private_key,
            'data': b'',
        }
        payload = bytearray(8)
        payload[0] = 1  # Ed25519 using Blake2b
        payload[1] = self._signature['flags']
        payload += signing_key_public(private_key)
        self.append(TAG_SIGNATURE_START, payload)
        if 0 == (self._signature['flags'] & SIGNATURE_FLAG_KEY_INCLUDE):
            self._signature['data'] = b''
```

--------------------------------

### Install udev rules on Linux

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Download and install the udev rules file to grant user permissions for Joulescope access.

```bash
$ wget https://raw.githubusercontent.com/jetperch/pyjoulescope/master/99-joulescope.rules
$ sudo cp 99-joulescope.rules /etc/udev/rules.d/
$ sudo udevadm control --reload-rules
```

--------------------------------

### Install Python and dependencies on Linux

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Install necessary packages using apt and verify the Python version.

```bash
$ sudo apt install python3-dev python3-pip libusb-1.0-0
$ python3 -VV
```

--------------------------------

### Install pyjoulescope from source

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Install developer dependencies or the package itself from the source directory.

```bash
pip3 install -U -e .[dev]
pip3 install -U .
```

--------------------------------

### Install development dependencies from requirements.txt

Source: https://joulescope.readthedocs.io/en/latest/user/install.html

Install dependencies listed in requirements.txt for developing pyjoulescope.

```bash
pip3 install -U -r requirements.txt

```

--------------------------------

### DataReader.data_get(start, stop, increment=None, units=None, out=None)

Source: https://joulescope.readthedocs.io/en/latest/api/data_recorder.html

Get the samples with statistics.

```APIDOC
## DataReader.data_get(start, stop, increment=None, units=None, out=None)

### Description
Get the samples with statistics.

### Method
data_get

### Parameters
- **start** - The starting sample id (inclusive).
- **stop** - The ending sample id (exclusive).
- **increment** - The number of raw samples.
- **units** - The units for start and stop. 'seconds' or None is in floating point seconds relative to the view. 'samples' is in stream buffer sample indices.
- **out** - The optional output np.ndarray((N, STATS_FIELD_COUNT), dtype=DTYPE) to populate with the result. None (default) will construct and return a new array.

### Returns
The np.ndarray((N, STATS_FIELD_COUNT), dtype=DTYPE) data.
```

--------------------------------

### View.start(stream_buffer)

Source: https://joulescope.readthedocs.io/en/latest/api/view.html

Starts streaming.

```APIDOC
## View.start(stream_buffer)

### Description
Starts streaming.

### Method
start

### Endpoint
View.start(stream_buffer)

### Parameters
#### Request Body
- **stream_buffer** (StreamBuffer) - Required - The stream buffer to start streaming from.

### Response
None

```

--------------------------------

### Data get method

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/data_recorder.html

Retrieves samples with statistics based on start, stop, increment, and units.

```python
    def data_get(self, start, stop, increment=None, units=None, out=None):
        """Get the samples with statistics.

        :param start: The starting sample id (inclusive).
        :param stop: The ending sample id (exclusive).
        :param increment: The number of raw samples.
        :param units: The units for start and stop.
            'seconds' or None is in floating point seconds relative to the view.
            'samples' is in stream buffer sample indices.
        :param out: The optional output np.ndarray((N, STATS_FIELD_COUNT), dtype=DTYPE) to populate with
            the result.  None (default) will construct and return a new array.
        :return: The np.ndarray((N, STATS_FIELD_COUNT), dtype=DTYPE) data.
        """
        log.debug('DataReader.get(start=%r,stop=%r,increment=%r)', start, stop, increment)
        start, stop = self.normalize_time_arguments(start, stop, units)
        if increment is None:
            increment = 1
        if self._fh is None:
            raise IOError('file not open')
        increment = max(1, int(np.round(increment)))
        out_len = (stop - start) // increment
        if out_len <= 0:
            return stats_array_factory(0)
        if out is not None:
            if len(out) < len(out_len):
                raise ValueError('out too small')
        else:
            out = stats_array_factory(out_len)

        out_len = len(out)
        if increment == 1:
            self._data_get_handler(start, stop, out)
        elif increment == self.config['samples_per_reduction']:
            out = self.get_reduction(start, stop, out=out)
        elif increment > self.config['samples_per_reduction']:
            r_out = self.get_reduction(start, stop)
            increment = int(increment / self.config['samples_per_reduction'])
            out = reduction_downsample(r_out, 0, len(r_out), increment)
        else:
            k_start = start
            for idx in range(out_len):
                k_stop = k_start + increment
                self._statistics_get_handler(k_start, k_stop, out[idx, :])
                k_start = k_stop
        return out
```

--------------------------------

### Install pyjoulescope from PyPI

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Install or upgrade the pyjoulescope package using pip.

```bash
pip3 install -U joulescope
```

--------------------------------

### Install Python on Debian-based Linux

Source: https://joulescope.readthedocs.io/en/latest/user/install.html

Use apt to install Python development headers, pip, and libusb, then verify the Python version.

```bash
$ sudo apt install python3-dev python3-pip libusb-1.0-0
$ python3 -VV

```

--------------------------------

### bootloader Method

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/v0/driver.html

Starts the bootloader for the device, waits for reconnection, and returns the bootloader instance.

```python
    def bootloader(self, progress_cbk=None):
        """Start the bootloader for this device.

        :param progress_cbk:  The optional Callable[float] which is called
            with the progress fraction from 0.0 to 1.0
        :return: (bootloader, existing_devices)  Use the bootloader instance
            to perform operations.  Use existing_devices to assist in
            determining when this device returns from bootloader mode.
        """
        if progress_cbk is None:
            progress_cbk = lambda x: None
        _, existing_devices, _ = scan_for_changes(name='Joulescope', devices=[self])
        existing_bootloaders = scan(name='bootloader')
        log.info('my_device = %s', str(self))
        log.info('existing_devices = %s', existing_devices)
        log.info('existing_bootloaders = %s', existing_bootloaders)
        self.stop()
        rv = self._usb.control_transfer_out(
            'device', 'vendor', request=UsbdRequest.CONTROLLER_BOOTLOADER,
            value=SensorBootloader.START)
        _ioerror_on_bad_result(rv)
        self.close()
        b = []
        time_start = time.time()
        while not len(b):
            time_elapsed = time.time() - time_start
            if time_elapsed > USB_RECONNECT_TIMEOUT_SECONDS:
                raise IOError('Timed out waiting for bootloader to connect')
            progress_cbk(time_elapsed / USB_RECONNECT_TIMEOUT_SECONDS)
            time.sleep(0.25)
            _, b, _ = scan_for_changes(name='bootloader', devices=existing_bootloaders)
        if len(b) != 1:
            raise IOError('More than one new bootloader found')
        b = b[0]
        b.open()
        return b, existing_devices
```

--------------------------------

### Install Python and libusb on macOS

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Use Homebrew to install Python and libusb, then verify the version.

```bash
$ brew install python3 libusb
$ python3 -VV
```

--------------------------------

### Install development dependencies

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Install required dependencies for developing pyjoulescope.

```bash
pip3 install -U -r requirements.txt
```

--------------------------------

### Get help for joulescope CLI

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/quickstart.rst.txt

Display all available commands for the joulescope tool.

```bash
joulescope help
```

--------------------------------

### Verify Python installation on Windows

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Check the installed Python version using the command prompt.

```bash
> python -VV
Python 3.13.0 (tags/v3.13.0:60403a5, Oct  7 2024, 09:38:07) [MSC v.1941 64 bit (AMD64)]
```

--------------------------------

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

Source: https://joulescope.readthedocs.io/en/latest/api/device.html

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

```APIDOC
## start(stop_fn=None, duration=None, contiguous_duration=None)

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

### Method
start

### Parameters
- **stop_fn** (function) - Optional - 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** (float) - Optional - The duration in seconds for the capture.
- **contiguous_duration** (float) - Optional - 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.

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

--------------------------------

### Start data streaming

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/v0/driver.html

Initiates the data streaming process.

```python
def start(self, stop_fn=None, duration=None, contiguous_duration=None):
    """Start data streaming.
```

--------------------------------

### Start Data Collection

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/data_recorder.html

Initializes a new data collection session with metadata and sets the end callback.

```python
def _collection_start(self, data=None):
    log.debug('_collection_start()')
    c = self._writer.collection_start(1, 0, data=data)
    c.metadata = {'start_sample_id': self._sample_id_tlv}
    c.on_end = self._collection_end
    self._sample_id_block = self._sample_id_tlv
```

--------------------------------

### info()

Source: https://joulescope.readthedocs.io/en/latest/api/device.html

Gets the device information structure.

```APIDOC
## info()

### Description
Gets the device information structure.

### Returns
The device information structure.
```

--------------------------------

### Start collection with optional id, type, and data

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/datafile.html

Creates a Collection object, appends a collection start tag, and adds the collection to the internal list. Note that start and end positions are updated later by collection_end().

```python
        c = Collection(id_, type_, data=data)
        # note: append writes start_position=0 and end_position=0.
        # Both are later updated by collection_end() in normal operation.
        c.start_position = self.append(TAG_COLLECTION_START, c.encode())
        self.collections.append(c)
        return c
```

--------------------------------

### View.samples_get(start=None, stop=None, units=None, fields=None)

Source: https://joulescope.readthedocs.io/en/latest/api/view.html

Gets exact samples over a range.

```APIDOC
## View.samples_get(start=None, stop=None, units=None, fields=None)

### Description
Gets exact samples over a range.

### Method
samples_get

### Endpoint
View.samples_get(start=None, stop=None, units=None, fields=None)

### Parameters
#### Request Body
- **start** (float or int) - Optional - The starting time.
- **stop** (float or int) - Optional - The ending time.
- **units** (str) - Optional - The units for start and stop. 'seconds' or None is in floating point seconds relative to the view. 'samples' is in stream buffer sample indices.
- **fields** (list) - Optional - The fields to get. None (default) gets the fundamental fields available for this view instance, which may vary depending upon the backend.

### Response
#### Success Response
- **samples** (list) - The exact samples over the specified range.

```

--------------------------------

### samples_get(start, stop, fields=None)

Source: https://joulescope.readthedocs.io/en/latest/api/stream_buffer.html

Retrieves exact sample data without any skips or reductions, including calibration values and metadata.

```APIDOC
## samples_get(start, stop, fields=None)

### Description
Get exact sample data without any skips or reductions.

### Parameters
- **start** (int) - Required - The starting sample id (inclusive).
- **stop** (int) - Required - The ending sample id (exclusive).
- **fields** (str or list) - Optional - The single field or list of field names to return. None (default) is equivalent to ['current', 'voltage', 'power', 'current_range', 'current_lsb', 'voltage_lsb']. Available fields:
  - 'current': The calibrated float32 current data array in amperes.
  - 'voltage': The calibrated float32 voltage data array in volts.
  - 'power': The calibrated float32 power data array in watts.
  - 'current_range': The current range. 0 = 10A, 6 = 18 uA, 7=off.
  - 'current_lsb': The general purpose input 0 (alias for gpi0).
  - 'voltage_lsb': The general purpose input 1 (alias for gpi1).
  - 'gpi0', 'gpi1', 'gpi2', 'gpi3': The general purpose inputs.
  - 'trigger_in': The trigger input.
  Short aliases are also supported: i, v, p, r, 0, 1, 2, 3, T. The gpi2, gpi3, and trigger_in signals require JS220 or JS320 hardware with the signal selected (see the device 'signals' parameter).

### Returns
- **dict** - A dict containing top-level 'time' and 'signals' keys. The 'time' value is a dict containing timing metadata for these samples. The 'signals' value is a dict with one key for each field in fields. Each field value is also a dict with entries 'value' and 'units'. However, if single field string is provided to fields, then just return that field's value.

```

--------------------------------

### DataReader.samples_get(start=None, stop=None, units=None, fields=None)

Source: https://joulescope.readthedocs.io/en/latest/api/data_recorder.html

Get exact samples over a range.

```APIDOC
## DataReader.samples_get(start=None, stop=None, units=None, fields=None)

### Description
Get exact samples over a range.

### Method
samples_get

### Parameters
- **start** - The starting time.
- **stop** - The ending time.
- **units** - The units for start and stop. 'seconds' or None is in floating point seconds relative to the view. 'samples' is in stream buffer sample indicies.
- **fields** - The fields to get.

### Returns
None
```

--------------------------------

### Install pyjoulescope with SSL bypass

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Use this command if corporate IT policies block the PyPI SSL certificate.

```bash
pip3 install --trusted-host pypi.org --trusted-host files.pythonhosted.org -U joulescope
```

--------------------------------

### Check Python version on Windows

Source: https://joulescope.readthedocs.io/en/latest/user/install.html

Run this command in a Command Prompt to verify Python installation. The output shows Python 3.13.0.

```text
> python -VV
Python 3.13.0 (tags/v3.13.0:60403a5, Oct  7 2024, 09:38:07) [MSC v.1941 64 bit (AMD64)]

```

--------------------------------

### Get sample ID range

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/data_recorder.html

Returns the range of sample IDs as [start, stop] based on the footer size. Returns [0, 0] if no file is open.

```python
@property
    def sample_id_range(self):
        """The sample ID range.

        :return: [start, stop] sample identifiers.
        """
        if self._f is not None:
            s_start = 0
            s_end = int(s_start + self.footer['size'])
            return [s_start, s_end]
        return [0, 0]
```

--------------------------------

### Create a virtual environment

Source: https://joulescope.readthedocs.io/en/latest/user/install.html

Create a new virtual environment for joulescope.

```bash
virtualenv ~/venv/joulescope

```

--------------------------------

### Activate virtualenv on Windows

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Create and activate the virtual environment on Windows.

```bash
virtualenv c:\venv\joulescope
source c:\venv\joulescope\Scripts\activate
```

--------------------------------

### Capture and Analyze Data with Joulescope

Source: https://joulescope.readthedocs.io/en/latest/_sources/index.rst.txt

This example demonstrates how to scan for a connected Joulescope, capture 0.1 seconds of data, and calculate the average current and voltage.

```python
import joulescope
import numpy as np
with joulescope.scan_require_one(config='auto') as js:
    data = js.read(contiguous_duration=0.1)
current, voltage = np.mean(data, axis=0, dtype=np.float64)
print(f'{current} A, {voltage} V')
```

--------------------------------

### Example statistics data structure

Source: https://joulescope.readthedocs.io/en/latest/_sources/api/statistics.rst.txt

Example statistics data structure returned by the statistics API. It shows the top-level keys time, signals, accumulators, and source, with signal statistics for current, voltage, and power including mean, variance, min, max, peak-to-peak, and integrated values. The source field is "sensor" in this example.

```json
{
  "time": {
    "range": {"value": [29.975386, 29.999424], "units": "s"},
    "delta": {"value": 0.024038, "units": "s"},
    "samples": {"value": 48076, "units": "samples"}
  },
  "signals": {
    "current": {
      "Âµ": {"value": 0.000299379503657111, "units": "A"},
      "Ïƒ2": {"value": 2.2021878912979553e-12, "units": "A"},
      "min": {"value": 0.00029360855114646256, "units": "A"},
      "max": {"value": 0.0003051375679206103, "units": "A"},
      "p2p": {"value": 1.1529016774147749e-05, "units": "A"},
      "âˆ«": {"value": 0.008981212667119223, "units": "C"}
    },
    "voltage": {
      "Âµ": {"value": 2.99890387873055,"units": "V"},
      "Ïƒ2": {"value": 1.0830626821348923e-06, "units": "V"},
      "min": {"value": 2.993824005126953, "units": "V"},
      "max": {"value": 3.002903699874878, "units": "V"},
      "p2p": {"value": 0.009079694747924805, "units": "V"}
    },
    "power": {
      "Âµ": {"value": 0.000897810357252683, "units": "W"},
      "Ïƒ2": {"value": 1.9910494110256852e-11, "units": "W"},
      "min": {"value": 0.0008803452947176993, "units": "W"},
      "max": {"value": 0.0009152597631327808, "units": "W"},
      "p2p": {"value": 3.49144684150815e-05, "units": "W"},
      "âˆ«": {"value": 0.026933793578814716, "units": "J"}
    },
    "current_range": {
      "Âµ": {"value": 4.0, "units": ""},
      "Ïƒ2": {"value": 0.0, "units": ""},
      "min": {"value": 4.0, "units": ""},
      "max": {"value": 4.0, "units": ""},
      "p2p": {"value": 0.0, "units": ""}
    },
    "current_lsb": {
      "Âµ": {"value": 0.5333222397870035, "units": ""},
      "Ïƒ2": {"value": 0.24889270730539995, "units": ""},
      "min": {"value": 0.0, "units": ""},
      "max": {"value": 1.0, "units": ""},
      "p2p": {"value": 1.0, "units": ""}
    },
    "voltage_lsb": {
      "Âµ": {"value": 0.5333430401863711, "units": ""},
      "Ïƒ2": {"value": 0.24889309698100895, "units": ""},
      "min": {"value": 0.0, "units": ""},
      "max": {"value": 1.0, "units": ""},
      "p2p": {"value": 1.0, "units": ""}
    }
  },
  "accumulators": {
    "charge": {"value": 0.0, "units": "C"},
    "energy": {"value": 0.0, "units": "J"}
  },
  "source": "sensor"
}
```

--------------------------------

### run_from_bootloader Method

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/v0/driver.html

Executes commands in bootloader mode and handles the transition back to the application.

```python
    def run_from_bootloader(self, fn):
        """Run commands from the bootloader and then return to the app.

        :param fn: The function(bootloader) to execute the commands.
        """
        b, existing_devices = self.bootloader()
        try:
            rc = fn(b)
        finally:
            b.go()  # go closes bootloader automatically
            d = []
            time_start = time.time()
            while not len(d):
                if (time.time() - time_start) > USB_RECONNECT_TIMEOUT_SECONDS:
                    raise IOError('Timed out waiting for application to connect')
                time.sleep(0.25)
                _, d, _ = scan_for_changes(name='Joulescope', devices=existing_devices)
            time.sleep(0.5)
            self._usb = d[0]._usb
            self.open()
        return rc
```

--------------------------------

### Build native modules on Windows

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Build native modules and set the PYTHONPATH for development on Windows.

```bash
python setup.py build_ext --inplace
set PYTHONPATH=%cd%
```

--------------------------------

### status()

Source: https://joulescope.readthedocs.io/en/latest/api/device.html

Gets the current device status.

```APIDOC
## status()

### Description
Gets the current device status.

### Method
status

### Parameters
None

### Returns
A dict containing status information.
```

--------------------------------

### statistics_callback (property)

Source: https://joulescope.readthedocs.io/en/latest/api/device.html

Gets the registered statistics callback.

```APIDOC
## statistics_callback (property)

### Description
Gets the registered statistics callback.

### Method
statistics_callback (property getter)

### Parameters
None
```

--------------------------------

### calibration_program Method

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/v0/driver.html

Programs calibration data by running the process from the bootloader.

```python
    def calibration_program(self, data, is_factory=False):
        return self.run_from_bootloader(lambda b: b.calibration_program(data, is_factory))
```

--------------------------------

### Get Reduction Statistics

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/data_recorder.html

Calculates statistics over a reduction range.

```python
    def _get_reduction_stats(self, start, stop):
        """Get statistics over the reduction

        :param start: The starting sample identifier (inclusive).
        :param stop: The ending sample identifier (exclusive).
        :return: The tuple of ((sample_start, sample_stop), :class:`Statistics`).
        """
        # log.debug('_get_reduction_stats(%s, %s)', start, stop)
        s = Statistics()
        sz = self.config['samples_per_reduction']
        incr = self.config['samples_per_block'] // sz
        r_start = start // sz
        if (r_start * sz) < start:
            r_start += 1
        r_stop = stop // sz
        if r_start >= r_stop:  # cannot use the reductions
            s_start = r_start * sz
            return (s_start, s_start), s
        r_idx = r_start
```

--------------------------------

### parameter_get(name, dtype)

Source: https://joulescope.readthedocs.io/en/latest/api/device.html

Gets a parameter value from the device.

```APIDOC
## parameter_get(name, dtype)

### Description
Gets a parameter value.

### Parameters
- **name** (string) – Required – Parameter name.
- **dtype** (string) - Optional - Data type. None defaults to enum string, 'actual' returns actual type.

### Method
parameter_get

### Errors
- **KeyError** - if name not found.
```

--------------------------------

### DataReader.normalize_time_arguments(start, stop, units=None)

Source: https://joulescope.readthedocs.io/en/latest/api/data_recorder.html

Normalize time arguments to range.

```APIDOC
## DataReader.normalize_time_arguments(start, stop, units=None)

### Description
Normalize time arguments to range.

### Method
normalize_time_arguments

### Parameters
- **start** - The start time or samples. None gets the first sample, equivalent to self.sample_id_range[0].
- **stop** - The stop time or samples. None gets the last sample, equivalent to self.sample_id_range[1].
- **units** - The time units which is one of ['seconds', 'samples'] None (default) id equivalent to 'samples'.

### Returns
(start_sample, stop_sample). When units=='samples', negative values are interpreted in standard Python notation relative to the last sample. None
```

--------------------------------

### DataRecorder class initialization

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/data_recorder.html

Initializes the DataRecorder to record Joulescope data to a file, supporting optional calibration and user-defined metadata.

```python
class DataRecorder:
    """Record Joulescope data to a file.

    :param filehandle: The file-like object or file name.
    :param calibration: The calibration bytes in datafile format.
        None (default) uses the unit gain calibration.
    :param user_data: Arbitrary JSON-serializable user data that is
        added to the file.
    """
    def __init__(self, filehandle, calibration=None, user_data=None):

        log.info('init')
        if isinstance(filehandle, str):
            self._fh = open(filehandle, 'wb')
            filehandle = self._fh
        else:
            self._fh = None

        self._sampling_frequency = 0
        self._samples_per_tlv = 0
        self._samples_per_block = 0
        self._samples_per_reduction = 0
        self._reductions_per_tlv = 0
        self._reduction = None

        self._sample_id_tlv = None  # sample id for start of next TLV
        self._sample_id_block = None  # sample id for start of current block, None if not started yet

        self._stream_buffer = None  # to ensure same
        self._sb_sample_id_last = None
        self._voltage_range = None
        self._data_buffer = []
        self._sample_buffers = {}

        self._writer = datafile.DataFileWriter(filehandle)
        self._closed = False
        self._total_size = 0

        if user_data is not None:
            b = json.dumps(user_data).encode('utf-8')
            self._writer.append(datafile.TAG_USER_JSON, b)
        if calibration is not None:
            if isinstance(calibration, Calibration):
                calibration = calibration.data
            self._writer.append_subfile('calibration', calibration)
```

--------------------------------

### View.statistics_get(start=None, stop=None, units=None, callback=None)

Source: https://joulescope.readthedocs.io/en/latest/api/view.html

Gets statistics over a range.

```APIDOC
## View.statistics_get(start=None, stop=None, units=None, callback=None)

### Description
Gets statistics over a range.

### Method
statistics_get

### Endpoint
View.statistics_get(start=None, stop=None, units=None, callback=None)

### Parameters
#### Request Body
- **start** (float or int) - Optional - The starting time.
- **stop** (float or int) - Optional - The ending time.
- **units** (str) - Optional - The units for start and stop. 'seconds' or None is in floating point seconds relative to the view. 'samples' is in stream buffer sample indices.
- **callback** (callable) - Optional - The optional callable. When provided, this method will not block and the callable will be called with the statistics data structure from the view thread.

### Response
#### Success Response
- **statistics** (object) - The statistics data structure or None if callback is provided.

```

--------------------------------

### Configure EXTIO settings via _extio_set

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/v0/driver.html

Constructs and sends a vendor-specific USB control transfer to update EXTIO parameters on the device.

```python
def _extio_set(self):
    msg = struct.pack('<BBBBIBBBBBBBBII',
                      PACKET_VERSION,
                      24,
                      PacketType.EXTIO,
                      0,  # hdr_rsv1
                      0,  # hdr_rsv4
                      0,  # flags
                      self._parameters['trigger_source'],
                      self._parameters['current_lsb'],
                      self._parameters['voltage_lsb'],
                      self._parameters['gpo0'],
                      self._parameters['gpo1'],
                      0,  # uart_tx mapping reserved
                      0,  # rsv1_u8
                      0,  # rsv3_u32, baudrate reserved
                      self._parameters['io_voltage'],
                      )
    rv = self._usb.control_transfer_out(
        'device', 'vendor', request=UsbdRequest.EXTIO,
        value=0, index=0, data=msg)
    _ioerror_on_bad_result(rv)
```

--------------------------------

### Data get handler for None

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/data_recorder.html

Handler that returns None when no data is available.

```python
    def _data_get_handler_none(self, start, stop, out):
        return None
```

--------------------------------

### Open device and configure stream buffer

Source: https://joulescope.readthedocs.io/en/latest/_modules/joulescope/v0/driver.html

The `_stream_buffer_open` method creates a stream buffer based on the configured buffer duration and reduction frequency. It selects `StreamBuffer` when input and output sampling frequencies match, otherwise `DownsamplingStreamBuffer`. The `open` method closes any existing stream buffer, clears statistics accumulators, opens the USB device, calls `_stream_buffer_open`, sets the current ranging, and attempts to fetch device info, calibration, and default parameters, logging warnings on failures.

```python
    def _stream_buffer_open(self):
        if self.stream_buffer:
            buffer, self.stream_buffer = self.stream_buffer, None
            del buffer
        stream_buffer_duration = self._parameters['buffer_duration']
        reduction_frequency = self._parameters['reduction_frequency']
        self._output_sampling_frequency = self.parameter_get('sampling_frequency', dtype='actual')
        reductions = _reduction_frequency_to_reductions(reduction_frequency)
        if self._input_sampling_frequency == self._output_sampling_frequency:
            log.info('Create StreamBuffer')
            self.stream_buffer = StreamBuffer(stream_buffer_duration, reductions,
                                              self._input_sampling_frequency)
        else:
            log.info('Create DownsamplingStreamBuffer')
            self.stream_buffer = DownsamplingStreamBuffer(stream_buffer_duration, reductions,
                                                          self._input_sampling_frequency,
                                                          self._output_sampling_frequency)
        self.stream_buffer.callback = self._statistics_callback_handler
```

```python
    def open(self, event_callback_fn=None):
        """Open the device for use.

        :param 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 :class:`DeviceEvent` values,
            and the message is a more detailed description of the event.
        :raise IOError: on failure.

        The event_callback_fn may be called asynchronous and from other
        threads.  The event_callback_fn must implement any thread safety.
        """
        if self.stream_buffer:
            self.close()
        self.statistics_accumulators_clear()
        self._usb.open(event_callback_fn)
        self._stream_buffer_open()
        self._current_ranging_set()
        try:
            info = self.info()
            if info is not None:
                log.info('info:\n%s', json.dumps(info, indent=2))
        except Exception:
            log.warning('could not fetch info record')
        try:
            self.calibration = self._calibration_read()
        except Exception:
            log.warning('could not fetch active calibration')
        try:
            cfg = self._parameters_defaults.get(self._config, {})
            for key, value in cfg.items():
                self.parameter_set(key, value)
        except Exception:
            log.warning('could not set defaults')
        return self
```

--------------------------------

### Build native modules on Linux and macOS

Source: https://joulescope.readthedocs.io/en/latest/_sources/user/install.rst.txt

Build native modules and set the PYTHONPATH for development.

```bash
python setup.py build_ext --inplace
export PYTHONPATH=`cwd`
```

--------------------------------

### DataReader.get_reduction(start=None, stop=None, units=None, out=None)

Source: https://joulescope.readthedocs.io/en/latest/api/data_recorder.html

Get the fixed reduction with statistics.

```APIDOC
## DataReader.get_reduction(start=None, stop=None, units=None, out=None)

### Description
Get the fixed reduction with statistics.

### Method
get_reduction

### Parameters
- **start** - The starting sample identifier (inclusive).
- **stop** - The ending sample identifier (exclusive).
- **units** - The units for start and stop. 'seconds' or None is in floating point seconds relative to the view. 'samples' is in stream buffer sample indices.
- **out** - The optional output np.ndarray((N, STATS_FIELD_COUNT), dtype=DTYPE) to populate with the result. None (default) will construct and return a new array.

### Returns
The np.ndarray((N, STATS_FIELD_COUNT), dtype=DTYPE) reduction data which normally is memory mapped to the underlying data, but will be copied on rollover.
```

--------------------------------

### open(event_callback_fn, mode, timeout)

Source: https://joulescope.readthedocs.io/en/latest/api/device.html

Opens the device for use. Optionally configures a callback for asynchronous events, sets the open mode, and specifies a timeout.

```APIDOC
## open(event_callback_fn, mode, timeout)

### Description
Opens the device with optional event callback, mode, and timeout.

### Parameters
- **event_callback_fn** (function) - Optional - Function(event, message) to call on asynchronous events.
- **mode** (string) - Optional - One of: 'defaults', 'restore', 'raw', or None (equivalent to 'defaults').
- **timeout** (float) - Optional - Timeout in seconds. None uses the default timeout.

### Method
open
```

--------------------------------

### sample_id_range

Source: https://joulescope.readthedocs.io/en/latest/api/stream_buffer.html

Property to get the range of sample ids currently available in the buffer.

```APIDOC
## sample_id_range (property)

### Description
Get the range of sample ids currently available in the buffer.

### Returns
- **tuple** - Tuple of sample_id start, sample_id end. Start and stop follow normal python indexing: start is inclusive, end is exclusive.

```
Tokens:
Raw