Metadata-Version: 2.4
Name: RigolWFM
Version: 1.5.0
Summary: Read, parse, and convert oscilloscope waveform files
Author-email: Scott Prahl <scott.prahl@oit.edu>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/scottprahl/RigolWFM
Project-URL: Documentation, https://rigolwfm.readthedocs.io
Project-URL: Source, https://github.com/scottprahl/RigolWFM
Project-URL: Tracker, https://github.com/scottprahl/RigolWFM/issues
Keywords: oscilloscope,waveform,parser,kaitai,Rigol,Tektronix,LeCroy,Agilent,Keysight,Siglent,Yokogawa,Rohde & Schwarz,wfm,DS1000B,DS1074B,DS1104B,DS1204B,DS1000C,DS1000CD,DS1000M,DS1000MD,DS1042C,DS1102CA,DS1202CA,DS1302CA,DS1062CA,DS1000D,DS1102D,DS1052D,DS1102D,DS1000E,DS1052E,DS1102E,DS1000Z,DS1054Z,MSO1054Z,DS1074Z,DS1074Z-S,MSO1074Z,DS1104Z,DS1104Z-S,MSO1104Z,DS1202Z,DS2000,DS2072A,DS2102A,MSO2102A,MSO2102A-S,DS2202A,MSO2202A,MSO2202A-S,DS2302A,MSO2302A,MSO2302A-S,DS4000,DS4012,MSO4012,DS4014,MSO4014,DS4022,MSO4022,DS4024,MSO4024,DS4032,MSO4032,DS4034,MSO4034,DS4052,MSO4052,DS4054,MSO4054,DS6000,DS6062,DS6064,DS6102,DS6104,MSO5000,MSO5074,MSO5354,MSO7000,DS7000,MSO8000,DS8000,DHO800,DHO814,DHO824,DHO1000,DHO1074,DHO1104
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: kaitaistruct>=0.9
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: requests
Provides-Extra: docs
Requires-Dist: Sphinx>=8.1.3; extra == "docs"
Requires-Dist: nbsphinx>=0.9.7; extra == "docs"
Requires-Dist: sphinx-automodapi; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: ipython; extra == "docs"
Requires-Dist: PyYAML; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: yamllint; extra == "dev"
Requires-Dist: rstcheck[sphinx,toml]; extra == "dev"
Requires-Dist: black[jupyter]; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pip; extra == "dev"
Requires-Dist: check-manifest; extra == "dev"
Requires-Dist: pyroma; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: jupyterlab; extra == "dev"
Requires-Dist: nbconvert; extra == "dev"
Requires-Dist: nbformat; extra == "dev"
Requires-Dist: imageio; extra == "dev"
Requires-Dist: pandas; extra == "dev"
Requires-Dist: PyYAML; extra == "dev"
Provides-Extra: lite
Requires-Dist: jupyterlite-core<0.8,>=0.7; extra == "lite"
Requires-Dist: jupyterlite-pyodide-kernel<0.8,>=0.7; extra == "lite"
Dynamic: license-file

.. |pypi-badge| image:: https://img.shields.io/pypi/v/RigolWFM?color=68CA66
   :target: https://pypi.org/project/RigolWFM/
   :alt: pypi

.. |github-badge| image:: https://img.shields.io/github/v/tag/scottprahl/RigolWFM?label=github&color=68CA66
   :target: https://github.com/scottprahl/RigolWFM
   :alt: github

.. |conda-badge| image:: https://img.shields.io/conda/vn/conda-forge/RigolWFM?label=conda&color=68CA66
   :target: https://github.com/conda-forge/RigolWFM-feedstock
   :alt: conda

.. |kaitaistruct| image:: https://img.shields.io/badge/kaitai-struct-68CA66
   :target: https://ide.kaitai.io
   :alt: kaitai-struct

.. |zenodo-badge| image:: https://zenodo.org/badge/244228290.svg
   :target: https://zenodo.org/badge/latestdoi/244228290
   :alt: doi

.. |license-badge| image:: https://img.shields.io/github/license/scottprahl/RigolWFM?color=68CA66
   :target: https://github.com/scottprahl/RigolWFM/blob/main/LICENSE.txt
   :alt: License

.. |test-badge| image:: https://github.com/scottprahl/RigolWFM/actions/workflows/test.yaml/badge.svg
   :target: https://github.com/scottprahl/RigolWFM/actions/workflows/test.yaml
   :alt: Testing

