Robot Arm

Control robotic arms for automated pick-and-place operations, positioning, and test fixture manipulation.

Import

from lager import Net, NetType

# For exception handling
from lager import InvalidNetError
from lager.automation.arm import (
    MovementTimeoutError,
    NotHomedError,
    OutOfBoundsError,
    UnsupportedFirmwareError,
)

Methods

Method	Description
`position()`	Get current arm position (x, y, z)
`move_to()`	Move to absolute coordinates
`move_relative()`	Move relative to current position
`go_home()`	Return arm to home position
`enable_motor()`	Enable arm motors
`disable_motor()`	Disable arm motors
`save_position()`	Recalibrate the arm on its current pose (`M889`)
`get_full_position()`	Get full position including joint angles
`sliding_rail_init()`	Initialize the sliding rail

Method Reference

Getting an Arm Net

Get a robotic arm net instance by name and type.

from lager import Net, NetType

# Get the arm net
arm = Net.get('arm1', type=NetType.Arm)

Parameters:

Parameter	Type	Description
`name`	`str`	Net name (configured in Lager system)
`type`	`NetType`	Must be `NetType.Arm`

Returns: Arm net instance with all methods listed below The net opens the arm that has the USB serial number in its address. It also reads the firmware version of the arm. arm.firmware_version is a tuple such as (2, 3, 5), or None if the arm did not report a version.

`position()`

Get the current arm position.

x, y, z = arm.position()
print(f"Position: X={x}, Y={y}, Z={z}")

Returns: tuple[float, float, float] - (x, y, z) coordinates in mm

`move_to(x, y, z, timeout=15.0)`

Move the arm to absolute coordinates with blocking wait.

# Move to specific position
arm.move_to(100, 200, 50)

# Move with longer timeout
arm.move_to(100, 200, 50, timeout=10.0)

Parameters:

Parameter	Type	Description
`x`	`float`	Target X coordinate (mm)
`y`	`float`	Target Y coordinate (mm)
`z`	`float`	Target Z coordinate (mm)
`timeout`	`float`	Maximum wait time in seconds (default: 15.0)

Raises:

OutOfBoundsError if the target is outside the workspace bounds. Nothing is sent to the arm.
UnsupportedFirmwareError if the arm firmware is older than V2.1.4, or the arm did not report its version. Nothing is sent to the arm.
NotHomedError if the arm is not homed after power-on
MovementTimeoutError if position not reached within timeout

`move_relative(dx=0, dy=0, dz=0, timeout=15.0)`

Move relative to current position.

# Move 10mm in X direction
new_x, new_y, new_z = arm.move_relative(dx=10)

# Move diagonally
new_x, new_y, new_z = arm.move_relative(dx=10, dy=10, dz=-5)

Parameters:

Parameter	Type	Description
`dx`	`float`	Relative X movement (mm)
`dy`	`float`	Relative Y movement (mm)
`dz`	`float`	Relative Z movement (mm)
`timeout`	`float`	Maximum wait time (default: 15.0)

Returns: tuple[float, float, float] - New (x, y, z) position after move Raises:

UnsupportedFirmwareError if the arm firmware is older than V2.1.4, or the arm did not report its version. Nothing is sent to the arm.
OutOfBoundsError if the current position plus the offsets is outside the workspace bounds. The arm does not move.
NotHomedError if the arm is not homed after power-on

`go_home(timeout=20.0)`

Move the arm to its home position (X=0, Y=300, Z=0). The method returns when the arm is at home. Call it first after the arm powers on, because the firmware refuses motion until then.

arm.go_home()

Raises: RuntimeError if the arm does not reach home within timeout seconds

`enable_motor()`

Enable the arm motors.

arm.enable_motor()

`disable_motor()`

Disable the arm motors (arm will be loose).

arm.disable_motor()

`save_position()`

Recalibrate the arm. save_position() sends M889, which replaces the stored calibration of the arm with its current pose. The arm calculates every later move from that calibration.

Call save_position() only when the arm is physically in its calibration pose. In any other pose, every later move is offset.

arm.save_position()

`get_full_position()`

Get the full position including joint angles.

x, y, z, e, a, b, c = arm.get_full_position()
print(f"Cartesian: ({x}, {y}, {z})")
print(f"Joint angles: A={a}, B={b}, C={c}")

Returns: tuple[float, ...] - (x, y, z, e, a, b, c) where a, b, c are joint angles If the arm firmware does not report joint angles, a, b and c are None.

End Effector Methods

