Connecting to sources…

How to build RoboArm: the whole process

58 steps to build RoboArm, from buying parts, printing and assembly to software, calibration and training, with the bill of materials, shop links and the official source…

RoboArm is an open-source three-axis robotic arm using three stepper motors and two servos. The repository provides SolidWorks parts and assemblies, STEP files, a hardware list, wiring and setup instructions, Arduino UNO firmware, and PySide6 desktop-control software.

Buy parts

  • Clone the project repository

    Clone the repository and enter the roboArm directory for local installation.

  • Keep validation tools off the Arduino

    All source code is in the project directory. The .venv directory is the local dependency environment, while .tools, if present, contains validation tools or build cache and does not need to be flashed or copied to the Arduino.

  • Download the Complete CAD Directory

    Download the entire roboArm Model directory and keep every filename and relative path unchanged so the assembly references remain intact.

Assemble

  • Mount the Shield and A4988 drivers

    Mount the CNC Shield V3 on the UNO and install one A4988 in each X, Y, and Z driver slot. Verify EN, STEP, DIR, VMOT, and GND from the module and Shield labels rather than using potentiometer orientation, since layouts can differ.

  • Connect and identify the three motors

    Connect the three motors to the X, Y, and Z motor interfaces. Use a multimeter to identify the two coil groups, connect the two wires of each coil to one output pair, and do not rely only on wire colors; do not send motion commands to an uninstalled axis.

  • Connect the independent motor supply

    Connect the Shield motor-power terminals to an independent DC supply, for example 12 V according to the board specification, and verify polarity and current capacity. USB powers only the control logic and cannot replace the motor supply; use the Shield's actual rating rather than assuming the A4988 VMOT range applies to the whole Shield.

  • Configure full-step mode for testing
  • Check the Shield power signals

    Confirm that RESET and SLEEP on the Shield are pulled high normally, the power supply is common-grounded, and sufficient power filtering is present near VMOT. If the board lacks sufficient capacitance, add it according to the driver manufacturer's instructions and verify its voltage rating and polarity.

  • Understand the shared three-axis enable

    D8 ENABLE is shared by all three axes, so running any axis enables all three drivers. Stopping or completing one axis stops only that axis's STEP while the others continue, and holding torque is released uniformly after all axes are idle.

  • Wire the D12/D13 servos
  • Open Native Files in SolidWorks

    Use SolidWorks compatible with version 2025 to open the native files. Other versions have not been verified, and the document does not identify which numbered assembly is the final robot.

  • Resolve Assembly References Locally

    When opening an assembly, allow SolidWorks to search this directory for referenced files. If a missing-file prompt appears, relocate the referenced files within this directory.

  • Stop on Missing Assembly Files

    Do not ignore the error or treat the assembly as a complete robot until all referenced files are available.

  • Repair the Complete STEP Export

    Inspect the complete assembly in SolidWorks, then either re-export a STEP containing all geometry or supply every externally referenced STEP file. The missing references include the transmission gear, arm, gripper, base, bearing outer ring, connectors, and linkage files listed in the document.

