.

User Limits Detailed Overview

MPX Software Topics > User Limits

Table of Contents

 

Introduction

This page describes User Limits for MPX software. See the UserLimits object.

User limits are a way that a user can configure and generate custom controller events. These events will be treated like other events (such as Mpx.EventType.Settled). A user limit will evaluate conditional statements on memory registers in the controller and generate an event when those registers meet the specified conditions. Also, when the event is generated, the user limit can write an output word (or bit) to a controller memory register.

Configuration of user limits can be split into three areas: General Configuration, Trigger Conditions, and Output Specification.

This section also discusses two more important topics: Beginning and Setting Configurations and Performance Characteristics of user limits.

General Configuration

UserLimit.Number – is the index used to access the user limit from the parent axis object. It is not a configuration property. However, it can be used to help configure other user limits when it is necessary to chain user limits together.

UserLimit.Action – specifies the action that the user limit’s parent axis is to perform when the user limit is fired.

UserLimit.Duration – specifies how long the user limit’s trigger conditions must evaluate true before the user limit fires. When the user limit trigger type is set up as a timer, then the duration represents the amount of time between timer events.

UserLimit.GenerateEvent – specifies when an event should be generated when the user limit is fired.
NOTE: If the user limit is configured to generate an action, but not generate an event, then an application will not be able to identify why the action occurred after the user limit is fired.

UserLimit.TriggerType – specifies the trigger type of the user limit. If TriggerType is set to UserLimitTrigger.None, then the user limit is disabled; it will never fire. When it is finished with a user limit, it is standard practice to set the TriggerType to UserLimitTrigger.None so that the controller will no longer use background time to process dead events.

The trigger type specifies how many condition blocks are used when configuring the user limit. (See table below.)

User Limit Trigger Type Condition Blocks Evaluated
None 0
Timer 0
SingleCondition 1
And 2
Or 2

Trigger Conditions

UserLimit.ConditionType specifies the type of comparison used for one of the user limit’s trigger conditions. The condition type specifies what user limit condition properties are used to configure the user limit. (See table below.)

Each condition type is described in more detail on the UserLimitConditionType enumeration page. Custom conditions are described in the Custom Trigger Conditions section.

ActiveHigh Axis Bit Capture Channel DedicatedIn DedicatedOut    Index Is64Bit IsSingle LimitType Logic Mask Monitor Node Position PositionError SrcAddress State Value Velocity
Signature                                          
DedicatedIn • •       •                              
DedicatedOut • •         •                            
GeneralIn • • •                                    
GeneralOut • • •                                    
CommandPosition   •                   •       •          
CommandVelocity   •                   •                 •
ActualPosition   •                   •       •          
ActualVelocity   •                   •                 •
PositionError   •                   •         •        
ControlDigitalIn •   •                                    
ControlDigitalOut •   •                                    
Monitor   •                   •   •           •  
SqNodeDigitalIn •   •                       •            
SqNodeDigitalOut •   •                       •            
SqNodeAnalogOut         •             •     •         •  
SqNodeAnalogIn         •             •     •         •  
UserBuffer               •   •   •               •  
Limit • •                 •                    
AxisDemand   •                   •               •  
CaptureState • •   •                                  
Custom                 • •   • •         •   •  
ActiveHigh Axis Bit Capture Channel DedicatedIn DedicatedOut Index Is64Bit IsSingle LimitType Logic Mask Monitor Node Position PositionError SrcAddress State Value Velocity

Output Specification

User limits have the ability to write a 32-bit word or a set of bits in a single 32-bit word of controller memory. This output is most commonly used to set the value of a digital or analog output. It can also be used to set a value in the user buffer, set the user limit to fire only once (single-short), or be configured for a custom output. (See Custom Output Specification)

Unlike user limit events, the output structure is used every time the user limit is evaluated in a ‘fired’ state, not just when the user limit fires.

UserLimit.OutputType – specifies the type of output to be written when the user limit’s trigger fires. (See table below.)

Each output type is described in more detail on the UserLimitOutputType enumeration page.