Soft Gripper

arm.soft_gripper_pick()     # Activate gripper to pick
arm.soft_gripper_place()    # Release gripper to place
arm.soft_gripper_neutral()  # Return to neutral state
arm.soft_gripper_stop()     # Stop gripper action

Air Picker

arm.air_picker_pick()       # Activate vacuum to pick
arm.air_picker_place()      # Release vacuum to place
arm.air_picker_neutral()    # Return to neutral state
arm.air_picker_stop()       # Stop vacuum action

Laser Module

arm.laser_on(value=0)      # Turn laser on with power level
arm.laser_off()            # Turn laser off

Conveyor Belt Methods

arm.conveyor_belt_forward(speed=0)    # Move belt forward (speed 0-100)
arm.conveyor_belt_backward(speed=0)   # Move belt backward (speed 0-100)
arm.conveyor_belt_stop()              # Stop belt

Sliding Rail Methods

arm.sliding_rail_init()  # Initialize the sliding rail

Utility Methods

`delay_ms(value)` / `delay_s(value)`

Add delay to the arm’s command queue.

arm.delay_ms(500)  # 500ms delay
arm.delay_s(2)     # 2 second delay

`set_acceleration(acceleration, travel_acceleration, retract_acceleration=60)`

Set the print, travel and retract acceleration in mm/s^2. The method sends M204 P<acceleration> T<travel_acceleration> R<retract_acceleration>.

arm.set_acceleration(100, 100, 60)

`set_module_type(module_type)`

Set the attached module type.

# 0=PEN, 1=LASER, 2=PNEUMATIC, 3=3D
arm.set_module_type(0)  # Set to PEN module

`get_module_type()`

Get the currently detected module type.

module = arm.get_module_type()
print(f"Module: {module}")  # 'PEN', 'LASER', 'PUMP', or '3D'

Examples

Basic Movement

from lager import Net, NetType

# Get the arm net
arm = Net.get('arm1', type=NetType.Arm)

# Go to home position
arm.go_home()

# Get current position
x, y, z = arm.position()
print(f"Home position: ({x}, {y}, {z})")

# Move to test position
arm.move_to(100, 250, 0)

# Move up
arm.move_relative(dz=50)

# Return home
arm.go_home()

Pick and Place

from lager import Net, NetType

# Get the arm net
arm = Net.get('arm1', type=NetType.Arm)

arm.go_home()

# Move to pick position
arm.move_to(100, 200, 50)     # Above target
arm.move_relative(dz=-30)     # Lower to pick height

# Pick up object
arm.soft_gripper_pick()
arm.delay_ms(500)

# Lift
arm.move_relative(dz=30)

# Move to place position
arm.move_to(150, 200, 50)
arm.move_relative(dz=-30)

# Place object
arm.soft_gripper_place()
arm.delay_ms(500)

# Return home
arm.move_relative(dz=30)
arm.go_home()

Automated Test Positioning

from lager import Net, NetType

# Test positions for probe points
PROBE_POSITIONS = [
    (100, 200, -10),  # Test point 1
    (120, 200, -10),  # Test point 2
    (140, 200, -10),  # Test point 3
]

# Get arm and probe nets
arm = Net.get('arm1', type=NetType.Arm)
adc = Net.get('PROBE', type=NetType.ADC)

arm.go_home()

results = []
for i, (x, y, z) in enumerate(PROBE_POSITIONS):
    # Move above position
    arm.move_to(x, y, z + 20)

    # Lower probe
    arm.move_to(x, y, z)
    arm.delay_ms(200)  # Settle time

    # Take measurement
    voltage = adc.input()
    results.append((i, voltage))
    print(f"Point {i}: {voltage}V")

    # Lift
    arm.move_relative(dz=20)

arm.go_home()

Error Handling

from lager import Net, NetType
from lager import InvalidNetError
from lager.automation.arm import (
    MovementTimeoutError,
    NotHomedError,
    OutOfBoundsError,
    UnsupportedFirmwareError,
)

try:
    arm = Net.get('arm1', type=NetType.Arm)
    arm.move_to(100, 200, 50, timeout=3.0)
except InvalidNetError as e:
    print(f"Arm net not found: {e}")
except UnsupportedFirmwareError as e:
    print(f"Update the arm firmware: {e}")
except NotHomedError as e:
    print(f"Home the arm first: {e}")
except OutOfBoundsError as e:
    print(f"Target is outside the workspace: {e}")
except MovementTimeoutError as e:
    print(f"Arm did not reach the target: {e}")