Software

  • Install dependencies and launch controller

    Create the .venv environment, install requirements.txt, and run main.py. The D:\roboArm path is only a Windows example and may be replaced by your clone directory.

  • Use the official Arduino Servo library

    Use the official Arduino Servo library for the D12 and D13 position servos, which cover 0–180°. The lower controller is an Arduino UNO.

  • Flash protocol v3 when required

    If the board still uses the previous long-press speed-limit protocol v4, flash the project's protocol v3 firmware. With protocol v3 already installed, no reflashing is needed; close the old upper-computer window and restart start.bat.

  • Install Arduino IDE

    Install Arduino IDE and connect the UNO using USB.

  • Open the firmware sketch

    Open D:\roboArm\arduino\roboarm_x\roboarm_x.ino in the IDE. Keep the file named the same as the roboarm_x folder.

  • Configure the board and library
  • Verify and upload firmware

    Close the project control software and all programs using the serial port. Click Verify; after it passes, click Upload. This firmware replaces the program previously stored on the board.

  • Set up Python dependencies

    On 64-bit Windows 10 or 11, install 64-bit Python 3.10–3.13, preferably 3.12, and add it to PATH. Create the virtual environment and install requirements; no activation is needed, an existing usable .venv may be reused, and `py -3.12` can replace `python` if Microsoft Store intercepts it.

  • Launch the control software

    Open the project directory and run `main.py` with the virtual environment, or double-click `start.bat`. Startup does not automatically connect or run, and the interface can open without an Arduino.

  • Implement the serial motion scheduler

    Implement the protocol with a fixed-length receive buffer, a fixed-length transmit queue, and `micros()` scheduling; the only wait is the 3µs STEP high pulse, so STOP need not wait for the complete movement. If the transmit queue is full, feedback lines may be dropped while motion and STOP still execute, and a later STATUS restores the current state.

  • Run the mocked unit tests

    Run the unittest suite with the project virtual environment. The tests use a mocked serial port and do not open COM7 or drive the motors.

  • Extend the A-axis interface

    For a future A-axis extension, identify the actual Shield jumper and pin mapping, then update handshake capabilities, status feedback, and tests. The firmware uses the Axis registry, while Python uses AXES and axis-named commands and feedback.

