PID Advisor Module

The PID Advisor Module provides the functionality available in the Advisor, Tuner and Display sub-tabs of the LabOne User Interface’s PID / PLL tab. The PID Advisor is a mathematical model of the instrument’s PID and can be used to calculate PID controller parameters for optimal feedback loop performance. The controller gains calculated by the module can be easily transferred to the device via the API and the results of the Advisor’s modeling are available as Bode and step response plot data as shown in Figure 1.

example pid advisor pll bode step combined
Figure 1. The plots generated by the LabOne Python API PID Advisor example (example_pid_advisor_pll.py) which configures the PID Advisor to optimize an internal PLL control loop. The data used in the Bode and step response plots is returned by the PID Advisor in the bode respectively step output parameters. See the Section Running the Examples in the Python Chapter for help getting started with the Python examples.

PID Advisor Module Work-Flow

PID Advisor usage via the LabOne APIs closely follows the work-flow used in the LabOne User Interface. Here are the steps required to calculate optimal PID parameters, transfer the parameters to an instrument and then continually modify the instrument’s parameters to minimize the residual error using Auto Tune.

  1. Create an instance of the PID Advisor module.

  2. Configure the module’s parameters using set() to specify, for example, which of the instrument’s PIDs to use and which type of device under test (DUT) to model. If values are specified for the P, I and D gains they serve as initial values for the optimization process. See Table 5 for a full list of PID Advisor parameters.

  3. Start the module by calling execute().

  4. Start optimization of the PID parameters by setting the calculate parameter to 1. The optimization process has finished when the value of calculate returns to 0. Optimization may take up to a minute to complete, but is much quicker in most cases.

  5. Read out the optimized parameters, Bode and step response plot data (see Figure 1) for inspection using get().

  6. Transfer the optimized gain parameters from the Advisor Module to the instrument’s nodes by setting the todevice parameter to 1.

  7. Enable the instrument’s PID (/DEV…​./PIDS/n/ENABLE).

  8. The Auto Tune functionality may be additionally enabled by setting tune to 1 and configuring the parameters in the tuner branch. This functionality continuously updates the instrument’s PID parameters specified by tuner/mode in order to minimize the residual error signal. Note, Auto Tune is not available for HF2 instruments.

The reader is encouraged to refer to the instrument-specific User Manual for more details on the Advisor optimization and Tuner process. Each of the LabOne APIs include an example to help get started programming with PID Advisor Module.

PLL Parameter Optimization on HF2 Instruments

On HF2 instruments the PID and PLL are implemented as two separate entities in the device’s firmware. On all other devices there is only a PID unit and a PLL is created by configuring a PID appropriately (by setting the device node /devN/pids/0/mode to 1, see your instrument User Manual for more information). Since both a PID and a PLL exist on HF2 devices, when the PID Advisor Module is used to model a PLL, the pid/type parameter must be set to either pid or pll to indicate which hardware unit on the HF2 is to be modeled by the Advisor.

The Matlab and Python APIs have additional HF2-specific examples for using the PID Advisor Module with the HF2’s PLL.

Instrument Settings written by todevice

This section lists which device nodes are configured upon setting the todevice parameter to 1. Note, the parameter is immediately set back to 0 and no sync() is performed, if a synchronization of instrument settings is required before proceeding, the user must execute a sync command manually.

For HF2 instruments there are two main cases to differentiate between, defined by whether type is set to "pid" or "pll" (see PLL Parameter Optimization on HF2 Instruments for an explanation). For UHF and MF devices type can only be set to "pid", for these devices Table 1 and Table 2 describe which device nodes are configured.

Table 1. The device nodes configured when type is "pid" (default behavior).The value of n in device nodes corresponds to the value of index.
Device node (/DEV…​/) Value set (prefix `` omitted) Device class

PIDS/n/P

Advised pid/p.

All devices

PIDS/n/I

Advised pid/i.

All devices

PIDS/n/D

Advised pid/d.

All devices

PIDS/n/DEMOD/TIMECONSTANT

User-configured or advised pid/timeconstant.

All devices

PIDS/n/DEMOD/ORDER

User-configured pid/order.

All devices

PIDS/n/DEMOD/HARMONIC

User-configured pid/harmonic.

All devices

PIDS/n/RATE

User-configured pid/rate.

Not HF2

PIDS/n/DLIMITTIMECONSTANT

User-configured or advised pid/dlimittimeconstant.

Not HF2

Table 2. The additional device nodes configured when type is "pid" (default behavior) and dut/source=4 (internal PLL). The value of n in device nodes corresponds to the value of index.
Device node (/DEV…​/) Value set Device class

PIDS/n/CENTER

User-configured dut/fcenter.

All devices

PIDS/n/LIMITLOWER

Calculated -bw*2, if autolimit=1.

Not HF2

PIDS/n/LIMITUPPER

Calculated bw*2, if autolimit=1.

Not HF2

PIDS/n/RANGE

Calculated bw*2, if autolimit=1.

HF2 only

