A7 Arm

A7 is a self-developed 7-DoF robotic arm.

Quick Start

from realhand import A7

with A7(
    side="left",
    interface_name="can0",
) as arm:
    arm.enable()  # Enable all 7 joint motors
    arm.home()  # Move the arm to the zero position
    arm.disable()  # Disable all 7 joint motors

Constructor Parameters

The constructor automatically checks whether all 7 motors are online.

Dependency requirement: A7 relies on Pinocchio for kinematics. Install the optional kinetix dependency:

pip install "realhand[kinetix] @ git+https://github.com/RealHand-Robotics/realbot-python-sdk.git"

Windows users: Pinocchio does not support installation via pip on Windows. Use conda install pinocchio -c conda-forge.

Exceptions:

• ImportError: The optional kinetix dependency (Pinocchio) is not installed
• ValueError: Invalid side or world_frame argument
• StateError: Motors did not respond on the CAN bus / initial data read failed

URDF paths: src/realhand/arm/kinetix/urdf/a7__left.urdf and a7__right.urdf

Coordinate Frames

A7 supports two world coordinate frames selected by the world_frame parameter.

URDF Frame (default)

This is the coordinate system defined by the URDF model file. Its origin is at the center of the arm base (Base_Link), as shown below:

• X axis: Positive X points from the back of the robot toward the front
• Y axis: Positive Y points to the robot’s left side from the robot’s perspective (the viewer’s right when facing the robot)
• Z axis: Positive Z points upward by the right-hand rule
• Rx, Ry, Rz: Rotations are applied in Z, Y, X order, with counterclockwise as positive

Maestro Frame

The Maestro frame applies two transformations relative to the URDF frame, as shown below:

1. Origin translation: Moves the world origin from the base center to the center of Joint 2 (the second shoulder joint)
2. Rotate Z by 90°: Rotates the URDF axes counterclockwise by +90° around Z at the new origin

After the transformation:

• X axis: Positive X points to the robot’s right side from the robot’s perspective (the viewer’s left when facing the robot)
• Y axis: Positive Y points from the back of the robot toward the front
• Z axis: Positive Z points upward by the right-hand rule

Note: These coordinate definitions mainly affect the Pose values used by move_p and move_l. They do not affect move_j.

Joint Definition

Zero Position

When all joint angles are [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], the arm should be in a natural hanging pose with joints perpendicular to each other. Call home() to return to the zero position, shown below:

Positive Rotation Direction

Positive joint angles follow the right-hand rule: point your right thumb along the positive rotation axis, and the direction in which your fingers curl is the positive direction.

• Axis 0 1 0 (positive Y): Angle increases rotate counterclockwise when viewed along +Y
• Axis 1 0 0 (positive X): Angle increases rotate counterclockwise when viewed along +X
• Axis 0 0 -1 (negative Z): Angle increases rotate clockwise when viewed from above
• Axis 0 -1 0 (negative Y): Angle increases rotate clockwise when viewed along +Y

A7 Left Arm Joint List (URDF frame)

A7 Right Arm Joint List (URDF frame)

Pose (TCP Pose) Representation

Pose represents the TCP (Tool Center Point) pose. It is a Pydantic model with 6 fields:

from realhand import Pose

pose = Pose(x=0.3, y=0.1, z=0.5, rx=0.0, ry=0.5, rz=0.0)

• Orientation uses extrinsic ZYX Euler angles: rotate around the world Z axis by rz, then the world Y axis by ry, and finally the world X axis by rx.

Lifecycle Management

API Reference

Notes

1. Calling arm.enable() causes a brief disable/enable cycle.
2. The arm must be disabled before setting the zero position.

Control Mode

Only PP (Profile Position) mode is currently supported. It is configured automatically when enable() is called.

You can import the ControlMode enum from realhand:

from realhand import ControlMode

CAN Bus

interface_name specifies the CAN interface name (for example "can0"), and interface_type specifies the interface type (default "socketcan").

For more information, including Windows usage, see CAN Bus Configuration.

Functional Modules