Add On Instructions -

How to Create and

Apply User-defined
Functions in Logix

Copyright © 2008 Rockwell Automation, Inc. All rights reserved.

 What is a User Defined Add-on Instruction?
• User created instruction that is re-usable in one or multiple
projects/applications
• Instructions encapsulate code that
can be developed by the user using
standard instruction set and other
add-on instructions
• Like a routine that can be instantiated
multiple times
• Each instance of the instruction
has its own backing data
• Create using LD, FBD, or ST languages
• Use them in all programming languages (LD, SFC, FBD, ST)
• Import/export instruction to XML files to create libraries
• Prevent change or protect intellectual property by locking instructions
Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 2
 AOI’s Customer Value

• How will the Add-on Instructions feature benefit me?

– Saves programming time by allowing for creation of commonly used custom instructions
– Promotes consistency between projects – no need to constantly re-invent commonly used
control algorithms
– Reduces debugging time by animating the values in logic for a specific call to the instruction
– Protects intellectual property, without the possibility of it being changed/copied
– Used in conjunction with RSView SE/ME Global objects further speed up development time

• Unique strengths
– Animation of values for each logic instance reduces debugging
– Pre-scan and false state scan modes provide for advanced operation control
– Automatically generated online-help reduces documentation development

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 3

 Creating an Instruction

• Controller Organizer extended to

include “Add-On Instruction”
folder
– Simplifies creation and navigation
• Add-On Instructions are defined
once in project
– Instruction can be shared by multiple
programs
– Number of instructions is limited only
by controller’s memory

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 4

 Instruction Data Definition

• User configurable instruction parameters

– Input (copied in), Output (copied out),
• Support atomic (BOOL, SINT, INT, DINT and REAL) data types
– InOut (passed by reference)
• Support both atomic (BOOL, SINT, INT, DINT and REAL) and compound data types
(UDT and Arrays)
– Parameter name and definitions stored on the controller, descriptions saved in project file
• Automatic data-type
conversion for numeric
values
– SINT, INT, DINT and REAL
– Inputs converted prior
instruction invocation
– Outputs converted after
instruction execution

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 5

 Instruction Local Tag Definitions

• Tags can be defined locally to the instruction

– User specified name, data-type and description
– Supports atomic (BOOL, SINT, INT, DINT, and REAL) and compound data types (UDT and Arrays)
– Tag definitions and names loaded into controller while descriptions are saved in project
• Tags only programmatically accessible by the code within the instruction
– Copy the local data to a Parameter if you want to programmatically access it
– Local tags can be accessed from an HMI if you know the local tag name (will not appear in FTView tag browser)

Pass-
through
Other add-on- descriptions
instructions can be
nested and will show Default
up as local tags values

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 6

 Override Instruction Scan Modes

• Permits execution of code to setup, initialize, or reset the instruction

– Prescan - Controller startup
– Postscan - SFC Automatic reset
– EnableIn is false (i.e. rung condition is false)
• Advanced control of instruction
operation

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 7

 Instruction Data Instances

• Each add-on-instruction instance has its own data instance, providing

for automatic data isolation
• Allows each instruction to work with a customizable data set
• Simplifies programming and makes debugging and maintenance easier

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 8

 Instruction Run-Time Monitor / Debug

• Instruction faceplate provides animated values

• Monitoring an Add-in-Instruction provides value animation based on the specific call
that is selected
Data context for run-time
monitoring and debugging.

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 9

 Tag Editor / Data Monitor

• Input & Output data for parameters associated with each

instance of the instruction are visible in the tag editor / data
monitor
• Local tags are hidden to avoid accidental changes

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 10

 Import / Export

• All add-on instructions referenced in a project are included as part of the full project L5K
import/export
– Ensures imported project is complete and executable
– Instructions can be manipulated / created in L5K
• Add-on Instructions can be individually exported / imported to a file – on a server for example
– Uses XML formatted L5X file
– Exchange between projects
– Store to folders for re-use
• If Add-on instruction is protected, the L5K/L5X contents will be encoded if you do not have the
password key on your computer

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 11

 Importing a new AOI version into an existing
project
• If you select “Compare to Existing…” you can see where the AOI is already used, and what the
differences are in the revision numbers, revision notes, and creation and editing dates.
– Then choose whether to import the new version or just continue to use the existing version.

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 12

 Turning on Source Protection

• To turn on the ability to configure source protection for an Add-On Instruction, first run
the Source Protection enabling utility in the Tools folder on the install CD.

• You can then configure source protection in RSLogix 5000 under Tools Security
Configure Source Protection

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 13

 Source Protection

• Instruction implementation can be locked down similar to routine source protection

– No Access or View-Only Access
– Maintained even in textual export formats (L5K, L5X)
– Protected instructions are encoded in export files
Encoded AOI – no
access

Encrypted code

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 14

 Add-On Instruction Design Considerations

• Limited to 512 Input / Output Parameters

• Nest to 62 Levels deep
• 2 MByte Maximum data instance (Parameters and locals)
• Message, Axis, Axis Groups, Alarms and Produced / Consumed Tags
must exist at program / controller scope and be passed as an InOut
Parameter
• Input and Output Parameters are limited to atomic (Bool, SINT, INT,
DINT, REAL) data-types (Use InOut for UDT / Structure tags)
• Create and Modify off-line only (on-line operation limited to monitoring)
• Code changes are applied to all instances but default value changes (for
parameters and locals) only effect new instances
• RSMACC Archive of AOIs is handled manually outside of RSLogix 5000
with an exported L5X file
• RSMACC Audit detects changes to an AOI only after the program is
downloaded and the MACC verification process is run
Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 15
 Programmatic Access to Select Project
