Metadata-Version: 2.4
Name: cds_rigol_dg1022z
Version: 0.3.0
Summary: Multi-instrument USB-TMC, VISA, and Ethernet control for Rigol DG1022Z generators
Author: PB LAB LLC
License: MIT License
        
        Copyright (c) 2026 PB LAB LLC
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://gitlab.com/test_equipments/rigol_dg1022z
Project-URL: Documentation, https://gitlab.com/test_equipments/rigol_dg1022z/-/blob/main/docs/index.html
Project-URL: Repository, https://gitlab.com/test_equipments/rigol_dg1022z.git
Project-URL: Issues, https://gitlab.com/test_equipments/rigol_dg1022z/-/issues
Keywords: rigol,dg1022z,dg1000z,function-generator,scpi,usbtmc,visa,laboratory-automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyusb>=1.2.1
Requires-Dist: libusb-package>=1.0.26.2
Requires-Dist: PySide6>=6.7
Requires-Dist: PyVISA>=1.14
Requires-Dist: packaging>=24.0
Provides-Extra: build
Requires-Dist: build>=1.2; extra == "build"
Requires-Dist: pyinstaller>=6.0; extra == "build"
Requires-Dist: twine>=6.0; extra == "build"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Provides-Extra: release
Requires-Dist: python-semantic-release<11,>=10; extra == "release"
Dynamic: license-file

# Rigol DG1022Z Control Center

Python control of the Rigol DG1000Z family over Ethernet, direct USB-TMC, or an
installed VISA runtime such as Rigol UltraSigma/IVI-VISA.

Licensed under the MIT License. See [LICENSE](LICENSE).

The included PySide6 desktop application mirrors the generator workflow with
channel controls, live waveform previews, modulation, sweep, burst, arbitrary
waveforms, counter readings, system actions, and a raw SCPI console.

The application is a multi-instrument workspace. Use **+ Add unit** to create an
independent tab for each generator. Tabs may mix Ethernet and USB connections.
Ethernet generators can be discovered automatically on local `/24` networks or
addressed manually when routing or firewall rules prevent discovery.
Connected USB serial numbers are reserved by their owning tab and are removed
from USB discovery in every other tab until disconnected or closed.
Once connected, the transport and endpoint controls are locked and grayed out
until the red **Disconnect** button is selected.

Each unit tab creates a device-specific diagnostic log, and the application
creates a separate general lifecycle log under:

```text
%USERPROFILE%\PB_LAB\DG1022Z_Control\logs
```

Open **File > Documentation** for the complete HTML manual. The desktop viewer
renders the same `docs/index.html` page that can be opened in a web browser, so
GUI instructions and Python automation examples share one source. The manual
links to the PB LAB operator guide, Rigol user guide, programming guide, and
datasheet.

## Install from PyPI

The standard installation includes the driver, GUI, Ethernet, direct USB-TMC,
VISA support, HTML documentation, and bundled Rigol manuals:

```powershell
py -m pip install cds_rigol_dg1022z
cds_rigol_dg1022z_gui
```

At startup the GUI checks PyPI in the background. When a newer package version
is available, a banner offers an explicit **Update now** action. The application
never installs an update without that click. Offline checks are silently
skipped. On Windows, the updater closes the GUI first so pip can replace the
running launcher safely, installs the package, and reopens the GUI automatically.

Python applications can then use:

```python
from cds_rigol_dg1022z import DG1022Z, discover_usb_connections
```

## Install for development

```powershell
py -m pip install -e ".[test,build]"
pytest
```

The automated suite covers device command generation, properties, malformed
responses, Ethernet framing and failures, USB-TMC packets and protocol errors,
logging, modulation, sweep, burst, arbitrary waveforms, and system commands.

## Automated releases

GitLab CI tests Python 3.10 through 3.13 and validates the wheel and source
distribution. On the default branch, Python Semantic Release updates the
version and changelog from Conventional Commits, creates a release commit and
tag, and publishes through PyPI Trusted Publishing. See
[RELEASING.md](RELEASING.md) for the one-time GitLab/PyPI setup and commit rules.

Physical-instrument smoke tests are opt-in:

