Python toolchain and compiler for the SCARA Robotics
Version: 1.0.2
Target: Industrial SCARA Robotic Manipulators
Toolchain: scaralang (scarac compiler & binary protocol engine)
Author: Vladimir Roncevic
License: GPL-3.0 / Apache-2.0
MOVE_J — Rapid Joint Point-to-Point MotionMOVE_L — Linear Cartesian Interpolated MotionARC_CW — Clockwise Circular Arc InterpolationARC_CCW — Counter-Clockwise Circular Arc InterpolationAPPROACH — Relative Vertical DescentRETRACT — Relative Vertical AscentJOG_AXIS — Manual Incremental Cartesian JogJOG_JOINT — Manual Incremental Joint JogPROBE — Tactile Surface SearchJUMP — 3D Parabolic Arch Pick & PlacePALLET_DEF — Matrix Pallet Grid DefinitionMOVE_PALLET — Pallet Index PositioningPUMP — Vacuum Generator ActuationVALVE — Vacuum Blow-Off Release ValveTOOL — Vertical Slide Stage ActuationTOOL_ORIENT — End-Effector Orientation ModeCONFIG ELBOW — Kinematic Arm Solution BranchCONFIG MOTOR — Stepper Drive Feedback ModeFRAME_SET / FRAME — Work Coordinate System (WCS)FRAME_RESET — Reset Coordinate System to World BaseHOME — Multi-Axis Calibration & Homing RoutineThe SCARA Domain-Specific Language (DSL) is a high-level, human-readable robotic programming language designed specifically for Selective Compliance Assembly Robot Arm (SCARA) 4-axis manipulators ($X, Y, Z, \Phi$).
Unlike generic CNC G-code, SCARA DSL is natively aware of:
JUMP arches, pallet matrix generation, rapid approach/retract moves).0xAA 0x55 wire protocol).A .scara program consists of sequence lines. Each line contains at most one statement. A statement starts with a command keyword, followed by optional or required parameters:
MOVE_L X 150.0 Y 45.0 Z 20.0
PUMP ON
WAIT 150
All command keywords and parameter identifiers are case-insensitive:
MOVE_L X 100.0 Y 50.0 Z 10.0
move_l x 100.0 y 50.0 z 10.0
Move_L X 100.0 Y 50.0 Z 10.0
All three variants produce identical AST nodes and binary instructions.
Parameters may be passed either using whitespace separation (KEY VALUE) or explicit assignment (KEY=VALUE):
# Whitespace style
MOVE_L X 150.0 Y 75.0 Z 20.0 P 45.0
# Assignment style
MOVE_L X=150.0 Y=75.0 Z=20.0 P=45.0
# Mixed style (fully supported)
JUMP X 150.0 Y=75.0 Z 20.0 ARCH=35.0
# or ; and extend to the end of the line:
# This is a comment
SPEED WORK 80.0 ; Set working feedrate to 80 mm/s
| Dimension | Axis | Unit | Description |
|---|---|---|---|
| Linear Coordinates | X, Y, Z |
Millimeters (mm) |
Absolute or frame-relative Cartesian position. |
| Tool Orientation | P / PHI |
Degrees (°) |
4th-axis end-effector yaw rotation ($\pm 180^\circ$). |
| Arc Center Offsets | I, J |
Millimeters (mm) |
Incremental vector offset from starting point to arc center. |
| Feedrate | SPEED |
mm/s |
Tool center point (TCP) linear speed. |
| Acceleration | ACCEL |
mm/s² |
Linear path acceleration and deceleration. |
| Time Delay | WAIT / WAIT_MS |
Milliseconds (ms) |
Hardware execution dwell. |
| Joint Angles | deg |
Degrees (°) |
Joint 1, Joint 2 arm angles, Joint 4 yaw. |
MOVE_JRapid Joint Point-to-Point Motion
Moves the robot arm to the target Cartesian coordinates using non-interpolated joint motion. Both arm joints articulate simultaneously at maximum speed without enforcing a straight-line Cartesian path. Best used for clearance travel and rapid repositioning.
MOVE_J X <x> Y <y> Z <z> [P <phi>]X: float (mm) — Target X coordinate.Y: float (mm) — Target Y coordinate.Z: float (mm) — Target Z coordinate.P / PHI: float (deg, optional) — Target tool orientation angle.MOVE_J X 150.0 Y -50.0 Z 40.0 P 0.0
MOVE_LLinear Cartesian Interpolated Motion
Executes a linear, straight-line trajectory from the current position to the destination coordinates at the currently active working feedrate (SPEED WORK).
MOVE_L X <x> Y <y> Z <z> [P <phi>]X: float (mm) — Target X coordinate.Y: float (mm) — Target Y coordinate.Z: float (mm) — Target Z coordinate.P / PHI: float (deg, optional) — Target tool orientation angle.MOVE_L X 180.0 Y 60.0 Z 15.0 P 90.0
ARC_CWClockwise Circular Arc Interpolation
Interpolates a circular arc in the XY plane in a clockwise direction. The arc begins at the current robot position and terminates at (X, Y). The circle center is defined relative to the starting position via I (X offset) and J (Y offset).
ARC_CW X <x> Y <y> I <i> J <j> [Z <z>] [P <p>]X, Y: float (mm) — Arc endpoint coordinates.I: float (mm) — Incremental X distance from start position to circle center.J: float (mm) — Incremental Y distance from start position to circle center.Z: float (mm, optional) — Helical motion target Z coordinate.P: float (deg, optional) — Final tool orientation.# Semi-circle of radius 25mm clockwise
ARC_CW X 150.0 Y 50.0 I 0.0 J 25.0
ARC_CCWCounter-Clockwise Circular Arc Interpolation
Interpolates a circular arc in the XY plane in a counter-clockwise direction from the current position to (X, Y) around the center offset (I, J).
ARC_CCW X <x> Y <y> I <i> J <j> [Z <z>] [P <p>]X, Y: float (mm) — Arc endpoint coordinates.I, J: float (mm) — Arc center vector offsets.Z: float (mm, optional) — Optional helical vertical coordinate.ARC_CCW X 100.0 Y 80.0 I -20.0 J 0.0
APPROACHRelative Vertical Descent
Performs a relative vertical descent along the negative Z axis from the current position by the specified clearance distance. Used to move down safely from clearance plane to pickup or placement plane.
APPROACH DIST <d>DIST: float (mm, > 0) — Vertical descent distance.APPROACH DIST 35.0
RETRACTRelative Vertical Ascent
Performs a relative vertical ascent along the positive Z axis from the current position by the specified clearance distance. Used to lift the tool up safely away from workpiece and fixtures before horizontal moves.
RETRACT DIST <d>DIST: float (mm, > 0) — Vertical ascent distance.RETRACT DIST 35.0
JOG_AXISManual Incremental Cartesian Jog
Commands a single-axis relative jog displacement along a chosen Cartesian degree of freedom. Used primarily in manual setup, calibration, and REPL control.
JOG_AXIS <X|Y|Z|PHI> <step>X, Y, Z, or PHI.step: float — Distance in mm (or degrees for PHI) to step.JOG_AXIS X 5.0
JOG_AXIS Z -1.0
JOG_AXIS PHI 15.0
JOG_JOINTManual Incremental Joint Jog
Rotates an individual robotic actuator joint by a relative angle.
JOG_JOINT <joint_id> <deg>joint_id: int (1 to 4) — Joint 1 (Base shoulder), Joint 2 (Elbow), Joint 3 (Z axis), Joint 4 (Wrist yaw).deg: float — Relative rotation in degrees (or mm for linear Z joint 3).JOG_JOINT 1 10.0
JOG_JOINT 2 -5.5
PROBETactile Surface Search
Drives the Z-axis downwards at a controlled speed until a tactile touch probe or microswitch sensor triggers. Upon contact, the current coordinate is registered, motion halts cleanly, and subsequent commands proceed from the probed plane.
PROBE [SPEED <s>] [DIST <d>]SPEED: float (mm/s, optional) — Search velocity (default: 10 mm/s).DIST: float (mm, optional) — Maximum search travel distance.PROBE SPEED 5.0 DIST 40.0
JUMP3D Parabolic Arch Pick & Place
The quintessential robotic pick-and-place command. Expands into a smooth, time-optimal 3D motion consisting of:
ARCH.(X, Y, Z).Eliminates discrete corner stops and optimizes cycle times.
JUMP X <x> Y <y> Z <z> [ARCH <h> | ARCH_HEIGHT <h>]X, Y, Z: float (mm) — Destination coordinates.ARCH / ARCH_HEIGHT: float (mm, optional) — Height of arch apex above the higher of source or target Z (default: 25.0 mm).JUMP X 220.0 Y 45.0 Z 10.0 ARCH 35.0
PALLET_DEFMatrix Pallet Grid Definition
Defines a structured 2D Cartesian pallet matrix of components or trays. Establishes the grid layout with row count, column count, and pitch offsets between cells.
PALLET_DEF <name> ROWS <r> COLS <c> DX <dx> DY <dy> [Z <z>] [P <p>]name: string — Unique identifier for the pallet grid.ROWS: int — Number of rows in the pallet grid.COLS: int — Number of columns in the pallet grid.DX: float (mm) — Pitch spacing between adjacent columns along X.DY: float (mm) — Pitch spacing between adjacent rows along Y.Z: float (mm, optional) — Default pallet working plane height.P: float (deg, optional) — Default component orientation.PALLET_DEF TRAY1 ROWS 4 COLS 6 DX 20.0 DY 25.0 Z 12.0
MOVE_PALLETPallet Index Positioning
Moves the robot to the specified 1-indexed cell within a previously defined pallet matrix. Automatically computes the Cartesian coordinates based on row and column index.
MOVE_PALLET <name> INDEX <i>name: string — Name of previously defined pallet.INDEX: int (1 to ROWSCOLS)* — 1-based sequential slot index.MOVE_PALLET TRAY1 INDEX 7
APPROACH DIST 15.0
PUMP ON
PUMPVacuum Generator Actuation
Controls the vacuum suction generator pump for end-effector pneumatic pick-and-place grippers.
PUMP <ON|OFF>ON (energize vacuum generator) or OFF (cut vacuum).PUMP ON is commanded while VALVE ON is active (pneumatic conflict), or if rapid motion occurs without an intervening WAIT to establish vacuum seal.PUMP ON
WAIT 150
VALVEVacuum Blow-Off Release Valve
Actuates the pneumatic release blow-off valve to exhaust vacuum pressure and instantaneously release gripped parts.
VALVE <ON|OFF>ON (open release valve) or OFF (close release valve).PUMP OFF
VALVE ON
WAIT 80
VALVE OFF
TOOLVertical Slide Stage Actuation
Controls a secondary high-speed pneumatic or motorized vertical slide stage mounted on the tool head.
TOOL <UP|DOWN>UP (retract tool head slide) or DOWN (extend tool head slide).TOOL DOWN
PUMP ON
WAIT 100
TOOL UP
TOOL_ORIENTEnd-Effector Orientation Mode
Configures the 4th-axis tool yaw tracking behavior during multi-axis path execution.
TOOL_ORIENT <AUTO|TANGENT|FIXED>AUTO: Automatically computes orientation to match arm configuration.TANGENT: Dynamically rotates the tool center point tangential to the travel path curve (vital for dispensing, cutting, and welding).FIXED: Preserves constant world orientation regardless of arm kinematics.TOOL_ORIENT TANGENT
SPEEDTravel and Working Feedrate Limit
Sets the maximum Cartesian linear velocity for subsequent motion segments. Supports separate definitions for rapid positioning (RAPID) and working contact travel (WORK).
SPEED <RAPID|WORK> <feedrate>RAPID or WORK.feedrate: float (mm/s, > 0) — Linear velocity limit.SPEED RAPID 250.0
SPEED WORK 60.0
ACCELPath Acceleration Limit
Configures the maximum linear path acceleration and deceleration for trajectory planning.
ACCEL <val>val: float (mm/s², > 0) — Acceleration limit.ACCEL 500.0
OVERRIDEDynamic Real-Time Speed Override
Applies a dynamic global percentage scaling factor to all path feedrates without modifying programmed velocity coordinates.
OVERRIDE <percent>percent: int or float (10 to 200) — Speed percentage (100 = 100% nominal speed).OVERRIDE 80
ZONECorner Path Blending & Rounding Mode
Controls corner rounding and trajectory continuous path blending between adjacent motion segments.
ZONE <OFF|FINE|EXACT|Z1..Z50>OFF / FINE / EXACT: Decelerates to an exact full stop at the programmed waypoint before beginning the next segment (zero corner rounding).Z1 to Z50: Blends corners smoothly with a tolerance zone of 1mm to 50mm, preserving continuous velocity and cutting cycle times.ZONE Z5
MOVE_L X 100.0 Y 50.0 Z 20.0
MOVE_L X 150.0 Y 100.0 Z 20.0
ZONE EXACT
CONFIG ELBOWKinematic Arm Solution Branch
Specifies the inverse kinematics arm solution configuration. For any SCARA Cartesian coordinate within the workspace, two valid joint angles exist: Elbow Left or Elbow Right.
CONFIG ELBOW <LEFT|RIGHT>LEFT or RIGHT.CONFIG ELBOW RIGHT
CONFIG MOTORStepper Drive Feedback Mode
Selects the actuation drive mode of the robot joint steppers.
CONFIG MOTOR <OPEN_LOOP|CLOSED_LOOP>OPEN_LOOP (standard microstepping) or CLOSED_LOOP (encoder closed-loop field-oriented control).CONFIG MOTOR CLOSED_LOOP
FRAME_SET / FRAMEWork Coordinate System (WCS)
Defines a local User Coordinate System offset from the robot base. All subsequent motion coordinates are interpreted relative to this frame.
FRAME X <x> Y <y> Z <z> [PHI <p>] or FRAME_SET X <x> Y <y> Z <z> [PHI <p>]X, Y, Z: float (mm) — Origin translation vector from base world origin.PHI: float (deg, optional) — Rotation angle of the work frame around Z.FRAME X 100.0 Y 50.0 Z 0.0 PHI 30.0
FRAME_RESETReset Coordinate System to World Base
Clears all active work coordinate transformations, restoring the global robot base origin as the reference coordinate frame.
FRAME_RESETFRAME_RESET
HOMEMulti-Axis Calibration & Homing Routine
Executes the hardware reference homing sequence for all axes (Joint 1, Joint 2, Z-axis, Tool yaw). Synchronizes stepper motor step counters with optical physical limit switches.
HOMEHOME produces a high-priority warning from MotionCalibrationValidator.HOME
WAIT / WAIT_MSTrajectory Dwell Delay
Pauses program execution for a specified duration in milliseconds. Used to allow pneumatic pressures to equalize, mechanical vibrations to dampen, or peripheral automation to index.
WAIT <ms> or WAIT_MS <ms>ms: int or float (>= 0) — Dwell delay in milliseconds.WAIT 200
SYNCTrajectory Buffer Barrier Flush
Inserts an execution barrier that blocks further command execution until the robot controller’s motion buffer completely drains and all axes come to a complete physical standstill.
SYNCSYNC
HOLDTrajectory Feed Hold (Pause)
Commands a controlled deceleration and immediate suspension of the running trajectory. Motors remain energized and position coordinates are preserved.
HOLDRESUMEResume Paused Trajectory
Resumes motion along a previously paused (HOLD) trajectory from the exact suspended coordinates.
RESUMEESTOPImmediate Emergency Stop
Executes an instantaneous hard stop aborting all motion, clearing command queues, and locking execution until an explicit reset.
ESTOPENABLEEnergize Motor Driver Stages
Powers up and energizes the stepper motor driver stages, applying holding torque to all axes.
ENABLEDISABLEDe-energize Motor Driver Stages
Cuts power to stepper driver motor windings, releasing holding torque. Allows manual positioning by hand.
DISABLEThe scaralang toolchain includes an industrial-grade static analyzer and linter (scarac lint). It inspects AST instructions before compilation and flags semantic issues into three severity categories: ERROR, WARNING, and INFO.
| Rule Identifier | Checker Service | Description | Severity |
|---|---|---|---|
MOTION_UNCALIBRATED |
MotionCalibrationValidator |
Motion instruction (MOVE_J, MOVE_L, etc.) is commanded before HOME homing routine. |
WARNING |
MOTION_DUPLICATE |
MotionDuplicateValidator |
Adjacent move instructions specify identical target coordinates, wasting trajectory planning cycles. | INFO |
MOTION_WORKSPACE_LIMIT |
TrajectoryValidator |
Target coordinate falls outside the physical reach envelope ($R_{min} \le r \le R_{max}$, $Z_{min} \le z \le Z_{max}$). | ERROR |
| Rule Identifier | Checker Service | Description | Severity |
|---|---|---|---|
PNEUMATIC_CONFLICT |
PneumaticConflictValidator |
PUMP ON and VALVE ON are commanded simultaneously, causing hardware pneumatic contention. |
ERROR |
PNEUMATIC_FLYBY |
PneumaticFlybyValidator |
PUMP ON is triggered without a subsequent dwell (WAIT) before initiating rapid motion, risking part drop. |
WARNING |
PNEUMATIC_REDUNDANT |
PneumaticRedundancyValidator |
Consecutive redundant state changes (e.g. PUMP ON followed immediately by PUMP ON). |
INFO |
| Rule Identifier | Checker Service | Description | Severity |
|---|---|---|---|
STATE_HOMING_REDUNDANT |
StateHomingValidator |
Multiple HOME commands placed without physical reason. |
INFO |
STATE_MOTOR_MODE |
MotorModeValidator |
Incompatible motor drive mode or configuration timing. | WARNING |
STATE_ZONE_CONFLICT |
StateZoneValidator |
Zone rounding enabled during precision pick/place or probing sequences. | WARNING |
| Rule Identifier | Checker Service | Description | Severity |
|---|---|---|---|
TIMING_DWELL_EXCESSIVE |
TimingDwellValidator |
Single WAIT command exceeds 60,000 ms (1 minute), likely an error. |
WARNING |
TIMING_BLEND_COLLISION |
TimingBlendZoneValidator |
Corner blend zone radius is larger than the motion segment distance. | ERROR |
# ------------------------------------------------------------------
# Industrial Palletizing Routine: Pick from Feeder, Place into Tray
# ------------------------------------------------------------------
CONFIG ELBOW LEFT
CONFIG MOTOR CLOSED_LOOP
SPEED RAPID 220.0
SPEED WORK 80.0
ACCEL 600.0
OVERRIDE 100
# 1. Calibrate reference home
HOME
# 2. Define a 3x4 Component Tray Matrix
PALLET_DEF TRAY_OUT ROWS 3 COLS 4 DX 30.0 DY 30.0 Z 10.0
# 3. Position above component feeder station
MOVE_J X 120.0 Y -60.0 Z 40.0
APPROACH DIST 35.0
# 4. Grip first component
PUMP ON
WAIT 150
RETRACT DIST 35.0
# 5. High-speed parabolic arch transfer to Pallet Slot #1
JUMP X 180.0 Y 50.0 Z 10.0 ARCH 30.0
# 6. Release component
PUMP OFF
VALVE ON
WAIT 60
VALVE OFF
# 7. Move directly to Pallet Slot #2 for second cycle
MOVE_PALLET TRAY_OUT INDEX 2
APPROACH DIST 10.0
# ------------------------------------------------------------------
# Continuous Circular Gasket Dispensing with Tangential Tool Yaw
# ------------------------------------------------------------------
SPEED RAPID 180.0
SPEED WORK 50.0
ACCEL 400.0
HOME
ZONE Z5
TOOL_ORIENT TANGENT
# Approach starting contour point
MOVE_J X 150.0 Y 0.0 Z 25.0
MOVE_L X 150.0 Y 0.0 Z 5.0
# Dispenser ON
TOOL DOWN
WAIT 50
# Continuous circular toolpath (R=40mm)
ARC_CW X 190.0 Y 40.0 I 0.0 J 40.0
ARC_CW X 230.0 Y 0.0 I 0.0 J -40.0
ARC_CW X 190.0 Y -40.0 I -40.0 J 0.0
ARC_CW X 150.0 Y 0.0 I 0.0 J 40.0
# Dispenser OFF
ZONE EXACT
TOOL UP
RETRACT DIST 30.0
# ------------------------------------------------------------------
# PCB Height Surface Probing and Touch-Off
# ------------------------------------------------------------------
CONFIG ELBOW RIGHT
SPEED RAPID 150.0
SPEED WORK 30.0
HOME
# Move above PCB test pad
MOVE_J X 140.0 Y 20.0 Z 35.0
# Search for PCB top plane at controlled velocity
PROBE SPEED 5.0 DIST 30.0
# Set Work Coordinate System relative to probed surface
FRAME X 140.0 Y 20.0 Z 0.0
# Dispense micro-dot exactly 0.5 mm above probed surface
MOVE_L X 0.0 Y 0.0 Z 0.5
TOOL DOWN
WAIT 100
TOOL UP
RETRACT DIST 20.0
FRAME_RESET