Robot Arm

Control robot arm operations for your device - motion commands, motor control, and position utilities. All positions are in millimeters (mm).

Requirements

The arm must run DexArm firmware V2.1.4 or later. Rotrics swapped the X and Y axes in V2.1.4. On older firmware, move and move-by fail with an error that tells you to update the firmware. position, go-home and the motor commands still work. Rotrics Studio updates the firmware.
After the arm powers on, run go-home before a move. The firmware refuses motion until the arm is homed, and a move fails with an error that says so.

Syntax

lager arm [OPTIONS] [NETNAME] COMMAND [ARGS]...

Global Options

Option	Description
`--box TEXT`	Lager Box name or IP
`--help`	Show help message and exit

Arguments

Argument	Description
`NETNAME`	Arm net name (optional if default is set)

Commands

Command	Description
`position`	Get current arm position
`move`	Move to an absolute XYZ position
`move-by`	Move by relative dX dY dZ offsets
`go-home`	Move the arm to its home position (X0 Y300 Z0)
`enable-motor`	Enable arm motors
`disable-motor`	Disable arm motors (the arm goes limp)
`read-and-save-position`	Recalibrate the arm on its current pose (`M889`)
`get-acceleration`	Print the arm’s acceleration settings
`set-acceleration`	Set arm acceleration parameters

Command Reference

`position`

Get the current arm position in millimeters.

lager arm [NETNAME] position [OPTIONS]

Options:

--box TEXT - Lager Box name or IP

Example:

lager arm ARM1 position --box my-lager-box

`move`

Move the arm to an absolute XYZ position in millimeters.

lager arm [NETNAME] move [OPTIONS]

Options:

--x FLOAT - Target X position (mm). Required
--y FLOAT - Target Y position (mm). Required
--z FLOAT - Target Z position (mm). Required
--box TEXT - Lager Box name or IP
--timeout FLOAT - Move timeout in seconds (default: 15.0, minimum: 0.1, maximum: 25.0)
--yes - Confirm the action without prompting

move needs all three axes. To move along one axis, use move-by with an offset on that axis only. The box refuses a target outside the workspace of the arm. See Workspace Bounds. The maximum timeout is 25 seconds. The hardware service on the box stops a device call after 30 seconds and restarts, so the box refuses a longer move timeout. A long move can take more than the 15-second default. If a long move times out, run it again with a larger --timeout. Examples:

# Move to specific coordinates
lager arm ARM1 move --x 100 --y 200 --z 50 --box my-lager-box --yes

# Move with custom timeout
lager arm ARM1 move --x 150 --y 250 --z 75 --timeout 10.0 --yes

`move-by`

Move the arm by relative offsets (delta movement) in millimeters.

lager arm [NETNAME] move-by [OPTIONS]

Options:

--dx FLOAT - Delta X offset (mm)
--dy FLOAT - Delta Y offset (mm)
--dz FLOAT - Delta Z offset (mm)
--box TEXT - Lager Box name or IP
--timeout FLOAT - Move timeout in seconds (default: 15.0, minimum: 0.1, maximum: 25.0)
--yes - Confirm the action without prompting

Omitted axes are left unchanged, so a single-axis jog needs only that one option. The box adds the offsets to the current position. It refuses a result outside the workspace of the arm. Examples:

# Jog the arm by +5 mm in every axis
lager arm ARM1 move-by --dx 5 --dy 5 --dz 5 --box my-lager-box --yes

# Move only in Z axis
lager arm ARM1 move-by --dz 10 --yes

# Move with custom timeout
lager arm ARM1 move-by --dx 10 --timeout 3.0 --yes

`go-home`

Move the arm to its home position (X0 Y300 Z0). The command returns when the arm is at home, which can take a few seconds. Run it first after the arm powers on.

lager arm [NETNAME] go-home [OPTIONS]

Options:

--box TEXT - Lager Box name or IP
--yes - Confirm the action without prompting

Example:

lager arm ARM1 go-home --box my-lager-box --yes

`enable-motor`

Enable the arm’s motor drivers.

lager arm [NETNAME] enable-motor [OPTIONS]

Options:

--box TEXT - Lager Box name or IP

Example:

lager arm ARM1 enable-motor --box my-lager-box

`disable-motor`

Disable the arm’s motor drivers. Use this before manual manipulation of the arm.

The arm goes limp at once and drops onto whatever is below it. Support the arm, or move it to a pose where a drop is safe, before you run this command. After enable-motor, run go-home before the next move.

lager arm [NETNAME] disable-motor [OPTIONS]

Options:

--box TEXT - Lager Box name or IP
--yes - Confirm without prompting

Without --yes, the command asks for confirmation. If you do not confirm, it sends nothing to the arm. Example:

lager arm ARM1 disable-motor --box my-lager-box

`read-and-save-position`

Recalibrate the arm. The box reads the current position, then sends M889. M889 replaces the stored calibration of the arm with its current pose, and the arm calculates every later move from that calibration.

Use this command only when the arm is physically in its calibration pose. In any other pose, every later move is offset. Rotrics documents the calibration pose as arm axes 1 and 2 at their limits. To recalibrate, disable the motors and move the arm into that pose by hand. Then run this command, and run go-home after it.

lager arm [NETNAME] read-and-save-position [OPTIONS]

Options:

--box TEXT - Lager Box name or IP
--yes - Confirm the recalibration without prompting

Without --yes, the command asks for confirmation. If you do not confirm, it sends nothing to the arm. Example:

lager arm ARM1 read-and-save-position --box my-lager-box

`get-acceleration`

Print the arm’s print, travel and retract acceleration in mm/s^2. The box reads them from the arm’s settings report (M503), which changes nothing on the arm.

