Skip to content

command-protocol.md

Latest commit

 

History

History
127 lines (93 loc) · 5.22 KB

command-protocol.md

File metadata and controls

127 lines (93 loc) · 5.22 KB
Raw

Command protocol reference

All commands are handled by a single parser, parseCommand(), in firmware/AAPA_for_software/AAPA_for_software.ino. Three groups share it:

  1. Native motion/config commands (used by the web UI and the desktop app)
  2. Extended : commands (homing, StallGuard, limits, motion profile, status)
  3. OAPA GRBL-style commands (used by N.I.N.A. TPPA — see nina-tppa-oapa.md)

Transports

Transport Details Response framing
USB serial 115200 baud, 8N1, commands terminated by \n \r\n (println)
TCP :23 WiFi AP 192.168.4.1, one client at a time \r\n
HTTP :80 GET /cmd?val=<url-encoded command>; GET / = web UI text/plain body

The parser trims input; an empty line returns ERR.

Native motion

Relative moves, in steps (the host computes steps from degrees). Upper- or lower-case axis letter; the character after it must be a digit or -.

Command Action Response
X<steps> move Azimuth by <steps> X: <steps>
Y<steps> move Altitude by <steps> Y: <steps> or Y CLAMPED: <actual> (req <steps>)

Y moves are clamped to the soft limits once the axis is homed (MINY/MAXY).

Example: X800 → X: 800

Native configuration

Form <type><axis><value>:

Command Action Response
C<axis><mA> set run current (mA) X mA: 600
H<axis><pct> set hold current (% of run) X Hold: 50%
S<axis><microsteps> set microstepping (0=full,16,32,64); auto-saved to NVS X Micro: 16 (saved)

Examples: CX600, HY40, SX16.

Extended : commands

Handled by parseColonCmd().

Command Action Response
:HOMEY StallGuard homing of Altitude (blocking, up to ~60 s) OK: Y homed / ERR: …
:OFFY <n> home offset in steps (stall point → home) OK OFFY=<n>
:MINY <n> / :MAXY <n> Y soft limits (steps, relative to home) OK MINY=<n>
:SGY <0-255> StallGuard threshold (higher = more sensitive) OK SGY=<n>
:DIRY <-1|1> homing direction OK DIRY=<n>
:HSPY <n> homing speed, step/s (min 50) OK HSPY=<n>
:SPDX <n> / :SPDY <n> max speed, step/s (clamped 50–2500) OK SPDX=<n>
:ACCX <n> / :ACCY <n> acceleration, step/s² (clamped 10–1500) OK ACCX=<n>
:RESETSPD reset speed/accel to 1500/500 OK reset speed/accel to 1500/500
:SAVE persist all config to NVS OK SAVED
:STOP decelerated stop of both axes (not instant) OK STOPPED
:RESETY set Y position to 0 (manual home) OK Y=0 (manual home, NVS pos invalidated)
:DREAD read DIAG pin + SG_RESULT + SGTHRS DIAGY_PIN=0 SG_RESULT=412 SGTHRS=80
:SGTEST [n] StallGuard diagnostic move + verdict see below
:STATUS full telemetry line see below

:HOMEY blocks the whole firmware loop while it runs (up to ~60 s). During that time the web/TCP/serial channels are not serviced and :STOP cannot be delivered — the emergency stop is cutting power. See calibration.md and troubleshooting.md.

:STATUS schema

Space-separated KEY:VALUE tokens:

POSX POSY BUSYX BUSYY HOMED OFFY MINY MAXY SGY DIRY HSPY SGRES DIAGY SPDX ACCX SPDY ACCY MSX MSY

Example:

POSX:0 POSY:1234 BUSYX:0 BUSYY:0 HOMED:1 OFFY:200 MINY:-100000 MAXY:100000 SGY:80 DIRY:-1 HSPY:1500 SGRES:412 DIAGY:0 SPDX:1500 ACCX:500 SPDY:1500 ACCY:500 MSX:16 MSY:16

BUSYX/BUSYY are 1 while an axis is moving — poll :STATUS to wait for a move to finish instead of guessing a delay.

:SGTEST verdict

Moves Y at homing speed and reports the StallGuard range plus a plain-English verdict, one of:

  • JP2_OPEN — DIAG stuck HIGH at rest (jumper JP2 open / wiring)
  • TMC2209_UART_FAIL — SG_RESULT always 0 (UART not talking to the driver)
  • SG_OK_but_no_stall — sensor works but nothing stalled (raise SGY or load)
  • OK_stall_detected — healthy

OAPA commands (N.I.N.A. TPPA)

An additive compatibility layer (parseOapaCmd() / buildOapaStatus()) so TPPA's "OAPA" adjustment system can drive AAPA directly. Units: 1 position unit = 1 microstep; the feed F is treated as step/s (clamped 50–2500). These do not collide with the native protocol.

Command Action Response
? status query two lines: <Idle|MPos:x,y,z|T:0,R:r,E:e,S:s|> then ok
$J=G91G21<A><d>F<f> relative jog of axis A∈{X,Y,Z} by d microsteps ok
$J=G53<A><t>F<f> absolute jog to machine position t ok
XC<mA> / YC<mA> run current (axis-first, opposite of native CX) ok
XH<pct> / YH<pct> hold current % ok

Example status line: <Idle|MPos:0.000,-50.000,0.000|T:0,R:0,E:0,S:0|>

Move completion is detected by the host polling ? until MPos reaches the target (±0.01) — there is no "done" flag, and OAPA jogs deliberately bypass the Y soft limits so the reported position always reaches the commanded target. Full details and the exact status regex are in nina-tppa-oapa.md.