Address AndMask Axis Bit Channel Index IsSingle NewState NewValueInt32 NewValueSingle Node OrMask
None                        
SingleShot                        
GeneralOut     • •       •        
ControlOut       •       •        
SqNodeDigitalOut       •       •     •  
SqNodeAnalogOut         •       •   •  
UserBuffer           • •   • •    
Custom • •         •     •   •

Beginning and Setting Configurations

In general, it is not possible to change a single user limit property and leave the user limit in a valid configuration state. As a result, it is necessary to allow multiple properties to be set and then have the new configuration copied onto the controller in a single method call. To accomplish this task, notify the user limit object when the application will begin creating a new configuration and when the new configuration should be copied onto the controller.

ConfigurationBegin – begins the configuration of the user limit object, allowing the application to change configuration related properties.

ConfigurationEnd – sends to the controller all changes made to the user limit configuration since the last call to ConfigurationBegin.

ConfigurationReset – sets the configuration of the user limit to the default disabled configuration. ConfigurationReset internally calls ConfigurationBegin and ConfigurationEnd.
ConfigurationReset is commonly used to reset all properties to their default value before creating a new configuration.

NOTE: It is not possible to change a user limit property without first calling ConfigurationBegin, even if the new configuration is a valid one. Calls to ConfigurationBegin and ConfigurationEnd must still be made prior to changing a user limit property. If a property is set without first calling ConfigurationBegin, then an exception will be thrown with error Mpx.Error.UserLimitCannotConfigure.

Sample Code (Putting It All Together)

Here is an example showing how to configure a user limit as a timer event with a period of 200 milliseconds. Every time the user limit is fired, a value of 1 will be written to user buffer data location 0.

VB Sample Code

 

' Reset the user limit configuration
timerEventUserLimit.ConfigurationReset()

' Start configuring the user limit
timerEventUserLimit.ConfigurationBegin()

timerEventUserLimit.GenerateEvent = True
timerEventUserLimit.Action = Mpx.Action.None
timerEventUserLimit.TriggerType = Mpx.UserLimitTrigger.Timer
timerEventUserLimit.Duration = 0.2 ' 200 milliseconds

timerEventUserLimit.OutputType = Mpx.UserLimitOutputType.UserBuffer
timerEventUserLimit.OutputIndex = 0
timerEventUserLimit.OutputIsSingle = False
timerEventUserLimit.OutputNewValueInt32 =1

' Copy the new configuration to the controller
timerEventUserLimit.ConfigurationEnd()

 

C# Sample Code

 

// Reset the user limit configuration
timerEventUserLimit.ConfigurationReset();

// Start configuring the user limit
timerEventUserLimit.ConfigurationBegin();

timerEventUserLimit.GenerateEvent = true;
timerEventUserLimit.Action = Mpx.Action.None;
timerEventUserLimit.TriggerType = Mpx.UserLimitTrigger.Timer;
timerEventUserLimit.Duration = 0.2; // 200 milliseconds

timerEventUserLimit.OutputType = Mpx.UserLimitOutputType.UserBuffer;
timerEventUserLimit.OutputIndex = 0;
timerEventUserLimit.OutputIsSingle = false;
timerEventUserLimit.OutputNewValueInt32 = 1;

// Copy the new configuration to the controller
timerEventUserLimit.ConfigurationEnd();

Performance Characteristics

It is important to understand that user limits:

 
  • are evaluated in the background cycle.

  • trigger events only when the limit is fired, changing state from False to True. In other words, a user limit must be reset by changing its state to False before it can trigger another event.

The foreground cycle processes crucial information that needs to be updated every servo cycle. The background cycle processes all other information. The background cycle runs continuously on the controller as often as it can. A foreground cycle starts when a timer interrupt on the controller puts the background cycle on hold. After the foreground cycle is done, the background cycle continues to run. The foreground cycle will be started at regular intervals at the rate of once per servo cycle. The background cycle runs as quickly as possible with whatever spare time the foreground cycle does not use.

Usually the background cycle will complete many cycles in the time it takes to complete a servo cycle. However, the time it takes to complete a single background cycle can end up spanning many servo cycles if the sample rate is raised or if the foreground cycle takes more time to process. If an application requires a high number of controller objects and features or a fast sample rate, it is possible that background cycles could take multiple servo cycles to process, even dozens if the controller is pushed to its limits.

