LADX
Start free
← Resources
Instructions·7 min read·

Add-on instructions: reuse that survives being copied

What an AOI is, where it beats a subroutine, the versioning trap, and the reason to keep them small.

Short answer

An add-on instruction packages logic and its data into a reusable block that appears on a rung like a built in instruction. Each instance carries its own data, so ten valves using the same AOI have ten independent sets of state. It differs from a subroutine, which shares whatever tags it is given, and from a UDT, which is data with no behaviour.

How wide each type isBOOLone bitINT-32,768 to 32,767DINT±2.1 billionREALfloating pointA DINT holding a BOOL wastes 31 bits, and nobody notices until the tag count does.

The problem an add-on instruction solves is copied logic. Every plant has the same valve control written twelve times, slightly differently, because it was pasted and then adjusted.

What it is

A block containing logic and a data type, instantiated per use, appearing on a rung like any built in instruction.

Parameters come in three kinds. Input is read once at the start. Output is written at the end. InOut is passed by reference, which is how an AOI operates on an array or a large structure without copying it.

The important word is instance. Each use has its own data, including its own timers and its own one shots, so ten valves cannot interfere with each other.

Where it beats a subroutine

A subroutine is shared code with no data of its own. Call it for valve one and then valve two, and any timer inside it is the same timer both times.

That is exactly the bug that takes a day to find, because it only shows when two instances are active together, which on a machine might be rarely.

The rule: anything with internal state, a timer, a counter, a one shot, an edge memory, should be an AOI rather than a subroutine. Stateless calculations can be either.

Keep them small

The most common design error is an AOI that grew.

It starts as valve control. Then it needs an interlock parameter. Then a manual mode. Then a simulation mode. Then a maintenance bypass. Eventually it has twenty two parameters, and nobody can use it without reading its source.

Small AOIs compose. A valve AOI, a motor AOI and a scaling AOI used together in an ordinary routine is easier to read, easier to test and easier to change than one station AOI that does everything.

Versioning, which is where it hurts

The trap: an AOI is used in forty places. It needs a change for one of them. Changing it changes all forty.

Three ways out, in descending order of preference.

  • Make it a parameter. If the difference is behavioural and legitimate, expose it as an input and default it so existing instances behave as before.
  • Make a new version. Valve_v2 alongside Valve_v1. Ugly in the tag list, honest about what is happening, and the only approach that lets forty instances stay untouched.
  • Change all forty and test all forty. Correct, expensive, and the reason people avoid AOIs after being burned once.

Testing

The underrated benefit. An AOI is a unit, and a unit can be tested on its own.

Instantiate it in a test routine, drive its inputs, check its outputs. That is a real test, repeatable, and it does not require the machine.

Doing this for the ten AOIs a machine is built from gets more coverage than any amount of testing the assembled program, and it catches the interactions that only appear at commissioning.

The portability caveat

AOIs are vendor specific. Rockwell has add-on instructions, Siemens has function blocks in TIA Portal, CODESYS has POUs.

They are conceptually similar and not interchangeable. An AOI heavy program is harder to convert to another platform than a flat one, which is worth knowing when the platform is not yet settled. It is not a reason to avoid them; it is a reason not to be surprised.

Common questions

What is the difference between an AOI and a subroutine?
A subroutine is shared code operating on whatever tags the caller passes, holding no state of its own. An AOI is an instance: each use has its own data, including timers and one shots, so two instances cannot interfere. Anything with internal state should be an AOI rather than a subroutine.
Can I edit an AOI on a running controller?
Generally no. Changing the definition changes every instance, and most controllers require the change offline with a download. This is the main practical constraint and it is worth knowing before an AOI ends up in forty places.
Should AOIs be big or small?
Small. An AOI that does one thing, a valve, a motor starter, a scaling calculation, is understandable and testable. One that runs a whole station accumulates parameters, becomes untestable in isolation, and is edited so often that its version number stops meaning anything.

Keep reading