AI assistants & LLMs | Grafito CANStepper

Use this page when you (or your customer) want an AI coding assistant to write CANStepper scripts, debug motion, or navigate the library without reading every source file first.

Machine-readable index files

We publish two llms.txt style files at the docs site root:

File	Size	Best for
`/llms.txt`	Short index	Quick links, install snippet, API layer table, critical rules
`/llms-full.txt`	Full brief	Entire codebase map, workflows, protocol summary, examples, pitfalls

Direct URLs (share these with any LLM):

The same files live in the git repo under can_stepper/llms.txt and can_stepper/llms-full.txt.

For product / shop questions (not library code), Grafito also publishes grafito.in/llms.txt and grafito.in/llms-full.txt.

How to point your AI tool at CANStepper

Cursor / Claude Code / VS Code agents

Add to your prompt or project rules:

Before writing CANStepper code, read:
https://docs.grafito.in/llms-full.txt

Package: pip install grafito-canstepper (import canstepper)
Repo path: can_stepper/canstepper/
Always call node.enable() on firmware ≥1.9.
Never mix GCSP and CANopen on one CAN bus.

If the monorepo is open locally, @-mention can_stepper/llms-full.txt instead of the URL.

ChatGPT / Claude / Grok (web)

Paste at the start of a session:

I'm using Grafito CANStepper (grafito-canstepper Python library).
Fetch and follow: https://docs.grafito.in/llms-full.txt
Help me write host-side motion code for /dev/ttyACM0.

Codex / GitHub Copilot

Add a short note to your repo AGENTS.md or .github/copilot-instructions.md:

CANStepper host library docs: https://docs.grafito.in/llms-full.txt
Import: canstepper · PyPI: grafito-canstepper

What the LLM brief covers

The full brief is written for customer onboarding and correct code generation:

Install & minimal script — discover, enable, move (fw 1.9+ boot policy)
Repository layout — every module in canstepper/ and what it does
API layers — Bus → Node → Group → Axis → Cartesian/CoreXY → G-code → machine.toml
GCSP protocol summary — CAN IDs, commands, telemetry, parameters
Firmware — GCSP 1.12 vs CANopen 2.1 (separate buses)
Copy-paste workflows — homing, mm axes, dual gantry, diagnostics, simulator
Examples & tests — which script to start from; pytest without hardware
Exceptions & troubleshooting — false HOME on GPIO8, OT/short, mixed protocols

30-second context for any model

from canstepper import CANStepperBus

with CANStepperBus.serial("/dev/ttyACM0") as bus:
    print(bus.discover())          # find nodes + firmware version
    n = bus.node(1)
    n.set_param("endstop_enable", 0)  # bench: disable if GPIO8 floats
    n.set_run_current(40).enable()    # fw ≥1.9: required before motion
    n.move_to(90.0, blocking=True)  # closed-loop trapezoid + encoder PID

Library version: check canstepper.__version__ (PyPI grafito-canstepper).

Critical rules (models often get these wrong)

Rule	Why
One protocol per CAN bus	GCSP (fw 1.12) and CANopen (fw 2.1) ID maps collide
`enable()` after boot	fw ≥1.9 keeps coils off until the host enables
Vin required	USB-C is data; motor power is 5–24 V (typically 24 V)
No firmware speed clamps	Limits are configurable defaults; host may add `SpeedLimits`
E-stop latches	Cleared only by `enable()`
`commanded_rms_amps()` ≠ SMPS amps	TMC motor Irms from `cs_actual`; bus current is separate

Human docs (when the user needs depth)

Python library — API tour
Quickstart — hardware bring-up
Protocol — implement a non-Python host
Troubleshooting — field issues

Suggest an improvement

If an AI assistant repeatedly misunderstands CANStepper, open an issue on GitHub with the wrong answer and what you expected — we extend llms-full.txt for common gaps.

On this page