Instructions Reference¶

Complete reference for all ladder logic instructions supported by PiPLC.

Overview¶

Instructions are the building blocks of ladder logic programs. They fall into two categories:

Input instructions: Control rung power flow (contacts, comparisons)
Output instructions: Execute when rung is TRUE (coils, timers, counters, math)

Memory Regions Quick Reference¶

Region	Format	Description	Data Type
I:	I:W/B	Physical inputs	Bit
O:	O:W/B	Physical outputs	Bit
B:	B:W/B	Internal bits	Bit
N:	N:W	Integers	32-bit signed
T:	T:W	Timers	TimerData structure
C:	C:W	Counters	CounterData structure
V:	V:W	Intervals	IntervalData structure

Where W = word number, B = bit number (0-31).

Contact Instructions (Inputs)¶

XIC — Examine If Closed¶

Symbol: --[ ]--

Examines a bit address. Passes power when the bit is TRUE (1).

Property	Value
Type	Input
Address	Bit (I:, O:, B:)
Rung Output	TRUE if bit = 1

    [I:0/0]──────(O:0/0)
    When I:0/0 is TRUE, output O:0/0 energizes.

XIO — Examine If Open¶

Symbol: --[/]--

Examines a bit address. Passes power when the bit is FALSE (0).

Property	Value
Type	Input
Address	Bit (I:, O:, B:)
Rung Output	TRUE if bit = 0

    [/I:0/1]──────(O:0/0)
    When I:0/1 is FALSE, output O:0/0 energizes.
    Use for normally-closed contacts like stop buttons.

Coil Instructions (Outputs)¶

OTE — Output Energize¶

Symbol: ---( )--- — Standard output coil. Follows rung power state.

Rung TRUE	Rung FALSE
Sets bit to 1	Sets bit to 0

OTL — Output Latch¶

Symbol: ---(L)--- — Latching output. Sets bit when rung is TRUE, retains state when FALSE.

Rung TRUE	Rung FALSE
Sets bit to 1	No change

OTU — Output Unlatch¶

Symbol: ---(U)--- — Unlatching output. Clears bit when rung is TRUE, retains when FALSE.

Rung TRUE	Rung FALSE
Sets bit to 0	No change

Tip

Use OTL/OTU pairs for seal-in (latch) logic. OTL sets the bit and it stays set until an OTU clears it.

Timer Instructions¶

Timers use the T: memory region and operate in milliseconds.

TON — Timer On-Delay¶

Accumulates time while the rung is TRUE. Resets when the rung goes FALSE.

    ──[ I:0/0 ]──[TON T:0 PRE:5000]──
    ──[ T:0.DN ]──( O:0/0 )──

The LED turns on 5 seconds after the button is pressed.

TOF — Timer Off-Delay¶

Starts timing when the rung transitions from TRUE to FALSE. Resets when rung goes TRUE again.

RTO — Retentive Timer¶

Accumulates time while the rung is TRUE. Does not reset when the rung goes FALSE — must be reset with a RES instruction.

Counter Instructions¶

Counters use the C: memory region.

CTU — Count Up¶

Increments C:x.ACC on each FALSE→TRUE rung transition. Sets C:x.DN when ACC ≥ PRE.

CTD — Count Down¶

Decrements C:x.ACC on each FALSE→TRUE rung transition. Sets C:x.DN when ACC ≥ PRE (use with CTU for up/down counting).

RES — Reset¶

Resets a Timer or Counter:

Timer: Clears ACC, DN, TT, EN bits
Counter: Clears ACC, DN, OV, UN bits

Compare Instructions (Inputs)¶

All compare instructions read from N: integer addresses and pass or block rung power.

Instruction	Symbol	Passes Power When
EQU	`[A = B]`	Source A = Source B
NEQ	`[A ≠ B]`	Source A ≠ Source B
GRT	`[A > B]`	Source A > Source B
GEQ	`[A ≥ B]`	Source A ≥ Source B
LES	`[A < B]`	Source A < Source B
LEQ	`[A ≤ B]`	Source A ≤ Source B

Math Instructions (Outputs)¶

All math instructions execute when the rung is TRUE and store results in N: addresses.

Instruction	Operation	Formula
ADD	Addition	Dest = A + B
SUB	Subtraction	Dest = A − B
MUL	Multiplication	Dest = A × B
DIV	Division	Dest = A ÷ B
MOD	Modulo	Dest = A mod B
NEG	Negate	Dest = −Source
ABS	Absolute value	Dest = \|Source\|
MOV	Move	Dest = Source
SCL	Scale	Dest = (Source − InMin) × (OutMax − OutMin) ÷ (InMax − InMin) + OutMin

Warning

Division by zero sets the result to 0 and does not fault the engine.

Bitwise Instructions (Outputs)¶

Operate on N: integer values at the bit level.

Instruction	Operation
BAND	Bitwise AND
BOR	Bitwise OR
BXOR	Bitwise XOR
BNOT	Bitwise NOT
BSL	Bit Shift Left
BSR	Bit Shift Right

Conversion Instructions¶

Instruction	Operation
N2B	Number to Bits — writes an integer word to a bit region

Scheduling Instructions (Inputs)¶

Scheduling instructions trigger based on the system clock. They do not use PLC memory addresses.

SCHD — Scheduled Input¶

Triggers TRUE for one scan when the system date/time matches the configured target (minute precision).

    ──[SCHD 2025-06-15T08:00]──( O:0/0 )──
    Output energizes for one scan at 8:00 AM on June 15, 2025.

Use for one-time scheduled events, maintenance reminders, or timed triggers.

WSCH — Weekly Scheduled Input¶

Triggers TRUE for one scan when the current day-of-week and time-of-day match. Supports selecting multiple days via a bitmask (Sun=0, Mon=1, ..., Sat=6).

    ──[WSCH Mon,Wed,Fri 18:00]──( O:0/0 )──
    Output energizes for one scan at 6:00 PM on Mon/Wed/Fri.

Use for recurring weekly schedules like maintenance tasks or shift changes.

Date Comparison Instructions (Inputs)¶

Date comparison instructions compare the system's current date against a target date. They use date-only comparison (time is ignored). Unlike SCHD, WSCH, and INTERVAL (which are one-shot), date comparisons evaluate continuously — they pass power on every scan where the condition is true.

Instruction	Symbol	Passes Power When
DATE<	`[DATE< target]`	Current date < target
DATE<=	`[DATE<= target]`	Current date ≤ target
DATE=	`[DATE= target]`	Current date = target
DATE>=	`[DATE>= target]`	Current date ≥ target
DATE>	`[DATE> target]`	Current date > target

    ──[DATE>= 2025-01-01]──( O:0/0 )──
    Output energizes from January 1, 2025 onward.

Use for seasonal operations, expiration checks, or scheduled maintenance windows.

Interval Instruction (Input)¶

INTERVAL — Timed Interval¶

Triggers TRUE for one scan at periodic intervals. Uses the V: (Interval) memory region for persistent state that survives PLC restarts.

Property	Value
Address	V:x
Parameters	Days (0–365), Hours (0–23), Minutes (0–59)

    ──[INTERVAL V:0 0d 0h 15m]──( O:0/0 )──
    Output energizes for one scan every 15 minutes.

    ──[INTERVAL V:1 2d 0h 0m]──( O:0/1 )──
    Output energizes for one scan every 2 days.

Use for log rotation, backup schedules, periodic sampling, or maintenance reminders.

Instruction Icons¶

PiPLC includes SVG icons for all instructions, visible in the instruction palette and on the ladder diagram. See the resources/icons/instructions/ directory for the full set.