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.py
, an example distributed on our public GitHub repository. It 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.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.
-
Create an instance of the PID Advisor module.
-
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 PID Advisor Module Node Tree for a full list of PID Advisor parameters. -
Start the module by calling
execute()
. -
Start optimization of the PID parameters by setting the
calculate
parameter to 1. The optimization process has finished when the value ofcalculate
returns to 0. Optimization may take up to a minute to complete, but is much quicker in most cases. -
Read out the optimized parameters, Bode and step response plot data (see Figure 1) for inspection using
get()
. -
Transfer the optimized gain parameters from the Advisor Module to the instrument’s nodes by setting the
todevice
parameter to 1. -
Enable the instrument’s PID (/DEV…./PIDS/n/ENABLE).
-
The Auto Tune functionality may be additionally enabled by setting
tune
to 1 and configuring the parameters in thetuner
branch. This functionality continuously updates the instrument’s PID parameters specified bytuner/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.
Device node (/DEV…/) | Value set (prefix `` omitted) | Device class |
---|---|---|
PIDS/n/P |
Advised |
All devices |
PIDS/n/I |
Advised |
All devices |
PIDS/n/D |
Advised |
All devices |
PIDS/n/DEMOD/TIMECONSTANT |
User-configured or advised |
All devices |
PIDS/n/DEMOD/ORDER |
User-configured |
All devices |
PIDS/n/DEMOD/HARMONIC |
User-configured |
All devices |
PIDS/n/RATE |
User-configured |
Not HF2 |
PIDS/n/DLIMITTIMECONSTANT |
User-configured or advised |
Not HF2 |
Device node (/DEV…/) | Value set | Device class |
---|---|---|
PIDS/n/CENTER |
User-configured |
All devices |
PIDS/n/LIMITLOWER |
Calculated |
Not HF2 |
PIDS/n/LIMITUPPER |
Calculated |
Not HF2 |
PIDS/n/RANGE |
Calculated |
HF2 only |
Device node (/DEV…/) | Value set |
---|---|
PLLS/n/AUTOTIMECONSTANT |
Set to 0. |
PLLS/n/AUTOPID |
Set to 0. |
PLLS/n/P |
Advised |
PLLS/n/I |
Advised |
PLLS/n/D |
Advised |
PLLS/n/HARMONIC |
Advised |
PLLS/n/ORDER |
Advised |
PLLS/n/TIMECONSTANT |
User-configured or advised |
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 Node Tree
The following section contains reference documentation for the settings and measurement data available on the PID advisor module.
Since these settings and data streams may be written and read using the LabOne APIs (Application Programming Interfaces) this section is of particular interest to users who would like to perform measurements programmatically via LabVIEW, Python, MATLAB, .NET or C.
ADVANCEDMODE
Read, Write Integer (64 bit) None If enabled, automatically calculate the start and stop value used in the Bode and step response plots.
/ADVANCEDMODE
Properties:
Type:
Unit:
AUTO
Read, Write Integer (64 bit) None If enabled, automatically trigger a new optimization process upon an input parameter value change.
/AUTO
Properties:
Type:
Unit:
BODE
Read ZIAdvisorWave None Contains the resulting bode plot of the PID simulation.
/BODE
Properties:
Type:
Unit:
CALCULATE
Read, Write Integer (64 bit) None Set to 1 to start the PID Advisor’s modelling process and calculation of optimal parameters. The module sets calculate to 0 when the calculation is finished.
/CALCULATE
Properties:
Type:
Unit:
DEMOD
Read, Write Integer (64 bit) None 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/HARMONIC
Properties:
Type:
Unit:
Read, Write Integer (64 bit) None 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/ORDER
Properties:
Type:
Unit:
Read, Write Double Seconds Only relevant when /DEV…/PIDS/n/INPUT is configured to be a demodulator output and pidAdvisor/pid/autobw=0. Specify the demodulator’s timeconstant 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.
/DEMOD/TIMECONSTANT
Properties:
Type:
Unit:
DEVICE
Read, Write String None Device string specifying the device for which the PID advisor is performed.
/DEVICE
Properties:
Type:
Unit:
DISPLAY
Read, Write Double Hz Start frequency for Bode plot. If advancedmode=0 the start value is automatically derived from the system properties.
/DISPLAY/FREQSTART
Properties:
Type:
Unit:
Read, Write Double Hz Stop frequency for Bode plot.
/DISPLAY/FREQSTOP
Properties:
Type:
Unit:
Read, Write Double Seconds Start time for step response. If advancedmode=0 the start value is 0.
/DISPLAY/TIMESTART
Properties:
Type:
Unit:
Read, Write Double Seconds Stop time for step response.
/DISPLAY/TIMESTOP
Properties:
Type:
Unit:
DUT
Read, Write Double Hz Bandwidth of the DUT (device under test).
/DUT/BW
Properties:
Type:
Unit:
Read, Write Double None Damping of the second order low pass filter.
/DUT/DAMPING
Properties:
Type:
Unit:
Read, Write Double Seconds IO Delay of the feedback system describing the earliest response for a step change.
/DUT/DELAY
Properties:
Type:
Unit:
Read, Write Double Hz Resonant frequency of the of the modelled resonator.
/DUT/FCENTER
Properties:
Type:
Unit:
Read, Write Double Depends on Input, Output, and DUT model Gain of the DUT transfer function.
/DUT/GAIN
Properties:
Type:
Unit:
Read, Write Double None Quality factor of the modelled resonator.
/DUT/Q
Properties:
Type:
Unit:
Read, Write Integer (enumerated) None Specifies the model used for the external DUT (device under test) to be controlled by the PID. 1 Low-pass first order. 2 Low-pass second order. 3 Resonator frequency. 4 Internal PLL. 5 Voltage-controlled oscillator (VCO). 6 Resonator amplitude.
/DUT/SOURCE
Properties:
Type:
Unit:
low_pass_1st_order
low_pass_2nd_order
resonator_frequency
internal_pll
vco
resonator_amplitude
IMPULSE
Read ZIAdvisorWave None Reserved for future use - not yet supported.
/IMPULSE
Properties:
Type:
Unit:
INDEX
Read, Write Integer (64 bit) None The 0-based index of the PID on the instrument to use for parameter detection.
/INDEX
Properties:
Type:
Unit:
PID
Read, Write Integer (64 bit) None 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/AUTOBW
Properties:
Type:
Unit:
Read, Write Integer (64 bit) None If enabled, set the instrument PID limits based upon the calculated bw value.
/PID/AUTOLIMIT
Properties:
Type:
Unit:
Read, Write 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/D
Properties:
Type:
Unit:
Read, Write Double Seconds The initial value to use in the Advisor for the differential filter timeconstant gain. After optimization has finished it contains the optimal value calculated by the Advisor.
/PID/DLIMITTIMECONSTANT
Properties:
Type:
Unit:
Read, Write 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/I
Properties:
Type:
Unit:
Read, Write Integer (64 bit) None 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/MODE
Properties:
Type:
Unit:
Read, Write 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/P
Properties:
Type:
Unit:
Read, Write Double Hz PID Advisor sampling rate of the PID control loop.
/PID/RATE
Properties:
Type:
Unit:
Read, Write Double Hz PID system target bandwidth.
/PID/TARGETBW
Properties:
Type:
Unit:
Read, Write String None HF2 instruments only. Specify whether to model the instrument’s PLL or PID hardware unit when dut/source=4 (internal PLL).
/PID/TYPE
Properties:
Type:
Unit:
PM
Read 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.
/PM
Properties:
Type:
Unit:
PROGRESS
Read Double None Reports the progress of a PID Advisor action as a value between 0 and 1.
/PROGRESS
Properties:
Type:
Unit:
RESPONSE
Read, Write Integer (64 bit) None 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.
/RESPONSE
Properties:
Type:
Unit:
STABLE
Read Integer (64 bit) None 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.
/STABLE
Properties:
Type:
Unit:
STEP
Read ZIAdvisorWave None The resulting step response data of the PID Advisor’s simulation.
/STEP
Properties:
Type:
Unit:
TARGETFAIL
Read Integer (64 bit) None A value of 1 indicates the simulated PID BW is smaller than the Target BW.
/TARGETFAIL
Properties:
Type:
Unit:
TF
Read, Write Integer (64 bit) None Switch the response calculation mode between closed or open loop.
/TF/CLOSEDLOOP
Properties:
Type:
Unit:
Read, Write Integer (64 bit) None Start point for the plant response simulation for open or closed loops.
/TF/INPUT
Properties:
Type:
Unit:
Read, Write Integer (64 bit) None End point for the plant response simulation for open or closed loops.
/TF/OUTPUT
Properties:
Type:
Unit:
TODEVICE
Read, Write Integer (64 bit) None 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.
/TODEVICE
Properties:
Type:
Unit: