Skip to content

Tag

pyrung.core.tag

Tag definitions for the immutable PLC engine.

Tags are lightweight references to values in SystemState. They carry type metadata but hold no runtime state.

TagType

Bases: Enum

Data types for tags (IEC 61131-3 naming).

MappingEntry dataclass

Logical-to-hardware mapping declaration used by TagMap.

Tag dataclass

A reference to a value in SystemState.

Tags define what a value is (name, type, behavior) but hold no runtime state. Values live only in SystemState.tags.

Attributes:

Name Type Description
name str

Unique identifier for this tag.
type TagType

Data type (BOOL, INT, DINT, REAL, WORD, CHAR).
default Any

Default value (None means use type default).
retentive bool

Whether value survives power cycles.

value property writable 

value: Any

Read or write this tag's value through the active runner scope.

Returns the current value as seen by the runner, including any pending patches or forces. Writes are staged as one-shot patches consumed at the next step().

Raises:

Type Description
RuntimeError

If called outside with runner.active(): ....
Example 
runner = PLCRunner(logic)
with runner.active():
    print(StartButton.value)    # read current value
    StartButton.value = True    # queue for next scan

map_to 

map_to(target: Tag) -> MappingEntry

Create a logical-to-hardware mapping entry.

as_value 

as_value() -> Any

Wrap this tag for text->numeric character-value conversion.

as_ascii 

as_ascii() -> Any

Wrap this tag for text->numeric ASCII-code conversion.

as_text 

as_text(
    *,
    suppress_zero: bool = True,
    pad: int | None = None,
    exponential: bool = False,
    termination_code: int | str | None = None,
) -> Any

Wrap this tag for numeric->text conversion.

as_binary 

as_binary() -> Any

Wrap this tag for numeric->text binary-copy conversion.

LiveTag dataclass

Bases: Tag

Tag with runner-bound staged value access via .value.

LiveTag is the concrete type returned by all IEC constructor functions (Bool, Int, Dint, Real, Word, Char) and by block indexing. It extends Tag with the .value property, which provides read/write access to the current runner state.

Note

.value requires an active runner scope. Access outside with runner.active(): ... raises RuntimeError.

ImmediateRef dataclass

Reference to the immediate (physical) value of an I/O tag.

Wraps an InputTag or OutputTag to access the physical I/O value directly, bypassing the scan-cycle image table.

tag property 

tag: Tag

Backward-compatible alias for tag-wrapped immediate operands.

InputTag dataclass

Bases: Tag

Tag representing a physical input channel.

InputTag instances are produced exclusively by indexing an InputBlock. They add the .immediate property for bypassing the scan-cycle image table.

.immediate semantics by context:

  • Simulation (pure): validation-time annotation only; no runtime effect.
  • Click dialect: transcription hint for Click software export.
  • CircuitPython dialect: generates direct hardware-read code.
  • Hardware-in-the-loop: triggers a real hardware read mid-scan.

You cannot create an InputTag directly; use InputBlock[n] instead.

Example 
X = InputBlock("X", TagType.BOOL, 1, 16)
sensor = X[3]          # LiveInputTag
sensor.immediate       # ImmediateRef — bypass image table

immediate property 

immediate: ImmediateRef

Return an ImmediateRef that bypasses the input image table.

OutputTag dataclass

Bases: Tag

Tag representing a physical output channel.

OutputTag instances are produced exclusively by indexing an OutputBlock. They add the .immediate property for bypassing the scan-cycle image table.

.immediate semantics by context:

  • Simulation (pure): validation-time annotation only; no runtime effect.
  • Click dialect: transcription hint for Click software export.
  • CircuitPython dialect: generates direct hardware-write code.
  • Hardware-in-the-loop: triggers a real hardware write mid-scan.

You cannot create an OutputTag directly; use OutputBlock[n] instead.

Example 
Y = OutputBlock("Y", TagType.BOOL, 1, 16)
valve = Y[1]           # LiveOutputTag
valve.immediate        # ImmediateRef — bypass image table

immediate property 

immediate: ImmediateRef

Return an ImmediateRef that bypasses the output image table.

LiveInputTag dataclass

Bases: LiveTag, InputTag

InputTag with runner-bound staged value access via .value.

LiveOutputTag dataclass

Bases: LiveTag, OutputTag

OutputTag with runner-bound staged value access via .value.

Bool dataclass

Bases: _TagTypeBase

Create a BOOL (1-bit boolean) tag.

Not retentive by default — resets to False on power cycle.

Example 
Button = Bool("Button")
Light  = Bool("Light", retentive=True)

Int dataclass

Bases: _TagTypeBase

Create an INT (16-bit signed integer, −32768 to 32767) tag.

Retentive by default — survives power cycles.

Example 
Step     = Int("Step")
preset = Int("preset", retentive=False)

Dint dataclass

Bases: _TagTypeBase

Create a DINT (32-bit signed integer, ±2 147 483 647) tag.

Retentive by default. Use for counters or values that exceed INT range.

Example 
TotalCount = Dint("TotalCount")

Real dataclass

Bases: _TagTypeBase

Create a REAL (32-bit IEEE 754 float) tag.

Retentive by default. Use for analog presets and process values.

Example 
Temperature = Real("Temperature")
FlowRate    = Real("FlowRate", retentive=False)

Word dataclass

Bases: _TagTypeBase

Create a WORD (16-bit unsigned integer, 0x0000–0xFFFF) tag.

Retentive by default. Use for bit-packed status registers or hex values. In the Click dialect, Hex is an alias for Word.

Example 
StatusWord = Word("StatusWord")

Char dataclass

Bases: _TagTypeBase

Create a CHAR (8-bit ASCII character) tag.

Retentive by default. Use for single-character text values. For multi-character strings, use a Block of CHAR tags. In the Click dialect, Txt is an alias for Char.

Example 
ModeChar = Char("ModeChar")

immediate 

immediate(
    value: Tag | BlockRange | ImmediateRef,
) -> ImmediateRef

Wrap a tag or block range as an immediate operand.