Table 3. The device nodes configured when type is "pll" (HF2 instruments only - see PLL Parameter Optimization on HF2 Instruments for an explanation). The value of n in device nodes corresponds to the value of index.
Device node (/DEV…​/) Value set

PLLS/n/AUTOTIMECONSTANT

Set to 0.

PLLS/n/AUTOPID

Set to 0.

PLLS/n/P

Advised pid/p.

PLLS/n/I

Advised pid/i.

PLLS/n/D

Advised pid/d.

PLLS/n/HARMONIC

Advised demod/harmonic.

PLLS/n/ORDER

Advised demod/order.

PLLS/n/TIMECONSTANT

User-configured or advised demod/timeconstant.

Monitoring the PID’s Output

This section is not directly related to the functionality of the PID Advisor itself, but describes how to monitor the PID’s behavior by accessing the corresponding device’s nodes on the Data Server.

MF and UHF Instruments

On MF and UHF instruments, the PID’s error, shift and output value are available from the device’s PID streaming nodes:

  • /DEV…​./PIDS/n/STREAM/ERROR

  • /DEV…​./PIDS/n/STREAM/SHIFT

  • /DEV…​./PIDS/n/STREAM/VALUE.

These are high-speed streaming nodes with timestamps available for each value. They may be recorded using the Data Acquisition Module (recommended) or via the subscribe and poll commands (very high-performance applications). The PID streams are aligned by timestamp with demodulator streams. A specific streaming rate may be requested by setting the /DEV…​/PIDS/n/STREAM/RATE node; the device firmware will set the next lowest configurable rate (which corresponds to a legal demodulator rate). The configured rate can be read out from the /DEV…​/PIDS/n/STREAM/EFFECTIVERATE node. If the instrument has the DIG Option installed, the PID’s outputs can also be obtained using the instrument’s scope at rates of up to 1.8 GHz (although not continuously). Note, that /DEV…​/PIDS/n/STREAM/{RATE EFFECTIVERATE} do not effect the rate of the PID itself, only the rate at which data is transferred to the PC. The rate of an instrument’s PID is configured by /DEV…​/PIDS/n/RATE.

HF2 Instruments

On HF2 instruments the PID’s error, shift and center values are available using the device nodes:

  • /DEV…​./PIDS/n/ERROR (output node),

  • /DEV…​./PIDS/n/SHIFT (output node),

  • /DEV…​./PIDS/n/CENTER (setting node),

where the PID’s output can be calculated as OUT = CENTER + SHIFT. When data is acquired from these nodes using the subscribe and poll commands the node values do not have timestamps associated with them (since the HF2 Data Server only supports API Level 1). Additionally, these nodes are not high-speed streaming nodes; they are updated at a low rate that depends on the rate of the PID, this is a approximately 10 Hz if one PID is enabled. It is not possible to configure the rate of the PID on HF2 instruments. It is possible, however, to subscribe to the /DEV…​/PIDS/n/ERROR node in the Data Acquisition Module, here, timestamps are approximated for each error value. It is not possible to view these values in the HF2 scope.

The PLL Module

Deprecation notice The PLL Advisor Module introduced in LabOne 14.08 became deprecated as of LabOne 16.12. In LabOne 16.12 the PLL Advisor’s functionality was combined within the PID Advisor module. Users of the PLL Advisor Module should use the PID Advisor Module instead.

PID Advisor Module Parameters

The following tables provide a comprehensive list of the module’s parameters, see:

Table 4. PID Advisor Input/Output Parameters.
Path Type Unit Description

calculate

int

-

Set to 1 to start the PID Advisor’s modeling process and calculation of optimal parameters. The module sets calculate to 0 when the calculation is finished.

response

int

-

