Skip to content

Instructions API

Tier: Stable Core

Domain objects for ladder logic instructions.

laddercodec.Contact dataclass

Bases: ConditionInstruction

A contact instruction (NO or NC).

from_csv_token classmethod 

from_csv_token(token: str) -> Contact

Parse NO/NC/immediate forms plus edge forms rise(...)/fall(...).

Also accepts wire-down prefix: T:X001, T:rise(X002).

cell_params 

cell_params() -> dict

Return ClickCell kwargs intrinsic to this instruction.

build_blob 

build_blob() -> bytes

Build the instruction data blob for this contact cell.

laddercodec.CompareContact dataclass

Bases: ConditionInstruction

A comparison contact (EQ, NE, GT, LT, GE, LE).

Occupies a condition column. The binary class name is Compare (type marker 0x2714).

from_csv_token classmethod 

from_csv_token(token: str) -> CompareContact

Parse DS1==1, DS2>=DS3, etc.

Also accepts wire-down prefix: T:DS1==1.

cell_params 

cell_params() -> dict

Return ClickCell kwargs intrinsic to this instruction.

build_blob 

build_blob() -> bytes

Build the instruction data blob for this compare contact cell.

laddercodec.Coil dataclass

Bases: AfInstruction

An output coil instruction.

from_csv_token classmethod 

from_csv_token(token: str) -> Coil

Parse coil forms with inner immediate wrapper and ranges.

cell_params 

cell_params() -> dict

Return ClickCell kwargs intrinsic to this instruction.

build_blob 

build_blob() -> bytes

Build the instruction data blob for this coil cell.

laddercodec.Timer dataclass

Bases: AfInstruction

A timer instruction (on_delay / off_delay).

Occupies the AF column. The binary class name is Tmr (type marker 0x2718). Each timer rung adds an extra grid row for the timer's visual height.

enable_func_code property 

enable_func_code: str

Compute the enable func_code: base + offset.

reset_func_code property 

reset_func_code: str

Compute the reset func_code (retentive only; "0" otherwise).

from_csv_token classmethod 

from_csv_token(token: str) -> Timer

Parse v1 timer: on_delay(T1,TD1,preset=1000,unit=Tms).

Positional: done_bit, current. Kwargs: preset, unit. Retained is never in the CSV — it's set by .reset() pin presence.

cell_params 

cell_params() -> dict

Return ClickCell kwargs intrinsic to this instruction.

build_blob 

build_blob() -> bytes

Build the instruction data blob for this timer cell.

laddercodec.Counter dataclass

Bases: AfInstruction

A counter instruction (count_up / count_down).

from_csv_token classmethod 

from_csv_token(token: str) -> Counter

Parse v1 counter: count_up(CT1,CTD1,preset=100).

build_blob 

build_blob() -> bytes

Build the instruction data blob for this counter cell.

laddercodec.Copy dataclass

Bases: AfInstruction

A single copy instruction.

Attributes

