niscope 0.8.0.dev0

NI-SCOPE Python API

Overall Status

master branch status
GitHub status

Info	Python bindings for NI Modular Instrument drivers. See GitHub for the latest source.
Author	National Instruments

About

The nimi-python repository generates Python bindings (Application Programming Interface) for interacting with the Modular Instrument drivers. Currently, the following drivers are supported:

• NI-DCPower (Python module: nidcpower)

• NI-DMM (Python module: nidmm)

• NI-FGEN (Python module: nifgen)

• NI-SCOPE (Python module: niscope)

• NI-SWITCH (Python module: niswitch)

• NI-ModInst (Python module: nimodinst)

It is implemented as a set of Mako templates and per-driver metafiles that produce a Python module for each driver. The driver is called through its public C API using the ctypes Python library.

nimi-python supports all the Operating Systems supported by the underlying driver.

nimi-python supports Python 2.7, 3.4 and later using CPython or PyPy.

NI-SCOPE Python API Status

NI-SCOPE (niscope)
Driver Version Tested Against	17.0.2
PyPI Version
Supported Python Version
Open Issues
Open Pull Requests

Installation

As a prerequisite to using the niscope module, you must install the NI-SCOPE runtime on your system. Visit ni.com/downloads to download the driver runtime for your devices.

The nimi-python modules (i.e. for NI-SCOPE) can be installed with pip:

$ python -m pip install niscope

Or easy_install from setuptools:

$ python -m easy_install niscope

Contributing

We welcome contributions! You can clone the project repository, build it, and install it by following these instructions.

Usage

The following is a basic example of using the niscope module to open a session to a High Speed Digitizer and capture a single record of 1000 points.

import niscope
with niscope.Session("Dev1") as session:
    session.channels[0].configure_vertical(range=1.0, coupling=niscope.VerticalCoupling.AC)
    session.channels[1].configure_vertical(range=10.0, coupling=niscope.VerticalCoupling.DC)
    session.configure_horizontal_timing(min_sample_rate=50000000, min_num_pts=1000, ref_position=50.0, num_records=5, enforce_realtime=True)
    with session.initiate():
        waveforms = session.channels[0,1].fetch(num_records=5)
    for wfm in waveforms:
        print('Channel {0}, record {1} samples acquired: {2:,}\n'.format(wfm.channel, wfm.record, len(wfm.wfm)))

    # Find all channel 1 records (Note channel name is always a sting even if integers used in channel[])
    chan1 = [wfm for wfm in waveforms if wfm.channel == '0']

    # Find all record number 3
    rec3 = [wfm for wfm in waveforms if wfm.record == 3]

The waveform returned from fetch is a flat list of Python objects

• Attributes:

  • relative_initial_x (float) the time (in seconds) from the trigger to the first sample in the fetched waveform

  • absolute_initial_x (float) timestamp (in seconds) of the first fetched sample. This timestamp is comparable between records and acquisitions; devices that do not support this parameter use 0 for this output.

  • x_increment (float) the time between points in the acquired waveform in seconds

  • channel (str) channel name this waveform was asquire from

  • record (int) record number of this waveform

  • gain (float) the gain factor of the given channel; useful for scaling binary data with the following formula:

    \begin{equation*} voltage = binary data * gain factor + offset \end{equation*}

  • offset (float) the offset factor of the given channel; useful for scaling binary data with the following formula:

    \begin{equation*} voltage = binary data * gain factor + offset \end{equation*}

  • wfm (array of float) floating point array of samples. Length will be of the actual samples acquired

• Such that all record 0 waveforms are first. For example, with a channel list of 0,1, you would have the following index values:

  • index 0 = record 0, channel 0

  • index 1 = record 0, channel 1

  • index 2 = record 1, channel 0

  • index 3 = record 1, channel 1

  • etc.

If you need more performance or need to work with SciPy, you can use the fetch_into() method instead of fetch(). This method takes an already allocated numpy array and puts the acquired samples in it. Data types supported:

• numpy.float64

• numpy.int8

• numpy.in16

• numpy.int32

voltage_range = 1.0
record_length = 2000
channels = [0, 1]
num_channels = len(channels)
num_records = 5
wfm = numpy.ndarray(num_channels * record_length, dtype=numpy.int8)
session.configure_vertical(voltage_range, niscope.VerticalCoupling.AC)
session.configure_horizontal_timing(50000000, record_length, 50.0, num_records, True)
with session.initiate():
    waveform_infos = session.channels[channels].fetch_into(wfm=wfm, num_records=num_records)

The waveform_infos returned from fetch_into is a 1D list of Python objects

• Attributes:

  • relative_initial_x (float) the time (in seconds) from the trigger to the first sample in the fetched waveform

  • absolute_initial_x (float) timestamp (in seconds) of the first fetched sample. This timestamp is comparable between records and acquisitions; devices that do not support this parameter use 0 for this output.

  • x_increment (float) the time between points in the acquired waveform in seconds

  • channel (str) channel name this waveform was asquire from

  • record (int) record number of this waveform

  • gain (float) the gain factor of the given channel; useful for scaling binary data with the following formula:

    \begin{equation*} voltage = binary data * gain factor + offset \end{equation*}

  • offset (float) the offset factor of the given channel; useful for scaling binary data with the following formula:

    \begin{equation*} voltage = binary data * gain factor + offset \end{equation*}

  • wfm (numpy array of datatype used) floating point array of samples. Length will be of the actual samples acquired

    Note

    Python 3 only

• Such that all record 0 waveforms are first. For example, with a channel list of 0,1, you would have the following index values:

  • index 0 = record 0, channel 0

  • index 1 = record 0, channel 1

  • index 2 = record 1, channel 0

  • index 3 = record 1, channel 1

  • etc.

Note

When using Python 2, the waveform_infos objects do not include the waveform for that record. Instead, samples are in the waveform passed into the function using the following layout:

• index 0 = record 0, channel 0

• index x = record 0, channel 1

• index 2x = record 1, channel 0

• index 3x = record 1, channel 1

• …

• Where x = the record length

Additional examples for NI-SCOPE are located in src/niscope/examples/ directory.

Support / Feedback

The packages included in nimi-python package are supported by NI. For support, open a request through the NI support portal at ni.com.

Bugs / Feature Requests

To report a bug or submit a feature request, please use the GitHub issues page.

Information to Include When Asking for Help

Please include all of the following information when opening an issue:

• Detailed steps on how to reproduce the problem and full traceback, if applicable. Code samples are encouraged!

• The python version used:

  $ python -c "import sys; print(sys.version)"

• The module (i.e. nidmm) and its version:

  $ python -m pip list

• The version of the driver used (i.e. NI-DMM 17.1). Follow this KB article to determine the version you have installed.

• The operating system, version, and bitness. For example 64-bit Windows 7.

Documentation

Documentation is available here.

License

nimi-python is licensed under an MIT-style license (see LICENSE). Other incorporated projects may be licensed under different licenses. All licenses allow for non-commercial and commercial use.