# Thumb-style gripper — design plan (2026-07-02)

Goal: a simple 1-DOF thumb gripper like SO-100 / smith300 for the LAST servo of the modular arm — one
moving "thumb" jaw that pivots on the servo output and closes against a fixed jaw. Cameron wants the
**thumb↔gripper mating via the servo** to be precise (not just eyeballed geometry dropped in Blender).

## 1. Mechanism
- **1-DOF angular jaw.** Last servo's output rotates a single **thumb** (moving jaw) that swings closed
  against a **fixed jaw** (palm) rigidly attached to the servo body. Simple, printable, proven.
- This is exactly what `so100_para.py` already encodes:
  - fixed jaw box on the `gripper` link: `xyz 0.0135 -0.055 0`, size `0.012 × 0.05 × 0.02` m (12×50×20mm finger).
  - moving jaw box on the `jaw` link: `xyz 0 -0.03 0`, same size; revolute about the output, range ~[-0.2, 2.0] rad.
- Reference geometry to copy the *contact profile* from: `/data/cameron/repos/SO-ARM100/STL/SO100/Follower/`.

## 2. Integration with our modular system (the clean part)
The gripper is just the **last module** with the yoke/holder repurposed — no new servo interface needed:
- **YOKE → THUMB.** The moving jaw is a rigid extension of the yoke: it mounts on the SAME horn-grip
  interface `yoke_exact` already uses to clamp the servo output. So the thumb's pivot axis IS the servo
  output axis (+Y through the horn) — mechanically exact, no extra tolerance stack. It rotates with output_N.
- **HOLDER → HOLDER + FIXED JAW.** The fixed jaw is unioned onto the gripper servo's holder (same
  boolean-union trick as the `base_cube*` base pieces → `base_holder.stl`).
- No connector / next-servo bridge (it's the chain end).

## 3. Precise thumb↔servo mating (Cameron's key ask) — how we guarantee it
1. **Pivot = servo output axis**, inherited from the yoke horn-grip. Define a `THUMB_MOUNT` interface =
   the yoke's existing horn clamp; the thumb is authored in the servo/yoke frame so its hinge is exact.
2. **Fixed-jaw mount** = a face on the holder at a defined offset (authored in the servo frame, union'd in).
3. **Closed-position constraint (the geometric solve):** pick jaw lengths + thumb rest angle so that at the
   servo's CLOSE angle the thumb's contact pad lands **flush and parallel** against the fixed-jaw pad. The
   thumb tip travels an arc of radius `PIVOT_TO_PAD` about the output axis; solve rest/close angles so the
   arc's endpoint plane coincides with the fixed-jaw face. This is what makes the "meeting" precise rather
   than approximate — it's a closed-form 2D solve in the plane ⟂ to the output axis.
4. **Contact faces:** start with flat parallel pads; options = shallow V-groove on each (centers round
   objects), or a recessed pocket for press-fit TPU pads (grip). Add slight over-travel so pads preload.

## 4. Build paths (pick one — I recommend the hybrid)
- **A. Direct copy.** Import the SO-100 Follower jaw+thumb STLs into Blender, place on the last servo.
  Fast, proven shape — but the servo mating is manual/approximate (defeats the "precise" ask).
- **B. Fully parametric.** Author thumb + fixed jaw in build123d/trimesh, mounted on our yoke-horn +
  holder interfaces. Full control, auto-fits any servo pose, integrates with `gen_two_servo`.
- **C. Hybrid (recommended).** Keep the proven SO-100 *contact profile* (the finger cross-section/curve),
  but generate the **mount base parametrically** on our yoke-horn + holder so the pivot & closed-flush
  constraint are exact. Mirrors the holder-carve precedent (Cameron drops rough geometry, agent fits it).

## 5. Pipeline integration
- Tag the last servo as the gripper (convention: last `servo_N` = gripper, or a `gripper` marker node in
  the GLB — same pass-through mechanism as `base_cube*`).
- `gen_two_servo`: for the gripper module emit **thumb (on yoke) + fixed jaw (union'd on holder)** instead
  of a plain yoke; the URDF's `output_N` becomes the jaw joint (revolute, close range e.g. 0→1.1 rad).
- Reuse `render_gripper.py` to render open vs closed and verify actuation + that pads meet flush.

## 6. Parameters to expose
`JAW_LEN`, `THUMB_LEN`, `PIVOT_TO_PAD`, `REST_ANGLE` (open), `CLOSE_ANGLE`, `PAD_TYPE` (flat / V / TPU-pocket),
`JAW_WIDTH`, `FINGER_THICK`, `PRELOAD` (over-travel mm). Grip aperture falls out of PIVOT_TO_PAD + angles.

## 7. Open questions for Cameron (answer in the morning)
1. **Angular jaw** (SO-100 thumb style, simple 1-DOF — my assumption) vs **parallel jaw** (needs a 4-bar
   linkage, better for flat objects, more parts)? Thumb-style ⇒ angular; confirm.
2. Target **grip aperture / object size** range (sets jaw length + angles)?
3. **Rigid pads** vs **TPU soft pads** (pockets)?
4. Build path **A / B / C** above? (I'll default to C — hybrid — unless you say otherwise.)
5. Does the thumb reuse the **yoke horn-grip** as its mount, or do you want a dedicated horn adapter?

## Next step when you say go
Prototype path C: parametric thumb on the yoke-horn interface + fixed jaw union'd on the holder, solve the
closed-flush constraint, wire `output_N` as the jaw joint, render open/closed. First pass ~ a few iterations.