except RuntimeError as e:
    print(f"Arm error: {e}")

Supported Hardware

Manufacturer	Model	Features
Rotrics	Dexarm	4-axis, multiple end effectors, conveyor support. Firmware V2.1.4 or later.

Exceptions

Exception	Module	Description
`OutOfBoundsError`	`lager.automation.arm.arm_net`	The target is outside the workspace bounds. It is also a `ValueError`.
`UnsupportedFirmwareError`	`lager.automation.arm.arm_net`	The arm firmware is older than V2.1.4, or the arm did not report its version.
`NotHomedError`	`lager.automation.arm.arm_net`	The arm is not homed after power-on.
`MovementTimeoutError`	`lager.automation.arm.arm_net`	Arm didn’t reach target position in time
`RuntimeError`	builtin	Arm device not found or cannot be opened

Notes

Always use the context manager (with statement) to ensure proper cleanup
Call go_home() after the arm powers on. The firmware refuses motion until then.
move_to() and move_relative() need arm firmware V2.1.4 or later. Rotrics swapped the X and Y axes in V2.1.4, so older firmware moves in a different frame.
A movement timeout error means that the arm did not arrive. The cause can be an obstruction, an unreachable target inside the bounds, or a long move. Pass a larger timeout for a long move.
Joint angles (a, b, c) are in the arm’s internal coordinate system
Default tolerance for position verification is 0.5mm
The arm auto-detects via USB VID/PID (0x0483:0x5740)
The box finds an arm only when it scans for instruments. The scan probes only a port with that USB ID, and the arm must report a USB serial number. See Detection for the LAGER_ARM_PROBE setting.
Dexarm defines approximate workspace bounds: X -300 to 300 mm, Y 170 to 360 mm, Z -140 to 100 mm. move_to() and move_relative() raise OutOfBoundsError for a target outside them, as the lager arm CLI does. move_to_blocking(), move_to_gcode() and fast_move_to() do not check the bounds or the firmware version.

Getting Started

Development

Power & Simulation

Measurement

I/O & Communication

Utilities

Import

Methods

Method Reference

Getting an Arm Net

`position()`

`move_to(x, y, z, timeout=15.0)`

`move_relative(dx=0, dy=0, dz=0, timeout=15.0)`

`go_home(timeout=20.0)`

`enable_motor()`

`disable_motor()`

`save_position()`

`get_full_position()`

End Effector Methods

Soft Gripper

Air Picker

Laser Module

Conveyor Belt Methods

Sliding Rail Methods

Utility Methods

`delay_ms(value)` / `delay_s(value)`

`set_acceleration(acceleration, travel_acceleration, retract_acceleration=60)`

`set_module_type(module_type)`

`get_module_type()`

Examples

Basic Movement

Pick and Place

Automated Test Positioning

Error Handling

Supported Hardware

Exceptions

Notes

​Import

​Methods

​Method Reference

​Getting an Arm Net

​position()

​move_to(x, y, z, timeout=15.0)

​move_relative(dx=0, dy=0, dz=0, timeout=15.0)

​go_home(timeout=20.0)

​enable_motor()

​disable_motor()

​save_position()

​get_full_position()

​End Effector Methods

​Soft Gripper

​Air Picker

​Laser Module

​Conveyor Belt Methods

​Sliding Rail Methods

​Utility Methods

​delay_ms(value) / delay_s(value)

​set_acceleration(acceleration, travel_acceleration, retract_acceleration=60)

​set_module_type(module_type)

​get_module_type()

​Examples

​Basic Movement

​Pick and Place

​Automated Test Positioning

​Error Handling

​Supported Hardware

​Exceptions

​Notes

Import

Methods

Method Reference

Getting an Arm Net

`position()`

`move_to(x, y, z, timeout=15.0)`

`move_relative(dx=0, dy=0, dz=0, timeout=15.0)`

`go_home(timeout=20.0)`

`enable_motor()`

`disable_motor()`

`save_position()`

`get_full_position()`

End Effector Methods

Soft Gripper

Air Picker

Laser Module

Conveyor Belt Methods

Sliding Rail Methods

Utility Methods

`delay_ms(value)` / `delay_s(value)`

`set_acceleration(acceleration, travel_acceleration, retract_acceleration=60)`

`set_module_type(module_type)`

`get_module_type()`

Examples

Basic Movement

Pick and Place

Automated Test Positioning

Error Handling

Supported Hardware

Exceptions

Notes