Initial site: landing page, blog posts, CI

Author: ssweber

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.9.25"
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install docs dependencies
+        run: uv sync --group docs
+
+      - name: Build docs
+        run: uv run mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/blog/these-arent-the-rungs.md

@@ -0,0 +1,62 @@
+# "These Aren't the Rungs You're Looking For"
+
+### How I reverse-engineered a PLC editor's clipboard format so my bytes could paste without any problems
+
+Ladder logic is the visual programming language for industrial controllers, rungs on a rail, each one a circuit that evaluates left to right: `|—[ Contact ]—( Output )|`. For years I haven't been able to test my CLICK PLC programs. I've got dozens of machines whose logic is stuck in an editor with no simulator, no scripting API, and no documented file format. So I built [pyrung](https://ssweber.github.io/pyrung/), a Python DSL where `with Rung(condition): instruction` maps directly to a ladder rung, meaning you can write logic in Python and test it with pytest.
+
+But I don't want to transpose after testing. The missing piece was getting rungs from Python into the CLICK editor without retyping them. There's no documented import format, but I found it does put ctrl-c rungs onto the clipboard in some binary format. Maybe I could figure it out. With an AI that could hold context across hex dumps and structural hypotheses, I decided to give it a go.
+
+Things started quickly and I thought it'd be a matter of days to figure out. Place bytes on the private clipboard, spoof the window handle so CLICK thought the paste came from itself, and write addresses to the project database so contacts wouldn't draw as blank placeholders. Done.
+
+The workflow that emerged was simple: a CSV file describing each rung's layout on CLICK's grid, a CLI tool that loaded them to the clipboard one by one and asked me whether it worked or crashed or came out wrong. We stored `.bin` files for each shape that captured the known-good bytes so we could diff against them later. Each new rung shape started as a native copy from CLICK and graduated when our synthetic bytes could paste without noticeable problems.
+
+## The Problem
+
+The first few shapes worked. CLICK accepted simple contacts & basic wires.
+
+Then we added instructions and that broke the rung. What should paste as one rung came back as multiple rungs with phantom `NOP` instructions jammed between them.
+
+The approach that had gotten us this far stopped working. Early on, byte diffing was all we could do. We didn't know the format so we captured native bytes, diffed against synthetic, and patched the differences one by one. Instructions introduced variable-length data and suddenly every new shape produced new differences. The AI built elaborate theories about each one, generated patch variants, ranked candidate bytes, and wrote handoff notes that read like desert island scribbles. The explanations were internally consistent and often wrong. I was learning hex as I went and the answer had to be simpler.
+
+I almost gave up, not because the problem was hard but because the approach didn't generalize. You can't diff your way to understanding a format.
+
+We needed a coherent model, so we went back to the basics. Stripped out contacts and instructions entirely and just got empty rungs working, then rungs with wires, then multi-row rungs. Byte 'close-enough' matches against native captures.
+
+## Stop Hex Diffing
+
+LLMs are *magnetically attracted* to hex diffs. Give an AI two binary files and it will compare them byte by byte, build elaborate theories about every difference, and confidently explain which offset controls what. The explanations sound great and they're often wrong.
+
+The cell grid has rigid structure: 0x40 bytes per cell when empty and 32 cells per row. But once we added content, the AI got confused. "The comment data is spilling over into column A." No it wasn't.
+
+It had built a complex model entirely from hex diffs: a 32-entry seed table, a continuation stream for overflow, shape-dependent seeding rules. We had a huge if/else chain encoder for some cases; elaborate, internally consistent, and mostly hallucination. The wrong model generated correct bytes for simple cases, so there was no reason to question it until extending it to multi-rung comments became impossible. I was about to remove comment support entirely.
+
+## Push, Push, Push
+
+The question that cracked it was simple: "Are we sure the comments aren't just an overlay that inserts and pushes things at known safe spots?" The AI initially argued no because the wire flag offsets were different between the two regions. I pushed back. The AI ran the math and every wire flag, every NOP byte, every linkage byte across all 63 flag positions mapped perfectly once you accounted for the displacement. The "mysterious offset shift" was a fixed constant. We didn't need the if/else chain. The cell grid had just been pushed forward by the comment payload.
+
+All that complexity simplified away. Each insight cascaded into the next because the AI could run the address math fast enough to keep up. The 32-entry header table turned out to be one entry plus a payload region. The "separator" between rungs turned out to be the next rung's preamble. The instruction "seed bytes" were just payload content at those addresses. The whole format collapsed to: ramp, dword, payload, grid. Repeat per rung.
+
+We'd been documenting what we saw in the hex rather than what produced it. Once we asked "what if there's only one structure that got displaced," everything fell into place.
+
+In code, it's two lines:
+
+```python
+struct.pack_into('<I', out, 0x0294, len(payload))
+out[0x0298:0x0298] = payload
+```
+
+Write the payload length as a dword, then slice-insert the payload at the boundary between the rung preamble and the cell grid:
+
+- Everything from 0x0298 onward shifts right by `len(payload)`
+- The cell grid, normally starting at 0x0A60, lands at 0x0A60 + payload length instead
+- No pointers to update, no offsets to rewrite, just insert and push
+
+## The Mind Trick
+
+We place our bytes on the clipboard under the private format. CLICK reads them back, checks whatever it checks, and renders a rung. A rung we wrote in Python, from a CSV, that never touched the editor until this moment.
+
+*These are perfectly normal rungs I copied myself.*
+
+---
+
+*The work described here lives in two repos: [clicknick](https://github.com/ssweber/clicknick) (clipboard glue, live verification) and [laddercodec](https://github.com/ssweber/laddercodec) (the binary codec). The reverse engineering ran from March 2–24, 2026, across roughly 200 commits, with a human doing the pasting and an AI doing the byte analysis. The format remains undocumented by its creator. Our encoder doesn't mind.*

docs/blog/why-pyrung.md

@@ -0,0 +1,59 @@
+# Why pyrung? A look at what else is out there
+
+## The big vendors have simulators. Click doesn't.
+
+Siemens has S7-PLCSIM. Allen-Bradley has the RSLogix Emulator. Beckhoff has TwinCAT's simulation manager. CODESYS has a built-in simulation mode and a paid Test Manager add-on. Even within AutomationDirect's own lineup, the Do-more and Productivity PLCs have software simulators built into their free programming tools.
+
+The Click PLC has none. AutomationDirect sells physical input simulator modules, toggle switches and potentiometer boards, but no software simulation. You write ladder in Click Programming Software, download to hardware, and test it there. If you don't have the hardware, you wait.
+
+## An emerging trend: people want more than GUI-only PLC programming
+
+For decades, PLC programming has meant vendor-specific graphical IDEs. You draw ladder in the vendor's editor, download to hardware, and hope. That's starting to change.
+
+For Structured Text, the vendor story is already meaningful. CODESYS has simulation, a Test Manager, Python scripting, and a unit testing framework (CoUnit). Beckhoff TwinCAT gives ST developers full Visual Studio integration with unit testing via TcUnit. Running a CODESYS soft PLC and driving tests from pytest over OPC-UA is an emerging pattern, though it amounts to integration testing against a running process rather than deterministic simulation of the logic itself. If your world is ST on those platforms, you're reasonably well served.
+
+Beyond the vendor ecosystems, independent projects are pushing further. [rungs.dev](https://rungs.dev/) is a browser-based ladder logic and ST editor with real-time simulation and an integrated test runner with deterministic, isolated scan cycles. It targets Allen-Bradley style (XIC/XIO/OTE, Add-On Instructions) and is the closest thing in spirit to pyrung's test-first philosophy, arriving from a completely different direction.
+
+Open-source PLC platforms like **OpenPLC** and **Beremiz** are full IEC 61131-3 environments with graphical editors, simulation modes, and multiple target hardware platforms. They're serious engineering, but they're PLC *replacements*, not test-first development tools for an existing vendor's hardware.
+
+## The ladder-as-text problem
+
+The pattern across all of this is clear: **people who want text go to Structured Text, and people who want ladder stay graphical.** The IEC standard positions ST as the text-based option. The CODESYS/Beckhoff ecosystem is investing heavily in that direction.
+
+But ladder remains the dominant language in North American discrete manufacturing, especially on platforms like Click, Do-more, and Allen-Bradley. Those users are stuck in proprietary graphical editors with no version control, no automated testing, and often no simulation. The ST crowd has options. The ladder crowd doesn't.
+
+The few Python projects that have tried to represent ladder, [pyladdersim](https://github.com/akshatnerella/pyladdersim) being the most visible, model rungs as flat lists of component objects:
+
+```python
+rung = Rung([Contact("Start"), InvertedContact("Stop"), Output("Lamp")])
+```
+
+The structure that makes ladder readable is lost. The idea of a proper text-based ladder with testability has been [floating around since at least 2000](https://mail.python.org/pipermail/python-list/2000-March/049350.html), but nobody shipped it. A CODESYS Forge user [asked for ladder scripting in Python in 2017](https://forge.codesys.com/forge/talk/Engineering/thread/fdc3d03c95/); the answer was "You can't do Ladder with Scripting."
+
+## What pyrung does differently
+
+```python
+with Program() as logic:
+    with Rung(Start, ~Stop):
+        out(Motor)
+    with Rung(Fault):
+        reset(Motor)
+```
+
+Condition on the rail, instruction in the body. The `with` block naturally separates "when this is true" from "do this," which is exactly what a ladder rung does. It reads like the diagram, runs as a deterministic scan cycle, and targets real Click PLC behavior faithfully.
+
+**The code looks like ladder.** Not Structured Text. Not flat lists. Not ASCII art. The DSL preserves the condition/instruction structure that makes ladder readable, in code a controls engineer can map to the diagram they already know.
+
+**You can watch it evaluate.** A full DAP-protocol VS Code debugger steps through scans rung by rung. Breakpoints on rungs, inline tag updates, force values, diff between scans, time-travel through history.
+
+**It targets real hardware faithfully.** Nearly the complete Click instruction set, memory banks, numeric quirks, scan-cycle semantics. If your program behaves differently in pyrung than on a Click PLC, that's a bug.
+
+**It deploys without transposing.** pyrung compiles to two backends from the same tested source. For Click, [laddercodec](https://github.com/ssweber/laddercodec) encodes your rungs into the bytes the CLICK editor expects on paste. For the ProductivityOpen P1AM-200, pyrung generates a self-contained CircuitPython scan loop that runs directly on the hardware with the same Modbus TCP interface as a Click. Write once, test once, deploy to either.
+
+## Where pyrung fits
+
+The emerging tools above are vendor-agnostic by design. rungs.dev runs in a browser. OpenPLC replaces the vendor stack entirely.
+
+pyrung chose fidelity over generality, because the whole point is to test before you deploy to a specific PLC. But fidelity to Click behavior doesn't mean fidelity to Click hardware alone. The same logic that simulates faithfully against Click's instruction set can also compile to CircuitPython and run on open hardware with no proprietary toolchain in the path. That combination, faithful simulation of a real vendor's behavior plus deployment to hardware the vendor doesn't control, is something none of the tools above attempt.
+
+The ladder-as-text problem has been open for 25 years. pyrung is a serious attempt at closing it.

docs/index.md

@@ -0,0 +1,71 @@
+# Ladder as Text
+
+```python
+from pyrung import Bool, Program, Rung, latch, reset
+
+Start = Bool("Start")
+Stop = Bool("Stop")
+Motor = Bool("Motor")
+
+with Program() as logic:
+    with Rung(Start):
+        latch(Motor)
+    with Rung(Stop):
+        reset(Motor)
+```
+
+That's a ladder rung. Condition on the `Rung`, instruction in the body. It reads like the diagram, runs as a deterministic scan cycle, tests with pytest, and compiles to real hardware.
+
+Ladder logic dominates North American discrete manufacturing, but the tooling hasn't kept up. No version control, no automated testing, no way to simulate without hardware. The Structured Text crowd has options. The ladder crowd doesn't.
+
+## pyrung
+
+[pyrung](https://ssweber.github.io/pyrung/) is a Python DSL for writing, simulating, and testing ladder logic. The `with` block naturally separates the condition from the instruction, which is exactly what a ladder rung does. A controls engineer can map it to the diagram they already know.
+
+Every scan produces an immutable state snapshot. Time is a variable you control. A DAP debugger lets you step through scans rung by rung in VS Code. Currently targets AutomationDirect Click PLC behavior faithfully: nearly the complete instruction set, memory banks, numeric quirks, scan-cycle semantics.
+
+### Two deployment targets
+
+pyrung compiles to two backends from the same source:
+
+**Click PLC** via [laddercodec](https://github.com/ssweber/laddercodec). Your tested logic encodes to the bytes the CLICK editor expects on paste. No transposing by hand.
+
+**ProductivityOpen P1AM-200** via CircuitPython code generation. Your tested logic becomes a self-contained scan loop that runs directly on the hardware, with the same Modbus TCP interface as a Click. No proprietary toolchain in the path.
+
+Write it once, test it once, pick your target.
+
+```mermaid
+graph LR
+    D[Click Project] -->|codegen| A[pyrung]
+    A -->|encode| B[laddercodec]
+    B -->|paste| C[ClickNick]
+    C --> D
+    D -->|download| E[Click PLC]
+    A -->|generate| G[CircuitPython]
+    G -->|deploy| H[P1AM-200]
+    E <-->|Modbus TCP| F[pyclickplc]
+    H <-->|Modbus TCP| F
+```
+
+### Existing projects welcome
+
+Generate pyrung code from an existing `.ckp` project. You don't have to start from scratch to get simulation and testing on programs you've already built.
+
+## The supporting projects
+
+Each of these works on its own, but they were designed to work with pyrung.
+
+**[ClickNick](https://github.com/ssweber/clicknick)** is the Windows-side glue. Autocomplete over the CLICK editor's instruction dialogs, a modern address editor with bulk editing and search/replace, a tag browser with hierarchy and array grouping, a DataView editor with drag-and-drop, and clipboard integration for pasting encoded rungs. Works alongside your existing `.ckp` projects.
+
+**[pyclickplc](https://ssweber.github.io/pyclickplc/)** is the Modbus TCP layer. Read and write registers on real Click hardware, or run pyrung as an emulated Click that any Modbus client can talk to. Also manages nickname and DataView files. Both the Click PLC and the P1AM-200 speak the same Modbus interface, so pyclickplc doesn't need to know which one it's talking to.
+
+**[laddercodec](https://github.com/ssweber/laddercodec)** is the binary codec for Click's undocumented clipboard format. Encodes rungs described in CSV into the bytes the CLICK editor expects on paste. Reverse-engineered from scratch; the format remains undocumented by its creator.
+
+## Limitations
+
+pyrung simulates Click PLC behavior as faithfully as possible, but it is not a certified simulator. If your program behaves differently in pyrung than on a Click PLC, that's a bug we want to know about, but you should always validate on real hardware before deploying to production. The CircuitPython target runs on a garbage-collected runtime, so sub-millisecond scan timing is not realistic. Modbus TCP has no built-in authentication; keep it on isolated networks.
+
+## Blog
+
+- [These Aren't the Rungs You're Looking For](blog/these-arent-the-rungs.md) - How I reverse-engineered Click's clipboard format so my bytes could paste without any problems.
+- [Why pyrung?](blog/why-pyrung.md) - A look at the PLC tooling landscape and where pyrung fits.

mkdocs.yml

@@ -0,0 +1,18 @@
+site_name: ssweber
+site_url: https://ssweber.github.io/
+
+theme:
+  name: material
+
+markdown_extensions:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+nav:
+  - Home: index.md
+  - Blog:
+    - "These Aren't the Rungs You're Looking For": blog/these-arent-the-rungs.md
+    - "Why pyrung?": blog/why-pyrung.md

pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "ssweber-site"
+version = "0.0.1"
+requires-python = ">=3.12"
+
+[dependency-groups]
+docs = [
+    "mkdocs-material",
+]