# AIRA Assembly Guide

> **Status**: This guide is a work in progress. Steps marked with `[TODO]` need photos and detailed instructions.

---

## Safety Warning

> **IMPORTANT — READ BEFORE PROCEEDING**
>
> AIRA uses high-torque industrial motors (Damiao J8009P: up to 35 Nm peak). Incorrect motor configuration — wrong CAN IDs, wrong Master/Slave IDs, or incorrect control parameters — **can cause violent, uncontrolled movement** that may damage the arm, your workspace, or cause injury.
>
> **You must configure and test every motor individually BEFORE assembling them into the arm.** Never power an assembled arm with unconfigured motors.
>
> By building and operating AIRA, you accept full responsibility for safe operation. Nextis provides this project as-is, with no warranty. See [LICENSE](../LICENSE).

---

## Prerequisites

- All 3D printed parts (see [BOM.md](BOM.md) for the full list)
  - **PLA-CF (black)**: All structural parts (19 pieces)
  - **TPU (orange)**: Soft finger tips (2 pieces)
- All components from [BOM.md](BOM.md)
- Soldering iron (for CAN bus wiring)
- M3, M4, M5 hex drivers
- Wire strippers
- A computer with a USB-CAN adapter connected
- 24V power supply (for follower motors)
- 5V power supply (for leader servos)

---

## Step 1: Print All Parts

**Material**: PLA-CF (carbon fiber reinforced PLA), black
- Layer height: 0.2 mm
- Infill: 30-40%
- Supports: Yes (tree supports recommended)
- Nozzle: Hardened steel (required for carbon fiber filament)

**Exception — TPU parts**:
- `soft_finger_v1` (x2): Print in **TPU (orange)**
- Layer height: 0.2 mm
- Infill: 20%
- Speed: Reduce to 20-30 mm/s

`[TODO]` Add STL file list with print orientation notes for each part.

---

## Step 2: Configure Motors (BEFORE Assembly)

> **This is the most critical step.** Configure each motor individually on the bench before installing it in the arm. A misconfigured motor inside an assembled arm can cause dangerous, uncontrolled movement.

### 2a: Set Up CAN Bus

Install the software and bring up the CAN interface:

```bash
git clone https://github.com/robertorobotics/Nextis-AIRA-3D
cd Nextis-AIRA-3D
pip install -e .
sudo aira-setup-can
```

### 2b: Configure Follower Motors (Damiao) — One at a Time

Each Damiao motor has two IDs that must be set:
- **Slave ID** (CAN ID): The address the motor listens on (1-7)
- **Master ID**: The address the motor sends responses to (0x11-0x17)

**Procedure — connect ONE motor at a time:**

1. Connect a single motor to the CAN bus and power it with 24V
2. Run `aira-setup`
3. The wizard will detect the motor, let you assign its Slave ID and Master ID
4. Verify the motor responds correctly by reading its position
5. Label the motor with its joint name (e.g., "Base - ID 1")
6. Disconnect it and repeat for the next motor

**Motor ID assignments:**

| Joint | Motor Model | Slave ID | Master ID |
|-------|------------|----------|-----------|
| Base | J8009P | 1 | 0x11 |
| Link 1 | J8009P | 2 | 0x12 |
| Link 2 | J4340P | 3 | 0x13 |
| Link 3 | J4340P | 4 | 0x14 |
| Link 4 | J4310 | 5 | 0x15 |
| Link 5 | J4310 | 6 | 0x16 |
| Gripper | J4310 | 7 | 0x17 |

> **Never connect two motors with the same Slave ID to the bus at the same time.** This will cause CAN bus conflicts and unpredictable behavior.

### 2c: Configure Leader Servos (Dynamixel) — One at a Time

1. Connect a single Dynamixel XL330-M077 to the U2D2 adapter
2. The setup wizard will detect it and let you assign its ID (1-7)
3. Label the servo with its joint name
4. Repeat for all 7 servos

### 2d: Bench Test

Once all motors are configured, connect all follower motors to the CAN bus simultaneously and verify:

```bash
aira-test-motors
```

All 7 motors should report their positions. If any motor does not respond, check its wiring and ID configuration before proceeding.

---

## Step 3: Wire CAN Bus

`[TODO]` CAN bus wiring diagram, daisy-chain topology, termination resistor placement (120 Ohm at each end of the bus).

---

## Step 4: Assemble Follower Arm

> **Only assemble after all motors are configured and tested (Step 2).**

`[TODO]` Step-by-step with photos for each sub-assembly:

### Base
### Link 1
### Link 2
### Link 3
### Link 4
### Link 5
### Gripper

---

## Step 5: Assemble Leader Arm

`[TODO]` Leader arm assembly instructions.

---

## Step 6: Final Integration Test

With both arms fully assembled:

1. Power on the follower arm (24V) and the leader arm (5V)
2. Run a quick position read to confirm all motors:
   ```bash
   aira-test-motors
   ```
3. Start teleoperation at **low gains** first:
   ```bash
   lerobot-teleoperate \
     --robot.type=aira_follower \
     --teleop.type=aira_leader
   ```

> **First-time tip**: Keep one hand on the power switch. If the arm moves unexpectedly, cut power immediately.

---

## Next Steps

See the main [README](../README.md) for:
- Recording demonstrations (`lerobot-record`)
- Training policies (`lerobot-train`)
- Deploying autonomous behavior (`lerobot-eval`)