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 the following figure.

Figure 1: example_pid_advisor_pll_bode_step_combined

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 node documentation 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 of /calculate 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 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 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.

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 previous section for an explanation). For all other devices /type can only be set to "pid". The following tables describe which device nodes are configured.

The following device nodes are 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

The following additional device nodes configured when /type is "pid" (default behavior) and /dut/source = 4 (internal PLL).

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

The following device nodes configured when /type is "pll" (HF2 instruments only).

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.

Non HF2 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.

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.