.. |docs-badge| image:: https://readthedocs.org/projects/rigolwfm/badge?color=68CA66
   :target: https://rigolwfm.readthedocs.io
   :alt: Docs

.. |downloads-badge| image:: https://img.shields.io/pypi/dm/RigolWFM?color=68CA66
   :target: https://pypi.org/project/RigolWFM/
   :alt: Downloads

.. |view| image:: https://img.shields.io/badge/view-scope_file-68CA66
   :target: https://scottprahl.github.io/RigolWFM/
   :alt: Oscilloscope Web Viewer

RigolWFM
=========

by Scott Prahl

A utility to process oscilloscope waveform files
------------------------------------------------

|pypi-badge| |github-badge| |conda-badge| |kaitaistruct| |zenodo-badge|

|license-badge| |test-badge| |docs-badge| |downloads-badge|

|view|

This project started as a resource for interpreting the proprietary ``.wfm``
files created by Rigol oscilloscopes.  It now also includes parsers for
Tektronix, LeCroy, Agilent / Keysight, Siglent, Yokogawa, and Rohde &
Schwarz waveform files.
Open source tools that can parse or convert these binary oscilloscope formats
are often balkanized: each program tends to support a single oscilloscope
group.  I have gathered a bunch together here.

This project leverages the domain specific language at
<https://doc.kaitai.io> to describe binary files.  Once a format has been
described in this text form, parsers can be generated for a wide range of
languages.

Installation
---------------

You can install locally using pip::
    
    pip install RigolWFM

or ``conda``::

    conda install -c conda-forge RigolWFM

or just open <https://scottprahl.github.io/RigolWFM/> and try the web version.

Usage
-----

Once ``RigolWFM`` is installed, you can plot signals from supported waveform
files by::

   import matplotlib.pyplot as plt
   from RigolWFM import Wfm

   w = Wfm.from_file("example.wfm")
   w.plot()
   plt.show()

``Wfm.from_file()`` will autodetect the file family for supported formats, so
the same call works for Rigol ``.wfm`` / ``.bin`` files, Tektronix ``.wfm`` /
``.isf`` files, LeCroy ``.trc`` files, Agilent / Keysight ``AGxx`` ``.bin``
files, supported Siglent ``.bin`` revisions, Yokogawa ``.wfm`` files, and
Rohde & Schwarz RTP XML ``.bin`` files with companion ``.Wfm.bin`` payloads.


Alternatively, ``wfmconvert`` can be used from the command line.  For example, the following should convert all the DS1000E files in the current directory to the ``.csv`` format::

   prompt> wfmconvert csv *.wfm

If you just wanted to convert channel 1 from a single file to ``.csv`` then::

   prompt> wfmconvert --channel 1 csv DS1102E.wfm

If you wanted to a signal `.wav` file using the second channel waveform (for use with LTspice) then:: 

   prompt> wfmconvert --channel 2 wav *.wfm

If you want to create a ``.wav`` file with channels one and four as signals (using the default auto scaling for Audacity or Sigrok Pulseview)::

   prompt> wfmconvert --channel 14 wav *.wfm

The project also includes a browser-based viewer at
<https://scottprahl.github.io/RigolWFM/>.  The current web app supports Rigol
``.wfm`` / ``.bin`` files, Tektronix ``.wfm`` / ``.isf`` files, LeCroy
``.trc`` files, Agilent / Keysight ``AGxx`` ``.bin`` files, Rohde &
Schwarz RTP XML ``.bin`` files plus their companion ``.Wfm.bin`` payloads,
and supported Siglent ``.bin`` revisions.

Status
------

There are binary file descriptions and normalized adapters for waveform files
created by the following oscilloscopes.  Most of these work directly through
``Wfm.from_file()``; rows with special limitations are called out in the notes.

