Skip to content

feat: add mechanical assembly guide #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jamro merged 5 commits into from
Sep 19, 2026
Merged

feat: add mechanical assembly guide #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3291016
docs: add assembly guide documentation
jamro Sep 19, 2026
1195fb1
docs: align documentation with assembly guide
jamro Sep 19, 2026
9f15c1f
docs: enhance assembly guide with detailed build steps and clarificat…
jamro Sep 19, 2026
8ef5420
docs: update assembly guide with visuals
jamro Sep 19, 2026
a87d83c
docs: revise assembly and build path documentation for clarity and in…
jamro Sep 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 18 additions & 22 deletions 3d_models/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,31 +22,26 @@ Two ways to get the mechanical set (same place in the build path):
1. **`ServoSizingTester.3mf`** — seat a real servo; do not force it. The body should slide, tabs sit, holes line up, and the shaft should have clearance. Tight or loose → sand/ream, or adjust servo CAD params ([parametric design](../docs/3d/parametric-design.md)).
2. **`ScrewSizingTest.3mf`** — M2 screw pilot-hole tolerance. Each hole is marked with its diameter. Drive an M2 screw into each hole and pick the tightest size that still cuts a thread (does not spin freely / slide through). Set Fusion user parameter `screw_thread_diameter` to that marked value, then re-export before printing structural parts. Details: [M2 screw holes](../docs/3d/parametric-design.md#m2-screw-holes).

Assembly uses **M2 screws** that thread directly into the printed PLA/PETG — no glue, no heat-set inserts. Easy to dismount and modify later. Full step-by-step assembly is **not documented yet** — use the [screw list](#screws) and part table below, then electrical and bring-up docs.
Assembly uses **M2 screws** that thread directly into the printed PLA/PETG — no glue, no heat-set inserts. Easy to dismount and modify later. Mechanical assembly continues around wiring and flashing — [docs/3d/assembly.md](../docs/3d/assembly.md) is the sequencing authority. Use the [screw list](#screws) below.

### Screws

**Spec:** M2 thread-forming (self-tapping) screws for plastic, **pan-head or button-head** — there are no counterbores/countersinks in any part, so heads sit on the plastic surface. CAD default pilot is **2.2 mm** (Fusion user parameter `screw_thread_diameter`); if your `ScrewSizingTest` winner differs, re-export at that diameter before printing structural parts.
**Spec:** M2 thread-forming (self-tapping) screws for plastic, **pan-head or button-head** — there are no counterbores/countersinks in any part, so heads sit on the plastic surface. CAD default pilot is **2.1 mm** (Fusion user parameter `screw_thread_diameter`); if your `ScrewSizingTest` winner differs, re-export at that diameter before printing structural parts. Details: [M2 screw holes](../docs/3d/parametric-design.md#m2-screw-holes).

**Measured pilot census** of the shipped `sg90` meshes (pilot Ø ≈ 2.1 mm; counted from exported meshes, not the Fusion source — treat as a verified starting point and test-fit as you go):
**One BOM for every servo preset** (`parts/sg90/`, `parts/fs0307/`, `parts/hd1370a/`, …). Printed parts scale with the servo choice, but the lengths below are the reference shopping list for all of them — including smaller models for smaller servos. Pilots are cut as deep as practical so nearby lengths often work too; if you already have different M2 lengths, test-fit before buying a full set. Per-step placement: [assembly guide](../docs/3d/assembly.md).

| Part | M2 pilots | Pilot depth | Notes |
| --- | --- | --- | --- |
| `AiEmblem.3mf` | 1 | 4.0 mm blind | emblem → shell |
| `Bell.3mf` | 1 | 6.6 mm through | bell → desk |
| `Chest.3mf` | 0 screws (5 channels) | 14–23 mm through | deep channels are servo-wire routing, not screws |
| `Coffee.3mf` | 1 | 8.5 mm blind | pairs with `Mug` |
| `Desk.3mf` | 10 | 5.0–7.5 mm through | frame joints |
| `DeskTop.3mf` | 5 | 2.5–3.5 mm through | pilots for top-mounted items |
| `Head.3mf` | 3 | 1× 5.0 mm + 2× 12.8 mm blind | the two deep pilots are servo tab screws |
| `LampButton.3mf` | 1 | 6.1 mm through | button retention |
| `Mug.3mf` | 1 | 2.5 mm through | pairs with `Coffee` |
| `SeatLeft.3mf` / `SeatRight.3mf` | 2 each | 7.0 mm through | chair assembly |
| Neck, arms, belly, hat, lamp, laptop, desk pad, chair | 0 | — | no M2 pilots |
**Shopping list (per robot):**

Only the **head** ships servo-tab pilots — the other four servos are retained by pocket fit plus the horn screw capturing each joint. Servo horn screws come **in the servo bags** (one per joint, five total); standard servo packs also include mounting screws, but only the head needs them — the rest are spares.
| Item | Qty | Typical use |
| --- | --- | --- |
| M2×4 mm | 8 | Emblem, PCA9685, MAX98357A |
| M2×8 mm | 21 | Hat, Neck↔Head, Chest center (prefer two), Belly↔Chest, LampBase, laptop, mug, Chair↔Desk, elbows |
| M2×16 mm | 15 | Chest side servos, SeatLeft/Right, DeskTop stack, USB-C, Bell |
| M2 nuts | 6 | Neck captured ×1, USB-C ×4, Bell ×1 |
| Servo bag screws | 5 | Neck shaft, Neck↔Head (robot’s left), Belly shaft, both arms |

Prefer **two** M2×8 for the Neck servo in `Chest`; one at the back is enough if space is tight (buy 21 either way). An M2 assortment covering **M2×4–M2×16** is the easy path.

**Shopping list (per robot):** ~30× **M2×6** (covers every pilot ≤ 8.5 mm deep) + ~5× **M2×12** (the two 12.8 mm head pilots + spares). One M2 assortment kit (M2×4–M2×12) is the easy path.

## Parts

Expand Down Expand Up @@ -85,11 +80,12 @@ Same filenames in each `parts/{servo_id}/3mf/` folder (and matching `stl/` / `st

## Next steps

Full build path (print → wire → flash): [docs/getting-started.md](../docs/getting-started.md).
Interleaved build path (assembly continues around wiring and flash): [docs/getting-started.md](../docs/getting-started.md). Sequencing authority: [docs/3d/assembly.md](../docs/3d/assembly.md).

1. Servo axes and safe ranges: [docs/robot-movement.md](../docs/robot-movement.md)
2. Wiring and power: [docs/hardware/wiring.md](../docs/hardware/wiring.md), [docs/hardware/README.md](../docs/hardware/README.md)
3. Bring-up and failures: [docs/hardware/testing.md](../docs/hardware/testing.md)
1. Assemble with mid-build wire/flash checkpoints: [docs/3d/assembly.md](../docs/3d/assembly.md)
2. Servo axes and safe ranges: [docs/robot-movement.md](../docs/robot-movement.md)
3. Wiring reference (use when the assembly guide calls for it): [docs/hardware/wiring.md](../docs/hardware/wiring.md), [docs/hardware/README.md](../docs/hardware/README.md)
4. Bring-up and failures: [docs/hardware/testing.md](../docs/hardware/testing.md)

## License

Expand Down
11 changes: 5 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,12 +44,10 @@ New to hardware? Start with **[From Code to Circuits](docs/hardware-for-software

1. **Get the electronics** — [hardware inventory](docs/hardware/components.md)
2. **3D print or order the parts** — [printables](3d_models/README.md), or [order from a provider](docs/3d/order-parts.md) if you have no printer. Different servo size: [parametric CAD](docs/3d/parametric-design.md)
3. **Assemble the mechanics** — fit the five servos — [3D models](3d_models/README.md), [servo axes](docs/robot-movement.md)
4. **Wire the electronics** — [wiring](docs/hardware/wiring.md), [hardware overview](docs/hardware/README.md)
5. **Flash the ESP32 firmware** — [getting started → Flash](docs/getting-started.md#4-flash)
6. **Configure Wi-Fi** — [getting started → Wi-Fi](docs/getting-started.md#5-wi-fi-setup)
7. **Test the robot** — web UI + a curl — [getting started → Prove it](docs/getting-started.md#6-prove-it)
8. **Connect your coding agent** — [Cursor hooks](docs/hooks.md) or [any IDE / REST](docs/integration.md)
3. **Assemble, wire, and flash (interleaved)** — mechanical assembly continues around wiring and flashing; [assembly guide](docs/3d/assembly.md) is the sequencing authority (Head + Hat, then wire/flash before centering, then remaining joins). Fit details: [3D models](3d_models/README.md), [servo axes](docs/robot-movement.md). Wiring: [wiring](docs/hardware/wiring.md), [hardware overview](docs/hardware/README.md). Flash: [getting started → Flash](docs/getting-started.md#4-flash)
4. **Configure Wi-Fi** — [getting started → Wi-Fi](docs/getting-started.md#5-wi-fi-setup)
5. **Test the robot** — web UI + a curl — [getting started → Prove it](docs/getting-started.md#6-prove-it)
6. **Connect your coding agent** — [Cursor hooks](docs/hooks.md) or [any IDE / REST](docs/integration.md)

Full walkthrough: [docs/getting-started.md](docs/getting-started.md).

Expand Down Expand Up @@ -113,6 +111,7 @@ Cursor projects can map agent events to poses via hooks — [docs/hooks.md](docs
| Parts / BOM | [docs/hardware/components.md](docs/hardware/components.md) |
| Wiring / power | [docs/hardware/README.md](docs/hardware/README.md) |
| Printable parts | [3d_models/README.md](3d_models/README.md) |
| Assemble printed parts | [docs/3d/assembly.md](docs/3d/assembly.md) |
| Resize CAD for another servo | [docs/3d/parametric-design.md](docs/3d/parametric-design.md) |
| Servo axes / safe ranges | [docs/robot-movement.md](docs/robot-movement.md) |
| HTTP API | [docs/api.md](docs/api.md) |
Expand Down
Loading
Loading