ruida-pa

Imported from StevenIsaacs/ruida-pa (AGENTS.md). Install upstream with npx skills add StevenIsaacs/ruida-pa. Copyright stays with the author.

AGENTS.md — ruida-pa

Project at a glance

A tool that decodes binary UDP packets captured from Ruida CNC/laser controllers. Entry point: rpa.py.

Commands

python rpa.py capture.log              # Decode a tshark log file
./capture <ip> <file>                  # Capture tshark log (bash)
./capture.ps1 -if Ethernet -ip <IP> -out <file>  # Capture (PowerShell)
./decode <file>                        # Produces <file>.tshark + <file>-vrb.tshark
./link <type> <case> <app>             # Symlink a test case into discovery/

• ./decode requires a venv to be active (checks $VIRTUAL_ENV). Create one from requirements.txt if needed.
• requirements.txt has bokeh (plotting). Everything else is stdlib.

Architecture

Only the Ruida UDP protocol is currently implemented. Adding a new protocol means creating a parallel protocols/<name>/ directory with its own analyzer.

Workflow

1. Capture traffic with ./capture → produces .log
2. Decode with ./decode → produces .tshark (summary) and -vrb.tshark (verbose)
3. Investigate unknown commands/parameters marked TBD in output

The ./link script creates symlinks (discovery/selected.log, selected.tshark, selected-vrb.tshark) pointing to a specific test case. Apps are identified as mk (MeerK40t), lb (LightBurn), rdw (RDWorks).

Key conventions

• Protocol command tables live in protocols/ruida/ruida_protocol.py (CT dict: byte → command name + param specs).

Mnemonic verification

• MT and CT protocol tables are defined ONLY in protocols/ruida/ruida_protocol.py (MT memory table and CT command table).
• A mnemonic is "verified" only when its byte-level semantics have been confirmed (e.g. from LightBurn captures, the ruida-laser source, or manual controller probing).
• Verified mnemonics are marked by appending # Verified <source> to the END of the mnemonic's declaration line, e.g.: 0x04: ("MEM_IO_ENABLE", TBDU35), # Verified LightBurn — where <source> names the verification source (e.g. LightBurn, ruida-laser).
• ALL mnemonics start in the UNVERIFIED state: no trailing comment at all. Never add the marker preemptively.
• When a mnemonic becomes verified, add the # Verified <source> comment to the corresponding line(s) AND update the VSCode extension's verified-mnemonic list in .vscode/extensions/local.gluescript-rpascript/syntaxes/rpascript.tmLanguage.json (the verified repository rule) so the mnemonic renders green in .rds files.

Scripting and TUI

• Parameter decoder tuples: (format_string, decoder_fn, raw_type) — e.g. ('X={}mm', dim, 'int_35').
• Checksum is a running sum of bytes in engrave/cut commands; excludes memory and jog commands. Known ~220-byte discrepancy with LightBurn captures.
• discovery/ is a separate git repo (submodule). Commit test case changes there, not in the parent.
• /gluescript TUI command for high-level job scripting (see docs/guides/gluescript-guide.md). Subcommands: new, show, stage, run, save, load, edit, list. save/load persist the current gluescript to .cglu files (the on-disk GlueScript format; .gs is deliberately unused). Jog commands (jog_*, including the jog_set_* config setters) and homing commands (home, home_z, home_u) are live-only actions — they act on the live session (movement jogs and homing execute immediately; jog_set_* configure jog speed/distance) and are never persisted to, or replayed from, .cglu files. Job-control commands (pause, resume, stop_job, reset) likewise act immediately on the live session and are never persisted to, or replayed from, .cglu files.

No test/lint/CI infrastructure

There are no unit tests, no formatter, no linter, no type checker, and no CI pipeline. Verify changes manually by running rpa.py against existing capture logs in discovery/.

Dev tips

• README states VSCode or its forks like VSCodium and Antigravity are the recommended IDEs for stepping through code alongside plots.

• Python is installed in the .venv directory.

• PEP8 compliance expected.

• .vscode/launch.json exists for debugging.

• --plot-moves opens a Bokeh server application in browser showing interactive head moves with power/speed popups, context menus, and filtering.

• Ignored dirs: discovery/, testing/, tmp/, build/, dist/, __pycache__, .png files.

• Temporary files are to be placed in tmp/.

• Test output files are to be placed in tmp/.

• Test output file names have the form <base>-<run>.<ext> where:

  • <base> is the base name of the input file.
  • <run> is a sequential two digit run number. New runs with the same input file will increment this number.
  • <ext> is the extension corresponding to the output file type where:
    • .log is a tshark capture file.
    • .txt is a decode text file.
    • .rds is a Ruida Script file.
    • .cglu is a GlueScript file.
    • .tshark is a generated tshark log file. NOTE: When doing round trip testing packet sequence and content should be identical to the input file. The timestamps can vary. For example, if the input file is discovery/selected.log then first test run using this input file will generate the following files:
    • tmp/selected-01.txt for the decode file.
    • tmp/selected-01.rds for the generated Ruida Script file.
    • When performing round trip testing using ruidascript, additional files will be generated:
      • tmp/selected-01.tshark for the tshark log using tmp/selected-01.rds as the input to ruidascript.
      • tmp/selected-01-rt.txt for the decode file generated using tmp/selected-01.tshark as the input file. A second run will have the number 02 instead of 01.

• commit.txt: To be written only when the user requests it (e.g. "Write a new commit.txt"). This contains pre-composed change summary lines and placed in the project root. Multiple summary lines are used when more than one issue (i.e. new feature or problem fix) has been resolved in a single commit. NOTE: Each issue should have only one line. Change details are to be written to the testing log (below). Each summary line should be prefixed a word indicating the nature of the change. These are:

  • version: The version number has been bumped.
  • feature: A new feature has been added.
  • fix: A problem has been fixed.

• Testing logs are maintained in docs/logs and have names formatted as <__version__>-testing.md. These are updated with detailed Problem, Solution and Verification information sections (not a bullet list). Within each section use bullet lists to itemize the problems, solutions and verifications. The testing log for the current version is to be updated when commit.txt is written.