RaftMotorControlCommands

MotorControl Commands

MotorControl accepts JSON commands through DeviceManager:

GET /devman/cmdjson?body={...}

The JSON body must include a device field that matches the configured device name.

Example (URL-encode the JSON in practice):

GET /devman/cmdjson?body={"device":"MotorControl","cmd":"motion","mode":"abs","pos":[50,50],"speed":75}

Common Fields

Field	Type	Description
device	string	Device name from SysType (name field).
cmd	string	Command name (see below).

Motion Command (cmd: motion)

Motion Fields

Field	Type	Description
mode	string	Motion mode (see below). Default: abs.
pos	array	Position array for position modes. Use null to skip axes.
vel	array	Velocity array for velocity modes. Use null to skip axes.
speed	number/string	Speed spec (see Speed Control).
motorCurrent	number	Motor current as percentage (0 = use default).
nosplit	bool	Prevent block splitting.
homing	bool	Mark as homing move.
more	bool	Hint that more moves are coming.
outOfBounds	string	Per-move override: allow, clamp, discard.
imm	bool	Immediate execution (stop, clear queue, then execute).
idx	number	Motion tracking index.
endstops	array	Endstop checks per axis (see Endstops).

Motion Modes

Mode	Description
abs	Absolute position in units.
rel	Relative position in units.
pos-abs-steps	Absolute position in steps (bypasses kinematics).
pos-rel-steps	Relative position in steps (bypasses kinematics).
vel	Velocity in units/sec.
vel-steps	Velocity in steps/sec.
prop or prop-abs	Proportionate absolute (0..1 mapped to axis bounds).
prop-rel	Proportionate relative (fraction of axis range).

Speed Control

Numeric values are percentages. String values support unit suffixes:

Suffix	Meaning
pc, percent	Percentage of max.
ups, unitsps	Units per second in the axis-native unit (mm for Cartesian, deg for SCARA/rotary, ...).
upm, unitspm	Units per minute.
sps	Steps per second.

Notes:

• Empty string means 100 percent of configured max.
• All speeds are capped by configured max.
• Unrecognised suffixes are treated as a percentage — the arm will be conspicuously slow, which is deliberate: it forces the caller to look rather than silently misinterpreting units.
• The mmps/mmpm suffixes were removed because they silently meant "deg/s" on geometries whose axis unit isn't mm (e.g. SCARA arms). Use ups/unitsps (geometry-neutral) or sps (raw stepper rate) instead.

Endstops Field

endstops is an array with one entry per axis. Each axis entry is a 2-element array [min, max] using these codes:

Code	Meaning
T	Check when moving toward the endstop.
X	No check for this endstop.
1	Always check (hit).
0	Reserved (not hit).

Example (check min on axis 0, max on axis 1):

{
  "device": "MotorControl",
  "cmd": "motion",
  "mode": "rel",
  "pos": [-10, 10, null],
  "endstops": [
    ["T", "X"],
    ["X", "T"],
    ["X", "X"]
  ]
}

Motion Examples

Absolute move:

{
  "device": "MotorControl",
  "cmd": "motion",
  "mode": "abs",
  "pos": [100.0, 50.0, 25.0],
  "speed": 75
}

Relative move:

{
  "device": "MotorControl",
  "cmd": "motion",
  "mode": "rel",
  "pos": [10.0, -5.0, null],
  "speed": "20ups"
}

Velocity mode:

{
  "device": "MotorControl",
  "cmd": "motion",
  "mode": "vel",
  "vel": [50.0, 0, 0],
  "speed": "100ups"
}

Step-based move:

{
  "device": "MotorControl",
  "cmd": "motion",
  "mode": "pos-abs-steps",
  "pos": [1000, 2000, 1500],
  "speed": "500sps"
}

Immediate execution:

{
  "device": "MotorControl",
  "cmd": "motion",
  "mode": "abs",
  "pos": [0, 0, 0],
  "imm": true,
  "speed": 100
}

Stop Command (cmd: stop)

Stops motion and optionally disables motors. Cancels the currently-executing block and clears every remaining queued block — the arm halts promptly rather than trickling out any queued moves.

Field	Type	Description
disableMotors	bool	Disable motors after stopping.

{
  "device": "MotorControl",
  "cmd": "stop",
  "disableMotors": true
}

Note: Prior firmware only cancelled the executing block, so a stop issued mid-stream could leave the arm slowly stepping through queued blocks ("crawl after kill"). Callers no longer need to loop stop/sleep to drain the queue.

Post-stop homing gate: if the arm was actually moving when stop arrived, the firmware also marks the position as uncertain and clears the per-axis homed flags. The next ramped move will be refused with MOTION_HOMING_REQUIRED until the caller re-homes (or calls setOrigin to explicitly re-assert a known position). A stop issued while the queue was already empty is a no-op and does NOT invalidate homing — safe for belt-and-braces "always send stop before home" patterns.

Set Origin (cmd: setOrigin)

Sets current position as origin.

{
  "device": "MotorControl",
  "cmd": "setOrigin"
}

Max Current (cmd: maxCurrent)

Field	Type	Description
axisIdx	number	Zero-based axis index.
maxCurrentA	number	Max current in amps.

{
  "device": "MotorControl",
  "cmd": "maxCurrent",
  "axisIdx": 0,
  "maxCurrentA": 1.5
}

Motor Off Timer (cmd: offAfter)

Field	Type	Description
offAfterS	number	Seconds to keep motors enabled after motion.

{
  "device": "MotorControl",
  "cmd": "offAfter",
  "offAfterS": 5.0
}

Motion Patterns

Start pattern:

{
  "device": "MotorControl",
  "cmd": "startPattern",
  "pattern": "homing-seek-center",
  "forMs": 30000
}

Stop pattern:

{
  "device": "MotorControl",
  "cmd": "stopPattern"
}

Home shortcut (uses configured homingPattern):

{
  "device": "MotorControl",
  "cmd": "home",
  "forMs": 30000
}

Return Codes

Motion commands return:

• RAFT_OK
• RAFT_BUSY
• RAFT_INVALID_DATA
• RAFT_INVALID_OPERATION
• RAFT_CANNOT_START
• RAFT_NOT_IMPLEMENTED

Related Pages

• RaftMotorControl Overview
• MotorControl Configuration
• Device Manager REST API