Calibrate and test

  • Set the A4988 current limit

    Set the A4988 limit according to the motor's rated phase current, module cooling capability, and actual sense resistor, using I_limit = VREF / (8 × R_sense). A cloned module may have a different sense resistor, so do not reuse one fixed VREF; configure cooling first and begin testing at low speed and unloaded.

  • Perform a safe unloaded first test

    The motors lose holding torque after all-stop, disconnection, or a timeout stop. Perform the first test without suspended loads, especially on the Z axis.

  • Account for the stopping and feedback limits

    The GUI stop relies on USB communication and is not an independent hardware emergency stop. The configured step count is the number of emitted pulses, and without encoder feedback the system cannot detect lost steps, jams, or the true position.

  • Select position servos

    Use 0–180° position servos. Continuous-rotation servos are not suitable for this angle control, and D12/D13 are reserved for the servos in this program.

  • Set the initial servo position

    After the UNO is powered on, reset, or receives uploaded firmware, both servos are written to 90°. Opening the USB serial connection usually also resets the UNO, so reconnecting may return the servos to 90°. Opening the GUI window itself does not send a motion command.

  • Interpret the servo angle values

    The angle beside the slider is the user's target, while “Device Set” is the angle the Arduino has confirmed it wrote; it is not feedback from a real angle sensor. The Servo library's default pulse-width mapping is used, so calibrate the actual angle and mechanical endpoints according to the servo model, starting with small adjustments near 90°.

  • Check the serial protocol

    Optionally set the Serial Monitor to 115200 and Newline or NL and CR. It should show READY protocol=3 axes=X,Y,Z servos=D12,D13 followed by alternating stepper and servo status. Send STATUS and SERVO_STATUS to check; do not use the monitor at the same time as the GUI.

  • Connect and select the serial port
  • Confirm connection status and telemetry
  • Test each axis forward
  • Test reverse and selected direction
  • Test larger step counts and speed

    Change the setting to 400 steps to test about two revolutions. With the default 200 full steps per revolution, revolutions equal pulses divided by 200 times the microstep multiplier; at full step, 500 pulses per second is about 150 RPM.

  • Test stopping and independent axes
  • Test concurrent axis tasks
  • Test USB disconnection safety

    Under an unloaded test condition, start a long task and unplug USB. If the Arduino still has power, it should stop about 1.5 seconds after the last valid heartbeat; if power is lost, drive is lost immediately. Reconnecting only reads status and does not automatically resume motion.

  • Increase speed cautiously

    After low-speed motion works normally, increase the speed gradually. This minimal version has no acceleration or deceleration curve, so starting directly at a high speed may lose steps; 2000 is the software limit and is not guaranteed to be reliable for every motor.

  • Verify servo angles and mapping

    Move a servo from 90° to small test positions of 80° and 100°, checking the D12/D13 mapping and direction separately, then inspect larger angles within the actual mechanical range. The log should show `SERVO D12 100` and `OK SERVO D12 angle=100` while the other servo retains its value; the GUI range is 0–180°.

  • Verify servo and stepper concurrency
  • Configure the v3 serial protocol

    Configure the serial interface for uppercase ASCII commands with LF line endings; CRLF is also accepted, and a line must not exceed 79 characters excluding the newline. Use a nonzero step count from −1000000 to 1000000 and a positive integer speed from 1 to 2000 STEP pulses per second.

  • Test independent axis movements

    Send MOVE commands with the axis, signed step count, and speed; a positive count moves forward and a negative count moves backward. An accepted command returns the axis `OK ...` and `RUNNING ...`, and the axes operate independently without guaranteed simultaneous starts or completion.

  • Stop individual axes or all

    Send STOP to end the selected axis task while preserving its existing counters; the response contains `reason=USER`, and STOP may also be issued to an idle axis. Use STOP ALL to stop all three axes first and then receive `OK STOP_ALL`.

  • Query axis and servo status

    Use STATUS to query all three stepper axes, or STATUS X, STATUS Y, and STATUS Z to query one selected axis. Under normal communication load, feedback rotates among the three axes and two servos about every 80 ms, with each device updating about every 400 ms.

  • Set the two servo angles

    Send SERVO D12 or SERVO D13 followed by an integer angle from 0 to 180. The controller returns the applied setting, such as `OK SERVO D12 angle=90`, or an ANGLE_RANGE, BAD_NUMBER, or SERVO_UNSUPPORTED error.

  • Read configured servo angles

    Use SERVO_STATUS to query both servo settings, or SERVO_STATUS D12 and SERVO_STATUS D13 to query one servo. The response contains the selected angle, while ordinary STATUS queries only the stepper axes.

  • Maintain the communication heartbeat

    Send PING to receive `OK PING`; the GUI automatically sends it about every 300 ms and hides the heartbeat log. During manual testing of a long movement, send a valid PING or STATUS at least every 1.5 seconds.

  • Verify the link-timeout behavior

    If no valid PING, STATUS, SERVO_STATUS, STOP, accepted MOVE, or SERVO arrives for more than 1500 ms during motion, all running stepper axes stop automatically and return `reason=LINK_TIMEOUT`. The servos retain their last target angles.

  • Handle busy and invalid commands

    During movement on an axis, another MOVE for that axis returns an error containing `code=BUSY` and the axis name, while other idle axes may still start. STOP does not clear existing counters, and an invalid command neither starts a motor nor changes the original task.

  • Validate the real robot

    Flash the firmware to the real hardware and verify the operating results using the acceptance procedure in Section 5.

Use it

  • Control the independent sliders

    The two sliders are independent; dragging a slider immediately sends the target angle, with an 80ms rate limit. Releasing the slider immediately submits the final value. The slider track can be clicked and the arrow keys can be used for fine adjustment; a new value replaces the same servo's unsent old angle.

  • Operate servos with the stepper axes

    Servo control does not wait for the servos to finish moving and can control the three stepper axes simultaneously. The Servo library uses timer interrupts, which affect UNO D9/D10 analogWrite PWM; this project's stepper outputs use ordinary digital outputs D2–D7. Measure actual stepper jitter and load behavior during parallel operation.

  • Understand STOP ALL behavior

    “Stop All Stepper”/STOP ALL stops only X/Y/Z and discards unsent servo targets. While the UNO remains powered, the servos continue outputting the last accepted target angle, without automatically returning to center or losing torque. A disconnection or communication timeout likewise leaves the servos at their last target; an UNO reset restores 90°.

  • Start the GUI after uploading

    After uploading, close the Serial Monitor and start the GUI. Opening the serial port resets the UNO; the GUI automatically waits about two seconds and performs the STOP ALL, STATUS, and SERVO_STATUS handshake. Control opens only after it receives confirmation that all axes stopped and status for both servos.

Documents