Skip to content

RaftMotorControlConfiguration

Jump to bottom
Rob Dobson edited this page Mar 3, 2026 · 1 revision

MotorControl Configuration

MotorControl is a DeviceManager device. Configure it in SysType under DevMan -> Devices with class MotorControl.

Device Entry (Top-Level)

{
  "DevMan": {
    "Devices": [
      {
        "enable": 1,
        "class": "MotorControl",
        "name": "MotorControl",
        "bus": "SERA",
        "homingPattern": "homing-seek-center",
        "motion": { },
        "ramp": { },
        "motorEn": { },
        "axes": [ ]
      }
    ]
  }
}

Top-Level Fields

Field Type Description
enable bool/number Enables the device when non-zero.
class string Must be MotorControl.
name string Device name used by /devman/cmdjson and /devman/devdata.
bus string Optional serial bus name for drivers that use UART (e.g., TMC2209).
homingPattern string Default pattern used by the home command (default: homing-seek-center).
motion object Motion and kinematics configuration.
ramp object Ramp generator and pipeline configuration.
motorEn object Motor enable pin and disable timeout configuration.
axes array Per-axis configuration (max 3 axes).

Motion Section (motion)

Field Type Description
geom string Kinematics type: XYZ or SingleArmSCARA.
blockDistMM number Max split block length in mm (0 disables splitting).
maxJunctionDeviationMM number Junction deviation for cornering in mm.
homeBeforeMove bool/number If true, homing is required before any ramped move.
outOfBounds string Default action: allow, clamp, or discard.
arm1LenMM number SCARA arm 1 length (SingleArmSCARA).
arm2LenMM number SCARA arm 2 length (SingleArmSCARA).
maxRadiusMM number SCARA max radius (defaults to arm1+arm2).
originTheta2OffsetDegrees number SCARA theta2 origin offset (default: 180).

Ramp Section (ramp)

Field Type Description
rampTimerEn bool/number Use timer ISR for ramp generation.
rampTimerUs number Timer period in microseconds.
pipelineLen number Motion pipeline length.

Motor Enable Section (motorEn)

Field Type Description
stepEnablePin string/number Enable pin name or GPIO.
stepEnLev bool/number Active level for enable pin.
stepDisableSecs number Seconds before motors are disabled after idle.

Axes Section (axes)

MotorControl supports up to 3 axes. Each axis entry has name, params, driver, and optional endstops.

Axis Params (axes[n].params)

Field Type Description
unitsPerRot number Units per rotation (mm or degrees).
stepsPerRot number Steps per rotation.
maxSpeedUps number Max speed in units/sec.
maxAccUps2 number Max acceleration in units/sec^2.
maxDegPerSec number Max degrees/sec for speed limits.
homingDegPerSec number Homing speed in degrees/sec.
minUnits number Minimum unit bound for this axis.
maxUnits number Maximum unit bound for this axis.
isPrimaryAxis bool/number True if axis is part of primary motion distance.
isDominantAxis bool/number Dominant axis for kinematics (if used).
isServoAxis bool/number True for servo-style axis (no stepping).

Driver Params (axes[n].driver)

Field Type Description
driver string Driver type (e.g., TMC2209).
hw string Hardware location (local supported).
addr number UART address for driver (if used).
stepPin string/number Step pin name or GPIO.
dirnPin string/number Direction pin name or GPIO.
invDirn bool/number Invert direction.
noUART bool/number Disable UART configuration.
writeOnly bool/number Write-only driver register access.
extSenseOhms number External sense resistor value.
extVRef bool/number Use external Vref.
extMStep bool/number Use external microstep selection.
intpol bool/number Enable microstep interpolation.
microsteps number Microsteps per step.
minPulseWidthUs number Minimum step pulse width.
rmsAmps number RMS motor current (amps).
holdModeOrFactor string/number Hold mode (freewheel, passive) or numeric factor.
holdDelay number Hold delay.
pwmFreqKHz number PWM frequency (kHz).
statusFreqHz number Status read frequency (Hz).