Set to 1 to calculate the Bode and the step response plot data from the current pid/* parameters (only relevant when auto=0). The module sets response back to 0 when the plot data has been calculated.

todevice

int

-

Set to 1 to transfer the calculated PID advisor data to the device, the module will immediately reset the parameter to 0 and configure the instrument’s nodes, see Instrument Settings written by todevice for more information.

pid/d

double

(Output Unit . s)/Input Unit

The initial value to use in the Advisor for the differential gain. After optimization has finished it contains the optimal value calculated by the Advisor.

pid/i

double

Output Unit/(Input Unit . s)

The initial value to use in the Advisor for the integral gain. After optimization has finished it contains the optimal value calculated by the Advisor.

pid/p

double

Output Unit/Input Unit

The initial value to use in the Advisor for the proportional gain. After optimization has finished it contains the optimal value calculated by the Advisor.

pid/dlimittimeconstant

double

s

The initial value to use in the Advisor for the differential filter time constant gain. After optimization has finished it contains the optimal value calculated by the Advisor.

Table 5. PID Advisor Input Parameters.
Path Type Unit Description

advancedmode

int

-

If enabled, automatically calculate the start and stop value used in the Bode and step response plots.

auto

int

-

If enabled, automatically trigger a new optimization process upon an input parameter value change.

demod/harmonic

int

-

Only relevant when /DEV…​/PIDS/n/INPUT is configured to be a demodulator output. Specifies the demodulator’s harmonic to use in the PID Advisor model. This value will be transferred to the instrument node (/DEV…​./DEMODS/m/HARMONIC) when the PID is enabled.

demod/order

int

-

Only relevant when /DEV…​/PIDS/n/INPUT is configured to be a demodulator output. Specifies the demodulator’s order to use in the PID Advisor model. This value will be transferred to the instrument node (/DEV…​./DEMODS/m/ORDER) when the PID is enabled.

demod/timeconstant

double

s

Only relevant when /DEV…​/PIDS/n/INPUT is configured to be a demodulator output and pid/autobw=0. Specify the demodulator’s time constant to use in the PID Advisor model. This value will be transferred to the instrument node (/DEV…​./DEMODS/m/TIMECONSTANT) when the PID is enabled.

display/freqstart

double

Hz

Start frequency for Bode plot. If advancedmode=0 the start value is automatically derived from the system properties.

display/freqstop

double

Hz

Stop frequency for Bode plot.

display/timestart

double

s

Start time for step response. If advancedmode=0 the start value is 0.

display/timestop

double

s

Stop time for step response.

dut/bw

double

Hz

Bandwidth of the DUT (device under test).

dut/damping

double

-

Damping of the second order low pass filter.

dut/delay

double

s

IO Delay of the feedback system describing the earliest response for a step change.

dut/fcenter

double

Hz

Resonant frequency of the of the modeled resonator.

dut/gain

double

Depends on Input, Output and DUT model

Gain of the DUT transfer function.

dut/q

double

-

Quality factor of the modeled resonator.

dut/source

int

-

Specifies the model used for the external DUT (device under test) to be controlled by the PID:

0:

All pass.

1:

Low-pass first order.

2:

Low-pass second order.

3:

Resonator frequency.

4:

Internal PLL.

5:

Voltage-controlled oscillator (VCO).

6:

Resonator amplitude.

index

int

-

The 0-based index of the PID on the instrument to use for parameter detection.

pid/autobw

int

-

If enabled, adjust the demodulator bandwidth to fit best to the specified target bandwidth of the full system. In this case, demod/timeconstant is ignored.

pid/autolimit

int

-

If enabled, set the instrument PID limits based upon the calculated bw value. See Table 2 for more information.

pid/mode

double

-

Select PID Advisor mode; bit encoded:

bit 0:

Optimize P gain.

bit 1:

Optimize I gain.

bit 2:

Optimize D gain.

bit 3:

Optimize D filter limit.

pid/rate

double

Hz

PID Advisor sampling rate of the PID control loop.

pid/targetbw

double

Hz

PID system target bandwidth.

pid/type

string

-

HF2 instruments only. Specify whether to model the instrument’s PLL or PID hardware unit when dut/source=4 (internal PLL). See PLL Parameter Optimization on HF2 Instruments.

targetbw

double

Hz

Requested PID bandwidth. Higher frequencies may need manual tuning.

tf/closedloop

int

-

Switch the response calculation mode between closed or open loop.

tf/input

int

-

Start point for the plant response simulation for open or closed loops.

tf/output

int

-

End point for the plant response simulation for open or closed loops.

tune

int

-

If enabled, optimize the instrument’s PID parameters so that the noise of the closed-loop system gets minimized. The HF2 doesn’t support tuning.

tuner/mode

int

-

Select tuner mode; bit encoded:

bit 0:

Tune P gain.

bit 1:

Tune I gain.

bit 2:

Tune D gain.

bit 3:

Tune D filter limit.

tuner/averagetime

double

s

Time for a tuner iteration.

Table 6. PID Advisor Output (read-only) Parameters.
Path Type Unit Description

bode

struct

-

The resulting Bode plot data of the PID Advisor’s simulation, see Figure 1 for an example. Contains the following fields:

flags

Reserved for future use.

grid

An array containing the frequency axis values for the complex Bode data.

samplecount

Reserved for future use.

sampleformat

Indicates that this struct contains Bode plot data (always equal to 0).

x

An array containing the real component values of the complex Bode data.

y

An array containing the imaginary component values of the complex Bode data.

bw

double

Hz

Calculated system bandwidth.

impulse

struct

-

Reserved for future use - not yet supported.

pm

double

deg

Simulated phase margin of the PID with the current settings. The phase margin should be greater than 45 deg and preferably greater than 65 deg for stable conditions.

pmfreq

double

Hz

Simulated phase margin frequency.

stable

int

-

If equal to 1, the PID Advisor found a stable solution with the given settings. If equal to 0, the solution was deemed instable - revise your settings and rerun the PID Advisor.

step

struct

-

The resulting step response data of the PID Advisor’s simulation, see Figure 1 for an example. Contains the following fields:

flags

Reserved for future use.

grid

An array containing the time axis values for the step response data.

samplecount

Reserved for future use.

sampleformat

Indicates that this struct contains step response plot data (always equal to 1).

x

An array containing the values of the step response.

y

Unused (all values=0).

targetfail

int

-

A value of 1 indicates the simulated PID BW is smaller than the Target BW.