Adding New Instruction Types¶
Quick workflow¶
This shows every instruction in the capture: known types display their model + to_csv() output, while RawInstruction and UnknownInstruction show a full tagged-field breakdown with tag IDs, sentinel types, and values.
From the inspect output you'll see one of two cases:
- RawInstruction — blob structure parsed, but no supported model matched yet. This can mean:
- a new variant of an existing instruction class, or
- an entirely new instruction class name
- UnknownInstruction — blob boundary could not be parsed cleanly (truncated/novel layout); inspect raw bytes before modeling
Tip: use the reported class='...' value. If the class name is already registered, you're likely adding a new variant; if it's new, you're likely adding a new instruction type.
Note: Email, Home, PositionMove, and VelocityMove are currently known enough
to round-trip, but they still intentionally surface as raw(...) passthroughs
until dedicated typed DSL models are added.
Base classes¶
All instruction dataclasses inherit from one of two base classes in model.py:
Condition— condition-side (Contact, CompareContact)Instruction— AF-side (Coil, Timer, Copy, BlockCopy, Fill, RawInstruction)
Both declare to_csv(), build_blob(), and cell_params() stubs. The pipeline uses these base classes for isinstance dispatch, so new instruction types that inherit from the right base class are automatically recognized by the encoder, decoder, grid builder, and CSV writer.
In addition, each instruction family module now exposes a small family spec in src/laddercodec/instructions/family.py. That spec is the shared source of truth for:
- binary class names
- CSV token names
- CSV call parsing
- supported pin names
For most new instruction families, the main extension point is: add the dataclass + codec logic in the family module, then register a SPEC for it.
Case 1: New variant of existing instruction¶
Example: adding oneshot to the Out coil (func code 8205, field[2] = "-1").
1. Read the field breakdown¶
[0][AF] RawInstruction class='Out'
csv: raw(Out,0x2715,1,rows=1,sub=1,6066=Y001,6067=,11f8=-1,11f5=0,3218=8205,0000=)
class: 'Out'
type_marker: 0x2715
field[0]: tag=0x6066 (std) value='Y001' # operand
field[1]: tag=0x6067 (std) value='' # range_end
field[2]: tag=0x11F8 (std) value='-1' # oneshot ← new
field[3]: tag=0x11F5 (std) value='0' # immediate
field[4]: tag=0x3218 (std) value='8205' # func_code ← new
field[5]: tag=0x0000 (std) value=''
Compare against existing field values (field[2] is normally "0", func code is normally "8193" for basic out). The diff tells you exactly what changed.
2. Update the instruction module¶
In src/laddercodec/instructions/<module>.py:
- Add the new func code to the lookup table
- Add any new fields to the dataclass (e.g.
oneshot: bool = False) - Update
build_blob()to emit the new field value - Update
to_csv()to include the new parameter. A flag kwarg is written only when set (oneshot=1, neveroneshot=0); value kwargs such asmode=andunit=are always written - Update
from_tags()to extract the new field from the func code table
If the new variant shares a class name with an existing family (CLICK v4's toggle,
debounce, flasher and timed are all class Out, type 0x2715), the existing family's
from_tags() must return None for func codes it doesn't know. Otherwise the variant
decodes silently as the old instruction. from_tags() dispatch tries every family in
turn, so the new family can set binary_class_names=() and leave the class name's
registry entry to the existing one (see out_variant.py).
3. Update the CSV-facing parse path¶
If the variant is covered by an existing family spec, update the family module's CSV parsing path rather than adding a new central converter branch. For example, extend from_csv_token() or the family's parse_af_call() hook so the new kwarg is understood:
from ..operands.checks import check_csv_flag
oneshot = check_csv_flag(call.kwargs, "oneshot", "Coil.oneshot")
return Coil(..., oneshot=oneshot)
Read a flag keyword with check_csv_flag: it takes 1 or 0 and reads an absent one
as off. It refuses a blank one as missing, and any other text as no flag, each with a
FieldError that names the field. A plain == "1" would read oneshot=2 as off without
a word.
4. Update the coverage CSV¶
The coverage fixture at tests/fixtures/coverage/golden/<rung_id>.csv should already exist for the variant. Verify the CSV token matches what your to_csv() produces (e.g. out(C47,oneshot=1)). Boolean flags use kwargs style: oneshot=1, not wrapper style.
5. Verify¶
Case 2: Entirely new instruction type¶
1. Read the field breakdown¶
Same as above. For new types, inspect will often show RawInstruction with a new class name (for example class='End'). UnknownInstruction is less common and usually means the blob format itself wasn't parsed cleanly. The inspect output shows the blob structure — class name, type marker, part count, field count, all tagged fields.
2. Create instruction module¶
In src/laddercodec/instructions/:
- New
@dataclassinheriting fromInstruction(orCondition) - Implement
to_csv(),build_blob(),cell_params(), and a module-levelfrom_tags() - Follow existing modules (coil.py, timer.py, copy.py) as templates
- Add
InstructionTypeenum value inmodel.pyif it uses a new type marker
Tall instructions: if the new instruction occupies more than 1 grid row in the binary/editor shape, return {"visual_rows": N} from cell_params().
The converter pads a tall box with blank rows from cell_params().
visual_rows sets both cell header bytes, +0x09 (rows spanned) and +0x0A
(sub-rows). When a native capture shows them differing, add "sub_rows" for
+0x0A: CLICK v4's timed coil spans 2 rows but writes 3 ({"visual_rows": 2, "sub_rows": 3}).
A fixed-height family must also set cell_params_from_tags on its SPEC (fixed_cell_params() in family.py, reading the same table as cell_params()); otherwise a raw(...) box of the family read from CSV gets 1 row.
Reading tags in from_tags(): Click's program files (Scr*.tmp) leave out every
tag at its default value, so a tag can be missing even though the clipboard always
has it. Read tags through the helpers in binary_helpers.py, never tags.get() with
a hand-picked fallback:
tag_value(tags, 0x6066)— a value tag, or its default when absenttag_int(tags, 0x21F9)— a numeric tag as aninttag_flag(tags, 0x1201)— a flag tag (0x11xx/0x12xx): set when present
The default is "" for string tags and "0" for numeric ones. A tag whose default is
something else goes in _TAG_DEFAULTS (or _CLASS_TAG_DEFAULTS), backed by a native
SCR + clipboard pair showing SCR leave it out at that value. The func code (0x3218)
is the exception: SCR leaves it out whenever the class and other fields determine it,
so each family derives it. tests/test_instruction_defaults.py checks the tables
against every native SCR + clipboard pair in the fixtures, then drops every default
tag from each fixture instruction and expects it to decode unchanged. When a new
SCR capture fails the first check, uv run devtools/scr_defaults_survey.py
--mismatches names the tag and the value SCR left out.
Also add a family SPEC in the module:
binary_class_namescsv_namesfrom_tagsparse_csv_call(for AF families)pin_namesif the family uses dot-prefixed continuation rowscell_params_from_tagsif every box of the family has one height (a raw box read from CSV takes it)
3. Register and export¶
| File | What to update |
|---|---|
instructions/__init__.py |
Register the family SPEC in AF_FAMILY_SPECS or CONDITION_FAMILY_SPECS, and re-export the new class |
__init__.py |
Re-export the new class in the public API |
tests/test_public_api.py |
Add the class to EXPECTED_ROOT_EXPORTS, which pins the root __all__ |
docs/gen_reference.py |
Add the class to the Instructions API page; make docs-build fails on an unlisted export |
KNOWN_AF_NAMES is now derived from the registered family specs, so csv/ast.py does not need manual token updates.
Thanks to the base classes and family specs, encode.py, _grid.py, devtools/inspect_bin.py, and most of the CSV token dispatch need no changes.
4. Update family CSV parsing if needed¶
For AF instructions, make sure the family SPEC can parse the CSV call:
- add the CSV token name to
csv_names - implement or extend
parse_csv_call - handle positional args and kwargs there
5. Update CSV writer¶
If the instruction has only generic blank padding, the existing tall-instruction stripping usually works automatically.
If the instruction has semantic lower rows or pins (like timers, counters, shifts, or drums), update csv/writer.py and possibly csv/converter.py to handle the reverse row-shaping explicitly.
6. Update coverage CSV and verify¶
Add tests/fixtures/coverage/golden/<rung_id>.csv files covering all variants.
Coverage testing¶
Coverage golden fixtures live in tests/fixtures/coverage/golden/. Each fixture is a hand-written CSV (<rung_id>.csv) paired with a generated binary (<rung_id>.bin).
Adding a fixture¶
- Create
tests/fixtures/coverage/golden/<rung_id>.csvby hand in the 33-column canonical format. Usually one rung per file; a file can hold several rungs (math__v4.csvholds 23) and is verified as one paste. - Run
make coverage-goldento generate the.binfrom the CSV. - Paste-verify in Click using
clicknick-rung guided. make test— each.csvwith a matching.bingets a parametrized test comparing encoded output to golden binaries, and fails if the fixture has noworkedentry in the directory'sverify_progress.log.
Regenerating coverage bins¶
Regenerates all .bin files from .csv sources and prunes the verify log for changed/deleted fixtures. Same workflow as make golden for ladder fixtures.
Smoke-testing combined fixtures¶
To quickly test multiple instruction types together in a single rung:
uv run devtools/combine_coverage.py # 4 random fixtures
uv run devtools/combine_coverage.py -n 6 # 6 random fixtures
uv run devtools/combine_coverage.py --seed 42 # reproducible pick
This picks N random coverage CSVs, stacks their data rows into one multi-row rung, and writes devtools/combined.csv + devtools/combined.bin for paste-testing.
Capturing from CLICK v4¶
New CLICK v4 instructions are captured in groups. The paste CSVs are built with
pyrung by scratchpad/click-v4/captures/v4_capture.py, whose README has the
CLICK-side steps and address map per group. Each rung's comment is its id, then
every AF token it should decode to, in row order:
Run clicknick against the local checkouts, so load encodes with the laddercodec
you are changing. From the clicknick directory:
make install-dev # editable ../pyclickplc, ../pyrung, ../laddercodec
UV_NO_SYNC=1 uv run --no-sync clicknick-rung load ../laddercodec/scratchpad/click-v4/captures/stubs/<group>.csv
# build each rung in CLICK as its comment says, copy them all back, then:
UV_NO_SYNC=1 uv run --no-sync clicknick-rung save ../laddercodec/scratchpad/click-v4/captures/copyback/<group>
A rung whose instruction laddercodec can't encode yet is pasted as a placeholder
(NOP, or a v3 instruction with 1 standing in for a blank or register preset);
its comment still names the target.
In laddercodec:
- Copy
scratchpad/click-v4/captures/copyback/<group>.bintotests/fixtures/v4_captures/.tests/test_v4_captures.pychecks every labelled rung: one still decoding asraw(...)is xfail, any other mismatch fails, and every capture must survivewrite_csv. - Map the fields of the raw blobs (
devtools/inspect_bin.py, or theraw(...)tokens in the saved CSV) and model the instruction until its rungs pass. - Add a test that re-encoding matches the blobs Click wrote, field for field
(see
test_out_variant_blobs_match_nativeandtest_time_event_drum_blobs_match_native). - For the encode side, copy
scratchpad/click-v4/captures/expected/<group>.csv(real tokens in the AF column) to a coverage golden<family>__v4.csv, runmake coverage-golden, and paste-verify it withclicknick-rung guided.
A typo made while building rungs in CLICK shows up as a failing rung, not an xfail. Fix the rung in CLICK and save again.
Clicknick compatibility¶
The clicknick-rung guided tool extracts operand addresses from CSV tokens for MDB provisioning. It uses to_csv() + regex to find address patterns, so new instruction types work automatically — no clicknick changes needed.