Metadata-Version: 2.4
Name: rigol-ds1000z
Version: 1.0.0
Summary: Python library for interfacing with Rigol DS1000Z series oscilloscopes.
License-Expression: MIT
License-File: LICENSE
Keywords: rigol,ds1000z,oscilloscope,scpi,visa,instrument
Author: amosborne
Author-email: alex@osborneee.com
Requires-Python: >=3.14,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Requires-Dist: PyVISA (>=1.14,<2.0)
Requires-Dist: PyVISA-py[hislip-discovery,usb-full] (>=0.8,<0.9)
Requires-Dist: matplotlib (>=3.10,<4.0)
Requires-Dist: numpy (>=2.1,<3.0)
Requires-Dist: pyserial (>=3.5,<4.0)
Requires-Dist: si-prefix (>=1.2,<2.0)
Requires-Dist: textual (==0.1.18)
Project-URL: Homepage, https://amosborne.github.io/rigol-ds1000z/
Project-URL: Repository, https://github.com/amosborne/rigol-ds1000z
Description-Content-Type: text/markdown

# rigol-ds1000z

In addition to this README, I have also written a [blog post](https://www.osborneee.com/rigol-ds1000z/) about this application.

## An oscilloscope user interface that never leaves the terminal.

![RigolDS1000Z_StillScreen](https://github.com/amosborne/rigol-ds1000z/raw/main/docs/rigol_ds1000z.png)

![Rigol_DS1000Z_Animated](https://github.com/amosborne/rigol-ds1000z/raw/main/docs/rigol_ds1000z.gif)

## A simple command line tool for grabbing data and pictures.

```shell
rigol-ds1000z --help
rigol-ds1000z --visa rsrc --display path/to/file.png
rigol-ds1000z --visa rsrc --waveform src path/to/file.csv 
```

Unless a VISA resource is specified with the `--visa` argument, the CLI will search for a Rigol DS1000Z series oscilloscope and connect to the first one it finds.

The CLI can capture and save to file an image of the display (`--display`) or the waveform data of the specified source channel (`--waveform`).

## A compact Python interface for automating test procedures.

See the provided [examples](https://github.com/amosborne/rigol-ds1000z/tree/main/examples) and read the [documentation.](https://amosborne.github.io/rigol-ds1000z/)

```python
from rigol_ds1000z import Rigol_DS1000Z
from rigol_ds1000z import process_display, process_waveform
from time import sleep

with Rigol_DS1000Z() as oscope:
    # reset to defaults and print the IEEE 488.2 instrument identifier
    oscope.rst()
    print(oscope.idn())

    # configure channel 2, the timebase, and the trigger
    channel = oscope.channel(2, probe=10, scale=1, coupling="AC", display=True)
    timebase = oscope.timebase(main_scale=200e-6)
    trigger = oscope.trigger(mode="EDGE", edge_source=2, coupling="DC", edge_level=0)

    # wait three seconds then single trigger
    oscope.single()
    sleep(3)

    # capture the display image
    display = oscope.display()
    process_display(display, show=True)

    # plot the channel 2 waveform data
    waveform = oscope.waveform(source=2)
    process_waveform(waveform, show=True)

```

## Installation instructions and notes to the user.

`pip install rigol-ds1000z`

Version 1.0.0 requires Python 3.14 or newer. The terminal interface still uses
Textual 0.1.18.

### Migrating from 0.3.0

- IEEE 488.2 commands are methods: use `oscope.rst()` and `oscope.idn()` in
  place of `oscope.ieee(rst=True)` and its returned fields.
- Edge trigger arguments and results use `edge_source`, `edge_slope`, and
  `edge_level`. Noise rejection uses `nreject`.
- Display brightness uses `wbrightness` and `gbrightness`. Use `oscope.clear()`
  to clear the display.
- Measurement results are in `.item`; use `counter_source` and `.counter_value`
  for the frequency counter, and `statistic_item=("MAX", "VPP")` for statistics.
- Returned namedtuple field order has changed; access results by field name.

Available on [PyPI](https://pypi.org/project/rigol-ds1000z/). This package uses [PyVISA](https://pyvisa.readthedocs.io/en/1.12.0/introduction/getting.html) to communicate with the oscilloscope. The user will have to install some VISA backend library for their operating system such as National Instrument's VISA library or libusb (this package supports both the "@ivi" and "@py" PyVISA backends transparently).

This software has been tested on Windows (Command Prompt and PowerShell), although it should be possible to run in other shells and/or operating systems. For best visual performance, a default of white text on a black background is recommended.

Reset and autoscale block on the IEEE 488.2 `*OPC?` query until the instrument reports the operation complete, so no fixed sleep is inserted. The user may still find that they require additional settle time after certain command sequences (for example, after arming a single-trigger acquisition before reading the trigger status).

## Software development and references.

[Rigol DS1000Z programming manual.](https://beyondmeasure.rigoltech.com/acton/attachment/1579/f-0386/1/-/-/-/-/DS1000Z_Programming%20Guide_EN.pdf)

| Command Category | Coverage |
| --- | --- |
| AUToscale, etc. | YES |
| ACQuire | YES |
| CALibrate | no |
| CHANnel | YES |
| CURSor | no |
| DECoder | no |
| DISPlay | YES |
| ETABle | no |
| FUNCtion | no |
| IEEE 488.2 | YES |
| LA | no |
| LAN | no |
| MATH | no |
| MASK | no |
| MEASure | YES |
| REFerence | no |
| STORage | no |
| SYSTem | no |
| TIMebase | YES |
| TRIGger | PARTIAL |
| WAVeform | YES |

- Package management by [Poetry](https://python-poetry.org/).
- Automated processing hooks by [pre-commit](https://pre-commit.com/).
- Code formatting in compliance with [PEP8](https://www.python.org/dev/peps/pep-0008/) by [isort](https://pycqa.github.io/isort/), [black](https://github.com/psf/black), and [flake8](https://gitlab.com/pycqa/flake8).
- Static type checking in compliance with [PEP484](https://www.python.org/dev/peps/pep-0484/) by [mypy](http://www.mypy-lang.org/).
- Test execution with random ordering and code coverage analysis by [pytest](https://docs.pytest.org/en/6.2.x/).
- Automated documentation generation by [sphinx](https://www.sphinx-doc.org/en/master/).

Installing the development environment requires running the following command sequence.

```shell
poetry install
poetry run pre-commit install
```

In order for all tests to pass channel 2 must be connected to the calibration square wave.

