How to build Tiny Engineer (a desk robot that gives an AI coding agent a body): the whole process
239 steps to build Tiny Engineer (a desk robot that gives an AI coding agent a body), from buying parts, printing and assembly to software, calibration and training, wit…
There is no kit or assembled price, and the creator gives no total parts cost. The main board is ordered from a PCB fab using the KiCad files: in discussion #50 the creator says JLCPCB has a five-board minimum, at about $75 with single-sided assembly or about $150 fully assembled on both sides (the creator's estimates, shipping extra); an assembled board at about $15–20 is only an interest check. The rest is an ESP32‑C3‑Zero, five servos, an OLED, a speaker, M2 screws, a 5 V ≥2 A supply and the printed parts, for which the docs give shop links but no prices
Bill of materials · Shopping list
| Part | Qty |
|---|---|
| Base | 1 |
| ButtonPocket | 1 |
| Bell | 1 |
| Button | 1 |
| Clamp | 4 |
| CableTunnel | 1 |
| ActionEmblem | 1 |
| 6×6 mm momentary tactile switch (4-pin) | 1 |
| Jumper wires, female DuPont end | 2 |
| M2×16 mm screws | 4 |
| M2×8 mm screws (or nearby short) | 17 |
Bill of materials · Default cart
| Part | Qty | ANY |
|---|---|---|
| Tiny Engineer main control board | 1 | |
| Waveshare ESP32-C3-Zero | 1 | |
| Tower Pro SG90 (or equivalent 9 g analog micro) | 5 | |
| Adafruit Mini Oval Speaker - 8 Ohm 1 Watt | 1 | |
| Waveshare 0.91inch OLED Module (SSD1306, 128×32, I2C) | 1 |
Buy parts
- Buy the Remaining Robot Parts
The PCB fabricator builds the board and optionally solders the selected components onto it. Separately buy the plug-in modules and the remaining robot cart parts listed in shopping.md.
- Choose the PCBA assembly level
Choose one-side PCBA if you will solder the 2.54 mm female header sockets for the Waveshare ESP32-C3-Zero, using two 1×9 rows, or choose both-sides PCBA with the headers assembled for you.
- Start a JLCPCB order
Create or sign in to a JLCPCB account and start a new PCB order.
- Upload the Gerber ZIP
Upload the Gerber ZIP from the Shop downloads or from the local export.
- Keep the standard board options
Keep most board options at sensible defaults. The document identifies a typical option match for this board in its six-row table.
- Enable PCB assembly
Turn on PCB Assembly and leave the stencil off because this PCBA flow does not need a separate stencil when the fab assembles the board.
- Configure the one-side PCBA
Select Economic PCBA, Top assembly side, and the desired assembly quantity. The fab may assemble fewer boards than the PCB quantity, while bare leftovers arrive without parts.
- Configure the fully assembled PCBA
Select Standard PCBA and Both sides assembly. The fab may add edge rails, so enabling depaneling can provide usable boards without manual rail cutting; the assembly quantity may be lower than the PCB quantity.
- Review the board layout
Continue to the fab’s viewer and review the board layout. Confirm that the outline, holes, and copper look right before proceeding.
- Upload BOM and placement files
Upload `bom.csv` and `positions.csv`, with `positions.csv` serving as the CPL or pick-and-place file, and then continue.
- Review the bill of materials
Check every line because stock and catalog entries change. If multiple catalog items match an ESP32 header part, choose the correct one manually. Resolve out-of-stock or wrong parts before paying, or update the schematic LCSC fields, re-export, wait for a new site deploy, and upload again.
- Review quote and place order
Review the cost quote, complete checkout, and track the shipment.
- Choose the Tower Pro SG90
Choose the Tower Pro SG90 for the easiest-to-buy servo option. The assembled robot is approximately 13 × 15 × 12 cm H×W×D.
- Choose the compact Feetech FS0307
Use the Feetech FS0307 when you want a smaller robot. Its assembled size is approximately 11 × 13 × 10 cm H×W×D.
- Choose the EMAX ES9051 alternative
Use the EMAX ES9051 as a compact alternative to the Feetech FS0307. The assembled size is approximately 11 × 13 × 10 cm H×W×D, and it must not be mixed with the FS0307.
- Consider the backward-compatible HD-1370A
The PowerHD HD-1370A remains supported for backward compatibility, but it is not the choice for a new build.
- Obtain the advanced USB-C option
For the advanced wiring path, use the Adafruit 5993 USB connector and follow the linked wiring instructions.
- Confirm the added modules
The default build uses the main control board. This advanced wiring adds a separate PCA9685 breakout, a MAX98357A breakout, and an Adafruit 5993 USB-C breakout.
- Choose adequate 5 V power
Provide a 5 V, at least 2 A source, with extra margin if several servos can move while audio plays. The current actually delivered depends on the charger or port.
- Choose USB or dedicated power
The Adafruit 5993 does not perform USB-PD voltage conversion. Feed it 5 V USB, or bypass it with a dedicated 5 V, at least 2 A PSU connected to the +5V and GND rails.
- Review the shopping guide
Select and buy the required components using shopping.md.
- Choose a 5 V power supply
Use a nominal 5 V source rated at least 2 A, with margin.
- Order printed parts from a bureau
If ordering printed parts from a bureau instead of printing at home, follow the order printed parts link. The linked instructions include the thin-wall disclaimer.
- Buy the ESP socket headers
Buy two Kinghelm KH-2.54FH-1X9P-H3.5 headers, LCSC/JLCPCB C55778388, with 2.54mm pitch and 1×9 THT contacts. Install one strip at each of the two ESP32-C3-Zero socket rows.
- Order the main control board
Order the open-source main control board from any fabrication service.
Print and make
- Check the ESP slot dimensions
Before relying on the carrier outline, re-check the ESP slot dimensions in your exported desk model; different servo presets produce different desk dimensions.
- Regenerate and order the PCB
Regenerate the Gerber, drill, BOM, and CPL outputs from `compact-carrier-board.kicad_pcb` instead of relying on committed copies, then use those outputs to order the carrier board.
- Fabricate the two-layer carrier
Fabricate the carrier as a 26 × 44mm, two-layer board. The ESP mounting slot measures 25.0 × 18.5mm, with three of its four sides only 3.0-3.6mm from full-height enclosure walls.
- Lay out the front-zone connections
Provide four J_PWR through-holes for 5V, GND, and external USB D+/D-, plus J_SERVO, J_I2C_OLED, J_I2C_PCA, and J_I2S. The two I2C connectors share the bus through onboard copper.
- Route the connections on-board
Route everything fully on-board without an off-board jumper. Connect J_SERVO directly to PCA9685 V+ with 5V, bypassing the ESP's 3.3V regulator, and give J_I2S its own onboard 5V feed.
- Run the PCB DRC check
Run DRC with KiCad 10.0.6 without `--refill-zones` so it judges the fill stored on disk. The result should be 0 violations and 0 unconnected items.
- Verify pad names on silk
Verify that every pad has a silk name: the outer row uses `GP21`-`GP6`, and the inner row uses `5V, GND, 3V3, GP0`-`GP5`. Both I2C headers are labeled `3V3/SDA/SCL/GND`, `J_I2S` is labeled `5V/BCLK/LRC/DIN/GND`, `J_PWR` is labeled `GND/D+/D-/5V`, and `J_SERVO` is labeled `5V/GND`.
- Check silk placement geometry
Check silk placement geometrically rather than through DRC. There should be no silk-to-silk overlaps, with 0.421mm minimum silk-to-pad and 0.383mm minimum silk-to-edge clearances.
- Adjust silkscreen and connectors
Set all seven text items to 1.0mm / 0.15mm, and move `J_I2C_PCA`, `J_PWR`, and `J_SERVO` clear of the new pin-name bands. Recheck every label against the 0.30mm edge margin, nudging the three marginal labels inward.
- Raise and refill GND clearance
Raise the GND clearance from 0.20mm to 0.25mm in both the zone's local clearance and the Default netclass. Refill the zone.
- Correct four left-side designators
Use each footprint's own text bounding box to shift the `J_ESP1`, `J_ESP2`, `J_I2C_OLED`, and `J_I2C_PCA` labels to the right. Position them at a 0.3mm margin from the board's left edge and confirm them visually.
- Validate and set GND zone inset
On the drill-fixed board, set the B.Cu GND zone outline 0.5mm inward from the board edge. Test from 1.0mm down to 0.3mm in 0.1mm increments with a fresh zone refill; 1.0mm and 0.8mm each produce one unconnected pad, while 0.6mm through 0.3mm pass, so use 0.5mm.
- Check the PCBWave DFM report
Identify the tightest feature as 0.15mm copper, the minimum thickness of the GND pour. It is above JLCPCB's 0.127mm floor but exactly at PCBWave's 0.15mm floor; check their DFM report before ordering if using PCBWave.
- Widen and rearrange the 5V trace
Size the 5V trace for IPC-2221 at 2A, 1oz copper, and a 10°C rise, giving an approximately 0.78mm minimum. Route the entire 44.9mm net at 1.0mm with no pinch points, and move the 5V pad to the inner row, 15.24mm closer to its loads.
- Resize the Full CAD Assembly
Open cad/TinyEngineer.f3d in Autodesk Fusion to adjust the full assembly or adapt it to different hardware sizes, including different servos.
- Add a New Parametric Part
Follow the adding-parts guide to apply parametric rules and the timeline, configure PRINT_LAYOUT and the Servo Configurator, export the part, and optionally apply mods.
- Match Parts to Your Servos
Match the parts/{servo_id}/ folder to the servos you bought. The available 3MF folders include sg90, fs0307, es9051, and hd1370a.
- Use the Interactive Print Queue
Open the Print page, use the Shop servo selection, preview the parts live, and download the .3mf or .stl files.
- Download the 3MF Part Files
Instead of using the print queue, download the .3mf files from the sg90, fs0307, es9051, or hd1370a parts folder.
- Choose PLA or PETG
Print the parts in an orientation that does not require supports, using PLA or PETG.
- Order Printed Parts Instead
If you do not have a printer, follow the printed-parts ordering guide to order the aggregated sets from a third-party service.
- Start with the Printing Guide
Begin the printing workflow with the Print first guidance.
- Print both fit testers first
For home printers, print ServoSizingTester.3mf and ScrewSizingTest.3mf before the rest of the set. Do not print the full robot until both fit; skip this step when ordering from a service.
- Print the LampDiffuser without scaling
Print LampDiffuser in white or translucent PLA; PETG is also fine. It is intentionally thin, about 0.38 mm with a 0.4 mm nozzle, and must not be scaled. If the slicer skips it, check for empty-layer errors, missing walls in the preview, or a thin-wall warning.
- Download the PCB Manufacturing Files
Download gerbers.zip, bom.csv, and positions.csv from the shop board lane or their direct links. These files are generated from the board sources at the latest GitHub Pages deployment, not from a release tag.
- Create a PCB Fabricator Account
Create an account with the selected PCB fabricator. This walkthrough uses JLCPCB, although another fabricator may be used.
- Check Stock and Component Orientation
Open the fabricator interface and review component stock and orientation before paying. Re-check the bill of materials and part availability for the selected fabricator and assembly service.
- Order the Main Control PCB
Use the downloaded manufacturing files to order the main control board from JLCPCB or another fabricator. Optionally order assembly with LCSC parts; the fabricator builds the PCB and solders the selected parts onto it.
- Install KiCad and Fabrication Toolkit
Install KiCad 10 and add the Fabrication Toolkit plugin through Plugin and Content Manager.
- Open the main control board project
Open `hardware/boards/main-control-board/main-control-board.kicad_pro` in KiCad.
- Export the fabrication files
Run Fabrication Toolkit so it writes under the board folder, typically `production/`, and confirm the Gerber ZIP, `bom.csv`, and `positions.csv` are present. Keep `production/` local because it is gitignored.
- Export files with the fabrication script
On a machine with KiCad Python (`pcbnew`) and the Toolkit installed or downloadable, run the export script. It writes the same three public filenames under `web/shop/fab/main-control-board/`, which is gitignored.
- Review placement and orientation
Review the component placement and orientation, then continue.
- Print the SG90 robot parts
Print the robot parts from the 3d_models/parts/sg90/3mf/ directory.
- Print the FS0307 robot parts
Print the robot parts from the 3d_models/parts/fs0307/3mf/ directory.
- Print the ES9051 robot parts
Print the robot parts from the 3d_models/parts/es9051/3mf/ directory.
- Print the HD-1370A robot parts
Print the robot parts from the 3d_models/parts/hd1370a/3mf/ directory.
- Match files to servo model
Choose the servo model in the Shop Section; it determines the CAD base and print set. Use the 3MF files for home printers or STL files for many print services.
- Print and check fit testers
Print the two small fit testers to check the servo pocket and M2 screw fit. Fit testers are optional, but recommended when the printer setup is not already known.
- Print the full color set
Order or print the fit testers first, perform the optional fit checks, and then print the full set by color: copper, black, or white.
Assemble
- Build the harness on the desk
Build the harness on the desk. This step comes after printing and before flashing.
- Seat the modular harness
Seat the harness using the modular assembly instructions. These replace sections 12–13 of the standard assembly instructions.
- Connect the common ground
Connect common GND to every module. Never jumper the 5 V and 3.3 V rails together.
- Connect the shared I2C bus
Connect the I2C SDA and SCL signals. The OLED and PCA9685 share this I2C bus.
- Connect the MAX98357A audio signals
Connect the I2S BCLK, LRC, and DIN signals to the MAX98357A. The speaker uses BTL wiring, so SPK− is not ground.
- Connect the USB data signals
Connect the USB D+ and D− data signals to the Adafruit 5993 USB-C breakout.
- Connect the PCA9685 enable signal
Connect ESP32 GP5 to PCA9685 OE. Firmware GPIO numbers are in include/pins.h and pinout.md; diagram labels GP0 through GP21 correspond to GPIO0 through GPIO21.
- Connect the 3.3 V logic rail
Connect ESP32 3V3 to PCA9685 VCC and OLED VCC. PCA9685 VCC is logic power; never jumper 5 V and 3.3 V together.
- Connect the 5 V rail last
Connect 5 V last: USB VBUS to ESP32 5V, PCA9685 5V, and MAX98357A Vin. PCA9685 V+ is servo power; leave servo leads unplugged until centering.
- Identify PCA9685 power pins
Treat V+ as the servo rail, normally the same as the PCA9685 5V pad; do not treat 5V as VCC.
- Connect the common ground
Connect the modules using the connection table and place the ESP32, PCA9685, OLED, MAX98357A, and servos on one common ground network.
- Connect power as drawn
Connect USB 5V to ESP32 5V, PCA9685 5V, and MAX98357A Vin, then connect PCA9685 V+ to servo 5V. Connect ESP32 3V3 only to PCA9685 VCC and OLED VCC.
- Connect servo-side ground
Connect USB GND to ESP32 GND, PCA9685 header GND, OLED GND, and MAX98357A GND, then connect servo GND through PCA9685 servo-header GND.
- Connect USB power and programming
Use the Adafruit 5993 USB block shown for VBUS/GND power; the single-USB design also requires D+ to GP19 and D− to GP18.
- Connect the shared I2C bus
Connect ESP32 GP0 to PCA9685 SDA and OLED SDA, and connect ESP32 GP1 to PCA9685 SCL and OLED SCL.
- Connect the MAX98357A I2S
Connect ESP32 GP2, GP3, and GP4 to MAX98357A BCLK, LRC, and DIN respectively, and connect USB 5V and USB GND to Vin and GND.
- Connect servos on channels 0–4
Connect the five HD-1370A servos to PCA9685 PWM channels 0–4. The PWM header is unnumbered; use robot-movement.md and include/servos.h for the channel-to-joint mapping.
- Leave unused ESP32 pads
Do not add wiring not shown for GP6, GP7, GP8, GP9, GP10, GP20, or GP21. GP9 is BOOT, and GP10 is connected to the onboard WS2812.
- Wire the PCA9685 enable pin
Wire ESP32-C3-Zero GP5 to the PCA9685 breakout OE pin; OE is active LOW. Add this wire on the breadboard and at the Adafruit breakout OE pin even if the base PNG omits it.
- Connect ESP32 native USB
Wire the Adafruit 5993 D−/D+ lines to the ESP32-C3-Zero GP18/GP19 native USB pins, even if the base PNG omits them.
- Do not add extra GPIO wiring
Items absent from the drawing are still part of the selected hardware, but do not add ESP32 GPIO connections for them on your own.
- Keep MAX98357A defaults
Leave MAX98357A GAIN and SD unwired so the breakout uses its defaults.
- Connect BTL speaker outputs safely
MAX98357A output is BTL, and neither SPK− nor SPK+ is ground. Never tie either output to GND or drive the speaker from an ESP32 GPIO.
- Install the single USB-C connector
Use the Adafruit 5993 as the robot's only USB-C connector. This vertical downstream USB Type-C breakout has two 5.1 kΩ CC resistors that request 5 V and up to about 1.5 A from the upstream port.
- Wire USB power and data
Wire USB 5V and GND to the robot's power rails and also connect D+/D−; do not rely on a drawing that shows only the power lines.
- Connect All GND Nets
Confirm that every GND in the PNG is one net, including USB, ESP32, both sides of the PCA9685, OLED, MAX98357A, and servo.
- Check PCA9685 Power
Check that PCA9685 VCC is about 3.3 V and PCA9685 5V or V+ is about 5 V, with no short between the two nets.
- Connect the OLED Clock Wire
Connect the OLED clock wire to Waveshare SCL; the PNG may still label it SCK.
- Verify I2S Wiring
Confirm that I2S connects GP2, GP3, and GP4 to BCLK, LRC, and DIN respectively, without swapping it with I2C.
- Check Speaker Wiring
If fitted, the speaker uses only SPK+ and SPK-, which are not in the PNG.
- Mount the carrier and connect interfaces
Mount the carrier beneath the ESP32-C3-Zero through the desk's ESP slot, then use the `J_PWR`, `J_SERVO`, `J_I2C_OLED`, `J_I2C_PCA`, and `J_I2S` interfaces for power, servo power, the OLED, PCA9685, and I2S devices.
- Leave the other holes unpopulated
Do not populate connectors at J_PWR, J_SERVO, J_I2C_OLED, J_I2C_PCA, or J_I2S. These through-holes accept direct wire connections and are excluded from the BOM and CPL at the footprint level.
- Install the two ESP header rows
Place J_ESP1 on the inner row nearer the wire end at (13.00, 16.89), with 5V/GND/3V3/GPIO0-5. Place J_ESP2 on the outer row nearest the slot edge at (13.00, 1.65), with GPIO21-GPIO6.
- Orient the C3-Zero Correctly
Hold the C3-Zero component side up with its USB-C over the carrier board’s 5V-bus edge, the long edge beside the 5V trace. Check the pad map against the module’s component-side view as seen from the face it plugs into.
- Connect the J_ESP2 Outer Row
Place the outer row, J_ESP2, nearest the slot edge at y=14.15 and connect GPIO21, GPIO20, GPIO19, GPIO18, GPIO10, GPIO9, GPIO8, GPIO7, and GPIO6. These pins provide mechanical/no-net support except GP19 and GP18, which are the native USB pair.
- Connect the J_ESP1 Inner Row
Place the inner row, J_ESP1, nearer the wire end at y=29.39 and connect 5V, GND, 3V3, GPIO0 (SDA), GPIO1 (SCL), GPIO2 (BCLK), GPIO3 (LRCLK), GPIO4 (DIN), and GPIO5.
- Verify the Pin Numbering Orientation
Confirm that pin 1 and pin 18 in both rows land at the 5V-bus edge, fixing the module’s USB-C to that edge. Reading from 1 to 18 from above must be counter-clockwise, matching Waveshare’s art: 1–9 down the left column, 10–18 up the right, and USB-C at the top.
- Connect the External USB-C Jack
Use the robot’s single external USB-C jack, Adafruit 5993, to carry both power and the ESP32’s native USB D+/D− lines, allowing flashing and serial CDC after the desk is sealed. Leave the C3-Zero’s onboard USB-C unused; this is a direct connection with no ESD or series-resistor circuitry specified.
- Route the Length-Matched USB Traces
Route D+/D− down the same 2.54 mm grid columns as their pads, at x=20.42 and 22.96. Passing the inner row, jog each line 1.27 mm laterally around the 3V3 and SDA columns, leaving 0.42 mm to the nearest pad edge, then return; keep both routes on F.Cu with no vias.
- Mark pin 1 before assembly
The silkscreen will be underneath when the pour face is used, so mark pin 1 before assembly.
Software
- Flash the robot firmware
Flash the Tiny Engineer firmware before integrating it with an IDE or custom agent.
- Join the 2.4 GHz Wi-Fi network
Join the robot to a 2.4 GHz Wi-Fi network on the same network used by the computer or IDE.
- Install the unified CLI from npm
Install the `tiny-engineer` package from npm; no repository clone is required.
- Run the CLI setup
Run the general setup, or run the Cursor-specific setup with `--yes`. Setup writes a hook timeout of at least 30 seconds.
- Install the IDE event hook
Configure the IDE hook so IDE events are mapped to robot poses and posted to `/anim`.
- Configure user connection preferences
Store the transport, URL, port, and token in `~/.config/tiny-engineer/env` on macOS/Linux or `%APPDATA%\tiny-engineer\env` on Windows; `TINY_ENGINEER_CONFIG_DIR` overrides the directory.
- Set the robot URL
Use `--url http://192.168.x.x`, or set `TINY_ENGINEER_URL`; otherwise the CLI uses `http://tiny-engineer.local`. Setup does not edit the project `.env` file.
- Select the host transport
Select HTTP or serial with `--transport http|serial` or `TINY_ENGINEER_TRANSPORT`; setup stores the selection in user config, and the default is HTTP.
- Configure HTTP authentication
For an HTTP device with an `access_token`, set `TINY_ENGINEER_TOKEN` in the process environment, user config, or project `.env`. The CLI sends `Authorization: Bearer …`; serial transport does not send Bearer.
- Set up and diagnose the checkout
Run setup and doctor from the repository checkout. This checkout uses the `dev` channel, while a registry install uses the `npm` channel.
- Run serial commands through the daemon
Serial commands auto-start `tiny-engineer daemon` and communicate with it on a local socket unless the daemon is disabled or the port is yielded. HTTP commands do not start it.
- Install the persistent daemon wrapper
Run `tiny-engineer daemon install` to assure a live process. It registers a per-user login wrapper, not a system-boot service, and restarts the process after a crash; while it is installed, `start --port` and `restart --port` are ignored.
- Release the USB serial port
Run `tiny-engineer daemon release` to free the USB port while leaving the daemon process running. The `daemon stop` and `stop --yield` commands are deprecated aliases of `release` and `release --yield`.
- Disable the daemon persistently
Run `tiny-engineer daemon disable` to exit the daemon and keep it down. It remains down until `tiny-engineer daemon start` is run.
- Yield the serial port temporarily
Run `tiny-engineer daemon release --yield` to keep the process running but refuse auto-start for 180 seconds and avoid reopening the port when that window ends. A PlatformIO `pio run -t upload` clears the yield afterward via `daemon start`.
- Restart from the desired checkout
Run `daemon restart` from the checkout you want so it replaces a daemon from a different checkout. A dev checkout replaces a running npm daemon, while an npm command leaves a dev daemon running.
- Call an Animation Route
Use the shell, JavaScript, or Python example to POST an animation name to the robot.
- Choose the Integration Path
Use the unified CLI for Cursor, Claude Code, or Antigravity. Use the REST API for a custom agent, another IDE, CI, or a system without Node.
- Migrate Deprecated Integrations
Prefer the unified `tiny-engineer` binary over the deprecated `tiny-engineer-cursor`, `tiny-engineer-antigravity`, and `tiny-engineer-claude-code` bins. Run setup, then uninstall to remove leftover hook entries.
- Add macOS Lock Events
On macOS, optionally run the host helper to POST `sleep` and `wakeup` when the screen locks or unlocks. The robot does not require the helper.
- Open the setup wizard
When boot Wi-Fi credentials are missing, join the `TinyEngineer-XXXX` setup AP and open the wizard at `http://192.168.4.1/config`. The captive portal can open the wizard automatically after a phone joins the network.
- Choose the connection mode
Choose `wifi` or `usb` for the connection mode. The selected `link_mode` is reported by the settings, auth, and health endpoints.
- Enable USB-only control
After choosing USB-only mode, reboot the ESP32-C3. Wi-Fi station and the HTTP API are disabled, so control uses the USB serial protocol.
- Connect to the HTTP API
After STA Wi-Fi connects, use the board IP on port 80 or `http://tiny-engineer.local`; the mDNS hostname requires 2.4 GHz Wi-Fi. If saved credentials fail, the device reopens setup AP mode.
- Configure API authentication
When an `access_token` is configured, send `Authorization: Bearer <token>` with every JSON API request. The default empty token requires no authentication, and `GET /auth` is always public.
- Send JSON request bodies
Send a JSON object body with `Content-Type: application/json` to routes that take parameters, except `POST /anim` and `/play`. Query parameters or form fields on these routes, or a body that is not a JSON object, return `400`.
- Enable Kaomoji Eyes
Set `eyes_style=kaomoji` to display looping faces from the expression library on the OLED. The loop lasts 3 seconds and contains 30 frames.
- Enable Cover Eyes
Set `eyes_style=cover`. Each eye fills one half of the 128×32 panel with a 64×32 white rectangle, while animations adjust the height and margins.
- Enable Dots Eyes
Set `eyes_style=dots` to render each eye as a filled circle. At the classic open height, its bounding box is 12×12 px, and its diameter scales with the rendered height.
- Enable Kawaii Eyes
Set `eyes_style=kawaii` to use round eyes about 23 px across, with dark pupils, white catch-lights, a small mouth, and dithered blush. The `typing` animation reads code, while `ring` keeps the eyes at full size.
- Add Custom Audio Cues
Replace stock WAV files in a filesystem built with `custom_audio_mod`, and provide a `.cue` file on LittleFS for each custom clip. Use `/welcome.cue` and the same naming pattern for `attention`, `error`, `abort`, and `dead`.
- Seat the ESP32 module
Push the ESP32 module into the main board sockets, aligning it with the USB mark printed on the board.
- Connect the USB-C data cable
Connect a USB-C data cable to the main board’s USB-C port, not the small port on the ESP32 module.
- Install the robot firmware
Wait for the model and flashable releases to load, then click Install to put the robot software on the ESP32 over USB.
- Confirm the successful flash
After the board is flashed, click Continue and proceed to mechanical assembly.
- Flash the module with PlatformIO CLI
Alternatively, run the CLI upload command to flash the module. A module flashed by itself will blink and halt while looking for the board.
- Flash the main control board
Flash the main control board; the robot then joins your Wi-Fi.
- Set up coding agent integration
Run the setup command to use Tiny Engineer with Claude Code, Cursor, or Antigravity.
- Configure an agent to send poses
Use the default client or a hook script to send poses to the ESP32-C3 over Wi‑Fi HTTP or USB serial.
- Configure USB CDC serial
Use the same cable for robot power and programming, with ARDUINO_USB_MODE=1 and ARDUINO_USB_CDC_ON_BOOT=1, and set the serial monitor to 115200.
Calibrate and test
- Calibrate the servo hub
In the servo-hub wizard step, choose guided calibration, skip calibration, or use assembly centering.
- Set the OLED orientation
In the setup wizard, configure the OLED orientation.
- Test the RGB LED
In the setup wizard, run the RGB LED test.
- Test the speaker
In the setup wizard, run the speaker test.
- Verify robot provisioning
Choose a connection mode before using the `/anim`, `/test/*`, and `/play` control APIs. Before provisioning, these routes return `503` with `{"ok":false,"error":"not provisioned"}`.
- Check API authentication status
Query the authentication endpoint to see whether API authentication is required and whether Wi-Fi is configured. The public response does not reveal the token.
- Check robot health
Query health information such as uptime, memory, CPU temperature, Wi-Fi status, and OLED availability. When authentication is enabled, send the token as a Bearer authorization header.
- Validate and save robot settings
Send settings with POST /settings, omitting fields whose saved values should remain unchanged. Empty objects, unknown fields, invalid types or ranges, incomplete servo limits, conflicting enabled-extension GPIO pins, and setup-only changes outside AP mode return 400 without saving anything.
- Set the hostname first
Before testing or saving WiFi in setup AP mode, set the hostname with POST /settings so mDNS registration uses the saved hostname.
- Prepare the WiFi network list
Prepare 1 to 5 networks with unique SSIDs and valid password lengths. A new SSID requires a password, an empty string means an open network, and omitting the password retains the password already saved for that network.
- Replace and test WiFi networks
Send the complete array to PUT /settings/wifi; list order determines boot priority for networks missed by a scan. Outside AP mode the list is saved without testing and applies at the next boot, while in AP mode the first network is tested and joined before saving; use a Bearer token when authentication is enabled.
- List on-device Actions
GET `/settings/actions` lists event-to-effect bindings and requires a Bearer token when authentication is enabled. GET `/actions` serves the SPA web UI shell instead of this JSON.
- Replace the Actions list
- Test an Action event
POST `/actions/test` with JSON `{ "type": "button.click" }` runs matching Actions without publishing a WebSocket or serial envelope. The endpoint requires a provisioned robot and a Bearer token when authentication is enabled; a missing or empty `type` returns 400.
- Move all five servos to 90°
In AP mode, move all five servos slowly to 90° over the full 0–180° electrical range without the saved safe-range clamp. The handler blocks until the move finishes and does not require Wi-Fi credentials.
- Move one servo to 90°
Send an `index` and `angle` to move one servo slowly through the full 0–180° electrical range at about 25°/s. Wrong fields return 400 without moving any servo.
- Test a servo after STA starts
After the STA connection is up, test a servo through `POST /test/servo`; this endpoint clamps movement to the saved minimum and maximum.
- Preview a logical LED color
In AP mode, send logical `R`, `G`, or `B` to light the firmware red, green, or blue channel using the saved `rgb_order`, or an included `rgb_order` field for the remap preview. Do not send `color` and `byte` together.
- Preview a logical LED byte
In AP mode, send a logical byte to light the corresponding channel independently of WS2812 channel order; channel 255 lights that channel. Do not send `color` and `byte` together.
- Release the LED preview hold
Send an empty body to release the LED hold and restore the dim-blue provisioning display. This setup operation does not require Wi-Fi credentials.
- Save the RGB channel order
In setup AP mode, save the labeled RGB permutation with `POST /settings` and `{"rgb_order":"GRB"}`. The saved order applies immediately to animation colors, boot status, halt blinks, and `POST /test/led`.
- Play the setup welcome audio
In setup AP mode, send a POST request with no body; it plays `welcome.wav` from LittleFS and blocks until playback finishes. It does not require Wi-Fi credentials and uses the same speaker gain as the settings `volume`.
- Preview the rotated OLED
In setup AP mode, send `{"rotate_180": true}` to apply `setRotation(2)` and draw `THIS WAY UP` without saving the change. Wrong fields return a 400 response.
- Preview the normal OLED orientation
In setup AP mode, send `{"rotate_180": false}` to apply `setRotation(0)` and draw the same `THIS WAY UP` test without saving.
- Restore the saved OLED orientation
In setup AP mode, send a POST request with an empty body to restore the saved rotation and the provisioning join-AP text.
- Save the OLED rotation setting
In setup AP mode, save the OLED rotation with `POST /settings` and `{"oled_rotate_180":true}`. The saved value applies immediately and on the next boot.
- Confirm the robot health endpoint
Open `http://tiny-engineer.local/health` or the OLED IP health endpoint and confirm that it responds.
- Check the CLI connection
Run `doctor` to check the wiring and connection configuration.
- Check daemon and serial status
Run the status command to check whether `daemon install` is enabled and the login wrapper is running. It also reports the host serial ports, the open daemon port, the channel, and the package root.
- Open USB for armed serial reactions
When serial reactions are armed—`rules.json` contains a rule and the user transport is `serial`—`daemon start` and `daemon restart` open the USB port. Otherwise, they leave the port closed.
- Check Robot Health
Request the health endpoint to verify the robot without causing motion.
- Check the BOM quantity
Confirm that the generated BOM groups the identical parts on one row as `"J_ESP1,J_ESP2"` and unambiguously reads quantity 2. JLCPCB assembly tooling and most BOM tools count designators rather than parsing Comment text.
- Check the CPL row coordinates
Confirm that the CPL has one row for J_ESP1 and one for J_ESP2, centered at (13.00, 16.89) and (13.00, 1.65). Read the coordinates directly from each footprint origin without manual derivation.
- Save zone fill and recheck DRC
After every track change, refill the GND zone through KiCad by using Fill All Zones and saving, or by using the `pcbnew.ZONE_FILLER` Python API. Then run `kicad-cli pcb drc` without `--refill-zones` to confirm the on-disk fill is current.
- Check the servo tester fit
Seat a real servo in ServoSizingTester.3mf without forcing it. Confirm that the body slides, the tabs sit, the holes line up, and the shaft has clearance; if it is tight or loose, sand or ream it, or adjust the servo CAD parameters.
- Size the M2 pilot holes
In ScrewSizingTest.3mf, drive an M2 screw into every diameter-marked hole and select the tightest hole that cuts a thread without spinning freely or allowing the screw to slide through. Set the Fusion user parameter `screw_thread_diameter` to that marked diameter, then re-export before printing structural parts.
- Open the web interface
Open http://tiny-engineer.local/ in a browser, or use the IP shown on the OLED.
- Check health and ring animation
Run the health check and request the ring animation. Confirm that /health is OK and that ring runs with motion, and with sound if LittleFS was uploaded. If .local is slow, use the OLED IP or curl -4.
- Configure servo horns and end stops
Start servo horns and end stops from `SERVO_SPECS` in `include/servos.h`, then tune them after installation if needed.
- Verify saved servo motion limits
Check that assembled motion remains inside the saved minimum and maximum values.
Data and training
- Receive outbound events
Connect to the outbound-events WebSocket on port 81 at `/events` while the HTTP server is running. The same event JSON is also sent over USB serial as `Evt` frames.
Use it
- Connect to authenticated events
Connect to the WebSocket events endpoint and replace YOUR_TOKEN with the authentication token.
- Watch serial event frames
Use `tiny-engineer watch` with an `http:` base for WebSocket delivery or `--transport serial` for `Evt` frames. Serial frames use the same JSON payload as WebSocket text frames and are dropped when the CDC transmit buffer cannot accept them.
- Open the endpoint index
Request the HTML index to list all routes and supported parameters. The page is built from `ui/` with Vite and embedded in the firmware.
- Test audio after station connection
After STA is up, use `POST /test/audio/bell` to play the bell or `POST /test/audio` for tones.
- Park and hold the servos
Send a POST request with no body to stop the current animation, smoothly move every joint to its calibrated midpoint, persist the pose to NVS, and keep PWM enabled until the next reboot. The endpoint requires a Bearer token when authentication is enabled and is available in setup AP and after provisioning.
- Connect a custom integration
For custom agents, unsupported IDEs, or scripts, call the REST API or serial protocol. The HTTP integration sends animation requests to `POST /anim`.
- Map IDE Events to Animations
Connect the animation requests to IDE hook, plugin, or lifecycle events. Choose the mapping; the robot only uses the `name` value.
- Review the Available Routes
Consult `api.md` for the full route list, including tests, servo, web UI, and `/play`.
- Return to the Getting-Started Checklist
After building the integrated PCB, return to the getting-started checklist to continue assembling and using Tiny Engineer.
- Map button events to a host program
With the extension enabled, presses publish `button.down`, `button.up`, `button.click`, `button.double_click`, and `button.long_click` over WebSocket and serial. Use the CLI to map an event to a host program, such as opening Music on a click.
Common problems
- SG90 model dimensions are inaccurate and prevent correct servo fitting. #30 #93
- OLED modules vary in dimensions, pinouts, and mounting requirements. #6
- The reference servo lacks a globally available, validated standard. #5
- Assembly documentation omits exact M2 screw lengths and required counts. #15
- Firmware flashing fails because ESP32 NVS storage cannot be found. #81
- The parametric head does not connect properly to the neck. #38
Parts
- The Tiny Engineer main control board (PCA9685 servo driver, MAX98357A amplifier and USB‑C on board); the advanced path uses those three as separate breakouts instead
- Waveshare ESP32‑C3‑Zero controller module
- 5 × Tower Pro SG90 micro servos (or five of the compact Feetech FS0307 / EMAX ES9051)
- Waveshare 0.91-inch OLED (SSD1306, 128×32, I²C) and an Adafruit 8 Ω 1 W mini oval speaker
- M2 thread-forming screws: 8 × 4 mm, 27 × 8 mm, 15 × 16 mm, plus 6 M2 nuts
- A 5 V ≥2 A USB supply and a USB‑C data cable; PLA or PETG prints (a copper set, a black set and a white or translucent lamp diffuser)
Tools
- A 3D printer (print the servo and screw sizing testers first), or a third-party print service
- A small screwdriver; with single-sided board assembly, two 1×9 rows of 2.54 mm female headers must be soldered by hand
- Chrome or Edge for browser flashing
Skills
- Ordering an assembled PCB: export Gerbers, BOM and placement files with KiCad 10 and the Fabrication Toolkit, then check every BOM line
- Assembly from sections 1–19 of the assembly guide, then servo calibration and joining 2.4 GHz Wi‑Fi in the setup wizard of section 20
- Node 18+ and npx tiny-engineer setup for IDE hooks, or curl against the REST API
Software
- ESP32‑C3 firmware (PlatformIO): animations, eye styles (classic, kaomoji, cover, dots), sound cues and streamed WAV playback; browser flashing and OTA updates
- The tiny-engineer CLI (npm): setup, hook and doctor for Cursor, Claude Code and Antigravity, over HTTP or serial
- HTTP API (/anim, /play, /settings and more) and a USB serial protocol
- Parametric Fusion CAD with a servo-preset add-in for exporting parts for new servos