--- sidebar_position: 5 title: Software API # draft: true --- ## `get_a1z_robot()` Factory function that creates a configured `ArmRobot` instance: ```python get_a1z_robot( can_channel="can0", # CAN channel name gravity_comp_factor=1.0, # Gravity compensation factor (0=off, 1=full compensation) zero_gravity_mode=True, # True=zero-force floating, False=position holding control_freq_hz=250, # Control loop frequency (Hz) urdf_path=None, # Override URDF path default_kp=None, # Override default position gain default_kd=None, # Override default velocity gain ) -> ArmRobot ``` ## Main `ArmRobot` Methods
Method Description
start(initial_kp, initial_kd) Enables the motors and starts the control loop.
stop() Performs a smooth shutdown with 0.3s decay, then disables the motors.
get_joint_pos() -> np.ndarray Gets the current joint angles (rad).
get_joint_state() -> dict Gets {`pos`, `vel`, `eff`}.
command_joint_pos(pos) Sets target joint angles using the default PD gains.
command_joint_state(joint_state) Sets target joint angles with custom gains.
move_joints(target, speed, kp, kd) Moves to the target position with linear interpolation (blocking).
is_running Indicates whether the control loop is running.
## `Kinematics` ```python from a1z.robots.kinematics import Kinematics kin = Kinematics("/path/to/urdf") # Forward kinematics -> 4x4 homogeneous transformation matrix T = kin.fk(q) # Inverse kinematics (damped least squares) converged, q_sol = kin.ik(target_pose, init_q=q0) ``` ## Joint Limits
Joint Name Mechanical Limit (deg) Mechanical Limit (rad) Soft Limit (deg) Soft Limit (rad)
0 arm_joint1 [-130°, 130°] [-2.269, 2.269] [-120°, 120°] [-2.094, 2.094]
1 arm_joint2 [-1.94°, 192.78°] [-0.034, 3.365] [0°, 180°] [0.000, 3.142]
2 arm_joint3 [-200.38°, 0°] [-3.497, 0.000] [-180°, 0°] [-3.142, 0]
3 arm_joint4 [-91.88°, 110.38°] [-1.604, 1.926] [-85°, 85°] [-1.484, 1.484]
4 arm_joint5 [-90°, 90°] [-1.571, 1.571] [-90°, 90°] [-1.484, 1.484]
5 arm_joint6 [-120°, 120°] [-2.094, 2.094] [-115°, 115°] [-2.007, 2.007]
## Default Control Parameters
Control Item Parameter Value
Default KP [30, 30, 30, 20, 5, 5]
Default KD [1, 1, 1, 0.5, 0.5, 0.5]
Joint Coordinate Sign [1, 1, -1, 1, 1, 1] (joint 3 is opposite to the URDF direction)
Gravity Torque Scale [1, 1, 1, 1, 1, 1]
Maximum Gravity Torque [50, 50, 50, 24, 10, 10] Nm
Torque Limit [70, 70, 70, 27, 10, 10] Nm
MotorA KT 2.8 (current-to-torque conversion factor)
Control Frequency 250 Hz
## Control Principles ### 1. MIT Hybrid Force-Position Control The motor firmware executes: ```bash τ_motor = kp × (pos_target - pos_actual) + kd × (vel_target - vel_actual) + τ_ff ``` The SDK executes the following at each control cycle (250 Hz by default): 1. Reads feedback from all motors over the CAN bus. 2. Uses Pinocchio RNEA to calculate the gravity compensation torque `τ_g(q)` for the current posture. 3. Performs safety checks: if `|τ_g|` exceeds the threshold, an emergency stop is triggered. 4. Composes the final torque: `τ_motor = (user_torque + τ_g × scale × factor) × joint_sign`. 5. Clips the torque to the safe range and sends it to the motors. ### 2. Zero-Force Floating Mode `kp=0, kd=small value`. The arm uses gravity compensation torque only to offset gravity, so it can be freely dragged. ### 3. Position Holding Mode `kp=default gain, kd=default gain`. PD control is combined with gravity compensation. ## Notes - For first-time use, set `gravity_comp_factor` to a small value, such as 0.3. After confirming that the compensation direction is correct, increase it gradually. - The system automatically triggers an emergency stop when gravity torque exceeds the safety threshold for any joint. - During shutdown, gravity compensation decays smoothly within 0.3s and damping is increased to prevent the arm from dropping suddenly after motor disable. - All target joint angles are clipped to the URDF limit range.