Application Frequency Response Functions
The Application Frequency Response API lets you trigger frequency responses in Automation1 Studio and do stability analysis on frequency responses that you collect. These AeroScript functions run on the Automation1-iSMC. But they are handled through a connected Automation1-MDK Studio application. Before you use these functions, you must connect Automation1 Studio to the controller.
Tip: By default, Automation1 Studio and Automation1 MachineApps try to register for Application Message and Application Frequency Response callbacks. The first application that registers will get the callbacks. The next application that tries to register will get an error. You can change the default behavior of Automation1 Studio in Settings. You can change the default behavior of a MachineApp in the MachineApps workspace in Automation1 Studio.
Frequency Response
Automation1 Studio has a Frequency Response utility that you can use to analyze the characteristics of the servo loop and its mechanical system.
How to access the Frequency Response utility
- Open Automation1 Studio.
- Select the Configure workspace.
- Find the Axes category. Then select the Servo topic.
- At the bottom of the main window, select the Frequency Response tab.
For information about how frequency responses are measured, see the Frequency Response Module.
While Automation1 Studio gives you an interface where you can easily measure frequency responses, the AppFrequencyResponse* functions let you measure multiple responses in succession. Then you can save them as frequency response files to make a streamlined workflow. The API supplies functions that you can use to run each of the supported loop input types:
- MultisinePlus loop input type - Use the
AppFrequencyResponseTriggerMultisinePlus()function. - Sinusoid loop input type - Use the
AppFrequencyResponseTriggerSinusoid()function. - White Noise loop input type - Use the
AppFrequencyResponseTriggerWhiteNoise()function. - Multisine loop input type - Use the
AppFrequencyResponseTriggerMultisine()function.
Each Frequency Response must run on a different, physical axis. Before you use these functions, you can use their related App*IsRegistered() functions to see if they are registered with an Automation1 Studio, Automation1 MachineApps, or a custom .NET application.
There are a number of configurations that you can do to change the behavior of the transmissions. Use the $mdkFilePath argument to specify the location and name of the output file on the client MDK machine. Relative paths are supported and are relative to the Automation1 folder in your Documents folder. To save to an absolute path outside of the MDK folder, turn on the Allow Saving to and Reading from Absolute Paths toggle in the Frequency Response settings in Automation1 Studio. Network and controller paths are not supported. Use the $frequencyResponseFileType argument to specify the type of file to save. Supported file types include Automation1 Frequency Response, CSV, and JSON.
Application Frequency Response Function Overloads
function AppFrequencyResponseTriggerMultisinePlus($axis as axis, $mdkFilePath as string, $startFrequency as real, $endFrequency as real, $numPoints as integer, $maxCurrentPercentage as real, $measurementType as TuningMeasurementType, $travelDistance as real, $travelVelocity as real)
Triggers a MultisinePlus frequency response transmission on the specified axis. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppFrequencyResponseTriggerMultisinePlusIsRegistered() function.
Arguments
$axis The axis on which to trigger the response.
$mdkFilePath The file name and relative path that specifies where the frequency response data will be saved in the MDK documents folder.
$startFrequency The starting frequency of the transmission, in Hz.
$endFrequency The ending frequency of the transmission, in Hz.
$numPoints The number of frequency points to include in the disturbance.
$maxCurrentPercentage Percentage of maximum current to be transmitted to the axis in the range (0, 100].
$measurementType The underlying control loop used to perform the frequency response.
$travelDistance The distance to move during the frequency response. Specify a value of 0.0 for this argument and $travelVelocity to disable motion.
$travelVelocity The velocity to move with during the frequency response. Specify a value of 0.0 for this argument and $travelDistance to disable motion.
enum TuningMeasurementType
| enum TuningMeasurementType
ServoOpenLoop = 0 CurrentOpenLoop = 2 AutoFocusOpenLoop = 3 end |
function AppFrequencyResponseTriggerMultisinePlus($axis as axis, $mdkFilePath as string, $startFrequency as real, $endFrequency as real, $numPoints as integer, $maxCurrentPercentage as real, $measurementType as TuningMeasurementType, $travelDistance as real, $travelVelocity as real, $frequencyResponseFileType as FrequencyResponseFileType)
Triggers a MultisinePlus frequency response transmission on the specified axis. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppFrequencyResponseTriggerMultisinePlusIsRegistered() function.
Arguments
$axis The axis on which to trigger the response.
$mdkFilePath The file name and relative path that specifies where the frequency response data will be saved in the MDK documents folder.
$startFrequency The starting frequency of the transmission, in Hz.
$endFrequency The ending frequency of the transmission, in Hz.
$numPoints The number of frequency points to include in the disturbance.
$maxCurrentPercentage Percentage of maximum current to be transmitted to the axis in the range (0, 100].
$measurementType The underlying control loop used to perform the frequency response.
$travelDistance The distance to move during the frequency response. Specify a value of 0.0 for this argument and $travelVelocity to disable motion.
$travelVelocity The velocity to move with during the frequency response. Specify a value of 0.0 for this argument and $travelDistance to disable motion.
$frequencyResponseFileType The format of the frequency response file that will be saved.
enum TuningMeasurementType
| enum TuningMeasurementType
ServoOpenLoop = 0 CurrentOpenLoop = 2 AutoFocusOpenLoop = 3 end |
enum FrequencyResponseFileType
| enum FrequencyResponseFileType
Fr = 0 Csv = 1 Json = 2 end |
function AppFrequencyResponseTriggerMultisinePlusIsRegistered() as integer
Returns if the AppFrequencyResponseTriggerMultisinePlus() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
function AppFrequencyResponseTriggerSinusoid($axis as axis, $mdkFilePath as string, $startFrequency as real, $endFrequency as real, $numDivisions as integer, $amplitude as real, $measurementType as TuningMeasurementType, $travelDistance as real, $travelVelocity as real)
Triggers a Sinusoidal frequency response transmission on the specified axis. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppFrequencyResponseTriggerSinusoidIsRegistered() function.
Arguments
$axis The axis on which to trigger the response.
$mdkFilePath The file name and relative path that specifies where the frequency response data will be saved in the MDK documents folder.
$startFrequency The starting frequency of the transmission, in Hz.
$endFrequency The ending frequency of the transmission, in Hz.
$numDivisions The number of divisions within the frequency range.
$amplitude The amplitude of the sinusoidal wave.
$measurementType The underlying control loop used to perform the frequency response.
$travelDistance The distance to move during the frequency response. Specify a value of 0.0 for this argument and $travelVelocity to disable motion.
$travelVelocity The velocity to move with during the frequency response. Specify a value of 0.0 for this argument and $travelDistance to disable motion.
enum TuningMeasurementType
| enum TuningMeasurementType
ServoOpenLoop = 0 CurrentOpenLoop = 2 AutoFocusOpenLoop = 3 end |
function AppFrequencyResponseTriggerSinusoid($axis as axis, $mdkFilePath as string, $startFrequency as real, $endFrequency as real, $numDivisions as integer, $amplitude as real, $measurementType as TuningMeasurementType, $travelDistance as real, $travelVelocity as real, $frequencyResponseFileType as FrequencyResponseFileType)
Triggers a Sinusoidal frequency response transmission on the specified axis. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppFrequencyResponseTriggerSinusoidIsRegistered() function.
Arguments
$axis The axis on which to trigger the response.
$mdkFilePath The file name and relative path that specifies where the frequency response data will be saved in the MDK documents folder.
$startFrequency The starting frequency of the transmission, in Hz.
$endFrequency The ending frequency of the transmission, in Hz.
$numDivisions The number of divisions within the frequency range.
$amplitude The amplitude of the sinusoidal wave.
$measurementType The underlying control loop used to perform the frequency response.
$travelDistance The distance to move during the frequency response. Specify a value of 0.0 for this argument and $travelVelocity to disable motion.
$travelVelocity The velocity to move with during the frequency response. Specify a value of 0.0 for this argument and $travelDistance to disable motion.
$frequencyResponseFileType The format of the frequency response file that will be saved.
enum TuningMeasurementType
| enum TuningMeasurementType
ServoOpenLoop = 0 CurrentOpenLoop = 2 AutoFocusOpenLoop = 3 end |
enum FrequencyResponseFileType
| enum FrequencyResponseFileType
Fr = 0 Csv = 1 Json = 2 end |
function AppFrequencyResponseTriggerSinusoidIsRegistered() as integer
Returns if the AppFrequencyResponseTriggerSinusoid() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
function AppFrequencyResponseTriggerWhiteNoise($axis as axis, $mdkFilePath as string, $startFrequency as real, $endFrequency as real, $numAverages as integer, $maxCurrentPercentage as real, $measurementType as TuningMeasurementType, $travelDistance as real, $travelVelocity as real)
Triggers a WhiteNoise frequency response transmission on the specified axis. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppFrequencyResponseTriggerWhiteNoiseIsRegistered() function.
Arguments
$axis The axis on which to trigger the response.
$mdkFilePath The file name and relative path that specifies where the frequency response data will be saved in the MDK documents folder.
$startFrequency The starting frequency of the transmission, in Hz.
$endFrequency The ending frequency of the transmission, in Hz.
$numAverages The number of white noise averages.
$maxCurrentPercentage Percentage of maximum current to be transmitted to the axis in the range (0, 100].
$measurementType The underlying control loop used to perform the frequency response.
$travelDistance The distance to move during the frequency response. Specify a value of 0.0 for this argument and $travelVelocity to disable motion.
$travelVelocity The velocity to move with during the frequency response. Specify a value of 0.0 for this argument and $travelDistance to disable motion.
enum TuningMeasurementType
| enum TuningMeasurementType
ServoOpenLoop = 0 CurrentOpenLoop = 2 AutoFocusOpenLoop = 3 end |
function AppFrequencyResponseTriggerWhiteNoise($axis as axis, $mdkFilePath as string, $startFrequency as real, $endFrequency as real, $numAverages as integer, $maxCurrentPercentage as real, $measurementType as TuningMeasurementType, $travelDistance as real, $travelVelocity as real, $frequencyResponseFileType as FrequencyResponseFileType)
Triggers a WhiteNoise frequency response transmission on the specified axis. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppFrequencyResponseTriggerWhiteNoiseIsRegistered() function.
Arguments
$axis The axis on which to trigger the response.
$mdkFilePath The file name and relative path that specifies where the frequency response data will be saved in the MDK documents folder.
$startFrequency The starting frequency of the transmission, in Hz.
$endFrequency The ending frequency of the transmission, in Hz.
$numAverages The number of white noise averages.
$maxCurrentPercentage Percentage of maximum current to be transmitted to the axis in the range (0, 100].
$measurementType The underlying control loop used to perform the frequency response.
$travelDistance The distance to move during the frequency response. Specify a value of 0.0 for this argument and $travelVelocity to disable motion.
$travelVelocity The velocity to move with during the frequency response. Specify a value of 0.0 for this argument and $travelDistance to disable motion.
$frequencyResponseFileType The format of the frequency response file that will be saved.
enum TuningMeasurementType
| enum TuningMeasurementType
ServoOpenLoop = 0 CurrentOpenLoop = 2 AutoFocusOpenLoop = 3 end |
enum FrequencyResponseFileType
| enum FrequencyResponseFileType
Fr = 0 Csv = 1 Json = 2 end |
function AppFrequencyResponseTriggerWhiteNoiseIsRegistered() as integer
Returns if the AppFrequencyResponseTriggerWhiteNoise() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
function AppFrequencyResponseTriggerMultisine($axis as axis, $mdkFilePath as string, $startFrequency as real, $endFrequency as real, $numPeriods as integer, $maxCurrentPercentage as real, $measurementType as TuningMeasurementType, $travelDistance as real, $travelVelocity as real)
Triggers a Multisine frequency response transmission on the specified axis. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppFrequencyResponseTriggerMultisineIsRegistered() function.
Arguments
$axis The axis on which to trigger the response.
$mdkFilePath The file name and relative path that specifies where the frequency response data will be saved in the MDK documents folder.
$startFrequency The starting frequency of the transmission, in Hz.
$endFrequency The ending frequency of the transmission, in Hz.
$numPeriods The number of sinusoid periods. Must be a power of 2.
$maxCurrentPercentage Percentage of maximum current to be transmitted to the axis in the range (0, 100].
$measurementType The underlying control loop used to perform the frequency response.
$travelDistance The distance to move during the frequency response. Specify a value of 0.0 for this argument and $travelVelocity to disable motion.
$travelVelocity The velocity to move with during the frequency response. Specify a value of 0.0 for this argument and $travelDistance to disable motion.
enum TuningMeasurementType
| enum TuningMeasurementType
ServoOpenLoop = 0 CurrentOpenLoop = 2 AutoFocusOpenLoop = 3 end |
function AppFrequencyResponseTriggerMultisine($axis as axis, $mdkFilePath as string, $startFrequency as real, $endFrequency as real, $numPeriods as integer, $maxCurrentPercentage as real, $measurementType as TuningMeasurementType, $travelDistance as real, $travelVelocity as real, $frequencyResponseFileType as FrequencyResponseFileType)
Triggers a Multisine frequency response transmission on the specified axis. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppFrequencyResponseTriggerMultisineIsRegistered() function.
Arguments
$axis The axis on which to trigger the response.
$mdkFilePath The file name and relative path that specifies where the frequency response data will be saved in the MDK documents folder.
$startFrequency The starting frequency of the transmission, in Hz.
$endFrequency The ending frequency of the transmission, in Hz.
$numPeriods The number of sinusoid periods. Must be a power of 2.
$maxCurrentPercentage Percentage of maximum current to be transmitted to the axis in the range (0, 100].
$measurementType The underlying control loop used to perform the frequency response.
$travelDistance The distance to move during the frequency response. Specify a value of 0.0 for this argument and $travelVelocity to disable motion.
$travelVelocity The velocity to move with during the frequency response. Specify a value of 0.0 for this argument and $travelDistance to disable motion.
$frequencyResponseFileType The format of the frequency response file that will be saved.
enum TuningMeasurementType
| enum TuningMeasurementType
ServoOpenLoop = 0 CurrentOpenLoop = 2 AutoFocusOpenLoop = 3 end |
enum FrequencyResponseFileType
| enum FrequencyResponseFileType
Fr = 0 Csv = 1 Json = 2 end |
function AppFrequencyResponseTriggerMultisineIsRegistered() as integer
Returns if the AppFrequencyResponseTriggerMultisine() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
Stability Analysis
Use the AppFrequencyResponsePerformStabilityAnalysis() function to do a stability analysis on a frequency response file. A stability analysis calculates stability metrics of a frequency response, which include the phase margin, magnitude crossover frequency, gain margin, phase crossover frequency, sensitivity peak, and sensitivity peak frequency. The calculated stability analysis metrics are returned by the $phaseMargin, $magnitudeCrossoverFrequency, $gainMargin, $phaseCrossoverFrequency, $sensitivityPeak, and $sensitivityPeakFrequency arguments. Before you use this function, you can use the AppFrequencyResponsePerformStabilityAnalysisIsRegistered() function to see if it is registered with an Automation1 Studio, Automation1 MachineApps, or a custom .NET application.
Use the $mdkFilePath argument to specify the frequency response file on the client MDK machine on which to do a stability analysis. Relative paths are supported and are relative to the Automation1 folder in your Documents folder. To save to an absolute path outside of the MDK folder, turn on the Allow Saving to and Reading from Absolute Paths toggle in the Frequency Response settings in Automation1 Studio. Network and controller paths are not supported.
function AppFrequencyResponsePerformStabilityAnalysis($mdkFilePath as string, ref $phaseMargin as real, ref $magnitudeCrossoverFrequency as real, ref $gainMargin as real, ref $phaseCrossoverFrequency as real, ref $sensitivityPeak as real, ref $sensitivityPeakFrequency as real)
Does a stability analysis on a saved frequency response file and returns the stability metrics. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppFrequencyResponsePerformStabilityAnalysisIsRegistered() function.
Arguments
$mdkFilePath The file name and relative path that specifies where the frequency response data will be read from the MDK documents folder.
ref $phaseMargin The difference between the measured phase and -180 degrees at the $magnitudeCrossoverFrequency, in degrees.
ref $magnitudeCrossoverFrequency The frequency at which the magnitude of the frequency response crosses over 0 dB, in Hz. The reported $phaseMargin is at this frequency.
ref $gainMargin The gain above or below the 0 dB line at the $phaseCrossoverFrequency, in dB.
ref $phaseCrossoverFrequency The frequency at which the phase of the frequency response crosses over -180 degrees, in Hz. The reported $gainMargin is at this frequency.
ref $sensitivityPeak The maximum amplitude of the measured sensitivity function, in dB.
ref $sensitivityPeakFrequency The frequency at which the reported $sensitivityPeak occurs, in Hz.
function AppFrequencyResponsePerformStabilityAnalysisIsRegistered() as integer
Returns if the AppFrequencyResponsePerformStabilityAnalysis() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
