# DG5000 Pro MATLAB Demonstration Retrospective

Date: 2026-07-29  
Project: Rigol DG5000 Pro direct TCP/SCPI control  
Primary demonstration: `DG5000Pro_MultiChannel_Sine_Demo.m`  
Status: Tested with a Rigol DG5254 Pro

## Purpose

This retrospective records the challenges, discarded approaches, and design
decisions that shaped the readable multi-channel MATLAB demonstration. It is
not a replacement for the source code.

## Error Messages Became Misleading

### Challenge

A failed TCP connection produced a long MATLAB exception that looked
intimidating to a new user.

### Attempt

The exception was translated into a shorter explanation that suggested
checking port 5025.

### Why It Was Unsatisfactory

Port 5025 was correct for the tested DG5254 Pro, but not every Rigol
instrument necessarily uses that port. A friendly translation could hide
useful MATLAB diagnostic information while presenting an inferred cause as a
fact.

### Resolution

Display the selected IP address and port as configuration context, then
preserve MATLAB's complete native exception report.

### Reusable Lesson

Add known context to an error without replacing uncertain technical details
with confident assumptions. Model-specific defaults belong in documentation,
not in a universal error diagnosis.

## Too Many Configuration Paths Obscured the Demonstration

### Challenge

Environment variables and override flags were introduced for output shutdown,
phase alignment, and technical error reporting. Hard-coded flags could also
produce Code Analyzer warnings for intentionally unreachable branches.

### Why It Was Unsatisfactory

The same behavior could be controlled from multiple places, making it harder
to determine which setting was active. The additional flexibility made the
demonstration less readable.

### Resolution

Remove the environment-variable overrides and options that did not materially
improve the experiment. Keep the meaningful connection, channel, and phase
reference settings together near the top of the script.

### Reusable Lesson

A demonstration should normally have one visible configuration path.
Flexibility has negative value when it obscures the active experiment.

## Functions Restored the Experimental Story

### Challenge

Validation, SCPI command construction, writing, reading, comparison, error
handling, and output control interrupted the main top-to-bottom flow.

### Resolution

Keep the main script as an ordered description of the experiment. Move
repetitive operations and implementation details into local functions.

### Reusable Lesson

Functions are valuable in a demonstration when their names expose the
experimental sequence. Reducing line count alone is not a sufficient reason
to create a function.

## A Numeric Matrix Simplified Channel Configuration

### Challenge

Each possible output required an enable state, frequency, amplitude, phase,
and expected load. Separate flags and parallel arrays required unnecessary
coordination.

### Resolution

Represent each channel as one row in a numeric configuration matrix. Select
enabled rows with a logical mask:

```matlab
activeRows = A(:, 2) == 1;
selectedChannels = A(activeRows, 1).';
```

Parameters in disabled rows do not participate in the experiment and may use
simple numeric placeholders.

### Reusable Lesson

When several properties describe the same collection of items, a row-oriented
configuration matrix plus logical indexing can be clearer than parallel
variables and repeated conditionals.

## Local Validation Should Not Duplicate the Instrument

### Challenge

MATLAB could attempt to encode every valid frequency, amplitude, phase,
channel count, waveform, and model-specific limit.

### Why It Was Unsatisfactory

Instrument limits can vary by model, waveform, load, configuration, and
firmware. A large local validator would be difficult to read and could still
be wrong.

### Resolution

Perform inexpensive structural checks locally:

- the configuration is numeric;
- the matrix has the expected shape;
- enabled channel positions do not exceed the declared model capacity.

Then write the requested settings to the instrument, read the settings back,
and compare actual values with desired values.

### Reusable Lesson

Validate data structure and program assumptions locally, while allowing the
instrument and its read-back results to remain authoritative about operating
limits.

## Output Enablement Became a Commit Step

### Challenge

Enabling outputs before verification could apply an incomplete, rejected, or
unexpected configuration to the connected circuit.

### Resolution

Use this order:

1. Validate the configuration structure.
2. Connect to and identify the instrument.
3. Turn off only the selected outputs while they are being configured.
4. Write the selected channel settings.
5. Read the settings back.
6. Compare desired and actual values.
7. Perform phase alignment when a selected phase-reference channel requests
   it.
8. Enable the selected outputs only after all checks pass.

### Reusable Lesson

For instrument control, separate configuration from activation. Treat output
enablement as a deliberate commit step after verification.

## Load Setting Belongs With Each Channel

### Challenge

The requested voltage depends on the Rigol's configured load. A waveform set
for a high-impedance oscilloscope input should not silently retain a 50-ohm or
other load setting from an earlier experiment.

### Resolution

Add expected load as the sixth column of the channel matrix. Write the load
before amplitude, read it back with the other channel settings, and represent
High-Z as MATLAB `Inf` while translating it to SCPI `INFinity`.

### Reusable Lesson

Configuration values that change another parameter's meaning belong in the
same experiment description and should be applied first. Instrument read-back
confirms the stored load setting; only an external measurement confirms the
voltage actually delivered to the physical load.

## What Remains Project-Specific

- The SCPI command forms and phase-alignment behavior are specific to the
  Rigol DG5000 Pro family and the tested firmware.
- Supported channel counts and waveform limits must come from the target
  instrument.
- The appropriate read-back comparison tolerance depends on the parameter and
  instrument resolution.
- Safe output levels depend on the connected load and experiment.

These details should remain in the DG5000 Pro project rather than being
promoted as universal MATLAB rules.