Since user limits are evaluated in the background cycle, events might not be generated or output might not be written in the same servo cycle as when the conditions for the user limit would otherwise first be evaluated as True. In the example below, a user limit is set up to evaluate True when the axis position is greater than 1000. We would expect the conditions of the user limit to evaluate True for sample of 240. The controller’s background cycle, however, does not evaluate the user limit until sample reaches 242. Therefore, an event is triggered two samples later than one would hope. The delay of two samples shown here is not indicative of typical controller setups. Background cycles are commonly evaluated more quickly than foreground cycles, but as explained above, it is possible for the foreground cycle to process more frequently.

The following example shows how it is possible to even miss a user limit when the conditions that would cause the user limit to evaluate as True and change too quickly back to False. In this example, a user limit has been set up to evaluate True when the axis position is greater than 200. The axis is performing sinusoidal motion of amplitude 220 encoder counts with an approximate period of eight samples. If the background cycle delays evaluating the user limit by even one servo cycle, it will miss triggering an event.

We now return to our first example to show the corollary to the previous example. It is equally possible to miss resetting the state of the user limit to False after the position drops below 1000, so that it will not trigger an event when the conditions for the user limit to evaluate True occur again.

NOTE: If it is important that user limits are evaluated every servo cycle, then the background cycle “maximum delta” must not exceed a value of 1. The maximum delta value can be checked on the Controller object’s “Stats” tab in Motion Console. More information can be found in the overview of SynqNet Controller Performance.

Custom Trigger Conditions

ConditionSrcAddress – the controller memory location to use as the source for the condition block’s comparision. Use VM3 or the Map object functions to obtain memory location string of interest. NOTE: VM3-strings are not guaranteed to be forward compatible with future versions of the MPX.

ConditionIs64Bit – determines if the comparison taking place is a 64-bit integer comparison.

ConditionIsSingle – determines if the comparison taking place is a single precision floating-point comparison.

ConditionValue – the value to which the controller memory location is compared against.

ConditionLogic – determines the type of comparison used. For example, to test if the source memory location is greater than a particular value, set ConditionLogic to Mpx.UserLimitLogic.Gt.

ConditionMask – determines which bits are used in the source memory location for the comparison. This is used only when ConditionIs64Bit is False and ConditionIsSingle is False.

Custom Output Specification

OutputAddress – the controller memory location where the output will be written. Use VM3 or the Map object functions to obtain memory location string of interest. NOTE: VM3-strings are not guaranteed to be forward compatible with future versions of the MPX.
OutputIsSingle - determines if a floating point value should be written when a user limit’s trigger fires.

OutputNewValueSingle – The new single precision floating-point value to be written when a user limit’s trigger is fired. This is used only when OutputIsSingle is True.

OutputAndMask – a bit mask that will be bit-wise AND-ed with the data pointed to by OutputPtr. This is used only when OutputIsSingle is False.

OutputOrMask – a bit mask that will be bit-wise OR-ed with the result of (AndMask bit-wise-AND (value at OutputOrMask) ). This is used only when OutputIsSingle is False.

Here is an example showing what happens for each combination of bits for OutputAddress, OutputAndMask, and OutputOrMask:

The setup of the four most common custom output operations are outlined below:
To set bit(s), set:

 

OutputIsSingle   = False
AndMask          = &Hffffffff
OrMask           = < bit(s) to set >

To clear bit(s), set:

 

OutputIsSingle   = False
AndMask          = Not < bit(s) to clear >
OrMask           = 0

To set an integer value, set:

 

OutputIsSingle   = False
AndMask          = 0
OrMask           = < integer value >

To set a float value, set:

 

OutputIsSingle         = True
OutputNewValueSingle   = <single-precision floating point value>

See Also

UserLimit Object

Enumerations
UserLimitConditionType
UserLimitLogic
UserLimitOutputType
UserLimitTrigger

 
       Legal Notice  |  Tech Email  |  Feedback
       Copyright © 2001-2021 Motion Engineering