Skip to content
View as markdown

Galaxea A1Z

The A1Z integration uses the vendor's 250 Hz position-control loop, the G1Z gravity model, and the G1Z gripper. The SDK is not published on PyPI, so install the pinned Git revision until the vendor publishes a compatible release.

Install from a source checkout

Create a developer environment with the official installer first. Then install the A1Z-specific SDK and tools below.

The repository setup script shows its complete plan and asks for confirmation before it changes the checkout environment or installs system packages:

bin/hardware/a1z/setup

The script runs a locked, inexact sync so it preserves other extras in the checkout. It installs can-utils on Ubuntu and libusb through Homebrew on macOS when needed. On other Linux distributions, it prints the missing system package instead of selecting a package manager for you.

Add the vendor SDK to a library environment

Follow the official installation guide and select the manipulation extra. In that environment, add the A1Z vendor SDK with the package manager that owns it:

python -m pip install 'a1z @ git+https://github.com/userguide-galaxea/GALAXEA-A1Z.git@e931ecd0e25ad35df251097ba42921b3d2fa7224'

On macOS, also install the userspace USB dependencies:

python -m pip install 'gs-usb==0.3.1' 'pyusb==1.3.1'
brew install libusb

On Linux, install the package that provides cansend. Ubuntu calls this package can-utils:

sudo apt-get install can-utils

Check the installation without changing the host:

dimos hardware a1z doctor --software-only

Linux setup

Connect and power the arm, then configure its CAN interface:

dimos hardware a1z configure-can

The command asks for confirmation, then uses sudo to:

  1. Load the Linux gs_usb kernel driver.
  2. Bind the HHS USB-CANFD adapter.
  3. Create the stable a1zcan SocketCAN interface at 1 Mbit/s.
  4. Send a safe probe and verify that the adapter transmitted it.

Do not start the arm unless configuration reports a successful transmission. Run the full read-only diagnostic afterward:

dimos hardware a1z doctor

After rebooting or reconnecting the HHS adapter, run configure-can again.

macOS setup

macOS uses the HHS adapter directly through libusb because it does not provide SocketCAN. The doctor verifies the gripper-capable SDK, finds the attached HHS USB-CANFD adapter, opens it in listen-only mode, and closes it without transmitting or enabling the arm:

dimos hardware a1z doctor

Run

The A1Z has no brakes or hardware e-stop button; the PSU switch is the hardware kill switch. Support the arm and clear its workspace before starting or stopping dimOS. Disabling the motors makes the arm fall.

dimos run keyboard-teleop-a1z

This launches keyboard teleoperation with mock hardware, the control coordinator, trajectory execution, and ManipulationModule. Select a CAN interface explicitly to use the real arm. Real-hardware startup waits for feedback from all six arm motors, validates the measured state, holds the measured pose, and then ramps gravity compensation:

dimos run keyboard-teleop-a1z --controlcoordinator.addresses '{"arm": "a1zcan"}'

On Linux, name another verified SocketCAN interface instead if needed:

dimos run keyboard-teleop-a1z --controlcoordinator.addresses '{"arm": "can0"}'

On macOS, the adapter uses its userspace USB transport; any address selects it. Without an address the blueprint runs a mock arm. The map can live in a config file shared by every A1Z blueprint; see Hardware configuration.

Troubleshooting

  • The interface is UP, but the arm does not respond. Some Linux gs_usb drivers create an interface but drop every transmission through the HHS adapter. Update to a kernel with the endpoint-discovery fix. On Jetson or another pinned-kernel system, follow the Galaxea driver guide and build the driver for the exact running kernel. Do not install a desktop kernel or copy a kernel module from another machine.
  • The bus behaves strangely after a crash. Replug the HHS adapter and rerun dimos hardware a1z configure-can on Linux or dimos hardware a1z doctor on macOS.
  • macOS cannot find or open the adapter. Check that libusb is installed, reconnect the adapter, and rerun dimos hardware a1z doctor.
  • The gripper remains stiff after shutdown. The adapter retries the disable command, but a degraded bus can still lose it. Support the arm and turn off the PSU.