# How to actually build a linear-rail gantry (for someone who never has)

Plain-language guide. A "linear axis" = something that moves in a straight line, driven by a motor.
Each axis is 5 parts: **(1) a straight rail/guide, (2) a carriage that slides on it, (3) a drive that
pushes the carriage, (4) a motor, (5) endstops to find home.** We have 3 axes (X, Z horizontal; Y vertical).

## 1. The rail + carriage (what slides)
Cheapest→most precise:
- **V-slot wheels on the aluminum extrusion** — plastic/delrin wheels roll in the extrusion groove. Cheap,
  forgiving, a little play. Good to start.
- **Smooth steel rod + LM linear bearings** — cheap, decent, needs 2 rods per axis.
- **MGN linear rail (MGN12)** — a steel rail with a recirculating-ball block. Precise, stiff, ~$15/axis.
  Recommended for the wrist accuracy we want.
Mount the rail to **2040 aluminum extrusion** (20×40 mm; stiffer than 2020 for the spans). Use 2020 for light
vertical members. Extrusion + T-nuts + corner brackets = the frame; no welding, all bolt-together.

## 2. The drive (what moves the carriage)
- **GT2 belt + pulley** (X, Z horizontal): fast, cheap, low friction. A loop of belt, one end each on the
  carriage, motor pulley in the middle. Downside: belts stretch slightly and are **back-drivable** (push the
  carriage and the motor spins) — fine for horizontal axes.
- **Leadscrew (T8, 8 mm)**: a threaded rod; the carriage has a nut; motor spins the rod → nut travels.
  Precise, and importantly **self-locking** (gravity cannot back-drive a low-lead screw) — the carriage stays
  put when the motor is off. Slower than belt.

## 3. ⚠ The vertical (Y) axis — your specific worry, and it is the right worry
The vertical axis is NOT gravity-supported: the whole arm hangs off it and gravity constantly pulls it down.
Three real failure modes and the fixes:
- **Back-drive / dropping when powered off.** A belt or high-lead screw lets gravity spin the motor and the
  arm crashes down the moment you cut power (or lose steps). → **Use a self-locking T8 leadscrew** on Y (it
  physically cannot back-drive), OR add a **brake**, OR a **gas-spring/counterbalance** to hold the weight.
- **Continuous holding torque + heat.** A stepper holding a load draws current and gets hot even standing
  still. A self-locking leadscrew removes this (the screw holds, not the motor). Belt-driven vertical would
  cook the motor.
- **Missed steps under load = position drift.** Size the motor with margin (below) and home against an
  endstop every session.
**Recommendation:** vertical Y = **T8 leadscrew, NEMA17**. Horizontal X/Z = **GT2 belt, NEMA17**.

## 4. Motors — sizing
NEMA17 (42 mm) stepper is the standard. Holding torque ~40–60 N·cm (0.4–0.6 N·m).
- Horizontal belt axes: almost no gravity load, just friction+acceleration → any NEMA17 is plenty.
- Vertical leadscrew axis: force to lift = arm weight (~1–2 kg = 10–20 N). Leadscrew torque
  `T = F·lead/(2π·efficiency)`; T8 lead 8 mm, eff ~0.3 → T ≈ 20·0.008/(2π·0.3) ≈ 0.085 N·m → NEMA17 easily
  covers it, and the screw self-locks so holding is free.
- Can we reuse STS3215 servos? They are position servos (great for the wrist), but for linear axes you want
  **open-loop steppers + a 3D-printer controller** (cheap, well-supported). Mixed is fine: steppers for XYZ,
  STS3215 for the 4 wrist joints.

## 5. Electronics
A **3D-printer control board** (BTT SKR / MKS, or even RAMPS) drives 3–5 steppers + endstops out of the box,
runs Marlin/Klipper. Wrist STS3215 run on their own serial bus (they daisy-chain). One 12–24 V supply.

## 6. Build order
1. Cut + bolt the extrusion frame (portal, feet on ground).
2. Mount rails/guides on each axis; check they slide smoothly by hand.
3. Add carriages; add drive (belt loops / leadscrew + nut).
4. Bolt motors via printed **motor mounts** (see gen_gantry motor variant / _autolog).
5. Add endstops at each axis home.
6. Wire the controller; set motor current; home each axis; set soft limits = the travel in gantry_arm.urdf.
7. Hang the wrist; calibrate.

## Gotchas
- Square the frame before tightening (diagonal measure). A racked gantry binds.
- Belt tension: firm, not guitar-string. Leadscrew: constrain one end (bearing), let the other float.
- Cable management: the hanging arm needs a drag chain so wires do not snag over the travel.