lager arm [NETNAME] get-acceleration [OPTIONS]

Options:

--box TEXT - Lager Box name or IP

Example:

lager arm ARM1 get-acceleration --box my-lager-box
# Acceleration (M204): print=60 travel=60 retract=40

`set-acceleration`

Set arm acceleration parameters for movement control.

lager arm [NETNAME] set-acceleration [OPTIONS]

Options:

--acceleration INTEGER - Print acceleration in mm/s^2 (minimum: 1)
--travel INTEGER - Travel acceleration in mm/s^2 (minimum: 1)
--retract INTEGER - Retract acceleration in mm/s^2 (minimum: 1). If you do not give it, the arm keeps its current retract value.
--box TEXT - Lager Box name or IP

The box sends M204 P<acceleration> T<travel> R<retract> to the arm, then reads the values back. It prints the values that the arm reports. If they are different from the values you set, the command fails. Example:

# Set acceleration parameters
lager arm ARM1 set-acceleration --acceleration 100 --travel 80 --retract 60 --box my-lager-box

Listing Arm Nets

When invoked with only --box and no subcommand, lists all arm nets on the box:

lager arm --box my-lager-box

Output:

Name   Net Type   Instrument      Channel        Address
===========================================================================
ARM1   arm        Rotrix_Dexarm   /dev/ttyACM0   USB0::0x0483::0x5740::<SERIAL>::INSTR

The channel is the serial port of the arm. The address carries the USB serial number of the arm. The box opens the arm that has this USB serial number.

Workspace Bounds

The box refuses a move or move-by target outside these approximate bounds for the Rotrics Dexarm:

Axis	Minimum (mm)	Maximum (mm)
X	-300	300
Y	170	360
Z	-140	100

For move, the CLI checks these bounds before it sends the command. It prints These coordinates are out of bounds: and one line for each axis that is out of range. For move-by, the box checks the target. Its error starts with Coordinates out of bounds and names each axis that is out of range.

Detection

The box finds an arm when it scans for instruments. lager instruments, lager nets add and lager nets add-all all start that scan.

The box probes only a serial port whose USB ID is 0483:5740.
The box sends the G-code M105 to that port and waits up to 1 second for a reply that contains ok.
The box never probes a port that belongs to another instrument or to a saved UART net. It also skips a port that another process holds.
The box does not probe an arm that a saved arm net already uses. It lists that arm from its USB serial number, because the box keeps the port of that arm open between arm commands.
The arm must report a USB serial number. The box drops an arm that has none.

To change the probe, set LAGER_ARM_PROBE in the box container:

Value	Effect
`auto`	Default. Probe only ports with the USB ID `0483:5740`.
`force`	Probe every serial port that no other instrument, saved UART net or process owns.
`off`	Do not probe for an arm.

lager box-config env set LAGER_ARM_PROBE=force --box my-lager-box
lager box-config apply --box my-lager-box

If a board on the box resets when its DTR or RTS line changes, do not use force. The probe opens each port and asserts DTR, which can reset that board. Use force only to diagnose a missing arm. Then remove the setting with lager box-config env unset LAGER_ARM_PROBE and run lager box-config apply.

Examples

# List arm nets
lager arm --box my-lager-box

# Get current position
lager arm ARM1 position --box my-lager-box

# Move to home position
lager arm ARM1 go-home --box my-lager-box --yes

# Move to specific coordinates
lager arm ARM1 move --x 100 --y 250 --z 30 --box my-lager-box --yes

# Jog the arm by +5 mm in X direction
lager arm ARM1 move-by --dx 5 --box my-lager-box --yes

# Disable motors for manual adjustment
lager arm ARM1 disable-motor --box my-lager-box

# Re-enable motors after adjustment
lager arm ARM1 enable-motor --box my-lager-box

# Recalibrate, only with the arm in its calibration pose
lager arm ARM1 read-and-save-position --box my-lager-box

# Configure acceleration
lager arm ARM1 set-acceleration --acceleration 100 --travel 80 --retract 60 --box my-lager-box

Supported Hardware

Manufacturer	Model	Description
Rotrics	Dexarm	Desktop robot arm with 3-axis control, firmware V2.1.4 or later

Notes

All positions are in millimeters (mm)
Home position is X0 Y300 Z0
Use --yes flag for non-interactive scripts and CI pipelines
Always re-enable motors after disabling them to resume normal operation
The --timeout option prevents commands from hanging if the arm fails to reach position. It cannot be more than 25 seconds.
If the USB connection to the arm drops, the current command fails. The next command opens the port again.
Default net can be set with lager defaults add --arm-net
If the arm does not appear in lager instruments, see Detection and the troubleshooting page

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Security

Development

Utilities

Requirements

Syntax

Global Options

Arguments

Commands

Command Reference

`position`

`move`

`move-by`

`go-home`

`enable-motor`

`disable-motor`

`read-and-save-position`

`get-acceleration`

`set-acceleration`

Listing Arm Nets

Workspace Bounds

Detection

Examples

Supported Hardware

Notes

​Requirements

​Syntax

​Global Options

​Arguments

​Commands

​Command Reference

​position

​move

​move-by

​go-home

​enable-motor

​disable-motor

​read-and-save-position

​get-acceleration

​set-acceleration

​Listing Arm Nets

​Workspace Bounds

​Detection

​Examples

​Supported Hardware

​Notes

Requirements

Syntax

Global Options

Arguments

Commands

Command Reference

`position`

`move`

`move-by`

`go-home`

`enable-motor`

`disable-motor`

`read-and-save-position`

`get-acceleration`

`set-acceleration`

Listing Arm Nets

Workspace Bounds

Detection

Examples

Supported Hardware

Notes