source: Source operand or literal (e.g. "DS7", "42", "3.14"). destination: Destination operand (e.g. "DS8"). format: Copy modifier — "none", "value", "text", "binary", or "ascii". oneshot: Execute once on OFF→ON transition. suppress_zero: Text option — "0" (don't suppress) or "1" (suppress). exponential: Text option — "0" (real) or "1" (exponential). termination_code: Text option — "0" (none) or "$HH" hex ASCII code (e.g. "$13" for 0x13).

from_csv_token classmethod 

from_csv_token(token: str) -> Copy

Parse copy(source, dest) with optional convert=to_* modifier.

Examples::

copy(DS7,DS8)
copy(42,DS9)
copy(DS26,DS27,oneshot=1)
copy(TXT1,DS10,convert=to_value)
copy(DS12,TXT2,convert=to_text(suppress_zero=1,exponential=0,termination_code=none))

cell_params 

cell_params() -> dict

Return ClickCell kwargs intrinsic to this instruction.

build_blob 

build_blob() -> bytes

Build the instruction data blob for this copy cell.

laddercodec.BlockCopy dataclass

Bases: AfInstruction

A block copy instruction (copy_type_idx=1).

Copies a contiguous range of source registers to a destination range.

Attributes

source_start, source_end: Source range (e.g. "DS28" .. "DS31"). dest_start, dest_end: Destination range. format: "none" or "value" (convert to numeric value). oneshot: Execute once on OFF→ON transition.

cell_params 

cell_params() -> dict

Return ClickCell kwargs intrinsic to this instruction.

build_blob 

build_blob() -> bytes

Build the instruction data blob for this block copy cell.

laddercodec.Fill dataclass

Bases: AfInstruction

A fill instruction (copy_type_idx=2).

Fills a contiguous range of destination registers with a single value.

Attributes

value: Source value — literal ("0") or tag ("DS56"). dest_start, dest_end: Destination range. oneshot: Execute once on OFF→ON transition.

cell_params 

cell_params() -> dict

Return ClickCell kwargs intrinsic to this instruction.

build_blob 

build_blob() -> bytes

Build the instruction data blob for this fill cell.

laddercodec.Pack dataclass

Bases: AfInstruction

A pack instruction (copy_type_idx=3).

Packs a range of source registers into a single destination.

Attributes

source_start, source_end: Source range (e.g. "C108" .. "C123"). destination: Destination operand (e.g. "DS167"). pack_type: "bits", "words", or "text". allow_whitespace: Text option — allow whitespace in text packing. oneshot: Execute once on OFF→ON transition.

laddercodec.Unpack dataclass

Bases: AfInstruction

An unpack instruction (copy_type_idx=4).

Unpacks a single source into a range of destination registers.

Attributes

source: Source operand (e.g. "DS172"). dest_start, dest_end: Destination range (e.g. "C128" .. "C143"). unpack_type: "bits" or "words". oneshot: Execute once on OFF→ON transition.

laddercodec.Shift dataclass

Bases: AfInstruction

A shift register instruction.

from_csv_token classmethod 

from_csv_token(token: str) -> Shift

Parse shift(C99..C106).

build_blob 

build_blob() -> bytes

Build the instruction data blob for this shift register.

laddercodec.Search dataclass

Bases: AfInstruction

A search instruction.

Attributes

table_start: Start of search table (e.g. "DS72"). table_end: End of search table (e.g. "DS81"). source: Value to search for — register ("DS71") or literal ("A"). result: Destination register for the result index. found: Found flag bit (e.g. "C81"). comparison: Comparison operator: "==", "!=", ">", "<", ">=", "<=". continuous: Search continuously (every scan). oneshot: Execute once on OFF→ON transition.

laddercodec.Drum dataclass

Bases: AfInstruction

A drum sequencer instruction (event_drum / time_drum).

Occupies the AF column. The binary class name is Drum (type marker 0x271B). Each drum rung takes 4 grid rows: row 0 = main, row 1 = reset, row 2 = jump, row 3 = jog.

build_blob 

build_blob() -> bytes

Build the instruction data blob for this drum cell.

laddercodec.Math dataclass

Bases: AfInstruction

A math instruction.

Attributes

expression: The formula in Click syntax (e.g. "DS65 + DS66"). Spaces around operators, uppercase function names. result: Destination register (e.g. "DS67"). mode: "decimal" or "hex". oneshot: Execute once on OFF→ON transition.

laddercodec.Call dataclass

Bases: AfInstruction

Subroutine call instruction.

laddercodec.Return dataclass

Bases: AfInstruction

Return instruction.

laddercodec.End dataclass

Bases: AfInstruction

Program terminator instruction.

laddercodec.ForLoop dataclass

Bases: AfInstruction

FOR loop instruction.

laddercodec.Next dataclass

Bases: AfInstruction

NEXT loop instruction.

laddercodec.Send dataclass

Bases: AfInstruction

A Modbus Send (SD) instruction.

laddercodec.Receive dataclass

Bases: AfInstruction

A Modbus Receive (RD) instruction.

laddercodec.ModbusAddress dataclass

Non-CLICK remote address (MODBUS 984 or hex).

laddercodec.ModbusRtuTarget dataclass

RTU serial target.

laddercodec.ModbusTcpTarget dataclass

TCP/IP target.

laddercodec.RawInstruction dataclass

Bases: AfInstruction

Opaque AF instruction — blob preserved for byte-exact round-trip.

Attributes

class_name: Binary class name (e.g. "Copy", "Cnt"). Extracted from the blob for CSV readability; also present inside blob. blob: Full instruction blob bytes (from cell offset +0x25 to the end of tagged fields, excluding tail and af_summary). part_count: Number of parts (1 = single-row, >1 = multi-row). Derived from the blob during construction.

cell_params 

cell_params() -> dict

Return ClickCell kwargs intrinsic to this instruction.

build_blob 

build_blob() -> bytes

Return the raw blob bytes (no-op — already stored).

to_csv 

to_csv() -> str

Serialize to decoded-fields raw(ClassName,0xTTTT,N,...) token.

Falls back to legacy hex format if decomposition fails.

from_csv_token classmethod 

from_csv_token(token: str) -> RawInstruction

Parse a raw CSV token (decoded-fields or legacy hex).

Decoded-fields format::

raw(ClassName,0xTTTT,N,field_specs...)

Legacy hex format::

raw(ClassName,hex_blob)