Names
• In V16, we updated the GSV instruction to provide read access to select project names:
Controller, Task, Program and Routine
– Specify the Task, program or routine from a list or utilize “THIS” to obtain the name based on
where the instruction is executed (Inheritance)
– Can be used within Add-on Instructions or Subroutines
– Because we store these names in the controller, this is a Logix Exclusive!
• GSV access to project names provides productivity boost
– Previously the same name would be used for a routine and into text strings that would be
used by an HMI
– Now you can create generic code to automatically grab the name(s) from the project and
generate the text strings to send to an HMI
• Reduces the time to reuse or instantiate code by eliminating redundant typing
• Reduces the checkout effort because it automatically gets the name for you

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 16

 Subroutines vs. Add-On Instructions
Subroutines Add-on Instructions
Calling Accessibility Within Program (multiple copies) Anywhere in Controller (single copy) ☺
Parameter Passing By Value By Value or Reference via InOut ☺
Numeric Parameters No Conversion, user must manage Automatic Datatype Conversion ☺
Datatypes Passed Atomic, Arrays, Structures ☺ Atomic (Arrays, Structures limited to InOut)
Parameter Checking None, user must manage Verification Checks ☺
Data Encapsulation
All data at program or controller scope
(accessible to anything)
Local data is isolated
(only accessible within instruction)
☺
Monitor / Debug Mixed data from multiple calls Single calling instance data ☺
Internal Language FBD, LD, SFC, ST ☺ FBD, LD, ST
Callable From FBD, LD, SFC, ST FBD, LD, SFC, ST
Protection Locked and View Only Locked and View Only
Documentation Routine, rung, textbox, line Instruction, revision info, vendor, rung, ☺
textbox, line, extended help

Execution
1. JSR/SBR/RTN add overhead
2. All data is copied
1. Call is more efficient
2. InOut passed by reference
☺
Performance 3. Indexed reference impact 3. References are automatically offset from
passed in backing tag location
Memory Management Manually manage all data not passed in/out Own data instance for each calling instance
to avoid conflicts, overlaps, etc. ☺
Edit / Modification On-line / Off-line ☺ Off-line Only
Import/Export LD Rungs and referenced tags / UDTs Full Instruction definition and code to L5X ☺
Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 17
 RSLogix 5000 User Defined Add-On Instruction
Competitive Strengths
• Pass by Reference
– InOut Tag brings an entire UDT available to AOI code
with one Reference pointer
• Instance based monitoring
– Some competitors do not provide a unique view per
data instance.
• Memory management made easy
– Datablob management is eliminated
• Flexible Routine naming – easy, unique (re-use)
• Automatic Datatype conversion for Atomic Input and
Output parameters
– Other vendors require user to add datatype conversion
instructions / blocks
– Fewer instructions to code and debug means faster
development
• Source password protection that works
– Some vendor’s code protection schemes can be
hacked
– In Logix the PW, source and export are encrypted to
prevent hacking
• Locked view only source option
– Most vendors can lock but source is not visible
– Permits the application critical code from being
modified but allows monitor and debug
Copyright © 2008 Rockwell Automation, Inc. All rights reserved.
• Description Pass-through for calling instance tags
– Another Logix Exclusive
– Automatically generates the descriptions for call to the
instruction (less typing)
• Controller Run Mode Pre-Scan / SFC Step Post-
Scan execution
– None of the environments we reviewed had a controller
pre-scan or SFC step post-scan
– Resets instructions to get them ready to run from a
known state (OTE off, TON reset...)
– Allows custom instruction to perform operations
typically on done by build in Instructions
• EnableIn (Rung state) False Execution
– All of the vendors we reviewed only executed the code
when the EnableIn / rung was true
– We let you set up some code to initiallize the instruction
for transition based operations (TON reset,
Oneshots...)
• Automatic Help Generation with Extended
Description
– None of the environments we reviewed provided any
help for UDFs
– Helps programmer and maintenance people
understand what the instruction does
• Create in LD, ST and FBD
18
 Factory Talk Asset Centre

Objective: “Manage Automation Assets”

What are “Automation Assets”?
• Logix Controllers (ControlLogix, CompactLogix,…)
• AB drives (PowerFlex, 1336,…)
• Classic PLC’s (PLC5, SLC500,…)
• Generic Electronic files
– Operator interfaces (Panelview Standard / Plus)
– RSNetworx files
– Rotary Equipment
– Excel tables, etc

What means “Manage”?

• Audit trail: log what changes are made to the asset's configuration, which individual performed the change,
when and from where.
• Versioning: store all versions of an asset's configuration in a secured central repository
• Access control: manage who can access the asset's configuration, in which degree and from where

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 19

 FTAsset Centre Experience during this lab

Audit trail: log what changes are made to the asset's configuration, which individual
performed the change, when and from where.

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 20

 What You Will Accomplish In This Lab?

As you complete the exercises in this hands-on session, you will:

• Create a new Add On Instruction in Ladder Logic, FBL, & Structured Text
• Examine and Monitor an AOI executing a program
• Nest AOI’s and Import / Export to new programs
• Setup OEM protection for AOI.
• Learn about the FT Asset Centre environment

Copyright © 2008 Rockwell Automation, Inc. All rights reserved. 21

Copyright © 2008 Rockwell Automation, Inc. All rights reserved.