1756-pm010_-en-p
1756-pm010_-en-p
1756-pm010_-en-p
Instructions
1756 ControlLogix, 1756 GuardLogix, 1769 CompactLogix, 1769
Compact GuardLogix, 1789 SoftLogix, 5069 CompactLogix, Emulate
5570
Activities including installation, adjustments, putting into service, use, assembly, disassembly, and maintenance are required to be carried out by suitably trained personnel in
accordance with applicable code of practice.
If this equipment is used in a manner not specified by the manufacturer, the protection provided by the equipment may be impaired.
In no event will Rockwell Automation, Inc. be responsible or liable for indirect or consequential damages resulting from the use or application of this equipment.
The examples and diagrams in this manual are included solely for illustrative purposes. Because of the many variables and requirements associated with any particular installation,
Rockwell Automation, Inc. cannot assume responsibility or liability for actual use based on the examples and diagrams.
No patent liability is assumed by Rockwell Automation, Inc. with respect to use of information, circuits, equipment, or software described in this manual.
Reproduction of the contents of this manual, in whole or in part, without written permission of Rockwell Automation, Inc., is prohibited.
Throughout this manual, when necessary, we use notes to make you aware of safety considerations.
WARNING: Identifies information about practices or circumstances that can cause an explosion in a hazardous environment, which may lead to personal injury or
death, property damage, or economic loss.
ATTENTION: Identifies information about practices or circumstances that can lead to personal injury or death, property damage, or economic loss. Attentions help
you identify a hazard, avoid a hazard, and recognize the consequence.
IMPORTANT: Identifies information that is critical for successful application and understanding of the product.
These labels may also be on or inside the equipment to provide specific precautions.
SHOCK HAZARD: Labels may be on or inside the equipment, for example, a drive or motor, to alert people that dangerous voltage may be present.
BURN HAZARD: Labels may be on or inside the equipment, for example, a drive or motor, to alert people that surfaces may reach dangerous temperatures.
ARC FLASH HAZARD: Labels may be on or inside the equipment, for example, a motor control center, to alert people to potential Arc Flash. Arc Flash will cause severe
injury or death. Wear proper Personal Protective Equipment (PPE). Follow ALL Regulatory requirements for safe work practices and for Personal Protective Equipment
(PPE).
Tip: Identifies information that is useful and can help to make a process easier to do or easier to understand.
Rockwell Automation recognizes that some of the terms that are currently used in our industry and in this publication are not in alignment with the movement toward inclusive
language in technology. We are proactively collaborating with industry peers to find alternatives to such terms and making changes to our products and content. Please excuse the
use of such terms in our content while we implement these changes.
Grammatical and editorial style changes are not included in this summary.
Global changes
None in this release.
Change Topic
Added notation to Safety instruction signature topic. Safety instruction signature on page 19
Introduction...................................................................................................................................................................................................................................................................................................11
General information......................................................................................................................................................................................................................................................................... 12
Parameters........................................................................................................................................................................................................................................................................................ 13
Local tags.......................................................................................................................................................................................................................................................................................... 13
Data Type........................................................................................................................................................................................................................................................................................... 13
Logic routine..................................................................................................................................................................................................................................................................................... 14
Instruction signature....................................................................................................................................................................................................................................................................... 15
Signature history.............................................................................................................................................................................................................................................................................. 16
Change History..................................................................................................................................................................................................................................................................................16
Help......................................................................................................................................................................................................................................................................................................17
Instruction functionality..................................................................................................................................................................................................................................................................17
Encapsulation.................................................................................................................................................................................................................................................................................... 17
Instruction signature....................................................................................................................................................................................................................................................................... 18
Programming languages................................................................................................................................................................................................................................................................. 19
Transitional instructions................................................................................................................................................................................................................................................................. 19
Instruction size................................................................................................................................................................................................................................................................................ 20
Runtime editing................................................................................................................................................................................................................................................................................20
Intended behavior............................................................................................................................................................................................................................................................................29
Parameters........................................................................................................................................................................................................................................................................................29
Naming conventions........................................................................................................................................................................................................................................................................29
Source protection............................................................................................................................................................................................................................................................................30
Local tags..........................................................................................................................................................................................................................................................................................30
Programming languages................................................................................................................................................................................................................................................................ 30
Test.....................................................................................................................................................................................................................................................................................................30
Help documentation........................................................................................................................................................................................................................................................................30
Create a parameter................................................................................................................................................................................................................................................................................... 33
Optimizing performance.................................................................................................................................................................................................................................................................42
Project documentation....................................................................................................................................................................................................................................................................61
Introduction................................................................................................................................................................................................................................................................................................. 69
Import considerations.....................................................................................................................................................................................................................................................................87
Import configuration.......................................................................................................................................................................................................................................................................89
If you design, program, or troubleshoot safety applications that use GuardLogix controllers, refer to the GuardLogix Safety Application Instruction Set Safety Reference Manual,
publication 1756-RM095.
This manual is one of a set of related manuals that show common procedures for programming and operating Logix 5000 controllers.
For a complete list of common procedures manuals, refer to the Logix 5000 Controllers Common Procedures Programming Manual, publication 1756-PM001.
The term Logix 5000 controller refers to any controller based on the Logix 5000 operating system. Rockwell Automation recognizes that some of the terms that are currently used
in our industry and in this publication are not in alignment with the movement toward inclusive language in technology. We are proactively collaborating with industry peers to find
alternatives to such terms and making changes to our products and content. Please excuse the use of such terms in our content while we implement these changes.
The Studio 5000 Automation Engineering & Design Environment® combines engineering and design elements into a common environment. The first element is the Studio 5000
Logix Designer® application. The Logix Designer application is the rebranding of RSLogix 5000® software and will continue to be the product to program Logix 5000™ controllers for
discrete, process, batch, motion, safety, and drive-based solutions.
The Studio 5000® environment is the foundation for the future of Rockwell Automation® engineering design tools and capabilities. The Studio 5000 environment is the one place for
design engineers to develop all elements of their control system.
Additional resources
These documents contain additional information concerning related Rockwell Automation products.
Resource Description
Industrial Automation Wiring and Grounding Guidelines, publication, 1770-4.1 Provides general guidelines for installing a Rockwell Automation industrial system.
Rockwell Automation product certifications Provides declarations of conformity, certificates, and other certification details.
Understanding terminology
This table defines some of the terms used in this manual when describing how parameters and arguments are used in Add-On Instructions.
Term Definition
Legal notices
Rockwell Automation publishes legal notices, such as privacy policies, license agreements, trademark disclosures, and other terms and conditions on the Legal Notices page of
the Rockwell Automation website.
You can view a full list of all open source software used in this product and their corresponding licenses at this URL:
You may obtain Corresponding Source code for open source packages included in this product from their respective project web site(s). Alternatively, you may obtain complete
Corresponding Source code by contacting Rockwell Automation via the Contact form on the Rockwell Automation website: http://www.rockwellautomation.com/global/about-
us/contact/contact.page. Please include "Open Source" as part of the request text.
Introduction
Add-On Instructions are used in your routines like any built-in instructions. You add calls to your instruction and then
define the arguments for any parameters.
Add-On Instructions are intended to be used to encapsulate commonly used functions or device control. They are not
intended to be a high-level hierarchical design tool. Programs with routines are better suited to contain code for the
area or unit levels of your application. The following table lists the benefits of using Add-On Instructions.
Provide an easier to understand interface • You can place complicated algorithms inside of an Add-On
Instruction, and then provide an easier to understand
interface by making only essential parameters visible or
required.
Export and import an Add-On Instruction • You can export an Add-On Instruction to an .L5X file that
can then be imported into another project. You can also
copy and paste between projects.
Track revisions, view change history, and confirm instruction • You can add an instruction signature to your Add-On
functionality Instruction, which generates a unique identifier and
prevents the instruction from being edited without
resulting in a change to the signature.
Use Add-On-Instructions across multiple projects. You can define the instructions, the instructions can be provided to
you by someone else, or they can be copied from another project.
Once defined in a project, they behave similarly to the built-in instructions already available in the Logix Designer
application. They appear on the instruction toolbar and in the instruction browser for easy access, just like built-in
Logix Designer application instructions.
Like standard Add-On Instructions, safety Add-On Instructions let you encapsulate commonly-used safety logic into
a single instruction, making it modular and easier to reuse. In addition to the instruction signature used for high-
integrity Add-On Instructions, safety Add-On Instructions feature a SIL 3 safety instruction signature for use in safety-
related functions up to and including SIL 3.
Refer to the safety reference manual for your controller, listed in the Additional resources on page , for details on
certifying safety Add-On Instructions and using them in SIL 3 safety applications.
General information
The General tab contains the information you enter when you first create the instruction. You can use this tab to
update that information. The description, revision, revision note, and vendor information is copied into the custom
help for the instruction. The revision is not automatically managed by the software. You are responsible for defining
how it is used and when it is updated.
Class information for safety controller projects appears on the General tab as well. The class can be standard or
safety. Safety Add-On Instructions must meet requirements specific to safety applications. See Safety Add-On
Instructions on page 18 for more information.
Parameters
• What data needs to be passed to the instruction?
• What information needs to be accessible outside of the instruction?
• Do alias parameters need to be defined for data from local tags that needs to be accessible from outside the
Add-On Instruction?
• How does the parameters display? The order of the parameters defines the appearance of instruction.
• Which parameters should be required or visible?
Local tags
• What data is needed for your logic to execute but is not public?
• Identify local tags you might use in your instruction. Local tags are useful for items such as intermediate
calculation values that you do not want to expose to users of your instruction.
• Do you want to create an alias parameter to provide outside access to a local tag?
Data Type
Parameters and local tags are used to define the Data Type that is used when executing the instruction. The
software builds the associated Data Type. The software orders the members of the Data Type that correspond to the
parameters in the order that the parameters are defined. Local tags are added as hidden members.
• A multi-dimensional array or an object type, which includes all Motion types, MSG, ALARM_ANALOG, and
ALARM_DIGITAL.
• A data type used only for InOut parameters (MODULE).
Logic routine
The logic routine of the Add-On Instruction defines the primary functionality of the instruction. It is the code that
executes whenever the instruction is called. The following image is the interface of an Add-On Instruction and its
primary logic routine that defines what the instruction does.
Instruction signature
The instruction signature, available for both standard and safety controllers, lets you quickly determine if the Add-On
Instruction has been modified. Each Add-On Instruction has its own instruction signature on the Add-On Instruction
definition. The instruction signature is required when an Add-On Instruction is used in SIL 3 safety-related functions,
and may be required for regulated industries. Use it when your application calls for a higher level of integrity.
Once generated, the instruction signature seals the Add-On Instruction, preventing it from being edited until the
signature is removed. This includes rung comments, tag descriptions, and any instruction documentation that was
created. When an instruction is sealed, you can perform only these actions:
The instruction signature does not prevent referenced Add-On Instructions or User-defined Data Types from being
modified. Changes to the parameters of a referenced Add-On Instruction or to the members of a referenced User-
defined Data Type can cause the instruction signature to become invalid. These changes include:
• Adding, deleting, or moving parameters, local tags, or members in referenced User-defined Data Types.
• Changing the name, data type, or display style of parameters, local tags, or members in referenced User-
defined Data Types.
If you want to enable project documentation or source protection on an Add-On Instruction to be sealed with an
instruction signature, you need to import the translated information or apply source protection before generating the
signature. You must have the source key to generate a signature or to create a signature history entry for a source-
protected Add-On Instruction that has an instruction signature.
See Defining Source Protection for an Add-On Instruction on page 52 for more information on source protecting
your Add-On Instruction.
Tip:
The instruction signature is not guaranteed to be maintained when migrating between major revisions of
RSLogix5000 or <Product_Name_RSL5K>.
Signature history
The Signature history provides a record of signatures for future reference. A signature history entry consists of the
name of the user, the instruction signature, the timestamp value, and a user-defined description. Up to six history
entries can be stored. If a seventh entry is made, the oldest entry is automatically deleted.
Change History
The Change History tab displays the creation and latest edit information that is tracked by the software. The By
fields show who made the change based on the Windows user name at the time of the change.
Help
The name, revision, description, and parameter definitions are used to automatically build the Instruction Help. Use
the Extended Description Text to provide additional Help documentation for the Add-On Instruction. This content
reflects updates as Parameters or other attributes are changed in the definition.
The Instruction Help Preview shows how your instruction will appear in the various languages, based on parameters
defined as required or visible.
Instruction functionality
Complex instructions tend to be highly application specific and not reusable, or require extensive configuration
support code. As with the built-in instructions, Add-On Instructions need to do one thing, do it well, and support
modular coding. Consider how the instruction will be used and manage interface complexity for the end user or
application.
Add-On Instructions are best at providing a specific type of functionality or device control.
Encapsulation
Add-On Instructions are designed to fully encapsulate the code and data associated with the instruction. The logic
inside an Add-On Instruction uses only the parameters and local tags defined by the instruction definition. There is
no direct programmatic access to controller or program scope tags. This lets the Add-On Instruction be a standalone
component that can execute in any application that calls it by using the parameters interface. It can be validated
once and then locked to prevent edits.
Refer to the the safety reference manual for your controller, listed in the Additional resources on page , for
information on how to certify a safety Add-On Instruction as well as details on requirements for safety applications,
the safety task signature, and a list of approved instructions and data types.
Instruction signature
The instruction signature, available for both standard and safety controllers, lets you quickly determine if the Add-On
Instruction has been modified. Each Add-On Instruction has its own instruction signature on the Add-On Instruction
definition. The instruction signature is required when an Add-On Instruction is used in SIL 3 safety-related functions,
and may be required for regulated industries. Use it when your application calls for a higher level of integrity.
Once generated, the instruction signature seals the Add-On Instruction, preventing it from being edited until the
signature is removed. This includes rung comments, tag descriptions, and any instruction documentation that was
created. When an instruction is sealed, you can perform only these actions:
The instruction signature does not prevent referenced Add-On Instructions or User-defined Data Types from being
modified. Changes to the parameters of a referenced Add-On Instruction or to the members of a referenced User-
defined Data Type can cause the instruction signature to become invalid. These changes include:
• Adding, deleting, or moving parameters, local tags, or members in referenced User-defined Data Types.
• Changing the name, data type, or display style of parameters, local tags, or members in referenced User-
defined Data Types.
If you want to enable project documentation or source protection on an Add-On Instruction to be sealed with an
instruction signature, you need to import the translated information or apply source protection before generating the
signature. You must have the source key to generate a signature or to create a signature history entry for a source-
protected Add-On Instruction that has an instruction signature.
See Defining Source Protection for an Add-On Instruction on page 52 for more information on source protecting
your Add-On Instruction.
Tip:
The instruction signature is not guaranteed to be maintained when migrating between major revisions of
RSLogix5000 or <Product_Name_RSL5K>.
The Safety Instruction Signature is a number that identifies the execution characteristics of the safety Add-On
Instruction (AOI). The Safety Instruction Signature is different than the ID, which consists of a number and time stamp
which helps determine if the instruction has been modified.
The Safety Instruction Signature takes into account a variety of factors that affect execution characteristics of the
Safety Instruction, such as firmware and software version, and technology considerations such as compilers and
hardware platform. Therefore, the Safety Instruction Signature is not guaranteed to be maintained when migrating
between major revisions of Logix Designer.
Tip: The Safety Instruction Signature is computed by the controller and may change upon download.
For details on how to certify a safety Add-On Instruction, refer to the safety reference manual for your controller,
listed in the Additional resources on page .
Programming languages
• What language do you want to use to program your instruction?
The primary logic of your instruction will consist of a single routine of code. Determine which software
programming language to use based on the use and type of application. Safety Add-On Instructions are
restricted to Ladder Diagram.
• If execution time and memory usage are critical factors, refer to the Logix5000 Controllers Execution Time
and Memory Use Reference Manual, publication 1756-RM087.
Transitional instructions
Some instructions execute (or retrigger) only when rung-condition-in toggles from false to true. These are
transitional-ladder diagram instructions. When used in an Add-On Instruction, these instructions will not detect the
rung-in transition to the false state. When the EnableIn bit is false, the Add-On Instruction logic routine no longer
executes, thus the transitional instruction does not detect the transition to the false state. Extra conditional logic is
required to handle triggering of transitional instructions contained in an Add-On Instruction.
Some examples of transitional instructions include: ONS, MSG, PXRQ, SRT, some of the ASCII instructions, and some of
the Motion instructions.
Tip: The EnableInFalse routine can be used to provide the conditioning required to retrigger transitional
instructions contained in an Add-On Instruction. However, this method will not work for calls to this Add-
On Instruction contained in a Structured Text routine, since EnableIn is always true for calls in Structured
Text.
Instruction size
Add-On Instructions have one primary logic routine that defines the behavior of the instruction when executed. This
logic routine is like any other routine in the project and has no additional restrictions in length. The total number of
Input parameters plus Output parameters plus local tags can be up to 512.
Logix Designer versions 27 and earlier do not set a limit on the number of InOut parameters. However, limit extended
properties (.@Min and .@Max syntax) should not be defined on an InOut parameter of an Add-On Instruction and
should not be used in Add-On Instruction definition logic or the logic does not verify.
Logix Designer version 28 limits the number of InOut parameters for Add-On Instructions to 40.
Logix Designer versions 29 and later limit the number of InOut parameters for Add-On Instructions to 64 and limit the
Add-On Instruction nesting levels to 16. Rockwell recommends limiting the level of nesting to eight levels to reduce
complexity and make the instruction easier to manage.
The maximum data instance supported (which includes Inputs, Outputs, and local tags) is two megabytes. The data
type size is displayed on the bottom of the Parameters and Local Tags tab in the Add-On Instruction Definition.
Runtime editing
Add-On Instructions can only be edited offline. If the intended functionality needs to be changed in a running
controller, consider carefully if an Add-On Instruction is suitable.
Add-On Instructions cannot call other routines through a JSR instruction. You must use nested instructions if you
need complex functionality consisting of multiple routines.
Tip: To nest Add-On Instructions, both the nested instruction and the instruction that calls it must be
of the same class type or the calling instruction will not verify. That is, standard Add-On Instructions
may call only standard Add-On Instructions and safety Add-On Instructions may call only safety Add-On
Instructions.
Parameters data types N/A Atomic, arrays, structures Atomic for any parameter
Parameter checking N/A None, user must manage Verification checks that
correct type of argument has
been provided for a parameter
Data encapsulation N/A All data at program or Local data is isolated (only
controller scope (accessible to accessible within instruction)
anything)
Monitor/debug In-line code with its data Mixed data from multiple calls, Single calling instance data,
which complicates debugging which simplifies debugging
Supported programming FBD, LD, SFC, ST FBD, LD, SFC, ST FBD, LD, ST
languages
Callable from N/A FBD, LD, SFC, ST FBD, LD, SFC through ST, ST
Protection Locked and view only Locked and view only Locked and view only
Documentation Routine, rung, textbox, line Routine, rung, textbox, line Instruction, revision
information, vendor, rung,
textbox, line, extended help
Memory use Most used Very compact Compact call requires more
memory than a subroutine call
Import/export Entire routine, including tags Entire routine, including tags Full instruction definition
and instruction definitions to and instruction definitions to including routines and tags to
L5X L5X L5X
The parameters of an Add-On Instruction are directly accessible in the controller's programming through this
instruction-defined tag within the normal tag-scoping rules.
Local tags are not accessible programmatically through this tag. This has impact on the usage of the Add-On
Instruction. If a structured (including UDTs), array, or nested Add-On Instruction type is used as a local tag (not InOut
parameters), then they are not programmatically available outside the Add-On Instruction definition.
BRK Break
RET Return
SBR Subroutine
Safety application instructions, such as Safety Mat (SMAT), may be used in safety Add-On Instructions only. For
detailed information on safety application instructions, refer to the GuardLogix Safety Application Instruction Set
Safety Reference Manual, publication 1756-RM095.
In addition, the following instructions may be used in an Add-On Instruction, but the data instances must be passed
as InOut parameters.
• AddOnInstructionDefinition
Tip: GSV-only. SSV instructions will not verify. Also, the classes that represent programming
components (Task, Program, Routine, AddOnInstructionDefinition) support only ’this’ as the
Instance Name.
• Axis
• Controller
• Controller Device
• CoordinateSystem
• CST
• DF1
• FaultLog
• HardwareStatus
• Message
• Module
• MotionGroup
• Program
Tip: The classes that represent programming components (Task, Program, Routine,
AddOnInstructionDefinition) support only ’this’ as the Instance Name.
• Redundancy
• Routine
• Safety
• Serial Port
• Task
• TimeSynchronize
• WallClockTime
When you enter a GSV or SSV instruction, Logix Designer application displays the object classes, object names, and
attribute names for each instruction. This table lists the attributes for the AddOnInstructionDefinition class.
For more information on using GSV and SSV instructions, refer to the Logix Controllers Instructions Reference Manual,
publication 1756-RM009.
Performance Argument values are copied in and out of Parameters access argument tags
the parameters of the Add-On Instruction. directly by reference, which leads to
This takes more time to execute a call to faster execution of instruction calls.
the instruction.
Parameter data types supported Atomic (SINT, DINT, INT, REAL, BOOL). Atomic, arrays, and structures.
When developing your logic, use the Size instruction to determine the actual size of the referenced array to
accommodate this flexibility.
Tip: When you monitor an array InOut parameter inside of the logic routine, the parameter definition is
used to determine the size of the array. For example, assume you have defined an InOut parameter to be
a 10-element array of DINTs and the end user passes in an array of 100 DINTs. Then if you open the Add-
On Instruction logic, select the appropriate context for that call, and monitor the array parameter, only 10
elements will be displayed.
For Output parameters, making a parameter visible is useful if you do not usually need to pass the parameter value
out to an argument, but you do want to display its value prominently for troubleshooting.
Required parameters are always visible, and InOut parameters are always required and visible. All Input and Output
parameters, regardless of being marked as required or visible, can be programmatically accessed as a member of the
instruction's tag.
The following picture shows a Simulation instruction in the function block editor.
If you want a pin that is displayed in Function Block, but wiring to it is optional, set it as Visible.
• If you want the parameter’s value displayed on the instruction face in Ladder, set the parameter as visible.
• An Output parameter of the BOOL tag type that is not required, but visible, will show as a status flag on the
right side of the block in Ladder. This can be used for status flags like DN or ER.
This table explains the effects of the Required and Visible parameter settings on the display of the instructions.
Does the Does the Do You Does the Can You Does the
Value Argument Need to Argument Change the Argument
display? display? Connect the display? Visibility display?
Parameter? Setting
Within the
Function
Block?
Input Y Y Y Y Y N/A N Y
Input N Y Y N N N/A Y N
Input N N N N N N/A Y N
Output Y Y Y Y Y N/A Y Y
Output N Y Y N N N/A Y N
Output N N N N N N/A Y N
InOut Y Y N Y N/A Y N Y
If you have a parameter for which the user must specify a tag as its source for input or its destination as output, and
you do not want this to be optional, set the parameter as required. Any required parameters are automatically set to
visible.
The Visible setting is always set to visible for InOut parameters. All InOut parameters are required.
Tip: When you are using your Add-On Instructions, the Visible setting may be overridden in Function
Block Diagram routines if the parameter is not required or already wired. Overriding the visibility at the
instruction call does not affect this definition configuration.
• Standard tags may not be used as Input, Output, or InOut parameters of a safety Add-On Instruction.
• Safety tags may be used as Input parameters for standard Add-On Instructions.
Constant values
InOut parameters may be designated as constant value tags to prevent their data from being modified by controller
logic. If the logic of an Add-On Instruction contains a write operation to a constant value parameter, the Add-On
Instruction does not verify in the Add-On Instruction definition context.
External Access
External Access defines the level of access that is allowed for external devices, such as an HMI, to see or change tag
values.
EnableOut parameter
Intended behavior
• What is the purpose for creating the Add-On Instruction?
• What problem is it expected to solve?
• How is it intended to function?
• Do you need to higher level of integrity on your Add-On Instruction?
If so, you can generate an instruction signature as a means to verify that your Add-On Instruction has not
been modified.
• Do you need to use safety application instructions and certify your safety Add-On Instruction to SIL-3
integrity?
For details on how to certify a safety Add-On Instruction, refer to the safety reference manual for your
controller, listed in the Additional resources on page .
Parameters
• What data needs to be passed to the instruction?
• What information needs to be accessible outside of the instruction?
• Do alias parameters need to be defined for data from local tags that needs to be accessible from outside the
Add-On Instruction?
• How does the parameters display? The order of the parameters defines the appearance of instruction.
• Which parameters should be required or visible?
Naming conventions
The instruction name is to be used as the mnemonic for your instruction. Although the name can be up to 40
characters long, you typically want to use shorter, more manageable names.
Source protection
• What type of source protection needs to be defined, if any?
• Who has access to the source key?
• Will you need to manage source protection and an instruction signature?
Source protection can be used to provide read-only access of the Add-On Instruction or to completely lock or
hide the Add-On Instruction and local tags.
Source protection must be applied prior to generating an instruction signature.
Local tags
• What data is needed for your logic to execute but is not public?
• Identify local tags you might use in your instruction. Local tags are useful for items such as intermediate
calculation values that you do not want to expose to users of your instruction.
• Do you want to create an alias parameter to provide outside access to a local tag?
Programming languages
• What language do you want to use to program your instruction?
The primary logic of your instruction will consist of a single routine of code. Determine which software
programming language to use based on the use and type of application. Safety Add-On Instructions are
restricted to Ladder Diagram.
• If execution time and memory usage are critical factors, refer to the Logix5000 Controllers Execution Time
and Memory Use Reference Manual, publication 1756-RM087.
Test
• How will you test the operation of your Add-On Instruction before commissioning it?
• What possible unexpected inputs could the instruction receive, and how will the instruction handle these
cases?
Help documentation
• What information needs to be in the instruction help?
When you are creating an instruction, you have the opportunity to enter information into various description
fields. You will also need to develop information on how to use the instruction and how it operates.
3. In the Name box, type a unique name for the new instruction.
The name can be up to 40 characters long. It must start with a letter or underscore and must contain only
letters, numbers, or underscores. The name must not match the name of a built-in instruction or an existing
Add-On Instructions.
4. In Description box, type a description for the new instruction, maximum 512 characters.
5. For safety projects, in the Class box, select either a Safety or Standard.
The Class field is available on the Add-On Instructions dialog box for safety controller projects.
6. In the Type box, select a programming language for Add-On Instruction logic.
The language Type defaults to Ladder Diagram for safety Add-On Instructions.
7. In Revision box, assign a Revision level for the instruction.
8. (Optional) In the Revision Note box, type a Revision note.
9. (Optional) In the Vendor box, add information about the Vendor.
10. Click OK to create the instruction.
Create a parameter
Use the Add-On Instruction Definition Editor to create the parameters for your instructions. Follow these steps to
define the parameters for your instruction.
To create a parameter
1. In the Controller Organizer, right-click an Add-On Instruction and select Open Definition.
2. On the Parameters tab, in the blank Name box, type a name for a parameter.
Tip: An instruction with only Input parameters, except EnableOut, is treated as an input
instruction in a Ladder diagram and is displayed left-justified. The EnableOut parameter is used
for the rung-out condition.
4. In the Data Type list, choose the type based on the parameter usage:
◦ An Input parameter is a passed by value into the Add-On Instruction and must be a SINT, INT, DINT,
REAL, or BOOL data type.
◦ An Output parameter is a passed by value out of the Add-On Instruction and must be a SINT, INT, DINT,
REAL, or BOOL data type.
◦ An InOut parameter is a passed by reference into the Add-On Instruction and can be any data type
including structures and array. Module reference parameters must be InOut parameters with the
MODULE data type (see Creating a module reference parameter on page 35).
5. If this parameter is intended as an alias for an existing local tag, select the Alias For check box to select the
local tag or its member.
Tip: You can also designate a parameter as an alias for a local tag by using the Tag Editor. See
Edit Parameters and Local Tags on page 38.
Tip: If you want to update existing invocations of the instruction to the new default values, select
the Copy all default values of parameters and local tags whose values were modified to all
tags of this instruction type check box at the bottom of the Add-On Instruction Definition Editor.
For details on copying default values, see Copying Parameter or Local Tag Default Values on page
39.
Tip: You can also create parameters by using the Tag Editor, New Parameter or Local Tag dialog
box, or by right-clicking a tag name in the logic of your routine.
The order that you create the parameters is how they appear in the data type and on the instruction face. To
rearrange the order of the Parameter tab on the Add-On Instruction Definition Editor, select the parameter row and
click Move Up or Move Down.
parameter, see Referencing a hardware module on page 73. You can use the module reference parameter in two
ways:
• In a GSV or SSV instruction, or an Add-on Instruction, you can use the module reference parameter as the
Instance Name or Add-on Instruction parameter.
• In an Add-on Instruction, or in a GSV or SSV instruction, you can pass the module reference parameter into
the InOut parameter of another nested Add-on Instruction.
• Module references parameters can only be InOut parameters with the MODULE data type.
• You can use a module reference parameter only in standard programs and Add-on Instructions, not in Safety
programs or Safety Add-on Instructions.
• Program parameters that reference a module must connect to a module, and cannot reference other module
reference parameters.
• Module reference parameters must be program or Add-on Instruction scope, not controller scope.
Tip: You cannot create a module reference tag. You can only reference modules using an InOut
parameter of the MODULE data type.
Tip: You can also create parameters by using the Tag Editor, New Parameter or Local Tag dialog
box, or by right-clicking a tag name in the logic of your routine.
For more information on using parameters in programs, see Logix5000 Controllers Program Parameters
Programming Manual, publication 1756-PM021.
Tip: You can access local tag values from an HMI by specifying the name of the local tag as a member in
an Add-On Instruction type tag. For example, the Motor_Starter v1.0 instruction, shown in step 2, has a tag
called ‘CheckAuxContact’. This tag can be referenced by an HMI through ‘instancetag.CheckAuxContact’,
where instancetag is the tag used to call the instruction.
You cannot use these data types for local tags - ALARM_ANALOG, ALARM_DIGITAL, MESSAGE, MODULE, or any
Motion data types, for example Axis or MOTION_GROUP. To use these type of tags in your Add-On Instruction,
define an InOut Parameter. Local tags also are limited to single dimension arrays, the same as User-Defined
Data Types.
Tip: Refer to the safety reference manual for your controller, listed in the Additional resources on
page , for a list of data types supported for safety instructions.
Tip: Select the Copy all default values of parameters and local tags whose values were
modified to all tags of this instruction type check box at the bottom of the Add-On Instruction
Definition Editor if you want to update existing invocations of the instruction to the new default
values. For details on copying default values, see Copying Parameter or Local Tag Default Values
on page 39.
Tip: When you create a local tag from the Local Tags tab, the External Accesssetting defaults to
None. You can edit the External Access setting by using the Tag Editor. See Edit Parameters and
Local Tags on page 38.
ATTENTION: Source-protected routines and other source-protected Add-On Instructions that use the
edited Add-On Instruction are not automatically updated if the source key is unavailable. The Add-On
Instruction or routine may still verify, but the resulting operation may not be as intended.
It is your responsibility to know where Add-On Instructions are used in logic when you make edits to
existing Add-On Instructions.
A confirmation dialog box shows you the impacts of the edits and lets you review the pending changes before
confirming or rejecting them.
To accomplish this update, Logix Designer application tracks the changes made to the Add-On Instruction parameters
from the original instruction to the final version. In contrast, the import and paste processes compare only parameter
names to associate arguments with parameters. Therefore, if two different parameters have the same name, but
different operational definitions, importing or pasting may impact the behavior of the instruction.
ATTENTION: Values cannot be modified when the instance tags are part of a source-protected Add-
On Instruction or you do not have sufficient permission to make edits.
If you change the default values of a parameter or local tag by using the Add-On Instruction Definition editor, you
can copy the modified values to all of the tags of the Add-On Instruction data type by selecting the Copy all default
values of parameters and local tags whose values were modified to all tags of this instruction type check box.
You can also click the copy default values icon to copy default values to all tags the Add-On Instruction data type. The
icon appears on the watch pane (as a context menu), data monitor, and logic editor when the Data Context is the Add-
On Instruction’s definition.
If you want to select which specific tags and values to copy, click the pull-down arrow of the copy default values icon
and select Copy Specified Values.
The Copy Default Values dialog box shows the current default values for the parameters and local tags, and the
instance tags where the Add-On Instruction is used or referenced.
Select the check boxes to select which values to copy to which tags, and click OK.
2. Expand the instruction and double-click the logic routine to open it.
In standard programs, you can use the User Interrupt Disable/Enable (UID/UIE) instructions to block a task switch if
you want to be sure the Add-On Instruction executes uninterrupted before switching to another task.
Tip: UID and UIE instructions are not supported in the safety task of GuardLogix projects.
Optimizing performance
The performance depends on the structuring, configuration, and the amount of code in an Add-On Instruction. You
can pass large amounts of data through a structure by using an InOut parameter. The size of data referenced by an
InOut parameter does not impact scan time and there is no difference between passing a user-defined type tag or an
atomic tag because it is passed by reference.
When a rung condition is false, any calls to an Add-On Instruction are still processed even though the logic routine is
not executed. The scan time can be affected when many instances of an Add-On Instruction are executed false. Be
sure to provide instructions in your documentation if an Add-On Instruction can be skipped when the rung condition
is false.
Like all built-in instructions in the controller, Add-On Instructions support the following four controller Scan modes.
True The instruction is scanned as the result of a true rung condition or the EnableIn
parameter is set True.
False The instruction is scanned as the result of a false rung condition or the EnableIn
parameter is set False. Instructions in the controller may or may not have logic that
executes only when that instruction is scanned false.
Prescan Occurs when the controller either powers up in Run mode or transitions from Program
to Run. Instructions in the controller may or may not have logic that executes only
when that instruction is executed in Prescan mode.
Postscan(1) Occurs as a result of an Action in a Sequential Function Chart (SFC) routine becoming
inactive if SFCs are configured for Automatic Reset. Instructions in the controller
may or may not have logic that executes only when that instruction is executed in
Postscan mode.
1
Postscan mode routines cannot be created for safety Add-On Instructions because safety instructions do not
support SFC.
The default behavior for executing an Add-On Instruction with no optional scan routines created may be sufficient for
the intended operation of the instruction. If you do not define an optional Scan Mode, the following default behavior of
an Add-On Instruction occurs.
False Does not execute any logic for the Add-On Instruction and does
not write any outputs. Input parameters are passed values.
For each Scan mode, you can define a routine that is programmed specifically for that Scan mode and can be
configured to execute in that mode.
True The main logic routine for the Add-On Instruction executes (not
optional).
The optional Prescan routine for an Add-On Instruction provides a way for an Add-On Instruction to define additional
behavior for Prescan mode. When a Prescan routine is defined and enabled, the Prescan routine executes normally
after the primary logic routine executes in Prescan mode. This is useful when you want to initialize tag values to
some known or predefined state prior to execution. For example, setting a PID instruction to Manual mode with a 0%
output prior to its first execution or to initialize some coefficient values in your Add-On Instruction.
When an Add-On Instruction executes in Prescan mode, any required parameters have their data passed.
• Values are passed to Input parameters from their arguments in the instruction call.
• Values are passed out of Output parameters to their arguments defined in the instruction call.
These values are passed even when the rung condition is false in Ladder Diagram or when the instruction call is in a
false conditional statement in Structured Text. When Function Block Diagram routines execute, the data values are
copied to all wired inputs and from all wired outputs, whether or not the parameters are required.
4. On the New Scan Mode Routine dialog box, from the Type list, select the type of programming language;
Ladder Diagram, Function Block, or Structured Text.
The Prescan routine can now be edited like any other routine.
When an Add-On Instruction is called by logic in an SFC Action or a call resides in a routine called by a JSR from an
SFC Action, and the Automatic Reset option is set, the Add-On Instruction executes in Postscan mode. The primary
logic routine of the Add-On Instruction executes in Postscan mode. Then if it is defined and enabled, the Postscan
routine for the Add-On Instruction executes. This could be useful in resetting internal states, status values, or de-
energizing instruction outputs automatically when the action is finished.
Tip: Because safety Add-On Instructions cannot be called from an SFC Action, this option is disabled for
safety Add-On Instructions.
4. On the New Scan Mode Routine dialog box, from the Type list, select the type of programming language;
Ladder Diagram, Function Block, or Structured Text.
7. Define if the postscan routine executes (or not) by checking or clearing Execute Postscan routine after the
logic routine is postscanned.
The Postscan routine can now be edited like any other routine.
When the Add-On Instruction is executed in the false condition and has an EnableInFalse routine defined and enabled,
any required parameters have their data passed.
• Values are passed to Input parameters from their arguments in the instruction call.
• Values are passed out of Output parameters from their arguments in the instruction call.
If the EnableInFalse routine is not enabled, the only action performed for the Add-On Instruction in the false condition
is that the values are passed to any required Input parameters in ladder logic.
Follow these steps to create an EnableInFalse routine. For more information on other scan mode instructions, see
Prescan routine on page 44 and Postscan routine on page 45.
4. On the New Scan Mode Routine dialog box, from the Type list, select the type of programming language;
Ladder Diagram, Function Block, or Structured Text.
The EnableInFalse routine can now be edited like any other routine.
To execute the primary logic routine in any of the language environments, the EnableIn parameter must be True
(1). In general, the EnableIn parameter should not be referenced by the primary logic routine within the instruction
definition. The EnableOut parameter will, by default, follow the state of the EnableIn parameter but can be overridden
by user logic to force the state of this parameter.
Tip: If EnableIn is False, then EnableOut cannot be made True in an EnableIn False routine.
If the EnableIn parameter of the instruction is False (0), the logic routine is not executed and the EnableOut
parameter is set False (0). If an EnableInFalse routine is included in the instruction definition and it is enabled, the
EnableInFalse routine will be executed.
Tip: An instruction with only Input parameters, except EnableOut, is treated as an input instruction (left-
justified) in a Ladder Diagram. The EnableOut parameter is used for the rung-out condition.
Changing the class of an Add-On Instruction results in the same class change being applied to the routines,
parameters, and local tags of the Add-On Instruction. The change does not affect nested Add-On Instructions or
existing instances of the Add-On Instruction.
If any parameters or tags become unverified due to the change of class, they are identified on the Parameters and
Local Tags tabs of the Add-On Instruction Editor.
If any of the restrictions for safety Add-On Instructions are violated by changing the class from standard to safety,
one of the following errors is displayed and the change does not succeed:
You must edit the parameter, tag, or routine types before the class change can be made.
Tip: If the safety controller project contains safety Add-On Instructions, you must remove them from the
project or change their class to standard before changing to a standard controller type.
Tip: When a fault occurs in an Add-On Instruction routine, a fault log is created that contains extended
information useful for troubleshooting.
Tip: Add-On Instructions can only be created or modified when offline. You can add, delete, or
modify tag arguments in calls to Add-On Instructions while editing online, but you cannot edit
arguments inside the Add-On Instruction while online.
Tip: When troubleshooting an Add-On Instruction, use a non-arrayed instance tag for the call to the
instruction. This lets you monitor and troubleshoot the instruction's logic routine with a data context.
Variable indexed arrays cannot be used to monitor the logic inside an Add-On Instruction.
The logic routine opens with animated logic for the specific calling instance.
Instruction Description
False In a ladder logic target routine, this entails placing an XIC before
an instance of the instruction and evaluating instruction results
when the XIC is false.
In a Function Block target routine, this entails executing an
instance of the instruction with the EnableIn parameter set to
zero (0).
Postscan With the controller configured for SFC Automatic Reset, place
an instance of the instruction into the Action of an SFC. Run
the SFC such that this Action is executed and the SFC proceeds
beyond the step that is associated with this Action.
Cannot modify the Source Protection settings if the Add-On Instruction is sealed. To source protect and seal an Add-
On Instruction, apply the source protection settings before sealing.
Source protection limits user access to your Add-On Instruction or blocks access to the internal logic or local tags
used by the instruction. You can protect Add-On Instructions using Source Key protection or License protection. You
can also apply Execution Protection to source-protected components to allow execution only on controllers with a
specific execution license.
License-based protection:
Tip: License-Based Source Protection is not supported on Sequential Function Chart routines in
version 30 of the Logix Designer application.
• Execution Protection is an extension of License-Based Source Protection. You can apply Execution Protection
to limit the execution of routines and Add-On Instructions, including equipment phase state routines, to
controllers that contain a specific execution license.
• When you protect a component with License-Based Source Protection, you can also lock it.
When locking a component, the routine's logic is compiled into executable code and encrypted. The code
is decrypted by the controller when it is ready for execution. As a result, sharing project files containing
locked components with users without licenses to use the locked components is possible. Those users
can use unprotected parts of the project, upload and download the project file, and copy and paste locked
components into other project files. However, if a component is protected using the Protect with controller
key and specific license option, executing the project requires an SD card with the correct execution
license.
Tip: Execution Protection and component locking is supported only on CompactLogix 5380,
CompactLogix 5480, and ControlLogix 5580 controllers in version 30 of the Logix Designer
application.
The Security Programming manual provides detailed instructions for configuring Source Protection for routines and
Add-On Instructions.
IMPORTANT: If you remove an instruction signature when the Add-On Instruction also has a
safety instruction signature, the safety instruction signature is also deleted.
1. Click Copy to copy the instruction signature and the safety instruction signature, if it exists, to the clipboard
to facilitate record-keeping.
Tip:
The instruction signature is not guaranteed to be maintained when migrating between major revisions of
RSLogix5000 or <Product_Name_RSL5K>.
Tip: To facilitate record-keeping, you can copy the entire signature history to the clipboard by
selecting all the rows in the signature history and choosing Copy from the Edit menu. The data is
copied in tab separated value (TSV) format.
To delete the signature history, click Clear Signature History. You must be offline to delete the Signature History.
If Logix Designer application detects an invalid safety instruction signature value, it generates a new safety
instruction signature value in the offline project and displays a warning indicating that the safety instruction
signature was changed. The safety instruction signature is deleted if the instruction signature is removed.
IMPORTANT: After testing the safety Add-On Instruction and verifying its functionality, you must
record the instruction signature, the safety instruction signature and the timestamp value. Recording
these values will help you determine if the instruction functionality has changed.
Refer to the safety reference manual for your controller, listed in the Additional resources on page
, for details on safety application requirements.
Tip: When an instruction is sealed, the instruction signature is displayed on the faceplate of the
instruction in the Ladder Diagram Editor and the Function Block Diagram Editor.
Tip: The first 32 bits of an AOI's signature (Safety ID) as it appears in the Quick View Pane and in
the signature report are comparable to the AOI's signature as it appears on the AOI Properties >
Signature tab.
• Include the instruction signature, safety instruction signature, and signature history on the Add-On
Instruction report by clicking Print Options on the Generate Report dialog box.
An alarm definition is associated with an Add-On Instruction or a defined data type. When a tag is created using a
data type or an Add-On Instruction that has alarm definitions, alarm conditions are created automatically based on
the alarm definitions.
Tip: Tag-based alarms and alarm definitions are supported only on CompactLogix 5380, CompactLogix
5480, and ControlLogix 5580 controllers.
◦ Advanced - Used to assign additional settings to the alarm definition, such as an FactoryTalk View
command to run in response to an alarm, latch state, acknowledgment requirement, alarm set
inclusion, and use of the alarm.
Tip: Alarm definitions associated with the tag are not included when an Add-On Instruction
tag is copied and pasted in a project.
After you copy and paste an Add-On Instruction tag, open the Alarm Definition list and
copy and paste the alarm definition for the tag. Follow these steps:
a. In the Controller Organizer, right-click Alarms and select Edit Alarm Definitions.
b. Right-click the alarm definition for the Add-On Instruction tag and select Copy.
c. Right-click again and select Paste. The alarm definition is pasted into the list with
_000 added to the alarm name.
d. Double-click the copy of the alarm definition to open the Alarm Definition
Properties dialog box.
e. In the Input box, change the input tag to the Add-On Instruction tag that you copied
and pasted.
When you reference an attribute from an individual alarm, you insert the owner of the alarm in the operand syntax.
Similarly, when you reference an attribute from an Add-On Instruction alarm set, you insert the alarm set container
(the AOI definition, AOI structured tag, or AOI array tag) in the operand syntax.
Tip:
In this version of the Logix Designer application, the @Alarms and @AlarmSet syntax is not supported in
the following instructions:
• CMP
• CPT
• FAL
• FSC
The following example shows how inserting an MOV instruction allows the @Alarms and @AlarmSet
syntax to work with CMP, CPT, FAL, and FSC instructions.
Unsupported expression:
Supported expression:
MOV(RightValve.ValveTimer.@Alarms.TM_ACC_1.Severity, MyIntermediateTag)
Tip:
In this version of the Logix Designer application, in the Structured Text editor, the @Alarms and
@AlarmSet syntax is supported only in simple arithmetic expressions, such as a + b. The following
example shows how inserting an additional step allows creation of more complex arithmetic expressions.
In addition, you can add your own custom text to the help by using the Extended Description field. You can provide
additional help documentation by entering it on the Help tab on the Add-On Instruction Definition Editor. The
instruction help is available in the instruction browser and from any call to the instruction in a language editor by
pressing F1.
This is an example of the Extended Description Text field in the Help tab on the Add-On Instruction Definition Editor.
This area lets you create directions on how to use and troubleshoot your instruction. The Instruction Help Preview
window shows how your text will look as generated instruction help.
Tip: When you are typing your text into the Extended Description Text field, you can use returns and
tabs in the field to format the text, and if you copy and paste text into the field tabs are preserved.
This is an example of the Logix Designer application generated help for the instruction. This information is
gathered from the definition descriptions that you complete when defining an instruction.
Project documentation
With RS Logix 5000 software, version 17 and later, you have the option to display project documentation, such as
tag descriptions and rung comments in any supported localized language. You can store project documentation for
multiple languages in a single project file rather than in language-specific project files. You define all the localized
languages that the project will support and set the current, default, and optional custom localized language. The
software uses the default language if the current language's content is blank for a particular component of the
project. However, you can use a custom language to tailor documentation to a specific type of project file user.
Enter the localized descriptions in your project, either when programming in that language or by using the import/
export utility to translate the documentation offline and then import it back into the project. Once you enable project
documentation in application, you can dynamically switch between languages as you use the software.
• Component descriptions in tags, routines, programs, equipment phases, user-defined data types, and Add-On
Instructions
• Engineering units and state identifiers added to tags, user-defined data types, or Add-On Instructions
• Trends
• Controllers
• Alarm Messages (in configuration of ALARM_ANALOG and ALARM_DIGITAL tags)
• Tasks
• Property descriptions for module in the Controller Organizer
• Rung comments, SFC text boxes, and FBD text boxes
If you want to allow project documentation on an Add-On Instruction that is sealed with an instruction signature, you
must enter the localized documentation into your Add-On Instruction before generating the signature. Because the
signature history is created after the instruction signature is generated, the signature history is not translatable.
If the translated information already exists when you generate the Add-On Instruction signature, you can switch
the language while keeping the signature intact because the switch does not alter the instruction definition, it only
changes the language that is displayed.
For more information on enabling a project to support multiple translations of project documentation, refer to the
online help.
If the stop pushbutton is closed and the start pushbutton is pressed then:
If the stop pushbutton is pressed (opened), then the motor stops. The following screen capture shows the General tab
for the Motor Starter Add-On Instruction.
The following screen capture shows the Parameters tab for the Motor Starter Example Definition Editor.
The following screen capture shows the Motor Starter Example ladder logic.
The following diagrams show the Motor Starter instruction called in three different programming languages. First is
Motor Starter Ladder Logic.
The following screen capture shows the Parameter tab for the Simulation Example Definition Editor.
The Simulation_DT_1st instruction reads the control variable from the PID instruction. The PID instruction reads the
SimOutput Parameter of the Simulation_DT_1st instruction.
Introduction
Add-On Instructions are used in your routines like any built-in instructions. You add calls to your instruction and then
define the arguments for any parameters.
IMPORTANT: Safety Add-On Instructions can be used only in safety routines, which are currently
restricted to ladder logic. Safety Add-On Instructions are shown in the Language Element toolbar
only when the routine is a safety routine.
2. From the Element list, select the Add-On Instruction you want to add to your routine.
3. Click Instruction Help to display the instruction help for any instruction in the browser.
4. Click OK.
1. Open the Add-On Instruction folder in the Controller Organizer and view the listed instructions.
If the instruction you want to use is not listed, you need to do one of the following:
◦ Create the instruction in your project.
◦ Copy and paste an instruction into your project.
◦ Get the file for an exported instruction definition and then import the instruction into your current
project.
2. Open the routine that will use the instruction.
3. Click the Add-On tab on the instruction toolbar.
4. Click the desired Add-On Instruction to insert it in the editor. Hover the cursor on an instruction to see a
preview of it.
Ladder Diagram:
Single and double question marks This is a required Input or Output parameter. Enter a tag.
Double question marks This is not a required parameter. You can either:
• Leave as is and use the default value.
• Enter a different value if it’s an Input parameter.
Item Description
NOTE: The instruction expects arguments for required parameters as listed in the instruction tooltip.
Tip: For help with an instruction, select the instruction and then press F1. In Structured Text, make sure
the cursor is in the blue instruction name.
Tracked components and their current states appear in the Tracked Components dialog box, which is accessible on
the Controller Properties dialog box - Security tab. The recommended limit on the number of Add-On Instructions
that can be tracked is 100. If this limit is exceeded, there might be a noticeable impact on performance in the Logix
Designer application.
The FactoryTalk Security permission Add-On Instruction: Modify controls a user's ability to change the tracking
status for an Add-On Instruction.
Tip: Tips:
• Component tracking is supported only on
CompactLogix 5370, ControlLogix 5570, Compact GuardLogix 5370, and GuardLogix 5570
controllers
in version 30 of the Logix Designer application.
• To optimize performance, configure component tracking so that the tracked state value is
calculated on demand rather than at regular intervals.
Attribute Value
Instance Name The module reference parameter you created in the Add-On
Instruction (IO_ModuleSts below)
1. In the routine that includes the Add-On Instruction, create another module reference parameter.
a. In the routine, right-click Parameters and Local Tags and then click New Parameter.
b. Enter the following values in the dialog box.
Attribute Value
Name ModuleRef_Slot01
c. Click the down arrow in the Parameter Connections box, and choose a hardware module. This is the
module that the parameter references.
You can now access the attributes associated with the Module Object from within the Add-On Instruction.
Topic Description
Instruction Help Use the instruction help to determine how to use the instruction
in your code.
Data Types A data type defined with the Add-On Instruction is used for the
tag that provides context for the execution from your code. A
tag must be defined of this Add-On Instruction-defined type on
the call to the instruction.
Indexed Tag You can use an indirect array indexed tag for the Instruction
instance. One drawback is that you cannot monitor the Add-On
Instruction by using this as a data context.
The following procedures demonstrate how to use the Jog parameter of the Motor Starter Add-On Instructions.
Use another instruction, an assignment, or an expression to read or write to the tag name of the parameter. Use this
format for the tag name of the parameter:
Add_On_Tag.Parameter
Where Is
2. Select the Vis check box of the Jog parameter to use it in your diagram.
3. Click OK.
4. Wire to the pin for the parameter.
b. For Structured Text, right-click the instruction name and select Properties.
The Language Editor opens with the Add-On Instruction's logic routine and with data values from the
instruction call.
As you view the logic you can:
◦ Identify the instruction call whose tags are being used for data.
◦ See the logic as it executes (when online).
◦ See Parameter and Local Tag values.
◦ Change local tag and parameter values for the data instance selected.
3. To edit the logic of the Add-On Instruction, select the instruction <definition> in Data Context.
IMPORTANT: Use caution when copying and pasting components between different versions of Logix
Designer programming application. Logix Designer application only supports pasting to the same
version or newer version of Logix Designer application. Pasting to an earlier version of Logix Designer
application is not supported. When pasting to an earlier version, the paste action may succeed, but
the results may not be as expected.
Tip: When copying and pasting Add-On Instructions, consider these guidelines:
• You cannot paste a safety Add-On Instruction into a standard routine.
• You cannot paste a safety Add-On Instruction into a safety project that has been safety-locked or
one that has a safety task signature.
• You cannot copy and paste a safety Add-On Instruction while online.
3. Open other projects in additional instances of the Logix Designer application and use copy and paste or drag
and drop to move a copy of the instruction from MyInstructions.ACD to another project.
If any of these instructions reference the same Add-On Instruction or User-Defined Data Type, there is only
one shared copy in the project file. When an Add-On Instruction is copied to another project, it also copies
any instruction it references to the target project.
Tip: If an Add-On Instruction uses Message (MSG) instruction and InOut parameters of type
MESSAGE, you may wish to export a rung containing the Add-On Instruction to include the
MESSAGE tags. This captures the message configuration data, such as type and path.
In deciding how to manage your Add-On Instruction definitions in export files, you need to consider your goals in
storing the definitions.
If Then
You want to store many Add-On Instructions that share a set of Export to separate files as described in Exporting to separate
common Add-On Instructions or User-Defined Data Types in a files on page 86.
common location
You want to distribute an Add-On Instruction as one file Export to a single file as described in Exporting to a single file
instruction
Tip: Add-On Instructions with instruction signatures are encrypted upon export to prevent modifications
to the export file.
Tip: A License-protected Add-On Instruction is written to the export file in an encoded format unless the
user's license contains Export permission. To export in non-encrypted text, the license must contain the
Export permission, and when saving the export file, the user must deselect the Encode Source Protected
Content option.
Import considerations
The EditedDate attribute of an Add-On Instruction must be updated if the Add-On Instruction is
modified by editing an L5K or L5X file. If Logix Designer application detects edits to the Add-On
Instruction, but the EditedDate attribute is the same, the Add-On Instruction will not be imported.
When importing Add-On Instructions directly or as references, consider the following guidelines:
Topic Consideration
Add-On Instructions While Online An Add-On Instruction cannot be overwritten during import
while online with the controller, though a new Add-On
Instruction may be created while online.
User-Defined Data Types Add-On Instructions cannot overwrite User-Defined Data Types.
Add-On Instructions and User-Defined Data Types must have
unique names.
Safety Add-On Instructions You cannot import a safety Add-On Instruction into a standard
task.
You cannot import a safety Add-On Instruction into a safety
project that has been safety-locked or one that has a safety
task signature.
You cannot import a safety Add-On Instruction while online.
Class, instruction signature, signature history, and safety
instruction signature, if it exists, remain intact when an Add-On
Instruction with an instruction signature is imported.
Import configuration
When you select a file to import, the Import Configuration dialog box lets you select how the Add-On Instruction and
referenced components are imported.
If there are no issues, you can simply click OK to complete the import.
If your Add-On Instruction collides with one already in the project, you can:
• Rename it, by typing a new, unique name in the Final Name list.
• Select Overwrite from the Operation list.
• Select Use Existing from the Operation list.
Tip: You can only rename an Add-On Instruction if it has not been sealed with an instruction signature.
To rename an Add-On Instruction that has been source-protected, you need the source key or the
required license.
The Collision Details button displays the Property Compare tab, which shows the differences between the two
instructions, and the Project References tab, which shows where the existing Add-On Instruction is used.
3. Review the Import Configuration dialog box, and from the Operations list, click Overwrite.
4. Click Collision Details to see any differences in the Add-On Instructions and to view where the Add-On
Instruction is used.
The Property Compare tab shows the differences between the instructions, in this case, the Revision,
Edited Date, and Software Revision.
Tip: The Compare dialog box only compares extended properties for each instruction definition,
such as description, revision, or edited date. For effective revision control, enter a detailed
revision note.
The Project References tab shows where the existing Add-On Instruction is used.
IMPORTANT: Check each routine where your Add-On Instruction is used to make sure that your
existing program code will work correctly with the new version of the instruction.
For more information on updates to arguments, see Updates to arguments following parameter edits on page 38.
Technical Support Center Find help with how-to videos, FAQs, chat, user forums, and product notification updates. rok.auto/support
Local Technical Support Phone Numbers Locate the telephone number for your country. rok.auto/phonesupport
Literature Library Find installation instructions, manuals, brochures, and technical data publications. rok.auto/literature
Product Compatibility and Download Center Get help determining how products interact, check features and capabilities, and find rok.auto/pcdc
(PCDC) associated firmware.
Documentation feedback
Your comments help us serve your documentation needs better. If you have any suggestions on how to improve our content, complete the form at rok.auto/docfeedback.
Rockwell Automation maintains current product environmental information on its website at rok.auto/pec.
Rockwell Otomasyon Ticaret A.Ş. Kar Plaza İş Merkezi E Blok Kat:6 34752 İçerenköy, İstanbul, Tel: +90 (216) 5698400 EEE Yönetmeliğine Uygundur