Endstops (axes[n].endstops)

Each endstop entry defines a switch for one axis.

Field Type Description
isMax bool/number True for max endstop, false for min.
name string Endstop name.
sensePin string/number Sense pin name or GPIO.
actLvl bool/number Active level for the switch.
inputType string Input mode (e.g., INPUT, INPUT_PULLUP).

Example: SandBot SCARA (Trimmed)

Note: Extra fields not recognized by MotorControl (for example gearFactor or debug) are ignored by this device and may be used by application-specific tooling.

{
  "DevMan": {
    "Devices": [
      {
        "class": "MotorControl",
        "name": "MotorControl",
        "bus": "SERA",
        "homingPattern": "homing-seek-center",
        "motion": {
          "geom": "SingleArmSCARA",
          "blockDistMM": 10,
          "homeBeforeMove": 0,
          "maxJunctionDeviationMM": 0.05,
          "arm1LenMM": 95,
          "arm2LenMM": 95,
          "originTheta2OffsetDegrees": 180
        },
        "ramp": {
          "rampTimerEn": true,
          "rampTimerUs": 20,
          "pipelineLen": 250
        },
        "motorEn": {
          "stepEnablePin": "4",
          "stepEnLev": 0,
          "stepDisableSecs": 100
        },
        "axes": [
          {
            "name": "shoulder",
            "params": {
              "unitsPerRot": 360,
              "stepsPerRot": 9600,
              "gearFactor": 3,
              "maxSpeedUps": 90,
              "maxAccUps2": 45,
              "maxDegPerSec": 360,
              "homingDegPerSec": 60
            },
            "driver": {
              "driver": "TMC2209",
              "hw": "local",
              "addr": 0,
              "stepPin": "15",
              "dirnPin": "16",
              "invDirn": 1,
              "writeOnly": 0,
              "extSenseOhms": 0.15,
              "extVRef": 0,
              "extMStep": 0,
              "intpol": 1,
              "microsteps": 16,
              "rmsAmps": 0.12,
              "holdModeOrFactor": 0.5,
              "holdDelay": 1,
              "pwmFreqKHz": 35
            },
            "endstops": [
              {
                "isMax": false,
                "name": "0min",
                "sensePin": "39",
                "actLvl": 0,
                "inputType": "INPUT"
              }
            ]
          }
        ]
      }
    ]
  }
}

Example: Simple Velocity-Based Machine

{
  "DevMan": {
    "Devices": [
      {
        "enable": 1,
        "class": "MotorControl",
        "name": "MotorControl",
        "bus": "SERA",
        "motion": {
          "geom": "XYZ",
          "blockDistMM": 10,
          "outOfBounds": "allow",
          "homeBeforeMove": 0,
          "maxJunctionDeviationMM": 0.05
        },
        "ramp": {
          "rampTimerEn": 1,
          "rampTimerUs": 100,
          "pipelineLen": 100
        },
        "motorEn": {
          "stepEnablePin": 27,
          "stepEnLev": 0,
          "stepDisableSecs": 1
        },
        "axes": [
          {
            "name": "X",
            "params": {
              "unitsPerRot": 360,
              "stepsPerRot": 768,
              "maxSpeedUps": 100,
              "maxAccUps2": 100
            },
            "driver": {
              "driver": "TMC2209",
              "hw": "local",
              "addr": 0,
              "stepPin": 15,
              "dirnPin": 12,
              "invDirn": 0,
              "writeOnly": 0,
              "extSenseOhms": 0.5,
              "extVRef": 0,
              "extMStep": 0,
              "intpol": 1,
              "microsteps": 16,
              "rmsAmps": 0.5,
              "holdModeOrFactor": 0.5,
              "holdDelay": 1,
              "pwmFreqKHz": 35
            }
          }
        ]
      }
    ]
  }
}

Related Pages

Clone this wiki locally