```powershell
$env:RIGOL_DG1022Z_IP = "192.168.1.100"
$env:RIGOL_DG1022Z_USB_SERIAL = "DG1ZA000000001"
pytest --run-hardware -m hardware
```

Hardware communication requires both the explicit `--run-hardware` flag and the
corresponding environment variable. This prevents stale or placeholder variables
from contacting lab equipment during an ordinary `pytest` run. Without the flag,
hardware tests are safely skipped and the complete offline unit suite still runs.

Launch the GUI:

```powershell
cds_rigol_dg1022z_gui
```

Closing a unit tab releases its connection. An unexpected command or transport
failure is contained to the operation/session and reported in a dialog; other
connected units remain available. No software can promise immunity from every
OS, hardware, or native-library failure, so output safety must still be enforced
in the connected test fixture.

## Ethernet

On the generator, open **Utility > I/O Config > LAN** and note the IP address.
The DG1000Z socket control port documented by Rigol is 5555.

```python
from cds_rigol_dg1022z import DG1022Z

with DG1022Z.ethernet("192.168.1.100") as dg:
    print(dg.identify())
    dg.channel(1).configure_sine(frequency=1000, amplitude=2.0)
    dg.channel(1).output_enabled = True
```

CLI test:

```powershell
cds_rigol_dg1022z --ethernet 192.168.1.100 --command "*IDN?"
```

## USB

Connect the rear USB Device connector to the PC. In the GUI, choose **USB** and
select **Refresh devices**. The picker combines:

- devices exposed by Rigol UltraSigma/IVI-VISA;
- devices available through direct USB-TMC/libusb.

When both backends report the same serial number, the VISA/UltraSigma entry is
shown once and preferred because it owns the active Windows driver association.
Already-connected serials are removed from pickers in other unit tabs.

```python
from cds_rigol_dg1022z import DG1022Z, discover_usb

print(discover_usb())
with DG1022Z.usb() as dg:
    print(dg.identify())
```

CLI test:

```powershell
cds_rigol_dg1022z --discover-usb
cds_rigol_dg1022z --discover-ethernet
cds_rigol_dg1022z --usb --command "*IDN?"
```

### Windows USB driver note

If UltraSigma or another VISA runtime owns the device, the application uses that
VISA resource. Otherwise, direct USB requires Windows to bind the interface to a
libusb-compatible driver such as WinUSB. A packaged application includes PyVISA,
PyUSB, and libusb, but it cannot silently replace a Windows driver association.

## Raw SCPI access

The generator's internal `.RSF` state files can be listed and recalled from the
GUI's **Saved States** tab or from Python:

```python
with DG1022Z.ethernet("192.168.1.100") as dg:
    states = dg.internal_state_files()
    for state in states:
        print(f"USER{state.slot}: {state.filename}")
    dg.recall_internal_state(states[0].slot)
```

Recall applies the complete state stored in that USER slot and may change active
outputs. Confirm the connected circuit is safe and verify the instrument front
panel afterward. This accesses internal generator storage; it does not upload an
RSF file from the PC.

Every command in the Rigol programming guide is available immediately, even when
there is no convenience wrapper:

```python
dg.write(":SOUR1:BURS ON")
cycles = dg.query(":SOUR1:BURS:NCYC?")
```

## Build a standalone executable

```powershell
pyinstaller --noconfirm --windowed --onefile --name Rigol-DG1022Z-Control `
  --icon assets/Function_Generator.ico `
  --add-data "assets;assets" --add-data "docs;docs" `
  --collect-all libusb_package --collect-all PySide6 `
  launch_gui.py
```

The resulting executable contains Python, PyUSB, and libusb. End users do not
install Python, NI-VISA, UltraSigma, or pip packages. Ethernet requires no driver.

## Safety

Outputs retain their last state if a program exits unexpectedly. Call
`outputs_off()` in a `finally` block when the connected equipment requires a
guaranteed safe shutdown.

## Included official documentation

- `docs/DG1000Z_DataSheet_EN.pdf`
- `docs/DG1000Z_UserGuide_EN.pdf`
- `docs/DG1000Z_ProgrammingGuide_EN.pdf`

These PDFs are supplied by Rigol and should be checked for redistribution terms
before publishing an installer outside your organization.