+--------------------+------------------+-------------------+-----------------------------------------------+
| Family             | Models           | Format            | Notes                                         |
+====================+==================+===================+===============================================+
| Rigol DS1000B      | DS1074/1104/     | ``.wfm``          | tested                                        |
|                    | 1204B            |                   |                                               |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Rigol DS1000C      | DS1042/1102/     | ``.wfm``          | tested (limited files)                        |
|                    | 1202CA           |                   |                                               |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Rigol DS1000D      | DS1052/1102D     | ``.wfm``          | tested (limited files)                        |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Rigol DS1000E      | DS1052/1102E     | ``.wfm``          | tested                                        |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Rigol DS1000Z      | DS1054Z,         | ``.wfm``          | tested                                        |
|                    | MSO1054Z, etc.   |                   |                                               |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Rigol DS2000       | DS2072A,         | ``.wfm``          | tested                                        |
|                    | MSO2102A, etc.   |                   |                                               |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Rigol DS4000       | DS4012-DS4054,   | ``.wfm``          | tested                                        |
|                    | MSO4012-MSO4054  |                   |                                               |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Rigol DS6000       | DS6062-DS6104    | ``.wfm``          | untested                                      |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Rigol MSO5000      | MSO5354, etc.    | ``.bin``          | tested                                        |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Rigol MSO7000 /    | DS7000, MSO7000, | ``.bin``          | tested                                        |
| MSO8000            | MSO8000, DS8000  |                   |                                               |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Rigol DHO800 /     | DHO800, DHO1000  | ``.bin``          | tested; calibrated float32 samples, official  |
| DHO1000            |                  | ``.wfm``          | ``.bin`` and proprietary ``.wfm`` support     |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Tektronix WFM      | modern DPO/DSA   | ``.wfm``          | supports ``WFM#001``/``WFM#002``/``WFM#003``; |
|                    | families         |                   | legacy ``LLWFM`` also supported               |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Tektronix ISF      | many Tek scopes  | ``.isf``          | tested                                        |
+--------------------+------------------+-------------------+-----------------------------------------------+
| LeCroy             | many WaveRunner/ | ``.trc``          | tested; handles SCPI-prefixed ``WAVEDESC``    |
|                    | WaveSurfer/etc.  |                   | files                                         |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Agilent /          | InfiniiVision /  | ``.bin``          | supports ``AG01``/``AG03``/``AG10`` analog    |
| Keysight           | Infiniium        |                   | captures; low-level parser preserves segments |
|                    |                  |                   | and multi-buffer metadata                     |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Rohde & Schwarz    | RTP / RTO / RTM  | ``.bin`` +        | normalized single-acquisition analog exports; |
| RTP export         | families         | ``.Wfm.bin``      | history / multi-acquisition captures reject   |
|                    |                  |                   | explicitly                                    |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Siglent            | documented       | ``.bin``          | supports documented V0.1-V6 revisions; old    |
|                    | ``.bin``         |                   | platform files are detectable via low-level   |
|                    | families         |                   | parsers but not normalized yet                |
+--------------------+------------------+-------------------+-----------------------------------------------+
| Yokogawa           | ASCII-header     | ``.wfm``          | tested single-file import path                |
|                    | waveform exports |                   |                                               |
+--------------------+------------------+-------------------+-----------------------------------------------+

Resources
---------

This has been a bit of an adventure.  In the process of nailing down the basic formats, I have gleaned information from a wide range of projects started by others.

* Shein's <https://sourceforge.net/projects/wfmreader>
* Wagenaars's <https://www.mathworks.com/matlabcentral/fileexchange/18999-read-binary-rigol-waveforms>
* Steele's <http://nsweb.tn.tudelft.nl/~gsteele/rigol2dat>
* Blaicher's <https://github.com/mabl/pyRigolWFM>
* Szkutnik's <https://github.com/michal-szkutnik/pyRigolWfm1000Z>
* Cat-Ion's <https://github.com/Cat-Ion/rigol-ds4000-wfm>
* Šolc's <https://www.tablix.org/~avian/blog/archives/2019/08/quick_and_ugly_wfm_data_export_for_rigol_ds2072a/>
* Contributions from <http://www.hakasoft.com.au/wfm_viewer>
* Rigol's documentation of the 1000E, 1000Z, 2000, and 6000 file formats.
* Rigol's documentation of the ``.bin`` formats for the 1000, 5000, and 8000
* Lathe's <https://github.com/Lathe26/WFM_for_Rigol_DHO800_900>
* Nezarati's <https://nezarati.github.io/waveform-viewer/index.html>
* Wavebin's <https://github.com/eyalroz/wavebin> Agilent / Keysight parsers and samples
* Agilent / Keysight ``.bin`` reference readers and programming guides
* Siglent's waveform format PDF and vendor reference parsers
* SMASH toolbox vendor importers for Tektronix, LeCroy, and Yokogawa formats

License
-------
    BSD 3-clause -- see the file ``LICENSE`` for details.
