laddercodec 0.1.5

Binary codec for AutomationDirect CLICK PLC ladder clipboard format

laddercodec

Binary codec for AutomationDirect CLICK PLC ladder clipboard format. Encodes and decodes the native clipboard binary used by CLICK Programming Software. Tested against v2.60-v3.9x captures. Zero runtime dependencies.

• Documentation: https://ssweber.github.io/laddercodec/
• LLM docs index: https://ssweber.github.io/laddercodec/llms.txt
• LLM full context: https://ssweber.github.io/laddercodec/llms-full.txt

Install

uv add laddercodec
# or
pip install laddercodec

Requires Python 3.11+.

Quick example

from laddercodec import read_csv, encode, decode

# CSV → binary (ready to paste into Click)
rungs = read_csv("my_rung.csv")
binary = encode(rungs[0])

# Binary → structured data
rung = decode(binary)
print(rung.logical_rows)
print(rung.instructions)

What's included

Encoder — encode() takes Rung objects or canonical CSV and produces clipboard binary ready to paste into Click. Supports all standard instruction types, wire topologies, and styled comments.

Decoder — decode() reads clipboard binary back into structured Python objects (contacts, coils, timers, wires, comments). decode_program() reads Click's internal Scr*.tmp program files.

CSV I/O — read_csv() and write_csv() convert between the 33-column canonical CSV format and Rung objects. Multi-file program bundles supported.

Binary format docs — Byte-level reverse engineering of Click's clipboard and program file formats: buffer layout, cell grid, wire flags, instruction blobs, and multi-rung framing.

Status

laddercodec is beta for clipboard encode/decode, CSV I/O, and decode_program().

Email, Home, Position, and Velocity still intentionally surface as raw(...) passthroughs so binary and SCR round-trips stay lossless while those families remain opaque.

Learn more

Quickstart	Encode, decode, and round-trip your first rung
Encoding guide	Build rungs, wire tokens, instruction types, comments
Decoding guide	Structured decode, program files, round-trip identity
CSV format	33-column canonical format, bundle layout, topology rules
Adding instructions	Extend the codec with new instruction types
API reference	Auto-generated from docstrings

Development

make install        # uv sync --all-extras --dev
make test           # pytest
make lint           # ruff + ty
make golden         # regenerate .bin from .csv fixtures
make docs-serve     # local docs dev server
make                # all of the above

License

MPL-2.0