diff --git a/3d_models/README.md b/3d_models/README.md index 663fc90..3358684 100644 --- a/3d_models/README.md +++ b/3d_models/README.md @@ -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 @@ -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 diff --git a/README.md b/README.md index 93cd679..e8dd1ec 100644 --- a/README.md +++ b/README.md @@ -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). @@ -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) | diff --git a/docs/3d/assembly.md b/docs/3d/assembly.md new file mode 100644 index 0000000..eb03d52 --- /dev/null +++ b/docs/3d/assembly.md @@ -0,0 +1,274 @@ +# Mechanical assembly + +How to join the printed parts and seat the five micro servos. Use **M2 screws** that thread into the plastic — no glue, no heat-set inserts. + +Screw lengths called out below (M2×4 / ×8 / ×16) match the reference shopping list. If you substitute nearby lengths, **test-fit** first. Totals: [3d_models/README.md → Screws](../../3d_models/README.md#screws). + +**Before you start:** print or order the set for your servo model ([3d_models/README.md](../../3d_models/README.md), [order-parts.md](order-parts.md)). All five servos are the same type; the printed pockets match that model. + +**Left / right:** throughout this guide, “robot’s left” and “robot’s right” mean the **figure’s** sides — not your left/right as you face it. + +### Build map + +1. Head + Hat (OLED + head servo) +2. **Wire, flash, setup AP** (required before any centering) +3. Center Neck → join Head/Neck → Chest side servos → mount on Chest → Belly → Chair +4. Desk stack → mount electronics → plug channels → Chair↔Desk +5. Arms → Lamp → setup wizard + +## 1. Head — OLED and servo + +1. Peel the protective sticker off the Waveshare OLED screen. +2. Plug the cable that shipped with the Waveshare OLED into the display **before** seating it. Once the OLED is in its pocket, the connector is hard to reach. +3. Take one of the five identical micro servos. Do **not** attach a horn yet. Orientation does not matter at this stage. +4. Seat the servo and the OLED into their dedicated pockets in the printed `Head`. +5. Route both cables through the openings in the shell — OLED cable on one side of the head, servo lead on the opposite side. +6. Clip each cable into the molded cable clips on the **back** of `Head` (clips are part of the print). + +![Head](./assembly_visuals/head_1.jpg) + +## 2. Hat + +1. Place `Hat` on top of `Head`. +2. Fasten with **two M2 screws** (M2×8 mm works). Thread into the printed plastic — do not overtighten. + +![Head](./assembly_visuals/head_2.jpg) + +## 2a. Electronics and firmware (required before centering) + +From here on you set each printed part on a servo that is already at **90°** (shaft center). That needs a working board. + +1. Build and wire the electronics ([wiring](../hardware/wiring.md), [getting started → Wire](../getting-started.md#3-wire-and-power)). +2. Flash the firmware ([getting started → Flash](../getting-started.md#4-flash)). + +You will use the **setup access point** and its web configurator — not the normal Wi‑Fi UI yet. Details: [getting started → Wi‑Fi setup](../getting-started.md#5-wi-fi-setup). + +After each centering step, **unplug the servo from the PCA9685** before you keep building. Leaving the lead attached makes the next joins awkward. You reconnect the correct channels later. + +### Center a servo + +Use this recipe whenever a later step says to center a servo: + +1. Plug the servo into any PCA9685 channel (channel mapping does not matter for centering). +2. Power the ESP32. Join the setup Wi‑Fi (`TinyEngineer-XXXX`), open `http://192.168.4.1/config`, and press **Move all to 90°**. The shaft is now at electrical center. +3. After you finish that joint, **unplug** the servo from the PCA9685 before the next awkward join. + +## 3. Neck — center a servo and attach `Neck` + +1. Take the **next** unused servo (not the one already in `Head`). Do **not** attach a plastic horn — `Neck` mounts on the shaft. +2. [Center that servo](#center-a-servo). +3. Press `Neck` onto the servo shaft so the part sits **perpendicular** to the servo body. +4. Align the raised bulge in the middle of `Neck` toward the **back** of the servo — the longer end of the servo body (cable / electronics side). +5. Fasten `Neck` with the **screw that came with the servo**, keeping that perpendicular orientation. +6. Drop an **M2 nut** into a hexagonal pocket on `Neck`: + - Use the pocket with the **larger** center hole. + - That pocket is on the **robot’s right**. + - The pocket with the smaller hole is for mounting a servo later — leave it empty for now. +7. Unplug this servo from the PCA9685 so the next steps are easier to handle. + +![Neck](./assembly_visuals/neck_1.jpg) + +## 4. Join `Neck` and `Head` + +1. [Center](#center-a-servo) the servo already inside `Head`. +2. Take the `Neck` assembly from §3. **First stage:** fit `Neck` onto the Head servo shaft — `Neck` has a dedicated pocket for that shaft. Gently push the Head cables aside if needed so the shaft seats fully. +3. **Second stage:** slide `Neck` further onto `Head` until the side with the M2 nut sits flush with `Head` and lines up with the mounting hole on that side. Keep the nut in its hex pocket so it does not fall out. +4. At 90°, `Neck` must sit **perpendicular** to `Head`. Adjust before fastening if needed. +5. Fasten `Neck` to `Head`: + - Robot’s right: M2 screw into the captured nut (M2×8 mm works). + - Robot’s left: the mounting screw that came with the servo. +6. Unplug the Head servo from the PCA9685 before continuing. + +![Neck](./assembly_visuals/neck_2.jpg) + +## 5. Chest — side servos + +1. Take the printed `Chest`. +2. Seat **two** unused servos in the side pockets (left and right). No horns yet. Shaft orientation does not matter — you will calibrate later. +3. Route each servo lead through the **vertical tunnel at the front** of `Chest` so the connectors exit from the **bottom** of the part. +4. Fasten both servos with **four M2 screws** total — two per servo (M2×16 mm works). Do not overtighten. + +![Chest](./assembly_visuals/chest_1.jpg) + +## 6. Mount head assembly on `Chest` + +1. Take the joined `Head` + `Neck` from [§4](#4-join-neck-and-head). The servo already fastened to `Neck` goes into the **center** servo pocket in `Chest`. +2. **Before** seating that servo, route its lead through the **central tunnel** in `Chest` and out the **bottom** of the part. +3. Seat the Neck servo fully in the center pocket. Keep front of `Head`/`Neck` on the same side as front of `Chest` (the side with the cable tunnels). +4. Fasten it to `Chest` with M2×8 mm screws. Prefer two screws; if space is tight, one screw at the back of the robot is enough. + +![Chest](./assembly_visuals/chest_2.jpg) + +## 7. Belly — last servo + +1. Take the **last** unused servo. [Center it](#center-a-servo). +2. Press `Belly` onto the servo shaft — `Belly` has a dedicated pocket for the shaft. Do **not** use a plastic horn. +3. Orient the servo **perpendicular** to `Belly`, with the longer end of the servo body toward the **rounded** side of `Belly`. +4. When alignment is correct, fasten with the **screw that came with the servo**. +5. Unplug this servo from the PCA9685 before continuing. + +![Belly](./assembly_visuals/belly_1.jpg) + +## 8. Route chest cables through `Belly` and join + +1. Take the three servo leads that exit the bottom of `Chest`: Neck (center) and the two side (hand) servos. +2. Pass them into `Belly` through the **large upper** opening, then out through the **lower side** opening. +3. Keep the same left-to-right order as they leave `Chest`: **left hand → neck → right hand**. That order is only an identification aid for later — not the PCA9685 channel sequence. +4. Orient `Belly` so its rounded side faces the **back** and matches the profile of `Chest`, then fasten with **four M2 screws** (M2×8 mm works). + +![Belly](./assembly_visuals/belly_2.jpg) + +## 9. Seat the body in `Chair` + +1. Take the robot body (`Head` through `Belly`). The servo already fastened to `Belly` goes into the dedicated pocket in `Chair`. +2. Orient so the front of the robot matches the front of the chair (the way the figure sits). +3. Route that servo’s lead through the **vertical tunnel** in `Chair` and out under the chair. +4. Slide `SeatLeft` and `SeatRight` in from the sides onto the rails / pockets on `Chair`. The seats lock the body servo in place so it cannot drop out of `Chair`. Watch the cables — do not pinch or crush them while seating the parts. +5. Fasten the two seat parts to each other with **two M2 screws** (M2×16 mm works). + +This finishes the **main robot body**. Set it aside — next steps build the desk. + +![Chair](./assembly_visuals/chair_1.jpg) + +## 10. Desk top stack + +1. Take `DeskTop`, `DeskPad`, and `Desk`. +2. Seat `DeskTop` into `DeskPad` — the parts nest together. +3. Place that stack onto `Desk`. Orient so the rounded cutout faces the robot (the side where the figure sits). +4. Fasten through the four corner holes with **four M2 screws** (M2×16 mm works). + +![Desk](./assembly_visuals/desk_1.jpg) + +## 11. Desk emblem + +1. Place `AiEmblem` on the front of the desk. +2. Fasten with **two short M2 screws** (M2×4 mm works). + +![Desk](./assembly_visuals/emblem_1.jpg) + +## 12. Electronics inside the desk + +By this point the boards should already be wired and soldered together as one harness ([wiring](../hardware/wiring.md)). This step only **mounts** that assembly into `Desk`. + +**Leave disconnected for now:** + +- ESP32 — do not attach the gold-pin jumper cables to the ESP32 pins yet +- PCA9685 — do not plug any servo connectors into the PCA9685 yet + +Everything else in the harness stays as already soldered and assembled. + +1. **USB-C breakout (Adafruit 5993)** — fasten with four longer M2 screws (M2×16 mm works) and secure with M2 nuts. +2. **PCA9685** — fasten to the rails on the inside of the desk front with four short M2 screws (M2×4 mm works). +3. **MAX98357A** — mount on the single rail on that same inner front wall with two M2 screws (M2×4 mm works). +4. **Speaker** — stick it to an inner wall, or leave it loose inside the desk for now. + +Mount in that order — USB first, then PCA9685, then MAX98357A, then the speaker — so later boards are not in the way. + +![Desk](./assembly_visuals/electronics_1.jpg) + +## 13. ESP32, power/AP smoke test, and `LampBase` + +1. Seat the **ESP32-C3-Zero** in the opening in the desk top from above. The pins must pass through the holes in the top; the module should sit flush in the recess and not stick up above the desk surface. +2. From underneath, connect the gold-pin jumper cables to the ESP32. +3. **Power/AP smoke test** (optional but recommended) before locking the module in: + - Confirm every wire is on the correct pin ([wiring](../hardware/wiring.md)). You can ignore servo plugs and the OLED for now — those come later. + - Firmware should already be on the board (flashed before servo centering). + - Apply power. The ESP32 LED should light and the board should start the **setup access point** for configuration. + - If that looks good, **disconnect power**. +4. Place the printed `LampButton` under `LampBase` so it can press the ESP32 **reset** button from above — keep that access easy. +5. Orient `LampBase` so its opening sits over the ESP32 status LED. +6. Fasten `LampBase` to the desk with **two M2 screws** (M2×8 mm works). This also holds the ESP32 from above. + +![Desk](./assembly_visuals/electronics_2.jpg) + +## 14. Desk props — laptop, mug, bell + +1. **Laptop** — slide `LaptopScreen` into the pocket on the underside of `LaptopCase`. Place the laptop on the desk and fasten with one M2 screw from under the desk (M2×8 mm works). +2. **Mug** — seat `Coffee` inside `Mug`. Place the mug in its dedicated spot on the desk and fasten the same way: one M2 screw from under the desk (M2×8 mm works). +3. **Bell** — first drive the M2 screw fully into `Bell` alone (M2×16 mm works). Then, with the screw already in the bell, drive that screw down into the desk from above and secure with an M2 nut underneath. + +![Desk](./assembly_visuals/desk_2.jpg) + +## 15. Connect servos and OLED + +Easiest with the desk tipped onto its front wall so the PCA9685 plugs face up, and the seated robot body beside it. + +1. Plug every servo lead and the OLED cable into the harness. +2. Use the correct PCA9685 channel order ([pinout](../hardware/pinout.md#pca9685-channels-not-esp32-gpio)): + + | Channel | Joint | + | --- | --- | + | 0 | Head pitch | + | 1 | Neck yaw | + | 2 | Left hand | + | 3 | Right hand | + | 4 | Body / torso | + + The left-to-right order through `Belly` is only an ID aid — **not** the channel sequence. Map explicitly: + + | Lead (as routed through Belly) | Channel | + | --- | --- | + | Left hand | 2 | + | Neck | 1 | + | Right hand | 3 | + + Head pitch → channel **0**. Body / torso (Belly servo under the chair) → channel **4**. +3. Power up and run a **servos + OLED smoke test**: servos respond, OLED shows something sensible, no brown-out or odd movement. If something is wrong, power down before swapping plugs. + +![Desk](./assembly_visuals/electronics_3.jpg) + +## 16. Fasten `Chair` to `Desk` + +1. Gently slide the desk up to the chair so the mounting holes on the desk (back / armrest sides) line up with the matching holes on `Chair`. +2. Fasten with **six M2 screws** total — three per side (M2×8 mm works). Do not force the parts; keep cables clear of the screw paths. + +![Desk](./assembly_visuals/body_1.jpg) + +## 17. Arms — elbow joints + +Build the arm assemblies only — do **not** mount them on the chest servos yet. + +1. At each elbow there is a screw hole joining the forearm to the upper arm. +2. Fasten left and right the same way: `ForearmLeft` to `UpperArm` and `ForearmRight` to `UpperArm` with one M2 screw per elbow (M2×8 mm works). Print / use two `UpperArm` parts (one per side). + +![Arms](./assembly_visuals/arms_1.jpg) + +## 18. Mount arms on the chest servos + +1. [Center](#center-a-servo) the side (hand) servos first. +2. Press each arm assembly onto its chest servo shaft. The upper arms have dedicated pockets for the shafts. +3. With the servos at 90°, set each arm so the hand sits at about shoulder height and the forearm points forward (toward the desk). +4. When the pose looks right, fasten each arm with the mounting screw that came with that servo. +5. Do this for both arms. If centering is not perfect, that is fine — you will refine it in the setup calibration later. + +![Body](./assembly_visuals/body_2.jpg) + +## 19. Lamp (press-fit) + +No screws — everything is a friction fit. + +1. Place `LampCap` onto `LampDiffuser`. +2. Push that stack into the opening in `LampBase`. + +![Lamp](./assembly_visuals/lamp_1.jpg) + +## 20. Setup wizard and first boot on Wi‑Fi + +The robot is built. What remains is servo calibration, Wi‑Fi, and a quick check that everything works. + +1. Connect power. The board should start the **setup access point**. +2. Join that Wi‑Fi and open the configurator (`http://192.168.4.1/config`). +3. Walk through the **entire setup wizard** (servo ranges, OLED, LED, speaker, hostname / home Wi‑Fi) — [getting started → Wi‑Fi setup](../getting-started.md#5-wi-fi-setup). +4. When the wizard is finished, **disconnect power**, then power on again. +5. The robot should join your home network and expose the **REST API**. Prove it with the web UI or a curl — [getting started → Prove it](../getting-started.md#6-prove-it), [api.md](../api.md). + +## Related + +| Topic | Doc | +| --- | --- | +| Parts inventory / printables | [3d_models/README.md](../../3d_models/README.md) | +| Print or order parts | [getting-started.md → Print and mechanical](../getting-started.md#2-print-and-mechanical) · [order-parts.md](order-parts.md) | +| Different servo size / CAD params | [parametric-design.md](parametric-design.md) | +| Servo axes and safe ranges | [robot-movement.md](../robot-movement.md) | +| Wire and power after assembly | [hardware/wiring.md](../hardware/wiring.md) · [hardware/README.md](../hardware/README.md) | +| Full build path | [getting-started.md](../getting-started.md) | diff --git a/docs/3d/assembly_visuals/arms_1.jpg b/docs/3d/assembly_visuals/arms_1.jpg new file mode 100644 index 0000000..efb9324 Binary files /dev/null and b/docs/3d/assembly_visuals/arms_1.jpg differ diff --git a/docs/3d/assembly_visuals/belly_1.jpg b/docs/3d/assembly_visuals/belly_1.jpg new file mode 100644 index 0000000..ce5c241 Binary files /dev/null and b/docs/3d/assembly_visuals/belly_1.jpg differ diff --git a/docs/3d/assembly_visuals/belly_2.jpg b/docs/3d/assembly_visuals/belly_2.jpg new file mode 100644 index 0000000..767151e Binary files /dev/null and b/docs/3d/assembly_visuals/belly_2.jpg differ diff --git a/docs/3d/assembly_visuals/body_1.jpg b/docs/3d/assembly_visuals/body_1.jpg new file mode 100644 index 0000000..8ba1da3 Binary files /dev/null and b/docs/3d/assembly_visuals/body_1.jpg differ diff --git a/docs/3d/assembly_visuals/body_2.jpg b/docs/3d/assembly_visuals/body_2.jpg new file mode 100644 index 0000000..675fec8 Binary files /dev/null and b/docs/3d/assembly_visuals/body_2.jpg differ diff --git a/docs/3d/assembly_visuals/chair_1.jpg b/docs/3d/assembly_visuals/chair_1.jpg new file mode 100644 index 0000000..904caab Binary files /dev/null and b/docs/3d/assembly_visuals/chair_1.jpg differ diff --git a/docs/3d/assembly_visuals/chest_1.jpg b/docs/3d/assembly_visuals/chest_1.jpg new file mode 100644 index 0000000..a866594 Binary files /dev/null and b/docs/3d/assembly_visuals/chest_1.jpg differ diff --git a/docs/3d/assembly_visuals/chest_2.jpg b/docs/3d/assembly_visuals/chest_2.jpg new file mode 100644 index 0000000..a73754b Binary files /dev/null and b/docs/3d/assembly_visuals/chest_2.jpg differ diff --git a/docs/3d/assembly_visuals/desk_1.jpg b/docs/3d/assembly_visuals/desk_1.jpg new file mode 100644 index 0000000..ec930cd Binary files /dev/null and b/docs/3d/assembly_visuals/desk_1.jpg differ diff --git a/docs/3d/assembly_visuals/desk_2.jpg b/docs/3d/assembly_visuals/desk_2.jpg new file mode 100644 index 0000000..e860a29 Binary files /dev/null and b/docs/3d/assembly_visuals/desk_2.jpg differ diff --git a/docs/3d/assembly_visuals/electronics_1.jpg b/docs/3d/assembly_visuals/electronics_1.jpg new file mode 100644 index 0000000..ad85a33 Binary files /dev/null and b/docs/3d/assembly_visuals/electronics_1.jpg differ diff --git a/docs/3d/assembly_visuals/electronics_2.jpg b/docs/3d/assembly_visuals/electronics_2.jpg new file mode 100644 index 0000000..6300f25 Binary files /dev/null and b/docs/3d/assembly_visuals/electronics_2.jpg differ diff --git a/docs/3d/assembly_visuals/electronics_3.jpg b/docs/3d/assembly_visuals/electronics_3.jpg new file mode 100644 index 0000000..6aa63ae Binary files /dev/null and b/docs/3d/assembly_visuals/electronics_3.jpg differ diff --git a/docs/3d/assembly_visuals/emblem_1.jpg b/docs/3d/assembly_visuals/emblem_1.jpg new file mode 100644 index 0000000..7c710d8 Binary files /dev/null and b/docs/3d/assembly_visuals/emblem_1.jpg differ diff --git a/docs/3d/assembly_visuals/head_1.jpg b/docs/3d/assembly_visuals/head_1.jpg new file mode 100644 index 0000000..28d6e7f Binary files /dev/null and b/docs/3d/assembly_visuals/head_1.jpg differ diff --git a/docs/3d/assembly_visuals/head_2.jpg b/docs/3d/assembly_visuals/head_2.jpg new file mode 100644 index 0000000..4679e8e Binary files /dev/null and b/docs/3d/assembly_visuals/head_2.jpg differ diff --git a/docs/3d/assembly_visuals/lamp_1.jpg b/docs/3d/assembly_visuals/lamp_1.jpg new file mode 100644 index 0000000..ac38654 Binary files /dev/null and b/docs/3d/assembly_visuals/lamp_1.jpg differ diff --git a/docs/3d/assembly_visuals/neck_1.jpg b/docs/3d/assembly_visuals/neck_1.jpg new file mode 100644 index 0000000..1ec8c93 Binary files /dev/null and b/docs/3d/assembly_visuals/neck_1.jpg differ diff --git a/docs/3d/assembly_visuals/neck_2.jpg b/docs/3d/assembly_visuals/neck_2.jpg new file mode 100644 index 0000000..1ff421e Binary files /dev/null and b/docs/3d/assembly_visuals/neck_2.jpg differ diff --git a/docs/3d/order-parts.md b/docs/3d/order-parts.md index 099cb89..7728967 100644 --- a/docs/3d/order-parts.md +++ b/docs/3d/order-parts.md @@ -1,6 +1,6 @@ # Order printed parts (no 3D printer) -No printer at home? You can still complete the mechanical step of the build by ordering the printed set from a third-party 3D-printing service, then continue with assembly, wiring, and flash as usual ([getting started](../getting-started.md)). +No printer at home? You can still get the printed set from a third-party 3D-printing service, then follow the interleaved build path: mechanical assembly continues around wiring and flashing ([assembly guide](assembly.md) is the sequencing authority; overview in [getting started](../getting-started.md)). Orders are at your own risk. Fit and finish can vary by provider and by design revision — especially on development builds there may be bugs — and we cannot guarantee every part will match every time. @@ -47,4 +47,4 @@ UI labels change; follow the outcomes, not exact button names. The flow below ma ## Next steps -Back to the build path: [getting started → Print and mechanical](../getting-started.md#2-print-and-mechanical) → wire → flash. Part inventory and home-print notes: [3d_models/README.md](../../3d_models/README.md). +Back to the interleaved build path: [getting started → Print and mechanical](../getting-started.md#2-print-and-mechanical), then [assemble](assembly.md) (wire and flash mid-assembly per that guide — not after all joins). Part inventory and home-print notes: [3d_models/README.md](../../3d_models/README.md). diff --git a/docs/3d/parametric-design.md b/docs/3d/parametric-design.md index 17f60d2..c82d7d4 100644 --- a/docs/3d/parametric-design.md +++ b/docs/3d/parametric-design.md @@ -106,9 +106,9 @@ Print [`ServoSizingTester`](../../3d_models/README.md#print-first) in the same | Value | When | | --- | --- | -| **2.2 mm** | CAD default and shipped `parts/*/3mf/` exports. Tested path on a **Creality Ender 3 V3 SE**, PLA, ~0.16 mm layer height ([printing notes](../hardware-for-software-engineers/06-3d-printing-and-mechanical-build.md)). | -| Smaller (e.g. 2.05–2.15 mm) | Screws feel loose / slide through on your printer — pick from `ScrewSizingTest`. | -| Larger (e.g. 2.25–2.35 mm) | Pilot too tight to start a thread without cracking — pick from `ScrewSizingTest`. | +| **2.1 mm** | CAD default and shipped `parts/*/3mf/` exports. Tested path on a **Creality Ender 3 V3 SE**, PLA, ~0.16 mm layer height ([printing notes](../hardware-for-software-engineers/06-3d-printing-and-mechanical-build.md)). | +| Smaller (e.g. 2.05–2.15 mm) | Pilot too tight to start a thread without cracking — pick from `ScrewSizingTest`. | +| Larger (e.g. 2.25–2.35 mm) | Screws feel loose / slide through on your printer — pick from `ScrewSizingTest`. | Always trust **your** `ScrewSizingTest` result over the table if they disagree. diff --git a/docs/README.md b/docs/README.md index 8999ced..4096bd4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,7 @@ Pick a path. Depth lives in the linked pages. | **Flash / configure** only | [getting-started.md](getting-started.md)#4-flash | | **Wire / power detail** | [getting-started.md](getting-started.md)#3-wire-and-power → [hardware/README.md](hardware/README.md) | | **Print / parts inventory** | [getting-started.md](getting-started.md)#2-print-and-mechanical → [../3d_models/README.md](../3d_models/README.md) | +| **Assemble printed parts** | [3d/assembly.md](3d/assembly.md) | | **Order printed parts** (no 3D printer) | [3d/order-parts.md](3d/order-parts.md) | | **Adapt CAD to a different servo** | [3d/parametric-design.md](3d/parametric-design.md) | | **Contribute a PCB** (KiCad) | [pcb.md](pcb.md) → [`hardware/`](../hardware/README.md) | diff --git a/docs/getting-started.md b/docs/getting-started.md index 56bdb30..75e846c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,6 @@ # Getting started -Build the robot end-to-end: parts → print → wire → flash → Wi‑Fi → one animation. Skip ahead if that stage is already done (e.g. robot on Wi‑Fi → jump to [hooks](hooks.md)). +Build the robot end-to-end: parts, print, then mechanical assembly interleaved with wiring and flash ([assembly guide](3d/assembly.md) is the sequencing authority), then Wi‑Fi and one animation. Skip ahead if that stage is already done (e.g. robot on Wi‑Fi → jump to [hooks](hooks.md)). ## What is the ESP32? @@ -27,20 +27,20 @@ Gather electronics from [hardware/components.md](hardware/components.md). Minimu Printables and CAD: [3d_models/README.md](../3d_models/README.md) (`parts/{servo_id}/3mf/*.3mf` ready to print PLA/PETG, no supports; source `cad/TinyEngineer.f3d` for edits / different hardware). No printer? [Order the aggregated sets from a provider](3d/order-parts.md) instead. Parametric servo sizes, Fusion add-in, and export: [3d/parametric-design.md](3d/parametric-design.md). When printing yourself, print [`ServoSizingTester`](../3d_models/README.md#print-first) and [`ScrewSizingTest`](../3d_models/README.md#print-first) first — confirm a real servo fits and pick an M2 pilot-hole diameter before queuing the rest of the set ([M2 screw holes](3d/parametric-design.md#m2-screw-holes)). Skip the testers-first step when ordering from a service. -Join printed parts with **M2 screws** that thread directly into the plastic (no glue, no inserts; easy to dismount later). A measured per-part screw list and shopping list (sg90) is in the [3D models README](../3d_models/README.md#screws) — ~30× M2×6 + ~5× M2×12, pan/button head. A full assembly SOP is **not documented yet** — use the parts table there as the inventory. After print: +Join printed parts with **M2 screws** that thread directly into the plastic (no glue, no inserts; easy to dismount later). Shopping list (M2×4 / ×8 / ×16 + nuts; same lengths for every servo preset): [3D models README → Screws](../3d_models/README.md#screws). Mechanical assembly continues around wiring and flashing — do not treat wire/flash as post-assembly steps. Sequencing authority: [3d/assembly.md](3d/assembly.md) (build map: Head + Hat, then wire/flash/setup AP before any centering, then the rest of the joins). After print: -- Fit the five servos (head, neck, left/right hand, body) — axes and safe ranges: [robot-movement.md](robot-movement.md) +- Start the assembly guide; fit servos as that guide calls for them (head, neck, left/right hand, body) — axes and safe ranges: [robot-movement.md](robot-movement.md) - Leave the ESP32 ceramic antenna clear of metal / dense plastic ([hardware/components.md](hardware/components.md)) ### 3. Wire and power -Canonical connections: [hardware/wiring.md](hardware/wiring.md) and the diagram [wiring/Tiny Engineer.drawio.png](wiring/Tiny%20Engineer.drawio.png). Overview: [hardware/README.md](hardware/README.md). +Wiring happens mid-assembly (after Head + Hat, before servo centering). Canonical connections: [hardware/wiring.md](hardware/wiring.md) and the diagram [wiring/Tiny Engineer.drawio.png](wiring/Tiny%20Engineer.drawio.png). Overview: [hardware/README.md](hardware/README.md). Follow [3d/assembly.md](3d/assembly.md) for when to pause mechanical work and wire. Before first power-up, run the assembly checks in wiring.md (common GND, PCA9685 **VCC** = 3.3 V vs **V+** = 5 V not shorted, OLED clock on **SCL**, speaker on **SPK+/SPK−** only). Prefer bench bring-up with a strong 5 V supply before seating everything in the printed shell. ### 4. Flash -Firmware is Arduino on [PlatformIO](https://platformio.org/) ([pioarduino](https://github.com/pioarduino/platform-espressif32) / Arduino-ESP32 3.x). Board and baud live in `platformio.ini`. +Flash in the same mid-assembly window as wiring (required before centering). Firmware is Arduino on [PlatformIO](https://platformio.org/) ([pioarduino](https://github.com/pioarduino/platform-espressif32) / Arduino-ESP32 3.x). Board and baud live in `platformio.ini`. Install [PlatformIO Core](https://docs.platformio.org/en/latest/core/installation.html) (or the PlatformIO extension). Connect the board over USB (Adafruit 5993 data lines when assembled). @@ -94,6 +94,7 @@ Robot on the same LAN → [hooks.md](hooks.md). Any IDE / scripts → [integrati | --- | --- | | Which wires / voltages? | [hardware/wiring.md](hardware/wiring.md), [hardware/pinout.md](hardware/pinout.md) | | What to print? | [3d_models/README.md](../3d_models/README.md) | +| How to assemble printed parts? | [3d/assembly.md](3d/assembly.md) | | `.local` slow or fails | OLED IP; `curl -4 http://…` | | OLED shows join AP / `192.168.4.1` | Wi‑Fi not saved or STA failed — finish the setup AP wizard | | Welcome / ring silent (servos move) | LittleFS missing WAVs — `pio run -t uploadfs` | diff --git a/docs/hardware-for-software-engineers/06-3d-printing-and-mechanical-build.md b/docs/hardware-for-software-engineers/06-3d-printing-and-mechanical-build.md index d5a5d3c..74c2740 100644 --- a/docs/hardware-for-software-engineers/06-3d-printing-and-mechanical-build.md +++ b/docs/hardware-for-software-engineers/06-3d-printing-and-mechanical-build.md @@ -58,9 +58,9 @@ The models are **prepared with clearance** so printed parts and hardware (servos > **If you've written backend code…** Printed holes are like JSON numbers — `2.0` isn't exactly 2.0 after float serialization. These files already budget slack; a badly calibrated printer can still eat it. -**Screws:** assembly uses **M2** screws that thread directly into the printed plastic — no glue, no heat-set inserts. A measured per-part screw list and shopping list (sg90) lives in the [3D models README](../../3d_models/README.md#screws): ~30× M2×6 + ~5× M2×12, pan/button head. Test fit as you go. +**Screws:** assembly uses **M2** screws that thread directly into the printed plastic — no glue, no heat-set inserts. Shopping list (M2×4 / ×8 / ×16 + nuts; same lengths for every servo preset) lives in the [3D models README](../../3d_models/README.md#screws). Join order: [assembly guide](../3d/assembly.md). Test fit as you go. -**If M2 screws feel loose (slide instead of cutting a thread):** print tolerances ate the pilot. Print [`ScrewSizingTest.3mf`](../../3d_models/README.md#print-first) first (alongside [`ServoSizingTester`](../../3d_models/README.md#print-first)), pick the labeled hole that bites firmly, set Fusion `screw_thread_diameter` to that diameter, and re-export. CAD default / shipped parts use **2.2 mm**. Full write-up: [M2 screw holes](../3d/parametric-design.md#m2-screw-holes). +**If M2 screws feel loose (slide instead of cutting a thread):** print tolerances ate the pilot. Print [`ScrewSizingTest.3mf`](../../3d_models/README.md#print-first) first (alongside [`ServoSizingTester`](../../3d_models/README.md#print-first)), pick the labeled hole that bites firmly, set Fusion `screw_thread_diameter` to that diameter, and re-export. CAD default / shipped parts use **2.1 mm**. Full write-up: [M2 screw holes](../3d/parametric-design.md#m2-screw-holes). --- @@ -100,7 +100,7 @@ Alternatives (FreeCAD, Onshape) can work but project source is Fusion. ## Mechanical assembly principles -Full step-by-step SOP is still a doc gap — these principles keep you out of trouble: +Step-by-step SOP: [assembly.md](../3d/assembly.md). Use that guide for the build sequence; principles below cover key failure modes. ### Servo installation @@ -140,4 +140,4 @@ Electronics can ship slow. Start printing **structural parts** (chest, head, cha **Next:** [Power budgets and safety](07-power-budgets-and-safety.md) -**Reference:** [3d_models/README.md](../../3d_models/README.md) · [cad/TinyEngineer.f3d](../../3d_models/cad/TinyEngineer.f3d) · [parametric design](../3d/parametric-design.md) · [robot-movement.md](../robot-movement.md) +**Reference:** [assembly.md](../3d/assembly.md) · [3d_models/README.md](../../3d_models/README.md) · [cad/TinyEngineer.f3d](../../3d_models/cad/TinyEngineer.f3d) · [parametric design](../3d/parametric-design.md) · [robot-movement.md](../robot-movement.md)